X DevAPI for C

Functions and types defined by X DevAPI for C. More...

Modules
	Session operations
	Statements operating on document collections
	Statements operating on tables
	SQL execution
	DDL statements
	Statement execution
	Result processing
	Meta data access
	Diagnostics

Files
file	xapi.h
	The main header for MySQL Connector/C++ X DevAPI for C.

Functions
mysqlx_session_t *	mysqlx_get_session_from_client (mysqlx_client_t *cli, mysqlx_error_t **error)
	Create a new session. More...

Macros
#define	RESULT_OK   0
	Return value indicating function/operation success.
#define	RESULT_MORE_DATA   8
	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()
#define	RESULT_NULL   16
	Return value flag indicating end of data items (documents or rows) in a query result. More...
#define	RESULT_INFO   32
	Return value flag indicating that operation generated information diagnostic entries.
#define	RESULT_WARNING   64
	Return value flag indicating that operation generated warnings.
#define	RESULT_ERROR   128
	Return value flag indicating function/operation error.

Typedefs
typedef struct mysqlx_error_struct	mysqlx_error_t
	Type of error handles. More...
typedef struct mysqlx_session_struct	mysqlx_session_t
	Type of session handles. More...
typedef struct mysqlx_client_struct	mysqlx_client_t
	Type of client handles. More...
typedef struct mysqlx_session_options_struct	mysqlx_session_options_t
	Type of handles for session configuration data. More...
typedef struct mysqlx_collection_options_struct	mysqlx_collection_options_t
	Type of handles for collection create/modify options. More...
typedef struct mysqlx_schema_struct	mysqlx_schema_t
	Type of database schema handles. More...
typedef struct mysqlx_collection_struct	mysqlx_collection_t
	Type of collection handles. More...
typedef struct mysqlx_table_struct	mysqlx_table_t
	Type of table handles. More...
typedef struct mysqlx_stmt_struct	mysqlx_stmt_t
	Type of statement handles. More...
typedef struct mysqlx_row_struct	mysqlx_row_t
	Type of row handles. More...
typedef struct mysqlx_result_struct	mysqlx_result_t
	Type of result handles. More...

Enumerations
enum	mysqlx_data_type_t { }
	The data type identifiers used in MYSQLX API. More...
enum	mysqlx_sort_direction_t { SORT_ORDER_ASC = 1 , SORT_ORDER_DESC = 2 }
	Sort directions in sorting operations such as ORDER BY. More...
enum	mysqlx_client_opt_type_t { MYSQLX_CLIENT_OPT_POOLING = - 1 , MYSQLX_CLIENT_OPT_POOL_MAX_SIZE = - 2 , MYSQLX_CLIENT_OPT_POOL_QUEUE_TIMEOUT = - 3 , MYSQLX_CLIENT_OPT_POOL_MAX_IDLE_TIME = - 4 }
	Client options for use with mysqlx_session_option_get() and mysqlx_session_option_set() functions. More...
enum	mysqlx_opt_type_t {   MYSQLX_OPT_URI = 1 , MYSQLX_OPT_HOST = 2 , MYSQLX_OPT_PORT = 3 , MYSQLX_OPT_PRIORITY = 4 ,   MYSQLX_OPT_USER = 5 , MYSQLX_OPT_PWD = 6 , MYSQLX_OPT_DB = 7 , MYSQLX_OPT_SSL_MODE = 8 ,   MYSQLX_OPT_SSL_CA = 9 , MYSQLX_OPT_AUTH = 10 , MYSQLX_OPT_SOCKET = 11 , MYSQLX_OPT_CONNECT_TIMEOUT = 12 ,   MYSQLX_OPT_CONNECTION_ATTRIBUTES = 13 , MYSQLX_OPT_TLS_VERSIONS = 14 , MYSQLX_OPT_TLS_CIPHERSUITES = 15 , MYSQLX_OPT_DNS_SRV = 16 ,   MYSQLX_OPT_COMPRESSION = 17 , MYSQLX_OPT_COMPRESSION_ALGORITHMS = 18 , MYSQLX_OPT_SSL_CAPATH = 19 , MYSQLX_OPT_SSL_CRL = 20 ,   MYSQLX_OPT_SSL_CRLPATH = 21 , MYSQLX_OPT_LAST }
	Session options for use with mysqlx_session_option_get() and mysqlx_session_option_set() functions. More...
enum	mysqlx_ssl_mode_t { SSL_MODE_DISABLED = 1 , SSL_MODE_REQUIRED = 2 , SSL_MODE_VERIFY_CA = 3 , SSL_MODE_VERIFY_IDENTITY = 4 }
	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. More...
