Opens a connection given a provider ID and a connection string.
This allows applications to open connections without having to create a data source (DSN) in the configuration. The format of
cnc_string is similar to PostgreSQL and MySQL connection strings. It is a semicolumn-separated series of <key>=<value
> pairs, where each key and value are encoded as per RFC 1738, see rfc1738_encode
for more information.
The possible keys depend on the provider, the "gda-sql-5.0 -L" command can be used to list the actual keys for each installed database provider.
For example the connection string to open an SQLite connection to a database file named "my_data.db" in the current directory would be
"DB_DIR=.;DB_NAME=my_data".
The cnc_string string must have the following format: "[<provider>://][<username>[:<password>]@]<
connection_params>" (if <username> and/or <password> are provided, and auth_string is null, then
these username and passwords will be used, and if <provider> is provided and provider_name is null then
this provider will be used). Note that if provided, <username>, <password> and <provider> must be encoded as per RFC
1738, see rfc1738_encode for more information.
The auth_string must contain the authentication information for the server to accept the connection. It is a string
containing semi-colon seperated named values, usually like "USERNAME=...;PASSWORD=..." where the ... are replaced by actual values. Note
that each name and value must be encoded as per RFC 1738, see rfc1738_encode for more
information.
The actual named parameters required depend on the provider being used, and that list is available as the auth_params member
of the ProviderInfo structure for each installed provider (use
get_provider_info to get it). Similarly to the format of the
connection string, use the "gda-sql-5.0 -L" command to list the possible named parameters.
Additionally, it is possible to have the connection string respect the "<provider_name>://<real cnc string>" format, in which
case the provider name and the real connection string will be extracted from that string (note that if provider_name is not
null then it will still be used as the provider ID).\
This method may fail with a GDA_CONNECTION_ERROR domain error (see the ConnectionError error codes) or a ConfigError domain error (see the ConfigError error codes).
| provider_name |
provider ID to connect to, or |
| cnc_string |
connection string. |
| auth_string |
authentication string, or |
| options |
options for the connection (see ConnectionOptions). |
|
a new Connection if connection opening was successful or |