MySQL Connector/C++
MySQL connector library for C and C++ applications
Modules | Files | Functions | Macros | Typedefs | Enumerations
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_tmysqlx_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++ 8 X DevAPI for C Reference 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

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

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

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

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

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

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

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

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

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

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

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

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
cliclient pool to get session from
[out]errorif 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().