mysqlnd_wireprotocol.h

Go to the documentation of this file.

/*
  +----------------------------------------------------------------------+
  | Copyright (c) The PHP Group                                          |
  +----------------------------------------------------------------------+
  | This source file is subject to version 3.01 of the PHP license,      |
  | that is bundled with this package in the file LICENSE, and is        |
  | available through the world-wide-web at the following url:           |
  | https://www.php.net/license/3_01.txt                                 |
  | If you did not receive a copy of the PHP license and are unable to   |
  | obtain it through the world-wide-web, please send a note to          |
  | license@php.net so we can mail you a copy immediately.               |
  +----------------------------------------------------------------------+
  | Authors: Andrey Hristov <andrey@php.net>                             |
  |          Ulf Wendel <uw@php.net>                                     |
  +----------------------------------------------------------------------+
*/
 
#ifndef MYSQLND_WIREPROTOCOL_H
#define MYSQLND_WIREPROTOCOL_H
 
#define MYSQLND_HEADER_SIZE 4
#define COMPRESSED_HEADER_SIZE 3
 
#define MYSQLND_NULL_LENGTH (zend_ulong) ~0
 
/* Used in mysqlnd_debug.c */
PHPAPI extern const char mysqlnd_read_header_name[];
PHPAPI extern const char mysqlnd_read_body_name[];
 
 
/* Packet handling */
#define PACKET_WRITE(conn, packet)  ((packet)->header.m->write_to_net((conn), (packet)))
#define PACKET_READ(conn, packet)   ((packet)->header.m->read_from_net((conn), (packet)))
#define PACKET_FREE(packet) \
    do { \
        DBG_INF_FMT("PACKET_FREE(%p)", packet); \
        if ((packet)->header.m->free_mem) { \
            ((packet)->header.m->free_mem((packet))); \
        } \
    } while (0);
 
PHPAPI extern const char * const mysqlnd_command_to_text[COM_END];
 
/* Low-level extraction functionality */
typedef struct st_mysqlnd_packet_methods {
    enum_func_status    (*read_from_net)(MYSQLND_CONN_DATA * conn, void * packet);
    size_t              (*write_to_net)(MYSQLND_CONN_DATA * conn, void * packet);
    void                (*free_mem)(void *packet);
} mysqlnd_packet_methods;
 
 
typedef struct st_mysqlnd_packet_header {
    size_t      size;
    zend_uchar    packet_no;
 
    mysqlnd_packet_methods *m;
} MYSQLND_PACKET_HEADER;
 
/* Server greets the client */
typedef struct st_mysqlnd_packet_greet {
    MYSQLND_PACKET_HEADER      header;
    uint8_t     protocol_version;
    char        *server_version;
    uint32_t    thread_id;
    char        intern_auth_plugin_data[SCRAMBLE_LENGTH];
    MYSQLND_STRING authentication_plugin_data;
    /* 1 byte pad */
    uint32_t    server_capabilities;
    uint8_t     charset_no;
    uint16_t    server_status;
    /* 13 byte pad, in 5.5 first 2 bytes are more capabilities followed by 1 byte scramble_length */
    bool    pre41;
    /* If error packet, we use these */
    char        error[MYSQLND_ERRMSG_SIZE+1];
    char        sqlstate[MYSQLND_SQLSTATE_LENGTH + 1];
    unsigned int    error_no;
    char        *auth_protocol;
} MYSQLND_PACKET_GREET;
 
 
/* Client authenticates */
typedef struct st_mysqlnd_packet_auth {
    MYSQLND_PACKET_HEADER      header;
    const char  *user;
    const zend_uchar  *auth_data;
    size_t      auth_data_len;
    const char  *db;
    const char  *auth_plugin_name;
    uint32_t    client_flags;
    uint32_t    max_packet_size;
    uint8_t     charset_no;
    /* Here the packet ends. This is user supplied data */
    bool    send_auth_data;
    bool    is_change_user_packet;
    bool    silent;
    HashTable  *connect_attr;
    size_t      db_len;
} MYSQLND_PACKET_AUTH;
 
