1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19  
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 /*
25  * Conversion parameters:
26  * inFile  = libgda-GdaConnection.html
27  * outPack = gda
28  * outFile = Connection
29  * strct   = GdaConnection
30  * realStrct=
31  * ctorStrct=
32  * clss    = Connection
33  * interf  = 
34  * class Code: No
35  * interface Code: No
36  * template for:
37  * extend  = GObject
38  * implements:
39  * prefixes:
40  * 	- gda_connection_
41  * omit structs:
42  * omit prefixes:
43  * omit code:
44  * omit signals:
45  * imports:
46  * 	- glib.Str
47  * 	- glib.ListG
48  * 	- gda.Blob
49  * 	- gda.Client
50  * 	- gda.Command
51  * 	- gda.DataModel
52  * 	- gda.ErrorGda
53  * 	- gda.FieldAttributes
54  * 	- gda.ParameterList
55  * 	- gda.Transaction
56  * structWrap:
57  * 	- GList* -> ListG
58  * 	- GdaBlob* -> Blob
59  * 	- GdaClient* -> Client
60  * 	- GdaCommand* -> Command
61  * 	- GdaDataModel* -> DataModel
62  * 	- GdaError* -> ErrorGda
63  * 	- GdaFieldAttributes* -> FieldAttributes
64  * 	- GdaParameterList* -> ParameterList
65  * 	- GdaTransaction* -> Transaction
66  * module aliases:
67  * local aliases:
68  * overrides:
69  */
70 
71 module gda.Connection;
72 
73 public  import gdac.gdatypes;
74 
75 private import gdac.gda;
76 private import glib.ConstructionException;
77 private import gobject.ObjectG;
78 
79 private import glib.Str;
80 private import glib.ListG;
81 private import gda.Blob;
82 private import gda.Client;
83 private import gda.Command;
84 private import gda.DataModel;
85 private import gda.ErrorGda;
86 private import gda.FieldAttributes;
87 private import gda.ParameterList;
88 private import gda.Transaction;
89 
90 
91 private import gobject.ObjectG;
92 
93 /**
94  *  The GdaConnection class offers access to all operations involving an
95  *  opened connection to a database. GdaConnection objects are obtained
96  *  via the GdaClient class.
97  *
98  *  Once obtained, applications can use GdaConnection to execute commands,
99  *  run transactions, and get information about all objects stored in the
100  *  underlying database.
101  */
102 public class Connection : ObjectG
103 {
104 	
105 	/** the main Gtk struct */
106 	protected GdaConnection* gdaConnection;
107 	
108 	
109 	/** Get the main Gtk struct */
110 	public GdaConnection* getConnectionStruct()
111 	{
112 		return gdaConnection;
113 	}
114 	
115 	
116 	/** the main Gtk struct as a void* */
117 	protected override void* getStruct()
118 	{
119 		return cast(void*)gdaConnection;
120 	}
121 	
122 	/**
123 	 * Sets our main struct and passes it to the parent class
124 	 */
125 	public this (GdaConnection* gdaConnection)
126 	{
127 		super(cast(GObject*)gdaConnection);
128 		this.gdaConnection = gdaConnection;
129 	}
130 	
131 	protected override void setStruct(GObject* obj)
132 	{
133 		super.setStruct(obj);
134 		gdaConnection = cast(GdaConnection*)obj;
135 	}
136 	
137 	/**
138 	 */
139 	
140 	/**
141 	 * This function creates a new GdaConnection object. It is not
142 	 * intended to be used directly by applications (use
143 	 * gda_client_open_connection instead).
144 	 * Params:
145 	 * client = a GdaClient object.
146 	 * provider = a GdaServerProvider object.
147 	 * dsn = GDA data source to connect to.
148 	 * username = user name to use to connect.
149 	 * password = password for username.
150 	 * options = options for the connection.
151 	 * Throws: ConstructionException GTK+ fails to create the object.
152 	 */
153 	public this (Client client, GdaServerProvider* provider, string dsn, string username, string password, GdaConnectionOptions options)
154 	{
155 		// GdaConnection* gda_connection_new (GdaClient *client,  GdaServerProvider *provider,  const gchar *dsn,  const gchar *username,  const gchar *password,  GdaConnectionOptions options);
156 		auto p = gda_connection_new((client is null) ? null : client.getClientStruct(), provider, Str.toStringz(dsn), Str.toStringz(username), Str.toStringz(password), options);
157 		if(p is null)
158 		{
159 			throw new ConstructionException("null returned by gda_connection_new((client is null) ? null : client.getClientStruct(), provider, Str.toStringz(dsn), Str.toStringz(username), Str.toStringz(password), options)");
160 		}
161 		this(cast(GdaConnection*) p);
162 	}
163 	
164 	/**
165 	 * Closes the connection to the underlying data source. After calling this
166 	 * function, you should not use anymore the GdaConnection object, since
167 	 * it may have been destroyed.
168 	 * Returns: TRUE if successful, FALSE otherwise.
169 	 */
170 	public int close()
171 	{
172 		// gboolean gda_connection_close (GdaConnection *cnc);
173 		return gda_connection_close(gdaConnection);
174 	}
175 	
176 	/**
177 	 * Checks whether a connection is open or not.
178 	 * Returns: TRUE if the connection is open, FALSE if it's not.
179 	 */
180 	public int isOpen()
181 	{
182 		// gboolean gda_connection_is_open (GdaConnection *cnc);
183 		return gda_connection_is_open(gdaConnection);
184 	}
185 	
186 	/**
187 	 * Gets the GdaClient object associated with a connection. This
188 	 * is always the client that created the connection, as returned
189 	 * by gda_client_open_connection.
190 	 * Returns: the client to which the connection belongs to.
191 	 */
192 	public Client getClient()
193 	{
194 		// GdaClient* gda_connection_get_client (GdaConnection *cnc);
195 		auto p = gda_connection_get_client(gdaConnection);
196 		
197 		if(p is null)
198 		{
199 			return null;
200 		}
201 		
202 		return ObjectG.getDObject!(Client)(cast(GdaClient*) p);
203 	}
204 	
205 	/**
206 	 * Associates a GdaClient with this connection. This function is
207 	 * not intended to be called by applications.
208 	 * Params:
209 	 * client = a GdaClient object.
210 	 */
211 	public void setClient(Client client)
212 	{
213 		// void gda_connection_set_client (GdaConnection *cnc,  GdaClient *client);
214 		gda_connection_set_client(gdaConnection, (client is null) ? null : client.getClientStruct());
215 	}
216 	
217 	/**
218 	 * Gets the GdaConnectionOptions used to open this connection.
219 	 * Returns: the connection options.
220 	 */
221 	public GdaConnectionOptions getOptions()
222 	{
223 		// GdaConnectionOptions gda_connection_get_options (GdaConnection *cnc);
224 		return gda_connection_get_options(gdaConnection);
225 	}
226 	
227 	/**
228 	 * Gets the version string of the underlying database server.
229 	 * Returns: the server version string.
230 	 */
231 	public string getServerVersion()
232 	{
233 		// const gchar* gda_connection_get_server_version (GdaConnection *cnc);
234 		return Str.toString(gda_connection_get_server_version(gdaConnection));
235 	}
236 	
237 	/**
238 	 * Gets the name of the currently active database in the given
239 	 * GdaConnection.
240 	 * Returns: the name of the current database.
241 	 */
242 	public string getDatabase()
243 	{
244 		// const gchar* gda_connection_get_database (GdaConnection *cnc);
245 		return Str.toString(gda_connection_get_database(gdaConnection));
246 	}
247 	
248 	/**
249 	 * Returns: the data source name the connection object is connected to.
250 	 */
251 	public string getDsn()
252 	{
253 		// const gchar* gda_connection_get_dsn (GdaConnection *cnc);
254 		return Str.toString(gda_connection_get_dsn(gdaConnection));
255 	}
256 	
257 	/**
258 	 * Gets the connection string used to open this connection.
259 	 * The connection string is the string sent over to the underlying
260 	 * database provider, which describes the parameters to be used
261 	 * to open a connection on the underlying data source.
262 	 * Returns: the connection string used when opening the connection.
263 	 */
264 	public string getCncString()
265 	{
266 		// const gchar* gda_connection_get_cnc_string (GdaConnection *cnc);
267 		return Str.toString(gda_connection_get_cnc_string(gdaConnection));
268 	}
269 	
270 	/**
271 	 * Gets the provider id that this connection is connected to.
272 	 * Returns: the provider ID used to open this connection.
273 	 */
274 	public string getProvider()
275 	{
276 		// const gchar* gda_connection_get_provider (GdaConnection *cnc);
277 		return Str.toString(gda_connection_get_provider(gdaConnection));
278 	}
279 	
280 	/**
281 	 * Gets the user name used to open this connection.
282 	 * Returns: the user name.
283 	 */
284 	public string getUsername()
285 	{
286 		// const gchar* gda_connection_get_username (GdaConnection *cnc);
287 		return Str.toString(gda_connection_get_username(gdaConnection));
288 	}
289 	
290 	/**
291 	 * Gets the password used to open this connection.
292 	 * Returns: the password.
293 	 */
294 	public string getPassword()
295 	{
296 		// const gchar* gda_connection_get_password (GdaConnection *cnc);
297 		return Str.toString(gda_connection_get_password(gdaConnection));
298 	}
299 	
300 	/**
301 	 * Adds an error to the given connection. This function is usually
302 	 * called by providers, to inform clients of errors that happened
303 	 * during some operation.
304 	 * As soon as a provider (or a client, it does not matter) calls this
305 	 * function, the connection object (and the associated GdaClient object)
306 	 * emits the "error" signal, to which clients can connect to be
307 	 * informed of errors.
308 	 * Params:
309 	 * error = is stored internally, so you don't need to unref it.
310 	 */
311 	public void addError(ErrorGda error)
312 	{
313 		// void gda_connection_add_error (GdaConnection *cnc,  GdaError *error);
314 		gda_connection_add_error(gdaConnection, (error is null) ? null : error.getErrorGdaStruct());
315 	}
316 	
317 	/**
318 	 * This is just another convenience function which lets you add
319 	 * a list of GdaError's to the given connection. As with
320 	 * gda_connection_add_error and gda_connection_add_error_string,
321 	 * this function makes the connection object emit the "error"
322 	 * signal. The only difference is that, instead of a notification
323 	 * for each error, this function only does one notification for
324 	 * the whole list of errors.
325 	 * error_list is copied to an internal list and freed.
326 	 * Params:
327 	 * errorList = a list of GdaError.
328 	 */
329 	public void addErrorList(ListG errorList)
330 	{
331 		// void gda_connection_add_error_list (GdaConnection *cnc,  GList *error_list);
332 		gda_connection_add_error_list(gdaConnection, (errorList is null) ? null : errorList.getListGStruct());
333 	}
334 	
335 	/**
336 	 * Changes the current database for the given connection. This operation
337 	 * is not available in all providers.
338 	 * Params:
339 	 * name = name of database to switch to.
340 	 * Returns: TRUE if successful, FALSE otherwise.
341 	 */
342 	public int changeDatabase(string name)
343 	{
344 		// gboolean gda_connection_change_database (GdaConnection *cnc,  const gchar *name);
345 		return gda_connection_change_database(gdaConnection, Str.toStringz(name));
346 	}
347 	
348 	/**
349 	 * Creates a new database named name on the given connection.
350 	 * Params:
351 	 * name = database name.
352 	 * Returns: TRUE if successful, FALSE otherwise.
353 	 */
354 	public int createDatabase(string name)
355 	{
356 		// gboolean gda_connection_create_database (GdaConnection *cnc,  const gchar *name);
357 		return gda_connection_create_database(gdaConnection, Str.toStringz(name));
358 	}
359 	
360 	/**
361 	 * Drops a database from the given connection.
362 	 * Params:
363 	 * name = database name.
364 	 * Returns: TRUE if successful, FALSE otherwise.
365 	 */
366 	public int dropDatabase(string name)
367 	{
368 		// gboolean gda_connection_drop_database (GdaConnection *cnc,  const gchar *name);
369 		return gda_connection_drop_database(gdaConnection, Str.toStringz(name));
370 	}
371 	
372 	/**
373 	 * Creates a table on the given connection from the specified set of fields.
374 	 * Params:
375 	 * tableName = name of the table to be created.
376 	 * attributes = description of all fields for the new table.
377 	 * Returns: TRUE if successful, FALSE otherwise.
378 	 */
379 	public int createTable(string tableName, GdaFieldAttributes** attributes)
380 	{
381 		// gboolean gda_connection_create_table (GdaConnection *cnc,  const gchar *table_name,  const GdaFieldAttributes *attributes[]);
382 		return gda_connection_create_table(gdaConnection, Str.toStringz(tableName), attributes);
383 	}
384 	
385 	/**
386 	 * Drops a table from the database.
387 	 * Params:
388 	 * tableName = name of the table to be removed
389 	 * Returns: TRUE if successful, FALSE otherwise.
390 	 */
391 	public int dropTable(string tableName)
392 	{
393 		// gboolean gda_connection_drop_table (GdaConnection *cnc,  const gchar *table_name);
394 		return gda_connection_drop_table(gdaConnection, Str.toStringz(tableName));
395 	}
396 	
397 	/**
398 	 * Executes a command on the underlying data source.
399 	 * This function provides the way to send several commands
400 	 * at once to the data source being accessed by the given
401 	 * GdaConnection object. The GdaCommand specified can contain
402 	 * a list of commands in its "text" property (usually a set
403 	 * of SQL commands separated by ';').
404 	 * The return value is a GList of GdaDataModel's, which you
405 	 * are responsible to free when not needed anymore.
406 	 * Params:
407 	 * cmd = a GdaCommand.
408 	 * params = parameter list.
409 	 * Returns: a list of GdaDataModel's, as returned by the underlying provider.
410 	 */
411 	public ListG executeCommand(Command cmd, ParameterList params)
412 	{
413 		// GList* gda_connection_execute_command (GdaConnection *cnc,  GdaCommand *cmd,  GdaParameterList *params);
414 		auto p = gda_connection_execute_command(gdaConnection, (cmd is null) ? null : cmd.getCommandStruct(), (params is null) ? null : params.getParameterListStruct());
415 		
416 		if(p is null)
417 		{
418 			return null;
419 		}
420 		
421 		return ObjectG.getDObject!(ListG)(cast(GList*) p);
422 	}
423 	
424 	/**
425 	 * Retrieve from the given GdaConnection the ID of the last inserted row.
426 	 * A connection must be specified, and, optionally, a result set. If not NULL,
427 	 * the underlying provider should try to get the last insert ID for the given result set.
428 	 * Params:
429 	 * recset = recordset.
430 	 * Returns: a string representing the ID of the last inserted row, or NULL if an error occurred or no row has been inserted. It is the caller's reponsibility to free the returned string.
431 	 */
432 	public string getLastInsertId(DataModel recset)
433 	{
434 		// gchar* gda_connection_get_last_insert_id (GdaConnection *cnc,  GdaDataModel *recset);
435 		return Str.toString(gda_connection_get_last_insert_id(gdaConnection, (recset is null) ? null : recset.getDataModelStruct()));
436 	}
437 	
438 	/**
439 	 * Executes a single command on the given connection.
440 	 * This function lets you retrieve a simple data model from
441 	 * the underlying difference, instead of having to retrieve
442 	 * a list of them, as is the case with gda_connection_execute_command.
443 	 * Params:
444 	 * cmd = a GdaCommand.
445 	 * params = parameter list.
446 	 * Returns: a GdaDataModel containing the data returned by the data source, or NULL on error.
447 	 */
448 	public DataModel executeSingleCommand(Command cmd, ParameterList params)
449 	{
450 		// GdaDataModel* gda_connection_execute_single_command  (GdaConnection *cnc,  GdaCommand *cmd,  GdaParameterList *params);
451 		auto p = gda_connection_execute_single_command(gdaConnection, (cmd is null) ? null : cmd.getCommandStruct(), (params is null) ? null : params.getParameterListStruct());
452 		
453 		if(p is null)
454 		{
455 			return null;
456 		}
457 		
458 		return ObjectG.getDObject!(DataModel)(cast(GdaDataModel*) p);
459 	}
460 	
461 	/**
462 	 * Executes a single command on the underlying database, and gets the
463 	 * number of rows affected.
464 	 * Params:
465 	 * cmd = a GdaCommand.
466 	 * params = parameter list.
467 	 * Returns: the number of affected rows by the executed command, or -1 on error.
468 	 */
469 	public int executeNonQuery(Command cmd, ParameterList params)
470 	{
471 		// gint gda_connection_execute_non_query (GdaConnection *cnc,  GdaCommand *cmd,  GdaParameterList *params);
472 		return gda_connection_execute_non_query(gdaConnection, (cmd is null) ? null : cmd.getCommandStruct(), (params is null) ? null : params.getParameterListStruct());
473 	}
474 	
475 	/**
476 	 * Starts a transaction on the data source, identified by the
477 	 * xaction parameter.
478 	 * Before starting a transaction, you can check whether the underlying
479 	 * provider does support transactions or not by using the
480 	 * gda_connection_supports function.
481 	 * Params:
482 	 * xaction = a GdaTransaction object.
483 	 * Returns: TRUE if the transaction was started successfully, FALSE otherwise.
484 	 */
485 	public int beginTransaction(Transaction xaction)
486 	{
487 		// gboolean gda_connection_begin_transaction (GdaConnection *cnc,  GdaTransaction *xaction);
488 		return gda_connection_begin_transaction(gdaConnection, (xaction is null) ? null : xaction.getTransactionStruct());
489 	}
490 	
491 	/**
492 	 * Commits the given transaction to the backend database. You need to do
493 	 * gda_connection_begin_transaction() first.
494 	 * Params:
495 	 * xaction = a GdaTransaction object.
496 	 * Returns: TRUE if the transaction was finished successfully, FALSE otherwise.
497 	 */
498 	public int commitTransaction(Transaction xaction)
499 	{
500 		// gboolean gda_connection_commit_transaction (GdaConnection *cnc,  GdaTransaction *xaction);
501 		return gda_connection_commit_transaction(gdaConnection, (xaction is null) ? null : xaction.getTransactionStruct());
502 	}
503 	
504 	/**
505 	 * Rollbacks the given transaction. This means that all changes
506 	 * made to the underlying data source since the last call to
507 	 * gda_connection_begin_transaction or gda_connection_commit_transaction
508 	 * will be discarded.
509 	 * Params:
510 	 * xaction = a GdaTransaction object.
511 	 * Returns: TRUE if the operation was successful, FALSE otherwise.
512 	 */
513 	public int rollbackTransaction(Transaction xaction)
514 	{
515 		// gboolean gda_connection_rollback_transaction (GdaConnection *cnc,  GdaTransaction *xaction);
516 		return gda_connection_rollback_transaction(gdaConnection, (xaction is null) ? null : xaction.getTransactionStruct());
517 	}
518 	
519 	/**
520 	 * Creates a BLOB (Binary Large OBject) with read/write access.
521 	 * Params:
522 	 * blob = a user-allocated GdaBlob structure.
523 	 * Returns: FALSE if the database does not support BLOBs. TRUE otherwise and the GdaBlob is created and ready to be used.
524 	 */
525 	public int createBlob(Blob blob)
526 	{
527 		// gboolean gda_connection_create_blob (GdaConnection *cnc,  GdaBlob *blob);
528 		return gda_connection_create_blob(gdaConnection, (blob is null) ? null : blob.getBlobStruct());
529 	}
530 	
531 	/**
532 	 * Retrieves a list of the last errors ocurred in the connection.
533 	 * You can make a copy of the list using gda_error_list_copy.
534 	 * Returns: a GList of GdaError.
535 	 */
536 	public ListG getErrors()
537 	{
538 		// const GList* gda_connection_get_errors (GdaConnection *cnc);
539 		auto p = gda_connection_get_errors(gdaConnection);
540 		
541 		if(p is null)
542 		{
543 			return null;
544 		}
545 		
546 		return ObjectG.getDObject!(ListG)(cast(GList*) p);
547 	}
548 	
549 	/**
550 	 * Asks the underlying provider for if a specific feature is supported.
551 	 * Params:
552 	 * feature = feature to ask for.
553 	 * Returns: TRUE if the provider supports it, FALSE if not.
554 	 */
555 	public int supports(GdaConnectionFeature feature)
556 	{
557 		// gboolean gda_connection_supports (GdaConnection *cnc,  GdaConnectionFeature feature);
558 		return gda_connection_supports(gdaConnection, feature);
559 	}
560 	
561 	/**
562 	 * Asks the underlying data source for a list of database objects.
563 	 * This is the function that lets applications ask the different
564 	 * providers about all their database objects (tables, views, procedures,
565 	 * etc). The set of database objects that are retrieved are given by the
566 	 * 2 parameters of this function: schema, which specifies the specific
567 	 * schema required, and params, which is a list of parameters that can
568 	 * be used to give more detail about the objects to be returned.
569 	 * The list of parameters is specific to each schema type.
570 	 * Params:
571 	 * schema = database schema to get.
572 	 * params = parameter list.
573 	 * Returns: a GdaDataModel containing the data required. The caller is responsible of freeing the returned model.
574 	 */
575 	public DataModel getSchema(GdaConnectionSchema schema, ParameterList params)
576 	{
577 		// GdaDataModel* gda_connection_get_schema (GdaConnection *cnc,  GdaConnectionSchema schema,  GdaParameterList *params);
578 		auto p = gda_connection_get_schema(gdaConnection, schema, (params is null) ? null : params.getParameterListStruct());
579 		
580 		if(p is null)
581 		{
582 			return null;
583 		}
584 		
585 		return ObjectG.getDObject!(DataModel)(cast(GdaDataModel*) p);
586 	}
587 }