Merge lp:~linuxjedi/libdrizzle/5.1-docs2 into lp:libdrizzle

[Andrew Hutchings]

Documentation updates for the API changes made in Seattle

=== modified file 'docs/api/connection.rst'
--- docs/api/connection.rst	2013-01-28 01:43:28 +0000
+++ docs/api/connection.rst	2013-02-07 16:43:36 +0000
@@ -13,30 +13,26 @@
 
    The internal drizzle connection object struct
 
+.. c:type:: drizzle_options_st
+
+   The internal structure containing connection options
+
 Functions
 ---------
 
-.. c:function:: drizzle_st* drizzle_create_tcp(const char *host, in_port_t port, const char *user, const char *password, const char *db, drizzle_options_t options)
-
-   Creates a TCP/IP connection connection object
-
-   :param host: The hostname or IP of the server
-   :param port: The port number of the server
-   :param user: The username of the server
-   :param password: The password of the server
-   :param db: The default DB to connect to on the server
-   :param options: The connection options to set
-   :returns: A newly allocated and setup connection object
-
-.. c:function:: drizzle_st* drizzle_create_uds(const char *uds, const char *user, const char *password, const char *db, drizzle_options_t options)
-
-   Creates a Unix Domain Socket connection object
-
-   :param uds: The path of the UDS file
-   :param user: The username of the server
-   :param password: The password of the server
-   :param db: The default DB to connect to on the server
-   :param options: The connection options to set
+.. c:function:: drizzle_st* drizzle_create(const char *host, in_port_t port, const char *user, const char *password, const char *db, drizzle_options_st *options)
+
+   Creates a connection connection object.  If a path beginning with ``/`` is given as the host the library will connect as a UDS socket.  Otherwise a TCP/IP conection is made.
+
+   .. note::
+      a connection does not happen until the first query or an explicit :c:func:`drizzle_connect` call is made
+
+   :param host: The socket path, hostname or IP of the server
+   :param port: The port number of the server (if TCP/IP)
+   :param user: The username of the server
+   :param password: The password of the server
+   :param db: The default DB to connect to on the server
+   :param options: A pointer to a :c:type:`drizzle_options_st` created using :c:func:`drizzle_options_create` or :c:type:`NULL`
    :returns: A newly allocated and setup connection object
 
 .. c:function:: int drizzle_timeout(const drizzle_st *con)
@@ -51,7 +47,7 @@
    Sets the connection timeout for the connection object
 
    :param drizzle: A connection object
-   :param int: The new timeout to set
+   :param timeout: The new timeout to set
 
 .. c:function:: drizzle_verbose_t drizzle_verbose(const drizzle_st *con)
 
@@ -103,34 +99,102 @@
    :param con: A connection object
    :returns: A string containing the sqlstate
 
-.. c:function:: drizzle_options_t drizzle_options(const drizzle_st *con)
-
-   Gets the connection options
-
-   :param con: A connection object
-   :returns: The options for the connection
-
-.. c:function:: void drizzle_set_options(drizzle_st *con, drizzle_options_t options)
-
-   Sets the connection options
-
-   :param con: A connection object
-   :param options: A bit field of the :c:type:`drizzle_options_t` options
-
-.. c:function:: void drizzle_add_options(drizzle_st *con, drizzle_options_t options)
-
-   Add connection options
-
-   :param con: A connection object
-   :param options: A bit field of the :c:type:`drizzle_options_t` options
-
-.. c:function:: void drizzle_remove_options(drizzle_st *con, drizzle_options_t options)
-
-   Removes connection options
-
-   :param con: A connection object
-   :param options: A bit field of the :c:type:`drizzle_options_t` options
-
+.. c:function:: drizzle_options_st *drizzle_options_create(void)
+
+   Create a new connection options object
+
+   :returns: The new connection options object
+
+.. c:function:: void drizzle_options_destroy(drizzle_options_st *options)
+
+   Destroys a connection options object
+
+   :param options: The options object to be destroyed
+
+.. c:function:: void drizzle_options_set_non_blocking(drizzle_options_st *options, bool state)
+
+   Sets/unsets non-blocking connect option
+
+   :param options: The options object to modify
+   :param state: Set option to true/false
+
+.. c:function:: bool drizzle_options_get_non_blocking(drizzle_options_st *options)
+
+   Gets the non-blocking connect option
+
+   :param options: The options object to get the value from
+   :returns: The state of the non-blocking option
+
+.. c:function:: void drizzle_options_set_raw_scramble(drizzle_options_st *options, bool state)
+
+   Sets/unsets the raw scramble connect option
+
+   :param options: The options object to modify
+   :param state: Set to true/false
+
+.. c:function:: bool drizzle_options_get_raw_scramble(drizzle_options_st *options)
+
+   Gets the raw scramble connect option
+
+   :param options: The options object to get the value from
+   :returns: The state of the raw scramble option
+
+.. c:function:: void drizzle_options_set_found_rows(drizzle_options_st *options, bool state)
+
+   Sets/unsets the found rows connect option
+
+   :param options: The options object to modify
+   :param state: Set to true/false
+
+.. c:function:: bool drizzle_options_get_found_rows(drizzle_options_st *options)
+
+   Gets the found rows connect option
+
+   :param options: The options object to get the value from
+   :returns: The state of the found rows option
+
+.. c:function:: void drizzle_options_set_interactive(drizzle_options_st *options, bool state)
+
+   Sets/unsets the interactive connect option
+
+   :param options: The options object to modify
+   :param state: Set to true/false
+
+.. c:function:: bool drizzle_options_get_interactive(drizzle_options_st *option)
+
+   Gets the interactive connect option
+
+   :param options: The options object to get the value from
+   :returns: The state of the interactive option
+
+.. c:function:: void drizzle_options_set_multi_statements(drizzle_options_st *options, bool state)
+
+   Sets/unsets the multi-statements connect option
+
+   :param options: The options object to modify
+   :parma state: Set to true/false
+
+.. c:function:: bool drizzle_options_get_multi_statements(drizzle_options_st *options)
+
+   Gets the multi-statements connect option
+
+   :param options: The options object to get the value from
+   :returns: The state of the multi-statements option
+
+.. c:function:: void drizzle_options_set_auth_plugin(drizzle_options_st *options, bool state)
+
+   Sets/unsets the auth plugin connect option
+
+   :param options: The optoins object to modify
+   :param state: Set to true/false
+
+.. c:function:: bool drizzle_options_get_auth_plugin(drizzle_options_st *options)
+
+   Gets the auth plugin connect option
+
+   :param options: The options object to get the value from
+   :returns: The state of the auth plugin option
+   
 .. c:function:: const char* drizzle_host(const drizzle_st *con)
 
    Gets the host name from a TCP/IP connection
 