/* Auth response packet */
typedef struct st_mysqlnd_packet_auth_response {
    MYSQLND_PACKET_HEADER      header;
    uint8_t     response_code;
    uint64_t    affected_rows;
    uint64_t    last_insert_id;
    uint16_t    server_status;
    uint16_t    warning_count;
    char        *message;
    size_t      message_len;
    /* If error packet, we use these */
    char        error[MYSQLND_ERRMSG_SIZE+1];
    char        sqlstate[MYSQLND_SQLSTATE_LENGTH + 1];
    unsigned int    error_no;
 
    char        *new_auth_protocol;
    size_t      new_auth_protocol_len;
    zend_uchar    *new_auth_protocol_data;
    size_t      new_auth_protocol_data_len;
} MYSQLND_PACKET_AUTH_RESPONSE;
 
 
/* Auth response packet */
typedef struct st_mysqlnd_packet_change_auth_response {
    MYSQLND_PACKET_HEADER      header;
    const zend_uchar  *auth_data;
    size_t              auth_data_len;
} MYSQLND_PACKET_CHANGE_AUTH_RESPONSE;
 
 
/* OK packet */
typedef struct st_mysqlnd_packet_ok {
    MYSQLND_PACKET_HEADER      header;
    uint8_t     field_count; /* always 0x0 */
    uint64_t    affected_rows;
    uint64_t    last_insert_id;
    uint16_t    server_status;
    uint16_t    warning_count;
    char        *message;
    size_t      message_len;
    /* If error packet, we use these */
    char        error[MYSQLND_ERRMSG_SIZE+1];
    char        sqlstate[MYSQLND_SQLSTATE_LENGTH + 1];
    unsigned int    error_no;
} MYSQLND_PACKET_OK;
 
 
/* Command packet */
typedef struct st_mysqlnd_packet_command {
    MYSQLND_PACKET_HEADER          header;
    enum php_mysqlnd_server_command   command;
    MYSQLND_CSTRING  argument;
} MYSQLND_PACKET_COMMAND;
 
 
/* EOF packet */
typedef struct st_mysqlnd_packet_eof {
    MYSQLND_PACKET_HEADER      header;
    uint8_t     field_count; /* 0xFE */
    uint16_t    warning_count;
    uint16_t    server_status;
    /* If error packet, we use these */
    char        error[MYSQLND_ERRMSG_SIZE+1];
    char        sqlstate[MYSQLND_SQLSTATE_LENGTH + 1];
    unsigned int    error_no;
} MYSQLND_PACKET_EOF;
/* EOF packet */
 
 
/* Result Set header*/
typedef struct st_mysqlnd_packet_rset_header {
    MYSQLND_PACKET_HEADER header;
    /*
      0x00 => ok
      ~0   => LOAD DATA LOCAL
      error_no != 0 => error
      others => result set -> Read res_field packets up to field_count
    */
    zend_ulong        field_count;
    /*
      These are filled if no SELECT query. For SELECT warning_count
      and server status are in the last row packet, the EOF packet.
    */
    uint16_t    warning_count;
    uint16_t    server_status;
    uint64_t    affected_rows;
    uint64_t    last_insert_id;
    /* This is for both LOAD DATA or info, when no result set */
    MYSQLND_STRING info_or_local_file;
    /* If error packet, we use these */
    MYSQLND_ERROR_INFO    error_info;
} MYSQLND_PACKET_RSET_HEADER;
 
 
/* Result set field packet */
typedef struct st_mysqlnd_packet_res_field {
    MYSQLND_PACKET_HEADER  header;
    MYSQLND_MEMORY_POOL      *memory_pool;
    MYSQLND_FIELD          *metadata;
    /* For table definitions, empty for result sets */
    bool                skip_parsing;
 
    MYSQLND_ERROR_INFO        error_info;
} MYSQLND_PACKET_RES_FIELD;
 
 
/* Row packet */
typedef struct st_mysqlnd_packet_row {
    MYSQLND_PACKET_HEADER  header;
    uint32_t    field_count;
    bool    eof;
    /*
      These are, of course, only for SELECT in the EOF packet,
      which is detected by this packet
    */
    uint16_t    warning_count;
    uint16_t    server_status;
 
    MYSQLND_ROW_BUFFER    row_buffer;
    MYSQLND_MEMORY_POOL * result_set_memory_pool;
 
    bool        binary_protocol;
    MYSQLND_FIELD  *fields_metadata;
 
    /* If error packet, we use these */
    MYSQLND_ERROR_INFO    error_info;
} MYSQLND_PACKET_ROW;
 
 
/* Statistics packet */
typedef struct st_mysqlnd_packet_stats {
    MYSQLND_PACKET_HEADER  header;
    MYSQLND_STRING message;
} MYSQLND_PACKET_STATS;
 
 
/* COM_PREPARE response packet */
typedef struct st_mysqlnd_packet_prepare_response {
    MYSQLND_PACKET_HEADER  header;
    /* also known as field_count 0x00=OK , 0xFF=error */
    unsigned char   error_code;
    zend_ulong    stmt_id;
    unsigned int    field_count;
    unsigned int    param_count;
    unsigned int    warning_count;
 
    /* present in case of error */
    MYSQLND_ERROR_INFO    error_info;
} MYSQLND_PACKET_PREPARE_RESPONSE;
 
 
/* Statistics packet */
typedef struct st_mysqlnd_packet_chg_user_resp {
    MYSQLND_PACKET_HEADER  header;
    uint32_t            response_code;
 
    /* message_len is not part of the packet*/
    uint16_t            server_capabilities;
    /* If error packet, we use these */
    MYSQLND_ERROR_INFO    error_info;
    bool            server_asked_323_auth;
 
    char        *new_auth_protocol;
    size_t      new_auth_protocol_len;
    zend_uchar    *new_auth_protocol_data;
    size_t      new_auth_protocol_data_len;
} MYSQLND_PACKET_CHG_USER_RESPONSE;
 
 
/* Command packet */
typedef struct st_mysqlnd_packet_sha256_pk_request {
    MYSQLND_PACKET_HEADER          header;
} MYSQLND_PACKET_SHA256_PK_REQUEST;
 
