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 }