MySQL 9.1.0
Source Code Documentation
service_command.h File Reference

Header file for the Command service. More...

#include "mysql/com_data.h"
#include "mysql/service_srv_session.h"
#include "decimal.h"
#include "mysql_time.h"
#include <stdint.h>
#include "field_types.h"
#include "mysql/strings/m_ctype.h"

Go to the source code of this file.

Classes

struct  st_send_field
 
struct  st_command_service_cbs
 
struct  command_service_st
 

Typedefs

typedef int(* start_result_metadata_t) (void *ctx, uint num_cols, uint flags, const CHARSET_INFO *resultcs)
 Indicates beginning of metadata for the result set. More...
 
typedef int(* field_metadata_t) (void *ctx, struct st_send_field *field, const CHARSET_INFO *charset)
 Field metadata is provided via this callback. More...
 
typedef int(* end_result_metadata_t) (void *ctx, uint server_status, uint warn_count)
 Indicates end of metadata for the result set. More...
 
typedef int(* start_row_t) (void *ctx)
 Indicates the beginning of a new row in the result set/metadata. More...
 
typedef int(* end_row_t) (void *ctx)
 Indicates the end of the current row in the result set/metadata. More...
 
typedef void(* abort_row_t) (void *ctx)
 An error occurred during execution. More...
 
typedef ulong(* get_client_capabilities_t) (void *ctx)
 Return client's capabilities (see mysql_com.h, CLIENT_*) More...
 
typedef int(* get_null_t) (void *ctx)
 Receive NULL value from server. More...
 
typedef int(* get_integer_t) (void *ctx, longlong value)
 Receive TINY/SHORT/LONG value from server. More...
 
typedef int(* get_longlong_t) (void *ctx, longlong value, uint is_unsigned)
 Get LONGLONG value from server. More...
 
typedef int(* get_decimal_t) (void *ctx, const decimal_t *value)
 Receive DECIMAL value from server. More...
 
typedef int(* get_double_t) (void *ctx, double value, uint32_t decimals)
 Receive FLOAT/DOUBLE from server. More...
 
typedef int(* get_date_t) (void *ctx, const MYSQL_TIME *value)
 Get DATE value from server. More...
 
typedef int(* get_time_t) (void *ctx, const MYSQL_TIME *value, uint decimals)
 Receive TIME value from server. More...
 
typedef int(* get_datetime_t) (void *ctx, const MYSQL_TIME *value, uint decimals)
 Receive DATETIME value from server. More...
 
typedef int(* get_string_t) (void *ctx, const char *value, size_t length, const CHARSET_INFO *valuecs)
 Get STRING value from server. More...
 
typedef void(* handle_ok_t) (void *ctx, uint server_status, uint statement_warn_count, ulonglong affected_rows, ulonglong last_insert_id, const char *message)
 Command ended with success. More...
 
typedef void(* handle_error_t) (void *ctx, uint sql_errno, const char *err_msg, const char *sqlstate)
 Command ended with ERROR. More...
 
typedef void(* shutdown_t) (void *ctx, int server_shutdown)
 Callback for shutdown notification from the server. More...
 
typedef bool(* connection_alive_t) (void *ctx)
 If the user of the srv_service is bound to a connection, this callback makes it possible to check if the connection is still alive. More...
 

Enumerations

enum  cs_text_or_binary { CS_TEXT_REPRESENTATION = 1 , CS_BINARY_REPRESENTATION = 2 }
 

Functions

int command_service_run_command (MYSQL_SESSION session, enum enum_server_command command, const union COM_DATA *data, const CHARSET_INFO *client_cs, const struct st_command_service_cbs *callbacks, enum cs_text_or_binary text_or_binary, void *service_callbacks_ctx)
 Executes a server command in a session. More...
 

Variables

struct command_service_stcommand_service
 

Detailed Description

Header file for the Command service.

This service is to provide means of executing different commands, like COM_QUERY, COM_STMT_PREPARE, in the server.

Typedef Documentation

◆ abort_row_t

typedef void(* abort_row_t) (void *ctx)

An error occurred during execution.

This callback indicates that an error occurred during command execution and the partial row should be dropped. Server will raise error and return.

Parameters
ctxPlugin's context