enum	mysqlx_auth_method_t { MYSQLX_AUTH_PLAIN = 1 , MYSQLX_AUTH_MYSQL41 = 2 , MYSQLX_AUTH_EXTERNAL = 3 , MYSQLX_AUTH_SHA256_MEMORY = 4 }
	Authentication method values for use with mysqlx_session_option_get() and mysqlx_session_option_set() functions setting or getting MYSQLX_OPT_AUTH option. More...
enum	mysqlx_collection_opt_t { MYSQLX_OPT_COLLECTION_REUSE = 1 , MYSQLX_OPT_COLLECTION_VALIDATION = 2 , MYSQLX_OPT_COLLECTION_LAST }
	Collection create/modify options. More...
enum	mysqlx_collection_validation_opt_t { MYSQLX_OPT_COLLECTION_VALIDATION_SCHEMA = 1024+ 1 , MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL = 1024+ 2 , MYSQLX_OPT_COLLECTION_VALIDATION_LAST }
	Collection validation options. More...
enum	mysqlx_collection_validation_level_t { MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_OFF = 2048+ 1 , MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_STRICT = 2048+ 2 , MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_LAST }
	Collection validation level options . More...
enum	mysqlx_compression_mode_t { MYSQLX_COMPRESSION_DISABLED = 1 , MYSQLX_COMPRESSION_PREFERRED = 2 , MYSQLX_COMPRESSION_REQUIRED = 3 }
	Compression modes. More...
enum	mysqlx_row_locking_t { ROW_LOCK_NONE = 0 , ROW_LOCK_SHARED = 1 , ROW_LOCK_EXCLUSIVE = 2 }
	Constants for defining the row locking options for mysqlx_set_row_locking() function. More...
enum	mysqlx_lock_contention_t { LOCK_CONTENTION_DEFAULT = 0 , LOCK_CONTENTION_NOWAIT = 1 , LOCK_CONTENTION_SKIP_LOCKED = 2 }
	Constants for defining the row locking options for mysqlx_set_row_locking() function. More...

Detailed Description

Functions and types defined by X DevAPI for C.

See Connector/C++ X DevAPI for C Example for introduction.

Macro Definition Documentation

RESULT_NULL

#define RESULT_NULL   16

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.

Typedef Documentation

mysqlx_error_t

typedef struct mysqlx_error_struct mysqlx_error_t

Type of error handles.

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

See also

mysqlx_error()

mysqlx_session_t

typedef struct mysqlx_session_struct mysqlx_session_t

Type of session handles.

See also

mysqlx_get_session()

mysqlx_client_t

typedef struct mysqlx_client_struct mysqlx_client_t

Type of client handles.

See also

mysqlx_get_client()

mysqlx_session_options_t

typedef struct mysqlx_session_options_struct mysqlx_session_options_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 also

mysqlx_get_session_from_options(), mysqlx_session_options_new(), mysqlx_session_option_set(), mysqlx_free().

mysqlx_collection_options_t

typedef struct mysqlx_collection_options_struct mysqlx_collection_options_t

Type of handles for collection create/modify options.

See also

mysqlx_collection_options_new(), mysqlx_collection_options_set(), mysqlx_free().

mysqlx_schema_t

typedef struct mysqlx_schema_struct mysqlx_schema_t

Type of database schema handles.

See also

mysqlx_get_schema()

mysqlx_collection_t

typedef struct mysqlx_collection_struct mysqlx_collection_t

Type of collection handles.

See also

mysqlx_get_collection()

mysqlx_table_t

typedef struct mysqlx_table_struct mysqlx_table_t

Type of table handles.

See also

mysqlx_get_table()

mysqlx_stmt_t

typedef struct mysqlx_stmt_struct mysqlx_stmt_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 also

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()

mysqlx_row_t

typedef struct mysqlx_row_struct mysqlx_row_t

Type of row handles.

See also

mysqlx_row_fetch_one()

mysqlx_result_t

typedef struct mysqlx_result_struct mysqlx_result_t

Type of result handles.

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

See also

mysqlx_execute(), mysqlx_store_result(), mysqlx_row_fetch_one(), mysqlx_json_fetch_one(), mysqlx_next_result())

Enumeration Type Documentation

mysqlx_data_type_t

enum mysqlx_data_type_t

The data type identifiers used in MYSQLX API.

