[libgda: 4/5] GdaConnection: New API added

[Daniel Espinosa Ortiz <despinosa src gnome org>]

commit f1ae596cd56c7f32600eb43cb5d45cd933a16389
Author: Pavlo Solntsev <p sun fun gmail com>
Date:   Wed Feb 13 22:28:05 2019 -0600

    GdaConnection: New API added
    
     - gda_connection_new_from_dsn was renamed to ..._from_dsn_name
     - gda_connection_open_from_dsn was renamed to ..._from_dsn_name
     - additional formatting around those functions

 libgda/gda-connection.c | 160 ++++++++++++++++++++++++++++++++++++++++--------
 libgda/gda-connection.h |  29 +++++++--
 2 files changed, 158 insertions(+), 31 deletions(-)
---
diff --git a/libgda/gda-connection.c b/libgda/gda-connection.c
index e45b48f10..568e91fe5 100644
--- a/libgda/gda-connection.c
+++ b/libgda/gda-connection.c
@@ -897,13 +897,13 @@ merge_column_types (const GType *struct_types, const GType *user_types)
 }
 
 /**
- * gda_connection_new_from_dsn:
- * @dsn: data source name.
+ * gda_connection_new_from_dsn_name:
+ * @dsn_name: data source name.
  * @auth_string: (nullable): authentication string, or %NULL
  * @options: options for the connection (see #GdaConnectionOptions).
  * @error: a place to store an error, or %NULL
  *
- * This function creates a new function, using a pre-defined data source (DSN),
+ * This function creates a new function, using a pre-defined data source (DSN) name,
  * see gda_config_define_dsn() for more information about how to define a DSN. If you don't want to define
  * a DSN, it is possible to use gda_connection_new_from_string() instead of this method.
  *
@@ -913,41 +913,44 @@ merge_column_types (const GType *struct_types, const GType *user_types)
  * must be encoded as per RFC 1738, see gda_rfc1738_encode() for more information.
  *
  * The @auth_string can contain the authentication information for the server
- * to accept the connection. It is a string containing semi-colon seperated named value, usually 
+ * to accept the connection. It is a string containing semi-colon separated named value, 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 gda_rfc1738_encode() for more information.
  *
  * The actual named parameters required depend on the provider being used, and that list is available
  * as the <parameter>auth_params</parameter> member of the #GdaProviderInfo structure for each installed
- * provider (use gda_config_get_provider_info() to get it). Also one can use the "gda-sql-6.0 -L" command to 
- * list the possible named parameters.
+ * provider (use gda_config_get_provider_info() to get it). Also one can use the "gda-sql-6.0 -L" command
+ * to list the possible named parameters.
  *
- * This method may fail with a GDA_CONNECTION_ERROR domain error (see the #GdaConnectionError error codes) 
+ * This method may fail with a GDA_CONNECTION_ERROR domain error (see the #GdaConnectionError error codes)
  * or a %GDA_CONFIG_ERROR domain error (see the #GdaConfigError error codes).
  *
  * The returned connection is not yet opened, you need to call gda_connection_open() or 
gda_connection_open_async().
  *
  * Returns: (transfer full): a new #GdaConnection or %NULL if there was an error.
  *
- * Since: 5.0.2
+ * Since: 6.0
  */
 GdaConnection *
-gda_connection_new_from_dsn (const gchar *dsn, const gchar *auth_string, 
-                            GdaConnectionOptions options, GError **error)
+gda_connection_new_from_dsn_name (const gchar *dsn_name,
+                                  const gchar *auth_string,
+                                  GdaConnectionOptions options,
+                                  GError **error)
 {
        GdaConnection *cnc = NULL;
        GdaDsnInfo *dsn_info;
        gchar *user, *pass, *real_dsn;
        gchar *real_auth_string = NULL;
 
-       g_return_val_if_fail (dsn && *dsn, NULL);
+       g_return_val_if_fail (dsn_name && *dsn_name, NULL);
+  g_return_val_if_fail (error == NULL || *error != NULL, NULL);
 
-       gda_dsn_split (dsn, &real_dsn, &user, &pass);
+       gda_dsn_split (dsn_name, &real_dsn, &user, &pass);
        if (!real_dsn) {
                g_free (user);
                g_free (pass);
                g_set_error (error, GDA_CONNECTION_ERROR, GDA_CONNECTION_DSN_NOT_FOUND_ERROR, 
-                            _("Malformed data source specification '%s'"), dsn);
+                            _("Malformed data source specification '%s'"), dsn_name);
                return NULL;
        }
 