◆ connection_alive_t

typedef bool(* connection_alive_t) (void *ctx)

If the user of the srv_service is bound to a connection, this callback makes it possible to check if the connection is still alive.

It should always return true unless the client closed the connection.

Returns
true if the connection is still alive false otherwise

◆ end_result_metadata_t

typedef int(* end_result_metadata_t) (void *ctx, uint server_status, uint warn_count)

Indicates end of metadata for the result set.

Parameters
ctxPlugin's context
server_statusStatus of server (see mysql_com.h, SERVER_STATUS_*)
warn_countNumber of warnings generated during execution to the moment when the metadata is sent.
Returns
1 an error occurred, server will abort the command 0 ok

◆ end_row_t

typedef int(* end_row_t) (void *ctx)

Indicates the end of the current row in the result set/metadata.

Parameters
ctxPlugin's context
Returns
1 an error occurred, server will abort the command 0 ok

◆ field_metadata_t

typedef int(* field_metadata_t) (void *ctx, struct st_send_field *field, const CHARSET_INFO *charset)

Field metadata is provided via this callback.

Parameters
ctxPlugin's context
fieldField's metadata (see field.h)
charsetField's charset
Returns
1 an error occurred, server will abort the command 0 ok

◆ get_client_capabilities_t

typedef ulong(* get_client_capabilities_t) (void *ctx)

Return client's capabilities (see mysql_com.h, CLIENT_*)

Parameters
ctxPlugin's context
Returns
Bitmap of client's capabilities

◆ get_date_t

typedef int(* get_date_t) (void *ctx, const MYSQL_TIME *value)

Get DATE value from server.

Parameters
ctxPlugin's context
valueValue received
Returns
1 an error occurred during storing, server will abort the command 0 ok

◆ get_datetime_t

typedef int(* get_datetime_t) (void *ctx, const MYSQL_TIME *value, uint decimals)

Receive DATETIME value from server.

Parameters
ctxPlugin's context
valueValue received
decimalsNumber of decimals
Returns
1 an error occurred during storing, server will abort the command 0 ok

◆ get_decimal_t

typedef int(* get_decimal_t) (void *ctx, const decimal_t *value)

Receive DECIMAL value from server.

Parameters
ctxPlugin's context
valueValue received
Returns
1 an error occurred, server will abort the command 0 ok

◆ get_double_t

typedef int(* get_double_t) (void *ctx, double value, uint32_t decimals)

Receive FLOAT/DOUBLE from server.

Parameters
ctxPlugin's context
valueValue received
decimalsNumber of decimals
Note
In order to know which type exactly was received, the plugin must track the metadata that was sent just prior to the result set.
Returns
1 an error occurred, server will abort the command 0 ok

◆ get_integer_t

typedef int(* get_integer_t) (void *ctx, longlong value)

Receive TINY/SHORT/LONG value from server.

Parameters
ctxPlugin's context
valueValue received
Note
In order to know which type exactly was received, the plugin must track the metadata that was sent just prior to the result set.
Returns
1 an error occurred, server will abort the command 0 ok

◆ get_longlong_t

typedef int(* get_longlong_t) (void *ctx, longlong value, uint is_unsigned)

Get LONGLONG value from server.

Parameters
ctxPlugin's context
valueValue received
is_unsignedTRUE <=> value is unsigned
Returns
1 an error occurred, server will abort the command 0 ok

◆ get_null_t

typedef int(* get_null_t) (void *ctx)

Receive NULL value from server.

Parameters
ctxPlugin's context
Returns
1 an error occurred, server will abort the command 0 ok

◆ get_string_t

typedef int(* get_string_t) (void *ctx, const char *value, size_t length, const CHARSET_INFO *valuecs)

Get STRING value from server.

Parameters
ctxPlugin's context
valueData
lengthData length
valuecsData charset
Note
In case of CS_BINARY_REPRESENTATION, get_string() receives as a parameter the charset of the string, as it is stored on disk.

In case of CS_TEXT_REPRESENTATION, the string value might be already a stringified value or non-string data, which is in character_set_results.

See also
start_result_metadata()
Returns
1 an error occurred, server will abort the command 0 ok

◆ get_time_t

