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