WL#9970 (Core SSL options) Documentation.

Author: rsomla1

include/mysql_devapi.h

@@ -271,7 +271,7 @@ class ViewDefinedAs
      Specify table select operation for which the view is created.
 
      @note In situations where select statement is modified after
-     passing it to definedAs() method, later changes do not afffect
+     passing it to definedAs() method, later changes do not affect
      view definition which uses the state of the statement at the time
      of definedAs() call.
   */
@@ -324,7 +324,7 @@ class ViewSecurity
 public:
 
   /**
-    Specify security characteristisc of a view.
+    Specify security characteristics of a view.
 
     @see https://dev.mysql.com/doc/refman/5.7/en/stored-programs-security.html
   */
@@ -363,8 +363,9 @@ class ViewAlgorithm
 
 
 /*
-  Base blass for Create/Alter View
+  Base class for Create/Alter View
 */
+
 template <class Op>
 class View_base
   : public ViewAlgorithm<Op>
@@ -887,26 +888,51 @@ class PUBLIC_API Table
   Represents session options to be passed at XSession/NodeSession object
   creation.
 
-  SessionSettings can be constructed using uri, common connect options (host,
-  port, user, password, database) or using pairs of SessionSettings::Options -
-  Value objects.
+  SessionSettings can be constructed using URL string, common connect options
+  (host, port, user, password, database) or with a list
+  of `SessionSettings::Options` constants followed by option value (unless
+  given option has no value, like `SSL_ENABLE`).
+
+  Examples:
+  ~~~~~~
+
+    SessionSettings from_url(http://github.com/"mysqlx://user:pwd@host:port/db?ssl-enable");
+
+    SessionSettings from_options("host", port, "user", "pwd", "db");
+
+    SessionSettings from_option_list(
+      SessionSettings::USER, "user",
+      SessionSettings::PWD,  "pwd",
+      SessionSettings::HOST, "host",
+      SessionSettings::PORT, port,
+      SessionSettings::DB,   "db",
+      SessionSettings::SSL_ENABLE
+    );
+  ~~~~~~
 
   @ingroup devapi
 */
 
 class PUBLIC_API SessionSettings
 {
 public:
+
+  /**
+    Session creation options
+
+    @note Specifying `SSL_CA` option implies `SSL_ENABLE`.
+  */
+
   enum Options
   {
-    URI,
-    HOST,
-    PORT,
-    USER,
-    PWD,
-    DB,
-    SSL_ENABLE,
-    SSL_CA
+    URI,          //!< connection URI or string
+    HOST,         //!< host name or IP address
+    PORT,         //!< X Plugin port to connect to
+    USER,         //!< user name
+    PWD,          //!< password
+    DB,           //!< default database
+    SSL_ENABLE,   //!< use TLS connection
+    SSL_CA        //!< path to a PEM file specifying trusted root certificates
   };
 
 
@@ -922,6 +948,19 @@ class PUBLIC_API SessionSettings
   {}
 
 
+  /**
+    Create a session using connection string or URL.
+
+    Connection sting has the form `"user:pass\@host:port/?option&option"`,
+    valid URL is like a connection string with a `mysqlx://` prefix. Possible
+    connection options are:
+
+    - `ssl-enable` : use TLS connection
+    - `ssl-ca=`<path> : path to a PEM file specifying trusted root certificates
+
+    Specifying `ssl-ca` option implies `ssl-enable`.
+  */
+
   SessionSettings(const string &uri)
   {
     add(URI, uri);
@@ -930,6 +969,9 @@ class PUBLIC_API SessionSettings
 
   /**
     Create session explicitly specifying session parameters.
+
+    @note Session settings constructed this way request an SSL connection
+    by default.
   */
 
   SessionSettings(const std::string &host, unsigned port,
@@ -956,9 +998,12 @@ class PUBLIC_API SessionSettings
     : SessionSettings(host, port, user, pwd.c_str(), db)
   {}
 
-      /**
-        Create session using the default port
-      */
+  /**
+    Create session using the default port
+
+    @note Session settings constructed this way request an SSL connection
+    by default.
+  */
 
   SessionSettings(const std::string &host,
                   const string  &user,
@@ -974,9 +1019,12 @@ class PUBLIC_API SessionSettings
     : SessionSettings(host, DEFAULT_MYSQLX_PORT, user, pwd, db)
   {}
 
-      /**
-        Create session on localhost.
-      */
+  /**
+    Create session on localhost.
+
+    @note Session settings constructed this way request an SSL connection
+    by default.
+  */
 
   SessionSettings(unsigned port,
                   const string  &user,
@@ -1054,7 +1102,25 @@ class PUBLIC_API SessionSettings
 
 
   /**
-    Passing option - value pairs
+    Create session using a list of session options.
+
+    The list of options consist of `SessionSettings::Options` constant
+    identifying the option to set, followed by option value (unless
+    not required, as in the case of `SSL_ENABLE`).
+
+    Example:
+    ~~~~~~
+      SessionSettings from_option_list(
+        SessionSettings::USER, "user",
+        SessionSettings::PWD,  "pwd",
+        SessionSettings::HOST, "host",
+        SessionSettings::PORT, port,
+        SessionSettings::DB,   "db",
+        SessionSettings::SSL_ENABLE
+      );
+    ~~~~~~
+
+    @see `SessionSettings::Options`.
   */
 
   template <typename V,typename...R>
@@ -1155,14 +1221,6 @@ namespace internal {
 
   public:
 
-    /**
-      Create session specified by mysqlx connection string.
-
-      Connection string can be either an utf8 encoded single-byte
-      string or a wide string (which is converted to utf8 before
-      parsing).
-    */
-
     XSession_base(SessionSettings settings);
 
     template<typename...T>
@@ -1303,11 +1361,42 @@ class PUBLIC_API XSession
 
 public:
 
+  /**
+    Create session specified by `SessionSettings` object.
+  */
+
   XSession(SessionSettings settings)
     : XSession_base(settings)
   {}
 
 
+  /**
+    Create session using given session settings.
+
+    This constructor forwards arguments to a `SessionSettings` constructor.
+    Thus all forms of specifying session options are also directly available
+    in `XSession` constructor.
+
+    Examples:
+    ~~~~~~
+
+      XSession from_uri("mysqlx://user:pwd@host:port/db?ssl-enable");
+
+      XSession from_options("host", port, "user", "pwd", "db");
+
+      XSession from_option_list(
+        SessionSettings::USER, "user",
+        SessionSettings::PWD,  "pwd",
+        SessionSettings::HOST, "host",
+        SessionSettings::PORT, port,
+        SessionSettings::DB,   "db",
+        SessionSettings::SSL_ENABLE
+      );
+    ~~~~~~
+
+    @see `SessionSettings`
+  */
+
   template<typename...T>
   XSession(T...options)
     : XSession_base(SessionSettings(options...))

include/mysql_xapi.h

@@ -106,7 +106,7 @@ typedef object_id* MYSQLX_GUID;
 /**
   Return value flag indicating that the last reading operation
   did not finish reading to the end and there is still more data
-  to be fetched by functions suchs as mysqlx_get_bytes()
+  to be fetched by functions such as mysqlx_get_bytes()
 */
 
 #define RESULT_MORE_DATA 8
@@ -331,17 +331,18 @@ typedef enum mysqlx_sort_direction_enum
   Session options for use with `mysqlx_session_option_get()`
   and `mysqlx_session_option_set()` functions.
 
-  TODO: Document the options and what data they expect
+  @note Specifying `MYSQLX_OPT_SSL_CA` option implies `MYSQLX_OPT_SSL_ENABLE`.
 */
 
 typedef enum mysqlx_opt_type_enum
 {
-  MYSQLX_OPT_HOST = 1,
-  MYSQLX_OPT_PORT = 2,
-  MYSQLX_OPT_USER = 3,
-  MYSQLX_OPT_PWD = 4,
-  MYSQLX_OPT_DB = 5,
-  MYSQLX_OPT_SSL_ENABLE = 6,
+  MYSQLX_OPT_HOST = 1,        /**< host name or IP address */
+  MYSQLX_OPT_PORT = 2,        /**< X Plugin port to connect to */
+  MYSQLX_OPT_USER = 3,        /**< user name */
+  MYSQLX_OPT_PWD = 4,         /**< password */
+  MYSQLX_OPT_DB = 5,          /**< default database */
+  MYSQLX_OPT_SSL_ENABLE = 6,  /**< use TLS connection */
+  /** path to a PEM file specifying trusted root certificates */
   MYSQLX_OPT_SSL_CA = 7,
 }
 mysqlx_opt_type_t;
@@ -427,13 +428,19 @@ mysqlx_get_session(const char *host, int port, const char *user,
 /**
   Create a session using connection string or URL.
 
-  Connection sting has the form `"user:pass\@host:port/?option"`, valid URL
-  is like a connection string with a `mysqlx://` prefix.
+  Connection sting has the form `"user:pass\@host:port/?option&option"`,
+  valid URL is like a connection string with a `mysqlx://` prefix. Possible
+  connection options are:
 
-  @param conn_string character connection string
+  - `ssl-enable` : use TLS connection
+  - `ssl-ca=`<path> : path to a PEM file specifying trusted root certificates
+
+  Specifying `ssl-ca` option implies `ssl-enable`.
+
+  @param conn_string    connection string
   @param[out] out_error if error happens during connect the error message
                         is returned through this parameter
-  @param[out] err_code if error happens during connect the error code
+  @param[out] err_code  if error happens during connect the error code
                         is returned through this parameter
 
   @return session handle if session could be created, otherwise NULL
@@ -2895,7 +2902,7 @@ mysqlx_result_next_warning(mysqlx_result_t *res);
   The order of parameters in the list is not fixed, but if
   `VIEW_COLUMNS()` (`VIEW_OPTION_COLUMNS`) is used it must be the
   last parameter before terminating the list with `PARAM_END`. See documentation
-  of the convenience macros for more details on possible vuew definition
+  of the convenience macros for more details on possible view definition
   options
 
 
@@ -2911,7 +2918,7 @@ mysqlx_view_create(mysqlx_schema_t *schema, const char *name,
 
 
 /**
-  Return a new statement which careates a view
+  Return a new statement which creates a view
 
   Creates a statement which will be used for creating a new view
   in a given schema based on a previously defined select statement. Before