xapi.h

/*
 * Copyright (c) 2016, 2024, Oracle and/or its affiliates.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License, version 2.0, as
 * published by the Free Software Foundation.
 *
 * This program is designed to work with certain software (including
 * but not limited to OpenSSL) that is licensed under separate terms, as
 * designated in a particular file or component or in included license
 * documentation. The authors of MySQL hereby grant you an additional
 * permission to link the program and your derivative works with the
 * separately licensed software that they have either included with
 * the program or referenced in the documentation.
 *
 * Without limiting anything contained in the foregoing, this file,
 * which is part of Connector/C++, is also subject to the
 * Universal FOSS Exception, version 1.0, a copy of which can be found at
 * https://oss.oracle.com/licenses/universal-foss-exception.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU General Public License, version 2.0, for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 */

/**
 @defgroup xapi X DevAPI for C

 Functions and types defined by X DevAPI for C. See @ref xapi_example for introduction.

 @{
 @defgroup xapi_sess Session operations

 @defgroup xapi_coll Statements operating on document collections

 @defgroup xapi_tbl Statements operating on tables

 @defgroup xapi_sql SQL execution

 @defgroup xapi_ddl DDL statements

 @note To create a table or a view, use reqular SQL statement.

 @defgroup xapi_stmt Statement execution

 @defgroup xapi_res Result processing

 @defgroup xapi_md Meta data access

 @defgroup xapi_diag Diagnostics
 @}
*/


/**
 @file
 The main header for MySQL Connector/C++ X DevAPI for C.

 This header should be included by C and C++ code which uses the X DevAPI
 for C implemented by MySQL Connector/C++

 @ingroup xapi
*/


#ifndefMYSQL_XAPI_H
#defineMYSQL_XAPI_H