=== modified file 'docs/api/constants.rst'
--- docs/api/constants.rst	2013-01-05 11:25:32 +0000
+++ docs/api/constants.rst	2013-02-07 16:43:36 +0000
@@ -179,58 +179,6 @@
 Connection
 ----------
 
-.. c:type:: drizzle_options_t
-
-   An ENUM of connection options intended to be used in a bit field
-
-   .. py:data:: DRIZZLE_CON_NONE
-
-      No option set
-
-   .. py:data:: DRIZZLE_CON_NON_BLOCKING
-
-      Connect in non-blocking mode
-
-   .. py:data:: DRIZZLE_CON_RAW_PACKET
-
-      Raw packet data mode (for low-level clients)
-
-   .. py:data:: DRIZZLE_CON_RAW_SCRAMBLE
-
-      Raw auth scramble data (for low-level clients)
-
-   .. py:data:: DRIZZLE_CON_READY
-
-      Connection is ready
-
-   .. py:data:: DRIZZLE_CON_NO_RESULT_READ
-
-      Don't read result data from buffer (advanced feature, use with caution)
-
-   .. py:data:: DRIZZLE_CON_IO_READY
-   
-      Used for event handling
-
-   .. py:data:: DRIZZLE_CON_LISTEN
-
-      Unused
-
-   .. py:data:: DRIZZLE_CON_FOUND_ROWS
-
-      Enable the FOUND_ROWS functionality
-
-   .. py:data:: DRIZZLE_CON_INTERACTIVE
-
-      This is an interactive client
-
-   .. py:data:: DRIZZLE_CON_MULTI_STATEMENTS
-
-      Multi-statement support
-
-   .. py:data:: DRIZZLE_CON_AUTH_PLUGIN
-
-      Authentiaction plugin support
-
 .. c:type:: drizzle_charset_t
 
    An ENUM of the possible character set with colation ID
 
=== modified file 'docs/api/query.rst'
--- docs/api/query.rst	2013-01-28 01:43:28 +0000
+++ docs/api/query.rst	2013-02-07 16:43:36 +0000
@@ -46,41 +46,16 @@
    :param ret_ptr: A pointer to a :c:type:`drizzle_return_t` to store the return status into
    :returns: A newly allocated result object
 
-.. c:function:: ssize_t drizzle_escape_string(char *to, const size_t max_to_size, const char *from, const size_t from_size)
-
-   Escape a string for an SQL query
-
+.. c:function:: ssize_t drizzle_escape_string(drizzle_st *con, char **to, const const char *from, const size_t from_size)
+
+   Escape a string for an SQL query.  The ``to`` parameter is allocated by the function and needs to be freed by the application when finished with.
+
+   :param con: a connection object
    :param to: the destination string
-   :param max_to_size: the maximum length of the 'to' parameter
    :param from: the source string
    :param from_size: the length of the source string
    :returns: the length of the 'to' string or -1 upon error due to empty parameters or overflow
 
-.. c:function:: bool drizzle_hex_string(char *to, const unsigned char *from, const size_t from_size)
-
-   Convert data into a hexadecimal string of the data.
-
-   .. note::
-      The allocated length of the 'to' string should always be at least double
-      the length of the 'from' string
-
-   :param to: the destination string
-   :param from: the source string
-   :param from_size: the length of the source string
-   :returns: a true upon success or false upon empty parameters
-
-.. c:function:: bool drizzle_mysql_password_hash(char *to, const char *from, const size_t from_size)
-
-   Convert data into a MySQL password hash string.
-
-   .. note::
-      The allocated length of the 'to' string should always be at least 41 bytes
-
-   :param to: the destination string
-   :param from: the source string:
-   :param from_size: the length of the source string
-   :returns: a true upons success or false upon empty parameters
-
 .. c:function:: void drizzle_result_free(drizzle_result_st *result)
 
    Frees a result object
 