@@ -986,7 +989,7 @@ gda_connection_new_from_dsn (const gchar *dsn, const gchar *auth_string,
                else
                        g_set_error (error, GDA_CONFIG_ERROR, GDA_CONFIG_PROVIDER_NOT_FOUND_ERROR,
                                     _("No provider '%s' installed"), dsn_info->provider);
-               
+
                if (prov)
                        cnc = _gda_server_provider_create_connection (prov, real_dsn, NULL,
                                                                      auth_string ? auth_string : 
real_auth_string,
@@ -1004,30 +1007,137 @@ gda_connection_new_from_dsn (const gchar *dsn, const gchar *auth_string,
 }
 
 /**
- * gda_connection_open_from_dsn:
+ * gda_connection_new_from_dsn:
  * @dsn: data source name.
  * @auth_string: (nullable): authentication string, or %NULL
  * @options: options for the connection (see #GdaConnectionOptions).
  * @error: a place to store an error, or %NULL
  *
+ * This function creates a new connection, using a pre-defined data source (DSN), see
+ * gda_config_define_dsn() for more information about how to define a DSN. If you don't want to
+ * define a DSN, it is possible to use gda_connection_new_from_string() instead of this method.
+ *
+ * The @auth_string can contain the authentication information for the server
+ * to accept the connection. It is a string containing semi-colon seperated named value, 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 gda_rfc1738_encode() for more information.
+ *
+ * If @auth_string is given, it wil be used, otherwise auth_string of #GdaDsnInfo will be used.
+ *
+ * The actual named parameters required depend on the provider being used, and that list is available
+ * as the <parameter>auth_params</parameter> member of the #GdaProviderInfo structure for each installed
+ * provider (use gda_config_get_provider_info() to get it). Also one can use the "gda-sql-6.0 -L" command
+ * to list the possible named parameters.
+ *
+ * This method may fail with a GDA_CONNECTION_ERROR domain error (see the #GdaConnectionError error codes)
+ * or a %GDA_CONFIG_ERROR domain error (see the #GdaConfigError error codes).
+ *
+ * The returned connection is not yet opened, you need to call gda_connection_open() or 
gda_connection_open_async().
+ *
+ * Returns: (transfer full): a new #GdaConnection or %NULL if there was an error.
+ *
+ * Since: 6.0
+ */
+GdaConnection *
+gda_connection_new_from_dsn (GdaDsnInfo *dsn,
+                             const gchar *auth_string,
+                             GdaConnectionOptions options,
+                             GError **error)
+{
+  GdaConnection *cnc = NULL;
+
+  g_return_val_if_fail (dsn, NULL);
+  g_return_val_if_fail (dsn->cnc_string, NULL);
+  g_return_val_if_fail (error == NULL || *error != NULL, NULL);
+
+/* try to find provider */
+  if (!dsn->provider)
+   {
+      GdaProviderInfo *pinfo = NULL;
+      GdaServerProvider *prov = NULL;
+
+      pinfo = gda_config_get_provider_info (dsn->provider);
+      if (pinfo)
+        prov = gda_config_get_provider (dsn->provider, error);
+      else
+        g_set_error (error, GDA_CONFIG_ERROR, GDA_CONFIG_PROVIDER_NOT_FOUND_ERROR,
+                     _("No provider '%s' installed"), dsn->provider);
+
+      if (prov)
+        cnc = _gda_server_provider_create_connection (prov, NULL, dsn->cnc_string,
+                                                      auth_string ? auth_string : dsn->auth_string,
+                                                      options);
+    }
+  else
+    g_set_error (error, GDA_CONNECTION_ERROR, GDA_CONNECTION_PROVIDER_NOT_FOUND_ERROR,
+                 "%s", _("Datasource configuration error: no provider specified"));
+
+  return cnc;
+}
+
+/**
+ * gda_connection_open_from_dsn_name:
+ * @dsn_name: data source name.
+ * @auth_string: (nullable): authentication string, or %NULL
+ * @options: options for the connection (see #GdaConnectionOptions).
+ * @error: a place to store an error, or %NULL
+ *
+ * This function creates a connection and opens it, using a DSN name. If opening fails, then no connection 
is created. The named DSN should be available.
+ * See gda_connection_new_from_dsn_name() for more information.
+ *
+ * Returns: (transfer full): a new #GdaConnection if connection opening was successful or %NULL if there was 
an error.
+ */
+GdaConnection *
+gda_connection_open_from_dsn_name (const gchar *dsn_name,
+                                   const gchar *auth_string,
+                                   GdaConnectionOptions options,
+                                   GError **error)
+{
+  GdaConnection *cnc = NULL;
+
+  g_return_val_if_fail (dsn_name && *dsn_name, NULL);
+  g_return_val_if_fail (error == NULL || *error != NULL, NULL);
+
+  cnc = gda_connection_new_from_dsn_name (dsn_name, auth_string, options, error);
+
+  if (cnc && !gda_connection_open (cnc, error))
+    g_clear_object (&cnc);
+
+  return cnc;
+}
+
+/**
+ * gda_connection_open_from_dsn:
+ * @dsn_name: data sourcename.
+ * @auth_string: (nullable): authentication string, or %NULL
+ * @options: options for the connection (see #GdaConnectionOptions).
+ * @error: a place to store an error, or %NULL
+ *
  * This function creates a connection and opens it, using a DSN. If opening fails, then no connection is 
created.
  * See gda_connection_new_from_dsn() for more information.
  *
  * Returns: (transfer full): a new #GdaConnection if connection opening was successful or %NULL if there was 
an error.
+ * Since: 6.0
  */
 GdaConnection *
-gda_connection_open_from_dsn (const gchar *dsn, const gchar *auth_string,
-                             GdaConnectionOptions options, GError **error)
+gda_connection_open_from_dsn (GdaDsnInfo *dsn,
+                              const gchar *auth_string,
+                              GdaConnectionOptions options,
+                              GError **error)
 {
-       GdaConnection *cnc;
-       cnc = gda_connection_new_from_dsn (dsn, auth_string, options, error);
-       if (cnc && !gda_connection_open (cnc, error)) {
-               g_object_unref (cnc);
-               cnc = NULL;
-       }
-       return cnc;
-}
+  GdaConnection *cnc = NULL;
 
+  g_return_val_if_fail (dsn, NULL);
+  g_return_val_if_fail (dsn->cnc_string, NULL);
+  g_return_val_if_fail (error == NULL || *error != NULL, NULL);
+
+  cnc = gda_connection_new_from_dsn (dsn, auth_string, options, error);
+
+  if (cnc && !gda_connection_open (cnc, error))
+    g_clear_object (&cnc);
+
+  return cnc;
+}
 
 /**
  * gda_connection_new_from_string:
diff --git a/libgda/gda-connection.h b/libgda/gda-connection.h
index 66a4c6f3b..92104ead9 100644
--- a/libgda/gda-connection.h
+++ b/libgda/gda-connection.h
@@ -42,6 +42,7 @@
 #include <libgda/gda-server-operation.h>
 #include <libgda/gda-batch.h>
 #include <libgda/gda-db-catalog.h>
+#include <libgda/gda-config.h>
 
 G_BEGIN_DECLS
 
@@ -62,13 +63,14 @@ typedef enum {
        GDA_CONNECTION_OPEN_ERROR,
        GDA_CONNECTION_ALREADY_OPENED_ERROR,
        GDA_CONNECTION_STATEMENT_TYPE_ERROR,
-       GDA_CONNECTION_CANT_LOCK_ERROR,
+  GDA_CONNECTION_CANT_LOCK_ERROR,
        GDA_CONNECTION_TASK_NOT_FOUND_ERROR,
        GDA_CONNECTION_CLOSED_ERROR,
        GDA_CONNECTION_META_DATA_CONTEXT_ERROR,
        GDA_CONNECTION_NO_MAIN_CONTEXT_ERROR
 } GdaConnectionError;
 
+
 #define GDA_CONNECTION_NONEXIST_DSN_ERROR GDA_CONNECTION_DSN_NOT_FOUND_ERROR
 
 /**
@@ -147,7 +149,7 @@ struct _GdaConnectionClass {
  * @GDA_CONNECTION_OPTIONS_READ_ONLY: this flag specifies that the connection to open should be in a 
read-only mode
  *                                    (this policy is not correctly enforced at the moment)
  * @GDA_CONNECTION_OPTIONS_SQL_IDENTIFIERS_CASE_SENSITIVE: this flag specifies that SQL identifiers 
submitted as input
- *                                    to Libgda have to keep their case sensitivity. 
+                                     to Libgda have to keep their case sensitivity. 
  * @GDA_CONNECTION_OPTIONS_AUTO_META_DATA: this flags specifies that if a #GdaMetaStore has been associated
  *                                     to the connection, then it is kept up to date with the evolutions in 
the
  *                                     database's structure. Be aware however that there are some drawbacks
@@ -258,13 +260,28 @@ typedef enum {
 } GdaConnectionMetaType;
 
 
-GdaConnection       *gda_connection_open_from_dsn        (const gchar *dsn, const gchar *auth_string,
-                                                         GdaConnectionOptions options, GError **error);
+GdaConnection       *gda_connection_open_from_dsn_name   (const gchar *dsn,
+                                                          const gchar *auth_string,
+                                                          GdaConnectionOptions options,
+                                                          GError **error);
+
+GdaConnection       *gda_connection_open_from_dsn        (GdaDsnInfo *dsn,
+                                                          const gchar *auth_string,
+                                                          GdaConnectionOptions options,
+                                                          GError **error);
 GdaConnection       *gda_connection_open_from_string     (const gchar *provider_name,
                                                          const gchar *cnc_string, const gchar *auth_string,
                                                          GdaConnectionOptions options, GError **error);
-GdaConnection       *gda_connection_new_from_dsn         (const gchar *dsn, const gchar *auth_string,
-                                                         GdaConnectionOptions options, GError **error);
+GdaConnection       *gda_connection_new_from_dsn_name     (const gchar *dsn_name,
+                                                           const gchar *auth_string,
+                                                           GdaConnectionOptions options,
+                                                           GError **error);
+
+GdaConnection       *gda_connection_new_from_dsn          (GdaDsnInfo *dsn,
+                                                           const gchar *auth_string,
+                                                           GdaConnectionOptions options,
+                                                           GError **error);
+
 GdaConnection       *gda_connection_new_from_string      (const gchar *provider_name, 
                                                          const gchar *cnc_string, const gchar *auth_string,
                                                          GdaConnectionOptions options, GError **error);