typedef int(* get_time_t) (void *ctx, const MYSQL_TIME *value, uint decimals)

Receive TIME value from server.

Parameters
ctxPlugin's context
valueValue received
decimalsNumber of decimals
Returns
1 an error occurred during storing, server will abort the command 0 ok

◆ handle_error_t

typedef void(* handle_error_t) (void *ctx, uint sql_errno, const char *err_msg, const char *sqlstate)

Command ended with ERROR.

Parameters
ctxPlugin's context
sql_errnoError code
err_msgError message
sqlstateSQL state corresponding to the error code

◆ handle_ok_t

typedef void(* handle_ok_t) (void *ctx, uint server_status, uint statement_warn_count, ulonglong affected_rows, ulonglong last_insert_id, const char *message)

Command ended with success.

Parameters
ctxPlugin's context
server_statusStatus of server (see mysql_com.h, SERVER_STATUS_*)
statement_warn_countNumber of warnings thrown during execution
affected_rowsNumber of rows affected by the command
last_insert_idLast insert id being assigned during execution
messageA message from server

◆ shutdown_t

typedef void(* shutdown_t) (void *ctx, int server_shutdown)

Callback for shutdown notification from the server.

Parameters
ctxPlugin's context
server_shutdownWhether this is a normal connection shutdown (0) or server shutdown (1).

◆ start_result_metadata_t

typedef int(* start_result_metadata_t) (void *ctx, uint num_cols, uint flags, const CHARSET_INFO *resultcs)

Indicates beginning of metadata for the result set.

Parameters
ctxPlugin's context
num_colsNumber of fields being sent
flagsFlags to alter the metadata sending
resultcsCharset of the result set
Note
resultcs is the charset in which the data should be encoded before sent to the client. This is the value of the session variable character_set_results. The implementor most probably will need to save this value in the context and use it as "to" charset in get_string().

In case of CS_BINARY_REPRESENTATION, get_string() receives as a parameter the charset of the string, as it is stored on disk.

In case of CS_TEXT_REPRESENTATION, the string value might be already a stringified value or non-string data, which is in character_set_results.

Returns
1 an error occurred, server will abort the command 0 ok

◆ start_row_t

typedef int(* start_row_t) (void *ctx)

Indicates the beginning of a new row in the result set/metadata.

Parameters
ctxPlugin's context
Returns
1 an error occurred, server will abort the command 0 ok

Enumeration Type Documentation

◆ cs_text_or_binary

Enumerator
CS_TEXT_REPRESENTATION 
CS_BINARY_REPRESENTATION 

Function Documentation

◆ command_service_run_command()

int command_service_run_command ( MYSQL_SESSION  session,
enum enum_server_command  command,
const union COM_DATA data,
const CHARSET_INFO client_cs,
const struct st_command_service_cbs callbacks,
enum cs_text_or_binary  text_or_binary,
void *  service_callbacks_ctx 
)

Executes a server command in a session.

There are two cases. Execution in a physical thread :

  1. initialized by the srv_session service
  2. NOT initialized by the srv_session service

In case of 1, if there is currently attached session, and it is different from the passed one, the former will be automatically detached. The session to be used for the execution will then be attached. After the command is executed, the attached session will not be detached. It will be detached by a next call to run_command() with another session as parameter. In other words, for all sessions used in a physical thread, there will be at most one in attached state.

In case of 2, the current state (current_thd) will be preserved. Then the given session will move to attached state and the command will be executed. After the execution the state of the session will be changed to detached and the preserved state (current_thd) will be restored.

The client charset is used for commands like COM_QUERY and COM_STMT_PREPARE to know how to threat the char* fields. This charset will be used until the next call of run_command when it may be changed again.

Parameters
sessionThe session
commandThe command to be executed.
dataThe data needed for the command to be executed
client_csThe charset for the string data input(COM_QUERY for example)
callbacksCallbacks to be used by the server to encode data and to communicate with the client (plugin) side.
text_or_binarySelect which representation the server will use for the data passed to the callbacks. For more information
See also
cs_text_or_binary enum
Parameters
service_callbacks_ctxContext passed to the command service callbacks
Returns
0 success 1 failure

Variable Documentation

◆ command_service

struct command_service_st * command_service