typedef struct  st_mysqlnd_packet_sha256_pk_request_response {
    MYSQLND_PACKET_HEADER  header;
    zend_uchar                *public_key;
    size_t                  public_key_len;
} MYSQLND_PACKET_SHA256_PK_REQUEST_RESPONSE;
 
typedef struct st_mysqlnd_packet_cached_sha2_result {
    MYSQLND_PACKET_HEADER      header;
    uint8_t     response_code;
    uint8_t     result;
    uint8_t     request;
    zend_uchar * password;
    size_t password_len;
    /* Used for auth switch request */
    char        *new_auth_protocol;
    size_t      new_auth_protocol_len;
    zend_uchar    *new_auth_protocol_data;
    size_t      new_auth_protocol_data_len;
    /* Used for error result */
    char        error[MYSQLND_ERRMSG_SIZE+1];
    char        sqlstate[MYSQLND_SQLSTATE_LENGTH + 1];
    unsigned int    error_no;
} MYSQLND_PACKET_CACHED_SHA2_RESULT;
 
 
 
zend_ulong        php_mysqlnd_net_field_length(const zend_uchar **packet);
zend_uchar *  php_mysqlnd_net_store_length(zend_uchar *packet, const uint64_t length);
size_t          php_mysqlnd_net_store_length_size(uint64_t length);
 
PHPAPI extern const char * const mysqlnd_empty_string;
 
enum_func_status php_mysqlnd_rowp_read_binary_protocol(MYSQLND_ROW_BUFFER * row_buffer, zval * fields,
                                         unsigned int field_count, const MYSQLND_FIELD * fields_metadata,
                                         bool as_int_or_float, MYSQLND_STATS * stats);
 
 
enum_func_status php_mysqlnd_rowp_read_text_protocol(MYSQLND_ROW_BUFFER * row_buffer, zval * fields,
                                         unsigned int field_count, const MYSQLND_FIELD * fields_metadata,
                                         bool as_int_or_float, MYSQLND_STATS * stats);
 
 
PHPAPI MYSQLND_PROTOCOL_PAYLOAD_DECODER_FACTORY * mysqlnd_protocol_payload_decoder_factory_init(MYSQLND_CONN_DATA * conn, const bool persistent);
PHPAPI void mysqlnd_protocol_payload_decoder_factory_free(MYSQLND_PROTOCOL_PAYLOAD_DECODER_FACTORY * const payload_decoder_factory);
 
#endif /* MYSQLND_WIREPROTOCOL_H */