Enumerator
MYSQLX_TYPE_SINT	64-bit signed integer number type
MYSQLX_TYPE_UINT	64-bit unsigned integer number type
MYSQLX_TYPE_DOUBLE	Floating point double number type.
MYSQLX_TYPE_FLOAT	Floating point float number type.
MYSQLX_TYPE_BYTES	Bytes array type.
MYSQLX_TYPE_TIME	Time type.
MYSQLX_TYPE_DATETIME	Datetime type.
MYSQLX_TYPE_SET	Set type.
MYSQLX_TYPE_ENUM	Enum type.
MYSQLX_TYPE_BIT	Bit type.
MYSQLX_TYPE_DECIMAL	Decimal type.
MYSQLX_TYPE_BOOL	Bool type.
MYSQLX_TYPE_JSON	JSON type.
MYSQLX_TYPE_STRING	String type.
MYSQLX_TYPE_GEOMETRY	Geometry type.
MYSQLX_TYPE_TIMESTAMP	Timestamp type.
MYSQLX_TYPE_NULL	NULL value.
MYSQLX_TYPE_EXPR	Expression type.

mysqlx_sort_direction_t

enum mysqlx_sort_direction_t

Sort directions in sorting operations such as ORDER BY.

Enumerator
SORT_ORDER_ASC	Ascending sorting (Default)
SORT_ORDER_DESC	Descending sorting.

mysqlx_client_opt_type_t

enum mysqlx_client_opt_type_t

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

Enumerator
MYSQLX_CLIENT_OPT_POOLING	disable/enable the pool. (Enabled by default)
MYSQLX_CLIENT_OPT_POOL_MAX_SIZE	size of the pool. (Defaults to 25)
MYSQLX_CLIENT_OPT_POOL_QUEUE_TIMEOUT	timeout for waiting for a connection in the pool (ms). (No timeout by default)
MYSQLX_CLIENT_OPT_POOL_MAX_IDLE_TIME	time for a connection to be in the pool without being used (ms).(Will not expire by default)

mysqlx_opt_type_t

enum mysqlx_opt_type_t

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.

Enumerator
MYSQLX_OPT_URI	connection URI or string
MYSQLX_OPT_HOST	DNS name of the host, IPv4 address or IPv6 address
MYSQLX_OPT_PORT	X Plugin port to connect to
MYSQLX_OPT_PRIORITY	Assign a priority (a number in range 1 to 100) to the last specified host; these priorities are used to determine the order in which multiple hosts are tried by the connection fail-over logic (see description of Session class)
MYSQLX_OPT_USER	user name
MYSQLX_OPT_PWD	password
MYSQLX_OPT_DB	default database
MYSQLX_OPT_SSL_MODE	Specify SSLMode option to be used. In plain C code the value should be a #mysqlx_ssl_mode_t enum constant.
MYSQLX_OPT_SSL_CA	path to a PEM file specifying trusted root certificates
MYSQLX_OPT_AUTH	Authentication method to use, see AuthMethod. In plain C code the value should be a #mysqlx_auth_method_t enum constant.
MYSQLX_OPT_SOCKET	unix socket path
MYSQLX_OPT_CONNECT_TIMEOUT	Sets connection timeout in milliseconds. In C++ code can be also set to a std::chrono::duration value.
MYSQLX_OPT_CONNECTION_ATTRIBUTES	Specifies connection attributes (key-value pairs) to be sent when a session is created. The value is a JSON string (in C++ code can be also a DbDoc object) defining additional attributes to be sent on top of the default ones. Setting this option to false (in C++ code) or NULL (in plain C code) disables sending any connection attributes (including the default ones). Setting it to true (in C++ code) or empty string (in plain C code) requests sending only the default attributes which is also the default behavior when this option is not set.
MYSQLX_OPT_TLS_VERSIONS	List of allowed TLS protocol versions, such as "TLSv1.2". The value is a string with comma separated versions. In C++ code it can also be an iterable container with versions.
MYSQLX_OPT_TLS_CIPHERSUITES	List of allowed TLS cipher suites. The value is a string with comma separated IANA cipher suitenames (such as "TLS_RSA_WITH_3DES_EDE_CBC_SHA"). In C++ code it can also be an iterable container with names. Unknown cipher suites are silently ignored.
MYSQLX_OPT_DNS_SRV	If enabled (true) will check hostname for DNS SRV record and use its configuration (hostname, port, priority and weight) to connect.
MYSQLX_OPT_COMPRESSION	enable or disable compression
MYSQLX_OPT_COMPRESSION_ALGORITHMS	Specify compression algorithms in order of preference
MYSQLX_OPT_SSL_CAPATH	Path to a directory containing PEM files specifying trusted root certificates.
MYSQLX_OPT_SSL_CRL	Path to a PEM file containing certificate revocation lists
MYSQLX_OPT_SSL_CRLPATH	Path to a directory containing PEM files with certificate revocation lists