#ifdef__cplusplus
extern"C" {
#endif


#include"common_constants.h"
#include"common/api.h"

#include<stdlib.h>
#include<stdint.h>
#include<stdbool.h>

/**
 @addtogroup xapi
 @{
*/


// FIXME
#defineSTDCALL

///////////////////// COMMON TYPE DECLARATIONS, REMOVE LATER

typedefcharobject_id[16];
typedefobject_id*MYSQLX_GUID;

/** Return value indicating function/operation success. */

#defineRESULT_OK 0

/**
 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 such as mysqlx_get_bytes()
*/

#defineRESULT_MORE_DATA 8

/**
 Return value flag indicating end of data items (documents or
 rows) in a query result. This is used by functions which iterate
 over result data.
*/

#defineRESULT_NULL 16

/**
 Return value flag indicating that operation generated
 information diagnostic entries.
*/

#defineRESULT_INFO 32

/** Return value flag indicating that operation generated warnings. */

#defineRESULT_WARNING 64

/** Return value flag indicating function/operation error. */

#defineRESULT_ERROR 128


#defineMYSQLX_MAX_ERROR_LEN 255
#defineMYSQLX_NULL_TERMINATED 0xFFFFFFFF

#defineMYSQLX_ERR_UNKNOWN 0xFFFF

#defineMYSQLX_COLLATION_UNDEFINED 0


/*
 Error codes
*/

#defineMYSQLX_ERROR_INDEX_OUT_OF_RANGE 1

/*
 Error messages
*/

#defineMYSQLX_ERROR_INDEX_OUT_OF_RANGE_MSG "Index is out of range"
#defineMYSQLX_ERROR_MISSING_SCHEMA_NAME_MSG "Missing schema name"
#defineMYSQLX_ERROR_MISSING_TABLE_NAME_MSG "Missing table name"
#defineMYSQLX_ERROR_MISSING_VIEW_NAME_MSG "Missing view name"
#defineMYSQLX_ERROR_MISSING_COLLECTION_NAME_MSG "Missing collection name"
#defineMYSQLX_ERROR_MISSING_COLLECTION_OPT_MSG "Missing collection options"
#defineMYSQLX_ERROR_MISSING_VIEW_NAME_MSG "Missing view name"
#defineMYSQLX_ERROR_MISSING_KEY_NAME_MSG "Missing key name"
#defineMYSQLX_ERROR_MISSING_HOST_NAME "Missing host name"
#defineMYSQLX_ERROR_MISSING_SOCKET_NAME "Missing socket name"
#defineMYSQLX_ERROR_MISSING_CONN_INFO "Missing connecting information"
#defineMYSQLX_ERROR_HANDLE_NULL_MSG "Handle cannot be NULL"
#defineMYSQLX_ERROR_VIEW_INVALID_STMT_TYPE "Invalid statement type for View. Only SELECT type is supported"
#defineMYSQLX_ERROR_VIEW_TYPE_MSG "Statement must be of VIEW type"
#defineMYSQLX_ERROR_OUTPUT_BUFFER_NULL "The output buffer cannot be NULL"
#defineMYSQLX_ERROR_OUTPUT_BUFFER_ZERO "The output buffer cannot have zero length"
#defineMYSQLX_ERROR_OUTPUT_VARIABLE_NULL "The output variable cannot be NULL"
#defineMYSQLX_ERROR_OP_NOT_SUPPORTED "The operation is not supported by the function"
#defineMYSQLX_ERROR_WRONG_SSL_MODE "Wrong value for SSL Mode"
#defineMYSQLX_ERROR_NO_TLS_SUPPORT "Can not create TLS session - this connector is built without TLS support"
#defineMYSQLX_ERROR_MIX_PRIORITY "Mixing hosts with and without priority is not allowed"
#defineMYSQLX_ERROR_DUPLICATED_OPTION "Option already defined"
#defineMYSQLX_ERROR_MAX_PRIORITY "Priority should be a value between 0 and 100"
#defineMYSQLX_ERROR_AUTH_METHOD "Unknown authentication method"
#defineMYSQLX_ERROR_ROW_LOCKING "Row locking is supported only for SELECT and FIND"
#defineMYSQLX_ERROR_WRONG_LOCKING_MODE "Wrong value for the row locking mode"
#defineMYSQLX_ERROR_WRONG_EXPRESSION "Expression could not be parsed"
#defineMYSQLX_ERROR_EMPTY_JSON "Empty JSON document string"


/* Opaque structures*/

/**
 Type of error handles.

 Error handles give access to diagnostic information from the session
 and statement operations.

 @see mysqlx_error()
*/

typedefstructmysqlx_error_structmysqlx_error_t;


/**
 Type of session handles.

 @see mysqlx_get_session()
*/

typedefstructmysqlx_session_structmysqlx_session_t;

/**
 Type of client handles.

 @see mysqlx_get_client()
*/

typedefstructmysqlx_client_structmysqlx_client_t;


/**
 Type of handles for session configuration data.

 Session can be created using previously prepared session configuration
 data. New configuration data is allocated by `mysqlx_session_options_new()`
 and can be manipulated using related functions.

 @see mysqlx_get_session_from_options(), mysqlx_session_options_new(),
 mysqlx_session_option_set(), mysqlx_free().
*/

typedefstructmysqlx_session_options_structmysqlx_session_options_t;

/**
 Type of handles for collection create/modify options.

 @see mysqlx_collection_options_new(), mysqlx_collection_options_set(),
 mysqlx_free().
*/

typedefstructmysqlx_collection_options_structmysqlx_collection_options_t;

/**
 Type of database schema handles.

 @see mysqlx_get_schema()
*/

typedefstructmysqlx_schema_structmysqlx_schema_t;


/**
 Type of collection handles.

 @see mysqlx_get_collection()
*/

typedefstructmysqlx_collection_structmysqlx_collection_t;


/**
 Type of table handles.

 @see mysqlx_get_table()
*/
typedefstructmysqlx_table_structmysqlx_table_t;


/**
 Type of statement handles.

 Some X DevAPI for C functions create statements without executing them. These
 functions return a statement handle which can be used to define statement
 properties and then execute it.

 @see mysqlx_sql_new(), mysqlx_table_select_new(), mysqlx_table_insert_new(),
 mysqlx_table_update_new(), mysqlx_table_delete_new(),
 mysqlx_collection_find_new(), mysqlx_collection_modify_new(),
 mysqlx_collection_add_new(), mysqlx_collection_remove_new()
*/

typedefstructmysqlx_stmt_structmysqlx_stmt_t;

typedefstructMysqlx_diag_basemysqlx_object_t;


/**
 Type of row handles.

 @see mysqlx_row_fetch_one()
*/

typedefstructmysqlx_row_structmysqlx_row_t;


/**
 Type of result handles.

 Functions which produce results return a result handle which is
 then used to examine the result.

 @see mysqlx_execute(), mysqlx_store_result(), mysqlx_row_fetch_one(),
 mysqlx_json_fetch_one(), mysqlx_next_result())
*/

typedefstructmysqlx_result_structmysqlx_result_t;


/**
 The data type identifiers used in MYSQLX API.
*/

typedefenummysqlx_data_type_enum
{
MYSQLX_TYPE_UNDEFINED=0,

/* Column types as defined in protobuf (mysqlx_resultset.proto)*/
MYSQLX_TYPE_SINT=1, /**< 64-bit signed integer number type*/
MYSQLX_TYPE_UINT=2, /**< 64-bit unsigned integer number type*/
MYSQLX_TYPE_DOUBLE=5, /**< Floating point double number type*/
MYSQLX_TYPE_FLOAT=6, /**< Floating point float number type*/
MYSQLX_TYPE_BYTES=7, /**< Bytes array type*/
MYSQLX_TYPE_TIME=10, /**< Time type*/
MYSQLX_TYPE_DATETIME=12,/**< Datetime type*/
MYSQLX_TYPE_SET=15, /**< Set type*/
MYSQLX_TYPE_ENUM=16,/**< Enum type*/
MYSQLX_TYPE_BIT=17, /**< Bit type*/
MYSQLX_TYPE_DECIMAL=18,/**< Decimal type*/

/* Column types from DevAPI (no number constants assigned, just names)*/
MYSQLX_TYPE_BOOL=19,/**< Bool type*/
MYSQLX_TYPE_JSON=20,/**< JSON type*/
MYSQLX_TYPE_STRING=21,/**< String type*/
MYSQLX_TYPE_GEOMETRY=22,/**< Geometry type*/
MYSQLX_TYPE_TIMESTAMP=23,/**< Timestamp type*/

MYSQLX_TYPE_NULL=100, /**< NULL value*/
MYSQLX_TYPE_EXPR=101/**< Expression type*/
} mysqlx_data_type_t;

#definePARAM_SINT(A) (void*)MYSQLX_TYPE_SINT, (int64_t)A
#definePARAM_UINT(A) (void*)MYSQLX_TYPE_UINT, (uint64_t)A
#definePARAM_FLOAT(A) (void*)MYSQLX_TYPE_FLOAT, (double)A
#definePARAM_DOUBLE(A) (void*)MYSQLX_TYPE_DOUBLE, (double)A
#definePARAM_BYTES(DATA, SIZE) (void*)MYSQLX_TYPE_BYTES, (void*)DATA, (size_t)SIZE
#definePARAM_STRING(A) (void*)MYSQLX_TYPE_STRING, A
#definePARAM_EXPR(A) (void*)MYSQLX_TYPE_EXPR, A
#definePARAM_NULL() (void*)MYSQLX_TYPE_NULL

#definePARAM_END (void*)0


/**
 Sort directions in sorting operations such as ORDER BY.
*/

typedefenummysqlx_sort_direction_enum
{
SORT_ORDER_ASC=1, /**< Ascending sorting (Default)*/
SORT_ORDER_DESC=2/**< Descending sorting*/
} mysqlx_sort_direction_t;


#definePARAM_SORT_ASC(A) A, SORT_ORDER_ASC
#definePARAM_SORT_DESC(A) A, SORT_ORDER_DESC

/**
 Client options for use with `mysqlx_session_option_get()`
 and `mysqlx_session_option_set()` functions.

*/

typedefenummysqlx_client_opt_type_enum
{

#define XAPI_CLIENT_OPT_ENUM_str(X,N) MYSQLX_CLIENT_OPT_##X = -N,
#defineXAPI_CLIENT_OPT_ENUM_bool(X,N) MYSQLX_CLIENT_OPT_##X = -N,
#defineXAPI_CLIENT_OPT_ENUM_num(X,N) MYSQLX_CLIENT_OPT_##X = -N,
#defineXAPI_CLIENT_OPT_ENUM_any(X,N) MYSQLX_CLIENT_OPT_##X = -N,

CLIENT_OPTION_LIST(XAPI_CLIENT_OPT_ENUM)
}
mysqlx_client_opt_type_t;

#defineOPT_POOLING(A) MYSQLX_CLIENT_OPT_POOLING, (int)(bool)(A)
#defineOPT_POOL_MAX_SIZE(A) MYSQLX_CLIENT_OPT_POOL_MAX_SIZE, (uint64_t)(A)
#defineOPT_POOL_QUEUE_TIMEOUT(A) MYSQLX_CLIENT_OPT_POOL_QUEUE_TIMEOUT, (uint64_t)(A)
#defineOPT_POOL_MAX_IDLE_TIME(A) MYSQLX_CLIENT_OPT_POOL_MAX_IDLE_TIME, (uint64_t)(A)

/**
 Session options for use with `mysqlx_session_option_get()`
 and `mysqlx_session_option_set()` functions.

 @note Specifying `MYSQLX_OPT_SSL_CA` option requires `MYSQLX_OPT_SSL_MODE`
 value of `SSL_MODE_VERIFY_CA` or `SSL_MODE_VERIFY_IDENTITY`.
 If `MYSQLX_OPT_SSL_MODE` is not explicitly given then setting
 `MYSQLX_OPT_SSL_CA` implies `SSL_MODE_VERIFY_CA`.

 \anchor opt_session
*/

typedefenummysqlx_opt_type_enum
{

#define XAPI_OPT_ENUM_str(X,N) MYSQLX_OPT_##X = N,
#defineXAPI_OPT_ENUM_num(X,N) MYSQLX_OPT_##X = N,
#defineXAPI_OPT_ENUM_any(X,N) MYSQLX_OPT_##X = N,
#defineXAPI_OPT_ENUM_bool(X,N) MYSQLX_OPT_##X = N,

SESSION_OPTION_LIST(XAPI_OPT_ENUM)
MYSQLX_OPT_LAST
}
mysqlx_opt_type_t;

#defineOPT_HOST(A) MYSQLX_OPT_HOST, (A)
#defineOPT_PORT(A) MYSQLX_OPT_PORT, (unsigned int)(A)
#ifndef_WIN32
#defineOPT_SOCKET(A) MYSQLX_OPT_SOCKET, (A)
#endif//_WIN32
#defineOPT_DNS_SRV(A) MYSQLX_OPT_DNS_SRV, (A)
#defineOPT_USER(A) MYSQLX_OPT_USER, (A)
#defineOPT_PWD(A) MYSQLX_OPT_PWD, (A)
#defineOPT_DB(A) MYSQLX_OPT_DB, (A)
#defineOPT_SSL_MODE(A) MYSQLX_OPT_SSL_MODE, (A)
#defineOPT_SSL_CA(A) MYSQLX_OPT_SSL_CA, (A)
#defineOPT_SSL_CAPATH(A) MYSQLX_OPT_SSL_CAPATH, (A)
#defineOPT_SSL_CRL(A) MYSQLX_OPT_SSL_CRL, (A)
#defineOPT_SSL_CRLPATH(A) MYSQLX_OPT_SSL_CRLPATH, (A)
#defineOPT_PRIORITY(A) MYSQLX_OPT_PRIORITY, (unsigned int)(A)
#defineOPT_AUTH(A) MYSQLX_OPT_AUTH, (unsigned int)(A)
#defineOPT_CONNECT_TIMEOUT(A) MYSQLX_OPT_CONNECT_TIMEOUT, (unsigned int)(A)
#defineOPT_CONNECTION_ATTRIBUTES(A) MYSQLX_OPT_CONNECTION_ATTRIBUTES, (A)
#defineOPT_TLS_VERSIONS(A) MYSQLX_OPT_TLS_VERSIONS, (A)
#defineOPT_TLS_CIPHERSUITES(A) MYSQLX_OPT_TLS_CIPHERSUITES, (A)
#defineOPT_COMPRESSION(A) MYSQLX_OPT_COMPRESSION, (unsigned int)(A)
#defineOPT_COMPRESSION_ALGORITHMS(A) MYSQLX_OPT_COMPRESSION_ALGORITHMS, (const char*)(A)


/**
 Session SSL mode values for use with `mysqlx_session_option_get()`
 and `mysqlx_session_option_set()` functions setting or getting
 MYSQLX_OPT_SSL_MODE option.
*/

typedefenummysqlx_ssl_mode_enum
{
#define XAPI_SSL_MODE_ENUM(X,N) SSL_MODE_##X = N,

SSL_MODE_LIST(XAPI_SSL_MODE_ENUM)
}
mysqlx_ssl_mode_t;

/**
 Authentication method values for use with `mysqlx_session_option_get()`
 and `mysqlx_session_option_set()` functions setting or getting
 MYSQLX_OPT_AUTH option.
*/

typedefenummysqlx_auth_method_enum
{
#define XAPI_AUTH_ENUM(X,N) MYSQLX_AUTH_##X = N,

AUTH_METHOD_LIST(XAPI_AUTH_ENUM)
}
mysqlx_auth_method_t;

/**
 Collection create/modify options

 \anchor opt_collection
*/

typedefenummysqlx_collection_opt_enum
{

#define XAPI_COLLECTION_OPT_ENUM(X,N) MYSQLX_OPT_COLLECTION_##X = N,

COLLECTION_OPTIONS_OPTION(XAPI_COLLECTION_OPT_ENUM)
MYSQLX_OPT_COLLECTION_LAST
}
mysqlx_collection_opt_t;

/**
 Collection validation options

 \anchor opt_collection_validation
*/

typedefenummysqlx_collection_validation_opt_enum
{

#define XAPI_COLLECTION_VALIDATION_OPT_ENUM(X,N) MYSQLX_OPT_COLLECTION_VALIDATION_##X = 1024+N,

COLLECTION_VALIDATION_OPTION(XAPI_COLLECTION_VALIDATION_OPT_ENUM)
MYSQLX_OPT_COLLECTION_VALIDATION_LAST
}
mysqlx_collection_validation_opt_t;

/**
 Collection validation level options
 \anchor opt_collection_validation_level
*/

typedefenummysqlx_collection_validation_level_enum
{

#define XAPI_COLLECTION_VALIDATION_LEVEL_ENUM(X,N) MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_##X = 2048+N,

COLLECTION_VALIDATION_LEVEL(XAPI_COLLECTION_VALIDATION_LEVEL_ENUM)
MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_LAST
}
mysqlx_collection_validation_level_t;

#defineVALIDATION_OFF MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_OFF
#defineVALIDATION_STRICT MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_STRICT

#defineOPT_COLLECTION_REUSE(X) MYSQLX_OPT_COLLECTION_REUSE, (unsigned int)X
#defineOPT_COLLECTION_VALIDATION(X) MYSQLX_OPT_COLLECTION_VALIDATION, (const char*)X
#defineOPT_COLLECTION_VALIDATION_LEVEL(X) MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL, (unsigned int)X
#defineOPT_COLLECTION_VALIDATION_SCHEMA(X) MYSQLX_OPT_COLLECTION_VALIDATION_SCHEMA, (const char*)X

/**
 Compression modes.
 TODO: see...
*/
typedefenummysqlx_compression_mode_enum
{
#define XAPI_COMPRESSION_ENUM(X,N) MYSQLX_COMPRESSION_##X = N,

COMPRESSION_MODE_LIST(XAPI_COMPRESSION_ENUM)
}
mysqlx_compression_mode_t;

/**
 Constants for defining the row locking options for
 mysqlx_set_row_locking() function.
 @see https://dev.mysql.com/doc/refman/8.0/en/innodb-locking-reads.html
*/
typedefenummysqlx_row_locking_enum
{
#define XAPI_ROW_LOCK_ENUM(X,N) ROW_LOCK_##X = N,

ROW_LOCK_NONE=0, /**< No locking */
LOCK_MODE_LIST(XAPI_ROW_LOCK_ENUM)
}
mysqlx_row_locking_t;

/**
 Constants for defining the row locking options for
 mysqlx_set_row_locking() function.
 @see https://dev.mysql.com/doc/refman/8.0/en/innodb-locking-reads.html#innodb-locking-reads-nowait-skip-locked
*/
typedefenummysqlx_lock_contention_enum
{
#define XAPI_LOCK_CONTENTION_ENUM(X,N) LOCK_CONTENTION_##X = N,

LOCK_CONTENTION_LIST(XAPI_LOCK_CONTENTION_ENUM)
}
mysqlx_lock_contention_t;

/*
 ====================================================================
 Client operations
 ====================================================================
*/

/**
 Create a client instance using connection string or URL and a client options
 JSON.

 Connection sting has the form `"user:pass@host:port/?option&option"`,
 valid URL is like a connection string with a `mysqlx://` prefix. Host is
 specified as either DNS name, IPv4 address of the form "nn.nn.nn.nn" or
 IPv6 address of the form "[nn:nn:nn:...]".

 Possible connection options are:

 - `ssl-mode` : TLS connection mode
 - `ssl-ca=`path : path to a PEM file specifying trusted root certificates

 Specifying `ssl-ca` option implies `ssl-mode=VERIFY_CA`.

 Client options are expressed in a JSON string format. Here is an example:
 ~~~~~~
 { "pooling": {
 "enabled": true,
 "maxSize": 25,
 "queueTimeout": 1000,
 "maxIdleTime": 5000}
 }
 ~~~~~~

 All options are defined under a document with key vale "pooling". Inside the
 document, the available options are these:
 - `enabled` : boolean value that enable or disable connection pooling. If
 disabled, session created from pool are the same as created
 directly without client handle.
 Enabled by default.
 - `maxSize` : integer that defines the max pooling sessions possible. If uses
 tries to get session from pool when maximum sessions are used,
 it will wait for an available session untill `queueTimeout`.
 Defaults to 25.
 - `queueTimeout` : integer value that defines the time, in milliseconds, that
 client will wait to get an available session.
 By default it doesn't timeouts.
 - `maxIdleTime` : integer value that defines the time, in milliseconds, that
 an available session will wait in the pool before it is
 removed.
 By default it doesn't cleans sessions.

 @param conn_string connection string
 @param client_opts client options in the form of a JSON string.
 @param[out] error if error happens during connect the error object
 is returned through this parameter

 @return client handle if client could be created, otherwise NULL
 is returned and the error information is returned through
 the error output parameter.

 @note The client returned by the function must be properly closed using
 `mysqlx_client_close()`.

 @note If an error object returned through the output parameter it must be
 freed using `mysqlx_free()`.

 @ingroup xapi_sess
*/

PUBLIC_APImysqlx_client_t*
mysqlx_get_client_from_url(constchar*conn_string, constchar*client_opts,
mysqlx_error_t**error);


/**
 Create a client pool using session configuration data.

 Client options are expressed in a JSON string format. Here is an example:
 ~~~~~~
 { "pooling": {
 "enabled": true,
 "maxSize": 25,
 "queueTimeout": 1000,
 "maxIdleTime": 5000}
 }
 ~~~~~~

 All options are defined under a document with key vale "pooling". Inside the
 document, the available options are these:
 - `enabled` : boolean value that enable or disable connection pooling. If
 disabled, session created from pool are the same as created
 directly without client handle.
 Enabled by default.
 - `maxSize` : integer that defines the max pooling sessions possible. If uses
 tries to get session from pool when maximum sessions are used,
 it will wait for an available session untill `queueTimeout`.
 Defaults to 25.
 - `queueTimeout` : integer value that defines the time, in milliseconds, that
 client will wait to get an available session.
 By default it doesn't timeouts.
 - `maxIdleTime` : integer value that defines the time, in milliseconds, that
 an available session will wait in the pool before it is
 removed.
 By default it doesn't cleans sessions.

 @param opt handle to client configuration data
 @param[out] error if error happens during connect the error object
 is returned through this parameter

 @return client handle if client could be created, otherwise NULL
 is returned and the error information is returned through
 the error output parameter.

 @note The client returned by the function must be properly closed using
 `mysqlx_client_close()`.

 @note If an error object returned through the output parameter it must be
 freed using `mysqlx_free()`.

 @ingroup xapi_sess
*/

PUBLIC_APImysqlx_client_t*
mysqlx_get_client_from_options(mysqlx_session_options_t*opt,
mysqlx_error_t**error);

/**
 Close the client pool and all sessions created by them.

 This function must be called by the user to prevent memory leaks.
 Closing client closes all sessions created by this client.\n
 Sessions created by this client are closed, but their resources are not freed.
 `mysqlx_session_close()` has to be called to prevent memory leaks.

 After a call to this function the given client handle becomes invalid.
 Any attempt to use the handle after this, results in undefined behavior.


 @param client client handle

 @ingroup xapi_sess
*/

PUBLIC_APIvoidmysqlx_client_close(mysqlx_client_t*client);

/*
 ====================================================================
 Session operations
 ====================================================================
*/

/**
 Create a new session

 @param cli client pool to get session from
 @param[out] error if error happens during connect the error object
 is returned through this parameter

 @note If an error object returned through the output parameter it must be
 freed using `mysqlx_free()`.
*/

PUBLIC_APImysqlx_session_t*
mysqlx_get_session_from_client(mysqlx_client_t*cli,
mysqlx_error_t**error);

/**
 Create a new session.

 @param host server host DNS name, IPv4 address or IPv6 address
 @param port port number
 @param user user name
 @param password password
 @param database default database name
 @param[out] error if error happens during connect the error object
 is returned through this parameter

 @return session handle if session could be created, otherwise NULL
 is returned and the error information is returned through
 output error parameter.

 @note The session returned by the function must be properly closed using
 `mysqlx_session_close()`.
 @note This function always establishes connection with SSL enabled
 @note If an error object returned through the output parameter it must be
 freed using `mysqlx_free()`.

 @ingroup xapi_sess
*/

PUBLIC_APImysqlx_session_t*
mysqlx_get_session(constchar*host, intport, constchar*user,
constchar*password, constchar*database,
mysqlx_error_t**error);


/**
 Create a session using connection string or URL.

 @param conn_string connection string
 @param[out] error if error happens during connect the error object
 is returned through this parameter

 @return session handle if session could be created, otherwise NULL
 is returned and the error information is returned through
 the error output parameter.


 Connection sting has the form

 "user:pass@connection-data/db?option&option"

 with optional `mysqlx://` prefix.

 The `connetction-data` part is either a single host address or a coma
 separated list of hosts in square brackets: `[host1, host2, ..., hostN]`.
 In the latter case the connection fail-over logic will be used when
 creating the session.

 A single host address is either a DNS host name, an IPv4 address of
 the form `nn.nn.nn.nn` or an IPv6 address of the form `[nn:nn:nn:...]`.
 On Unix systems a host can be specified as a path to a Unix domain
 socket - this path must start with `/` or `.`.

 Characters like `/` in the connection data, which otherwise have a special
 meaning inside a connection string, must be represented using percent
 encoding (e.g., `%2F` for `/`). Another option is to enclose a host name or
 a socket path in round braces. For example, one can write

 "mysqlx://(./path/to/socket)/db"

 instead of

 "mysqlx://.%2Fpath%2Fto%2Fsocket/db"

 To specify priorities for hosts in a multi-host settings, use list of pairs
 of the form `(address=host,priority=N)`. If priorities are specified, they
 must be given to all hosts in the list.

 The optional `db` part of the connection string defines the default schema
 of the session.

 Possible connection options are:

 - `ssl-mode=...` : see `#MYSQLX_OPT_SSL_MODE`; the value is a case insensitive
 name of the SSL mode
 - `ssl-ca=...` : see `#MYSQLX_OPT_SSL_CA`
 - `auth=...`: see `#MYSQLX_OPT_AUTH`; the value is a case insensitive name of
 the authentication method
 - `connect-timeout=...`: see `#MYSQLX_OPT_CONNECT_TIMEOUT`
 - `connection-attributes=[...]` : see `#MYSQLX_OPT_CONNECTION_ATTRIBUTES`
 but the key-value pairs are not given by a JSON document but as a list;\n
 Examples:\n
 `"mysqlx://user@host?connection-attributes=[foo=bar,qux,baz=]"` -
 specify additional attributes to be sent\n
 `"mysqlx://user@host?connection-attributes=false"` -
 send no connection attributes\n
 `"mysqlx://user@host?connection-attributes=true"` -
 send default connection attributes\n
 `"mysqlx://user@host?connection-attributes=[]"` -
 the same as setting to `true`\n
 `"mysqlx://user@host?connection-attributes"` -
 the same as setting to `true`\n
 - `tls-versions=[...]` : see `#MYSQLX_OPT_TLS_VERSIONS`
 - `tls-ciphersuites=[...]` : see `#MYSQLX_OPT_TLS_CIPHERSUITES`
 - `compression=...` : see `#MYSQLX_OPT_COMPRESSION`
 - `compression-algorithms=[...]` : see `#MYSQLX_OPT_COMPRESSION_ALGORITHMS`


 @note The session returned by the function must be properly closed using
 `mysqlx_session_close()`.
 @note If an error object returned through the output parameter it must be
 freed using `mysqlx_free()`.

 @ingroup xapi_sess
*/

PUBLIC_APImysqlx_session_t*
mysqlx_get_session_from_url(constchar*conn_string,
mysqlx_error_t**error);

/**
 Create a session using session configuration data.

 @param opt handle to session configuration data
 @param[out] error if error happens during connect the error object
 is returned through this parameter

 @return session handle if session could be created, otherwise NULL
 is returned and the error information is returned through
 the error output parameter.

 @note The session returned by the function must be properly closed using
 `mysqlx_session_close()`.
 @note If an error object returned through the output parameter it must be
 freed using `mysqlx_free()`.

 @ingroup xapi_sess
*/

PUBLIC_APImysqlx_session_t*
mysqlx_get_session_from_options(mysqlx_session_options_t*opt,
mysqlx_error_t**error);



/**
 Close the session.

 This function must be called by the user to prevent memory leaks.
 Closing session frees all related resources, including those
 allocated by statements and results belonging to the session.

 After a call to this function the given session handle becomes invalid.
 Any attempt to use the handle after this, results in undefined behavior.

 @param session session handle

 @ingroup xapi_sess
*/

PUBLIC_APIvoidmysqlx_session_close(mysqlx_session_t*session);


/**
 Check the session validity.

 @param sess session handle

 @return 1 - if the session is valid, 0 - if the session is not valid

 @note The function checks only the internal session status without
 communicating with server(s).

 @note This function cannot be called for a session that was closed,
 because in this case the session handle itself is invalid and
 cannot be used in API calls.

 @ingroup xapi_sess
*/

PUBLIC_APIintmysqlx_session_valid(mysqlx_session_t*sess);

/**
 Get a list of schemas.

 The result is returned as a set of rows with one column containing schema
 name. The rows can be read with functions such as `mysqlx_row_fetch_one()`,
 `mysqlx_store_result()` etc.

 @param sess session handle
 @param schema_pattern schema name pattern to search, using "%" as a wildcard
 character; if this parameter is NULL then all schemas will be
 returned.

 @return handle to the result with rows containing schema names.
 NULL is returned only in case of an error. The error details
 can be obtained using `mysqlx_error()` function

 @ingroup xapi_sess
*/

PUBLIC_APImysqlx_result_t*
mysqlx_get_schemas(mysqlx_session_t*sess, constchar*schema_pattern);


/**
 Get a schema object and optionally check if it exists on the server.

 @param sess session handle
 @param schema_name name of the schema
 @param check flag to verify if the schema with the given name
 exists on the server (1 - check, 0 - do not check)

 @return handle to the schema object or NULL
 if an error occurred or the schema does not exist on the server

 @note Performing existence check involves communication with server(s).
 Without the check, this operation is executed locally. It is then possible
 to create a handle to a non-existent schema. Attempt to use such
 a handle later would eventually trigger an error.

 @ingroup xapi_sess
*/

PUBLIC_APImysqlx_schema_t*
mysqlx_get_schema(mysqlx_session_t*sess, constchar*schema_name,
unsigned intcheck);


/**
 Get a list of tables and views in a schema.

 The result is returned as a set of rows with two columns. The first column
 contains table/view name, the second column contains object type, either
 "TABLE" or "VIEW". The rows can be read with functions such as
 `mysqlx_row_fetch_one()`, `mysqlx_store_result()` etc.

 @param schema schema handle
 @param table_pattern table name pattern to search, using "%" as a wildcard
 character; if this parameter is NULL then all tables/views in the
 given schema will be returned.
 @param get_views flag specifying whether view names should be included
 into the result. 0 - do not show views (only table names are in
 the result), 1 - show views (table and view names are in the result)

 @return handle to the result with rows containing table/view names.
 NULL is returned only in case of an error. The error details
 can be obtained using `mysqlx_error()` function

 @note this function does not return names of tables that represent
 collections, use `mysqlx_get_collections()` function for getting
 collections.

 @ingroup xapi_sess
*/

PUBLIC_APImysqlx_result_t*
mysqlx_get_tables(mysqlx_schema_t*schema,
constchar*table_pattern,
intget_views);


/**
 Get a table object and optionally check if it exists in the schema

 @param schema schema handle
 @param tab_name name of the table
 @param check flag to verify if the table with the given name
 exists in the schema (1 - check, 0 - do not check)

 @return handle to the table or NULL
 if an error occurred or the table does not exist in the schema

 @note Performing existence check involves communication with server(s).
 Without the check, this operation is executed locally. It is then possible
 to create a handle to a non-existent table. Attempt to use such
 a handle later would eventually trigger an error.

 @ingroup xapi_sess
*/

PUBLIC_APImysqlx_table_t*
mysqlx_get_table(mysqlx_schema_t*schema, constchar*tab_name,
unsigned intcheck);