=== modified file 'docs/examples/binlog.rst'
--- docs/examples/binlog.rst	2013-01-05 10:27:32 +0000
+++ docs/examples/binlog.rst	2013-02-07 16:43:36 +0000
@@ -7,15 +7,43 @@
     #include <stdio.h>
     #include <stdlib.h>
 
+    void binlog_error(drizzle_return_t ret, drizzle_st *connection, void *context)
+    {
+      (void) context;
+      if (ret != DRIZZLE_RETURN_EOF)
+      {
+        printf("Error retrieving binlog: %s\n", drizzle_error(connection));
+      }
+    }
+
+
+    void binlog_event(drizzle_binlog_event_st *event, void *context)
+    {
+      (void) context;
+      printf("Timestamp: %"PRIu32"\n", drizzle_binlog_event_timestamp(event));
+      printf("Type: %"PRIu8"\n", drizzle_binlog_event_type(event));
+      printf("Server-id: %"PRIu32"\n", drizzle_binlog_event_server_id(event));
+      printf("Next-pos: %"PRIu32"\n", drizzle_binlog_event_next_pos(event));
+      length= drizzle_binlog_event_length(event);
+      printf("Length: %"PRIu32"\n", length);
+      data= drizzle_binlog_event_data(event);
+      printf("Data: 0x");
+      for (i=0; i<length; i++)
+        printf("%02X ", data[i]);
+      printf("\n\n");
+    }
+
+
+
     int main(int argc, char *argv[])
     {
       (void) argc;
       (void) argv;
       drizzle_st *con;
       drizzle_return_t ret;
-      drizzle_result_st *result;
+      drizzle_binlog_st *binlog;
 
-      con = drizzle_create_tcp("localhost", 3306, "root", "", "", 0);
+      con = drizzle_create("localhost", 3306, "root", "", "", 0);
       if (con == NULL)
       {
         printf("Drizzle connection object creation error\n");
@@ -28,32 +56,15 @@
         return EXIT_FAILURE;
       }
 
-      result= drizzle_start_binlog(con, 0, "", 0, &ret);
-      if (ret != DRIZZLE_RETURN_OK)
+      binlog= drizzle_binlog_init(con, binlog_event, binlog_error, NULL, true);
+      ret= drizzle_binlog_start(binlog, 0, "", 0);
+      if (ret != DRIZZLE_RETURN_EOF)
       {
         printf("Drizzle binlog start failure\n");
         return EXIT_FAILURE;
       }
 
-      while (ret == DRIZZLE_RETURN_OK)
-      {
-        uint32_t i, length;
-        const unsigned char *data;
-        ret= drizzle_binlog_get_event(result);
-        if (ret != DRIZZLE_RETURN_OK)
-          break;
-        printf("Timestamp: %"PRIu32"\n", drizzle_binlog_event_timestamp(result));
-        printf("Type: %"PRIu8"\n", drizzle_binlog_event_type(result));
-        printf("Server-id: %"PRIu32"\n", drizzle_binlog_event_server_id(result));
-        printf("Next-pos: %"PRIu32"\n", drizzle_binlog_event_next_pos(result));
-        length= drizzle_binlog_event_length(result);
-        printf("Length: %"PRIu32"\n", length);
-        data= drizzle_binlog_event_data(result);
-        printf("Data: 0x");
-        for (i=0; i<length; i++)
-          printf("%02X ", data[i]);
-        printf("\n\n");
-      }
+
 
       drizzle_quit(con);
       return EXIT_SUCCESS;
 
=== modified file 'docs/examples/buffered.rst'
--- docs/examples/buffered.rst	2013-01-10 22:14:47 +0000
+++ docs/examples/buffered.rst	2013-02-07 16:43:36 +0000
@@ -36,7 +36,7 @@
       drizzle_row_t row;
       int num_fields;
 
-      con = drizzle_create_tcp("localhost", 3306, "user", "pass", "test", 0);
+      con = drizzle_create("localhost", 3306, "user", "pass", "test", 0);
       if (con == NULL)
       {
         printf("Drizzle connection object creation error\n");
 
=== modified file 'docs/examples/unbuffered.rst'
--- docs/examples/unbuffered.rst	2013-01-10 22:14:47 +0000
+++ docs/examples/unbuffered.rst	2013-02-07 16:43:36 +0000
@@ -38,7 +38,7 @@
       drizzle_row_t row;
       int num_fields;
 
-      con = drizzle_create_tcp("localhost", 3306, "root", "", "libdrizzle", 0);
+      con = drizzle_create("localhost", 3306, "root", "", "libdrizzle", 0);
       if (con == NULL)
       {
         printf("Drizzle connection object creation error\n");