mysqlx_ssl_mode_t

enum mysqlx_ssl_mode_t

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.

Enumerator
SSL_MODE_DISABLED	Establish an unencrypted connection.
SSL_MODE_REQUIRED	Establish a secure connection if the server supports secure connections. The connection attempt fails if a secure connection cannot be established. This is the default if SSL_MODE is not specified.
SSL_MODE_VERIFY_CA	Like REQUIRED, but additionally verify the server TLS certificate against the configured Certificate Authority (CA) certificates (defined by SSL_CA Option). The connection attempt fails if no valid matching CA certificates are found.
SSL_MODE_VERIFY_IDENTITY	Like VERIFY_CA, but additionally verify that the server certificate matches the host to which the connection is attempted.

mysqlx_auth_method_t

enum mysqlx_auth_method_t

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

Enumerator
MYSQLX_AUTH_PLAIN	Plain text authentication method. The password is sent as a clear text. This method is used by default in encrypted connections.
MYSQLX_AUTH_MYSQL41	Authentication method supported by MySQL 4.1 and newer. The password is hashed before being sent to the server. This authentication method works over unencrypted connections
MYSQLX_AUTH_EXTERNAL	External authentication when the server establishes the user authenticity by other means such as SSL/x509 certificates. Currently not supported by X Plugin
MYSQLX_AUTH_SHA256_MEMORY	Authentication using SHA256 password hashes stored in server-side cache. This authentication method works over unencrypted connections.

mysqlx_collection_opt_t

enum mysqlx_collection_opt_t

Collection create/modify options.

Enumerator
MYSQLX_OPT_COLLECTION_REUSE	Use existing collection. Expects a boolean value.
MYSQLX_OPT_COLLECTION_VALIDATION	Collection validation options. Expects CollectionValidation or a json string.

mysqlx_collection_validation_opt_t

enum mysqlx_collection_validation_opt_t

Collection validation options.

Enumerator
MYSQLX_OPT_COLLECTION_VALIDATION_SCHEMA	Collection validation schema, as defined by https://dev.mysql.com/doc/refman/8.0/en/json-validation-functions.html#function_json-schema-valid
MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL	Defines level of validation on the collection, see CollectionValidation::Level. In plain C code the value should be mysqlx_collection_validation_level_t.

mysqlx_collection_validation_level_t

enum mysqlx_collection_validation_level_t

Collection validation level options .

Enumerator
MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_OFF	No validation will be done on the collection.
MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_STRICT	All collection documents have to comply to validation schema.

mysqlx_compression_mode_t

enum mysqlx_compression_mode_t

Compression modes.

TODO: see...

Enumerator
MYSQLX_COMPRESSION_DISABLED	Disables the compression.
MYSQLX_COMPRESSION_PREFERRED	Request compression, but not return error if compression is requested, but could not be used
MYSQLX_COMPRESSION_REQUIRED	Request compression and return error if compression is not supported by the server

mysqlx_row_locking_t

enum mysqlx_row_locking_t

Constants for defining the row locking options for mysqlx_set_row_locking() function.

See also

https://dev.mysql.com/doc/refman/8.0/en/innodb-locking-reads.html

Enumerator
ROW_LOCK_NONE	No locking.
ROW_LOCK_SHARED	Sets a shared mode lock on any rows that are read. Other sessions can read the rows, but cannot modify them until your transaction commits. If any of these rows were changed by another transaction that has not yet committed, your query waits until that transaction ends and then uses the latest values.
ROW_LOCK_EXCLUSIVE	For index records the search encounters, locks the rows and any associated index entries, the same as if you issued an UPDATE statement for those rows. Other transactions are blocked from updating those rows, from doing locking in LOCK_SHARED, or from reading the data in certain transaction isolation levels.

mysqlx_lock_contention_t

enum mysqlx_lock_contention_t

Constants for defining the row locking options for mysqlx_set_row_locking() function.

See also

https://dev.mysql.com/doc/refman/8.0/en/innodb-locking-reads.html#innodb-locking-reads-nowait-skip-locked

Enumerator
LOCK_CONTENTION_DEFAULT	Block query until existing row locks are released.
LOCK_CONTENTION_NOWAIT	Return error if lock could not be obtained immediately.
LOCK_CONTENTION_SKIP_LOCKED	Execute query immediately, excluding items that are locked from the query results.

Function Documentation

mysqlx_get_session_from_client()

mysqlx_session_t * mysqlx_get_session_from_client	(	mysqlx_client_t *	cli,
		mysqlx_error_t **	error
	)

Create a new session.

Parameters

	cli	client pool to get session from
[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().