1 /* Copyright (c) 2000, 2021, Oracle and/or its affiliates. 2 3 This program is free software; you can redistribute it and/or modify 4 it under the terms of the GNU General Public License, version 2.0, 5 as published by the Free Software Foundation. 6 7 This program is also distributed with certain software (including 8 but not limited to OpenSSL) that is licensed under separate terms, 9 as designated in a particular file or component or in included license 10 documentation. The authors of MySQL hereby grant you an additional 11 permission to link the program and your derivative works with the 12 separately licensed software that they have included with MySQL. 13 14 Without limiting anything contained in the foregoing, this file, 15 which is part of C Driver for MySQL (Connector/C), is also subject to the 16 Universal FOSS Exception, version 1.0, a copy of which can be found at 17 http://oss.oracle.com/licenses/universal-foss-exception. 18 19 This program is distributed in the hope that it will be useful, 20 but WITHOUT ANY WARRANTY; without even the implied warranty of 21 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 22 GNU General Public License, version 2.0, for more details. 23 24 You should have received a copy of the GNU General Public License 25 along with this program; if not, write to the Free Software 26 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ 27 28 /* 29 This file defines the client API to MySQL and also the ABI of the 30 dynamically linked libperconaserverclient. 31 32 The ABI should never be changed in a released product of MySQL, 33 thus you need to take great care when changing the file. In case 34 the file is changed so the ABI is broken, you must also update 35 the SHARED_LIB_MAJOR_VERSION in cmake/mysql_version.cmake 36 */ 37 38 #ifndef _mysql_h 39 #define _mysql_h 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 #ifndef MY_GLOBAL_INCLUDED /* If not standard header */ 46 #ifndef MYSQL_ABI_CHECK 47 #include <sys/types.h> 48 #endif 49 typedef char my_bool; 50 #if !defined(_WIN32) 51 #define STDCALL 52 #else 53 #define STDCALL __stdcall 54 #endif 55 56 #ifndef my_socket_defined 57 #ifdef _WIN32 58 #include <windows.h> 59 #ifdef WIN32_LEAN_AND_MEAN 60 #include <winsock2.h> 61 #endif 62 #define my_socket SOCKET 63 #else 64 typedef int my_socket; 65 #endif /* _WIN32 */ 66 #endif /* my_socket_defined */ 67 #endif /* MY_GLOBAL_INCLUDED */ 68 69 #include "mysql_version.h" 70 #include "mysql_com.h" 71 #include "mysql_time.h" 72 73 #include "my_list.h" /* for LISTs used in 'MYSQL' and 'MYSQL_STMT' */ 74 75 /* Include declarations of plug-in API */ 76 #include "mysql/client_plugin.h" 77 78 extern unsigned int mysql_port; 79 extern char *mysql_unix_port; 80 81 #define CLIENT_NET_READ_TIMEOUT 365*24*3600 /* Timeout on read */ 82 #define CLIENT_NET_WRITE_TIMEOUT 365*24*3600 /* Timeout on write */ 83 84 #define IS_PRI_KEY(n) ((n) & PRI_KEY_FLAG) 85 #define IS_NOT_NULL(n) ((n) & NOT_NULL_FLAG) 86 #define IS_BLOB(n) ((n) & BLOB_FLAG) 87 /** 88 Returns true if the value is a number which does not need quotes for 89 the sql_lex.cc parser to parse correctly. 90 */ 91 #define IS_NUM(t) (((t) <= MYSQL_TYPE_INT24 && (t) != MYSQL_TYPE_TIMESTAMP) || (t) == MYSQL_TYPE_YEAR || (t) == MYSQL_TYPE_NEWDECIMAL) 92 #define IS_LONGDATA(t) ((t) >= MYSQL_TYPE_TINY_BLOB && (t) <= MYSQL_TYPE_STRING) 93 94 95 typedef struct st_mysql_field { 96 char *name; /* Name of column */ 97 char *org_name; /* Original column name, if an alias */ 98 char *table; /* Table of column if column was a field */ 99 char *org_table; /* Org table name, if table was an alias */ 100 char *db; /* Database for table */ 101 char *catalog; /* Catalog for table */ 102 char *def; /* Default value (set by mysql_list_fields) */ 103 unsigned long length; /* Width of column (create length) */ 104 unsigned long max_length; /* Max width for selected set */ 105 unsigned int name_length; 106 unsigned int org_name_length; 107 unsigned int table_length; 108 unsigned int org_table_length; 109 unsigned int db_length; 110 unsigned int catalog_length; 111 unsigned int def_length; 112 unsigned int flags; /* Div flags */ 113 unsigned int decimals; /* Number of decimals in field */ 114 unsigned int charsetnr; /* Character set */ 115 enum enum_field_types type; /* Type of field. See mysql_com.h for types */ 116 void *extension; 117 } MYSQL_FIELD; 118 119 typedef char **MYSQL_ROW; /* return data as array of strings */ 120 typedef unsigned int MYSQL_FIELD_OFFSET; /* offset to current field */ 121 122 #ifndef MY_GLOBAL_INCLUDED 123 #if defined (_WIN32) 124 typedef unsigned __int64 my_ulonglong; 125 #else 126 typedef unsigned long long my_ulonglong; 127 #endif 128 #endif 129 130 #include "typelib.h" 131 132 #define MYSQL_COUNT_ERROR (~(my_ulonglong) 0) 133 134 /* backward compatibility define - to be removed eventually */ 135 #define ER_WARN_DATA_TRUNCATED WARN_DATA_TRUNCATED 136 137 typedef struct st_mysql_rows { 138 struct st_mysql_rows *next; /* list of rows */ 139 MYSQL_ROW data; 140 unsigned long length; 141 } MYSQL_ROWS; 142 143 typedef MYSQL_ROWS *MYSQL_ROW_OFFSET; /* offset to current row */ 144 145 #include "my_alloc.h" 146 147 typedef struct embedded_query_result EMBEDDED_QUERY_RESULT; 148 typedef struct st_mysql_data { 149 MYSQL_ROWS *data; 150 struct embedded_query_result *embedded_info; 151 MEM_ROOT alloc; 152 my_ulonglong rows; 153 unsigned int fields; 154 /* extra info for embedded library */ 155 void *extension; 156 } MYSQL_DATA; 157 158 enum mysql_option 159 { 160 MYSQL_OPT_CONNECT_TIMEOUT, MYSQL_OPT_COMPRESS, MYSQL_OPT_NAMED_PIPE, 161 MYSQL_INIT_COMMAND, MYSQL_READ_DEFAULT_FILE, MYSQL_READ_DEFAULT_GROUP, 162 MYSQL_SET_CHARSET_DIR, MYSQL_SET_CHARSET_NAME, MYSQL_OPT_LOCAL_INFILE, 163 MYSQL_OPT_PROTOCOL, MYSQL_SHARED_MEMORY_BASE_NAME, MYSQL_OPT_READ_TIMEOUT, 164 MYSQL_OPT_WRITE_TIMEOUT, MYSQL_OPT_USE_RESULT, 165 MYSQL_OPT_USE_REMOTE_CONNECTION, MYSQL_OPT_USE_EMBEDDED_CONNECTION, 166 MYSQL_OPT_GUESS_CONNECTION, MYSQL_SET_CLIENT_IP, MYSQL_SECURE_AUTH, 167 MYSQL_REPORT_DATA_TRUNCATION, MYSQL_OPT_RECONNECT, 168 MYSQL_OPT_SSL_VERIFY_SERVER_CERT, MYSQL_PLUGIN_DIR, MYSQL_DEFAULT_AUTH, 169 MYSQL_OPT_BIND, 170 MYSQL_OPT_SSL_KEY, MYSQL_OPT_SSL_CERT, 171 MYSQL_OPT_SSL_CA, MYSQL_OPT_SSL_CAPATH, MYSQL_OPT_SSL_CIPHER, 172 MYSQL_OPT_SSL_CRL, MYSQL_OPT_SSL_CRLPATH, 173 MYSQL_OPT_CONNECT_ATTR_RESET, MYSQL_OPT_CONNECT_ATTR_ADD, 174 MYSQL_OPT_CONNECT_ATTR_DELETE, 175 MYSQL_SERVER_PUBLIC_KEY, 176 MYSQL_ENABLE_CLEARTEXT_PLUGIN, 177 MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS, 178 MYSQL_OPT_SSL_ENFORCE, 179 MYSQL_OPT_MAX_ALLOWED_PACKET, MYSQL_OPT_NET_BUFFER_LENGTH, 180 MYSQL_OPT_TLS_VERSION, 181 MYSQL_OPT_SSL_MODE, 182 MYSQL_OPT_GET_SERVER_PUBLIC_KEY 183 }; 184 185 /** 186 @todo remove the "extension", move st_mysql_options completely 187 out of mysql.h 188 */ 189 struct st_mysql_options_extention; 190 191 struct st_mysql_options { 192 unsigned int connect_timeout, read_timeout, write_timeout; 193 unsigned int port, protocol; 194 unsigned long client_flag; 195 char *host,*user,*password,*unix_socket,*db; 196 struct st_dynamic_array *init_commands; 197 char *my_cnf_file,*my_cnf_group, *charset_dir, *charset_name; 198 char *ssl_key; /* PEM key file */ 199 char *ssl_cert; /* PEM cert file */ 200 char *ssl_ca; /* PEM CA file */ 201 char *ssl_capath; /* PEM directory of CA-s? */ 202 char *ssl_cipher; /* cipher to use */ 203 char *shared_memory_base_name; 204 unsigned long max_allowed_packet; 205 my_bool use_ssl; /* Deprecated ! Former use_ssl */ 206 my_bool compress,named_pipe; 207 my_bool unused1; 208 my_bool unused2; 209 my_bool unused3; 210 my_bool unused4; 211 enum mysql_option methods_to_use; 212 union { 213 /* 214 The ip/hostname to use when authenticating 215 client against embedded server built with 216 grant tables - only used in embedded server 217 */ 218 char *client_ip; 219 220 /* 221 The local address to bind when connecting to 222 remote server - not used in embedded server 223 */ 224 char *bind_address; 225 } ci; 226 my_bool unused5; 227 /* 0 - never report, 1 - always report (default) */ 228 my_bool report_data_truncation; 229 230 /* function pointers for local infile support */ 231 int (*local_infile_init)(void **, const char *, void *); 232 int (*local_infile_read)(void *, char *, unsigned int); 233 void (*local_infile_end)(void *); 234 int (*local_infile_error)(void *, char *, unsigned int); 235 void *local_infile_userdata; 236 struct st_mysql_options_extention *extension; 237 }; 238 239 enum mysql_status 240 { 241 MYSQL_STATUS_READY, MYSQL_STATUS_GET_RESULT, MYSQL_STATUS_USE_RESULT, 242 MYSQL_STATUS_STATEMENT_GET_RESULT 243 }; 244 245 enum mysql_protocol_type 246 { 247 MYSQL_PROTOCOL_DEFAULT, MYSQL_PROTOCOL_TCP, MYSQL_PROTOCOL_SOCKET, 248 MYSQL_PROTOCOL_PIPE, MYSQL_PROTOCOL_MEMORY 249 }; 250 251 enum mysql_ssl_mode 252 { 253 SSL_MODE_DISABLED= 1, SSL_MODE_PREFERRED, SSL_MODE_REQUIRED, 254 SSL_MODE_VERIFY_CA, SSL_MODE_VERIFY_IDENTITY 255 }; 256 257 typedef struct character_set 258 { 259 unsigned int number; /* character set number */ 260 unsigned int state; /* character set state */ 261 const char *csname; /* collation name */ 262 const char *name; /* character set name */ 263 const char *comment; /* comment */ 264 const char *dir; /* character set directory */ 265 unsigned int mbminlen; /* min. length for multibyte strings */ 266 unsigned int mbmaxlen; /* max. length for multibyte strings */ 267 } MY_CHARSET_INFO; 268 269 struct st_mysql_methods; 270 struct st_mysql_stmt; 271 272 typedef struct st_mysql 273 { 274 NET net; /* Communication parameters */ 275 unsigned char *connector_fd; /* ConnectorFd for SSL */ 276 char *host,*user,*passwd,*unix_socket,*server_version,*host_info; 277 char *info, *db; 278 struct charset_info_st *charset; 279 MYSQL_FIELD *fields; 280 MEM_ROOT field_alloc; 281 my_ulonglong affected_rows; 282 my_ulonglong insert_id; /* id if insert on table with NEXTNR */ 283 my_ulonglong extra_info; /* Not used */ 284 unsigned long thread_id; /* Id for connection in server */ 285 unsigned long packet_length; 286 unsigned int port; 287 unsigned long client_flag,server_capabilities; 288 unsigned int protocol_version; 289 unsigned int field_count; 290 unsigned int server_status; 291 unsigned int server_language; 292 unsigned int warning_count; 293 struct st_mysql_options options; 294 enum mysql_status status; 295 my_bool free_me; /* If free in mysql_close */ 296 my_bool reconnect; /* set to 1 if automatic reconnect */ 297 298 /* session-wide random string */ 299 char scramble[SCRAMBLE_LENGTH+1]; 300 my_bool unused1; 301 void *unused2, *unused3, *unused4, *unused5; 302 303 LIST *stmts; /* list of all statements */ 304 const struct st_mysql_methods *methods; 305 void *thd; 306 /* 307 Points to boolean flag in MYSQL_RES or MYSQL_STMT. We set this flag 308 from mysql_stmt_close if close had to cancel result set of this object. 309 */ 310 my_bool *unbuffered_fetch_owner; 311 /* needed for embedded server - no net buffer to store the 'info' */ 312 char *info_buffer; 313 void *extension; 314 } MYSQL; 315 316 317 typedef struct st_mysql_res { 318 my_ulonglong row_count; 319 MYSQL_FIELD *fields; 320 MYSQL_DATA *data; 321 MYSQL_ROWS *data_cursor; 322 unsigned long *lengths; /* column lengths of current row */ 323 MYSQL *handle; /* for unbuffered reads */ 324 const struct st_mysql_methods *methods; 325 MYSQL_ROW row; /* If unbuffered read */ 326 MYSQL_ROW current_row; /* buffer to current row */ 327 MEM_ROOT field_alloc; 328 unsigned int field_count, current_field; 329 my_bool eof; /* Used by mysql_fetch_row */ 330 /* mysql_stmt_close() had to cancel this result */ 331 my_bool unbuffered_fetch_cancelled; 332 void *extension; 333 } MYSQL_RES; 334 335 336 #if !defined(MYSQL_SERVER) && !defined(MYSQL_CLIENT) 337 #define MYSQL_CLIENT 338 #endif 339 340 /* 341 Set up and bring down the server; to ensure that applications will 342 work when linked against either the standard client library or the 343 embedded server library, these functions should be called. 344 */ 345 int STDCALL mysql_server_init(int argc, char **argv, char **groups); 346 void STDCALL mysql_server_end(void); 347 348 /* 349 mysql_server_init/end need to be called when using libmysqld or 350 libperconaserverclient (exactly, mysql_server_init() is called by 351 mysql_init() so you don't need to call it explicitely; but you need to call 352 mysql_server_end() to free memory). The names are a bit misleading 353 (mysql_SERVER* to be used when using libmysqlCLIENT). So we add more general 354 names which suit well whether you're using libmysqld or 355 libperconaserverclient. We intend to promote these aliases over the 356 mysql_server* ones. 357 */ 358 #define mysql_library_init mysql_server_init 359 #define mysql_library_end mysql_server_end 360 361 362 /* 363 Set up and bring down a thread; these function should be called 364 for each thread in an application which opens at least one MySQL 365 connection. All uses of the connection(s) should be between these 366 function calls. 367 */ 368 my_bool STDCALL mysql_thread_init(void); 369 void STDCALL mysql_thread_end(void); 370 371 /* 372 Functions to get information from the MYSQL and MYSQL_RES structures 373 Should definitely be used if one uses shared libraries. 374 */ 375 376 my_ulonglong STDCALL mysql_num_rows(MYSQL_RES *res); 377 unsigned int STDCALL mysql_num_fields(MYSQL_RES *res); 378 my_bool STDCALL mysql_eof(MYSQL_RES *res); 379 MYSQL_FIELD *STDCALL mysql_fetch_field_direct(MYSQL_RES *res, 380 unsigned int fieldnr); 381 MYSQL_FIELD * STDCALL mysql_fetch_fields(MYSQL_RES *res); 382 MYSQL_ROW_OFFSET STDCALL mysql_row_tell(MYSQL_RES *res); 383 MYSQL_FIELD_OFFSET STDCALL mysql_field_tell(MYSQL_RES *res); 384 385 unsigned int STDCALL mysql_field_count(MYSQL *mysql); 386 my_ulonglong STDCALL mysql_affected_rows(MYSQL *mysql); 387 my_ulonglong STDCALL mysql_insert_id(MYSQL *mysql); 388 unsigned int STDCALL mysql_errno(MYSQL *mysql); 389 const char * STDCALL mysql_error(MYSQL *mysql); 390 const char *STDCALL mysql_sqlstate(MYSQL *mysql); 391 unsigned int STDCALL mysql_warning_count(MYSQL *mysql); 392 const char * STDCALL mysql_info(MYSQL *mysql); 393 unsigned long STDCALL mysql_thread_id(MYSQL *mysql); 394 const char * STDCALL mysql_character_set_name(MYSQL *mysql); 395 int STDCALL mysql_set_character_set(MYSQL *mysql, const char *csname); 396 397 MYSQL * STDCALL mysql_init(MYSQL *mysql); 398 my_bool STDCALL mysql_ssl_set(MYSQL *mysql, const char *key, 399 const char *cert, const char *ca, 400 const char *capath, const char *cipher); 401 const char * STDCALL mysql_get_ssl_cipher(MYSQL *mysql); 402 my_bool STDCALL mysql_change_user(MYSQL *mysql, const char *user, 403 const char *passwd, const char *db); 404 MYSQL * STDCALL mysql_real_connect(MYSQL *mysql, const char *host, 405 const char *user, 406 const char *passwd, 407 const char *db, 408 unsigned int port, 409 const char *unix_socket, 410 unsigned long clientflag); 411 int STDCALL mysql_select_db(MYSQL *mysql, const char *db); 412 int STDCALL mysql_query(MYSQL *mysql, const char *q); 413 int STDCALL mysql_send_query(MYSQL *mysql, const char *q, 414 unsigned long length); 415 int STDCALL mysql_real_query(MYSQL *mysql, const char *q, 416 unsigned long length); 417 MYSQL_RES * STDCALL mysql_store_result(MYSQL *mysql); 418 MYSQL_RES * STDCALL mysql_use_result(MYSQL *mysql); 419 420 void STDCALL mysql_get_character_set_info(MYSQL *mysql, 421 MY_CHARSET_INFO *charset); 422 423 int STDCALL mysql_session_track_get_first(MYSQL *mysql, 424 enum enum_session_state_type type, 425 const char **data, 426 size_t *length); 427 int STDCALL mysql_session_track_get_next(MYSQL *mysql, 428 enum enum_session_state_type type, 429 const char **data, 430 size_t *length); 431 /* local infile support */ 432 433 #define LOCAL_INFILE_ERROR_LEN 512 434 435 void 436 mysql_set_local_infile_handler(MYSQL *mysql, 437 int (*local_infile_init)(void **, const char *, 438 void *), 439 int (*local_infile_read)(void *, char *, 440 unsigned int), 441 void (*local_infile_end)(void *), 442 int (*local_infile_error)(void *, char*, 443 unsigned int), 444 void *); 445 446 void 447 mysql_set_local_infile_default(MYSQL *mysql); 448 449 int STDCALL mysql_shutdown(MYSQL *mysql, 450 enum mysql_enum_shutdown_level 451 shutdown_level); 452 int STDCALL mysql_dump_debug_info(MYSQL *mysql); 453 int STDCALL mysql_refresh(MYSQL *mysql, 454 unsigned int refresh_options); 455 int STDCALL mysql_kill(MYSQL *mysql,unsigned long pid); 456 int STDCALL mysql_set_server_option(MYSQL *mysql, 457 enum enum_mysql_set_option 458 option); 459 int STDCALL mysql_ping(MYSQL *mysql); 460 const char * STDCALL mysql_stat(MYSQL *mysql); 461 const char * STDCALL mysql_get_server_info(MYSQL *mysql); 462 const char * STDCALL mysql_get_client_info(void); 463 unsigned long STDCALL mysql_get_client_version(void); 464 const char * STDCALL mysql_get_host_info(MYSQL *mysql); 465 unsigned long STDCALL mysql_get_server_version(MYSQL *mysql); 466 unsigned int STDCALL mysql_get_proto_info(MYSQL *mysql); 467 MYSQL_RES * STDCALL mysql_list_dbs(MYSQL *mysql,const char *wild); 468 MYSQL_RES * STDCALL mysql_list_tables(MYSQL *mysql,const char *wild); 469 MYSQL_RES * STDCALL mysql_list_processes(MYSQL *mysql); 470 int STDCALL mysql_options(MYSQL *mysql,enum mysql_option option, 471 const void *arg); 472 int STDCALL mysql_options4(MYSQL *mysql,enum mysql_option option, 473 const void *arg1, const void *arg2); 474 int STDCALL mysql_get_option(MYSQL *mysql, enum mysql_option option, 475 const void *arg); 476 void STDCALL mysql_free_result(MYSQL_RES *result); 477 void STDCALL mysql_data_seek(MYSQL_RES *result, 478 my_ulonglong offset); 479 MYSQL_ROW_OFFSET STDCALL mysql_row_seek(MYSQL_RES *result, 480 MYSQL_ROW_OFFSET offset); 481 MYSQL_FIELD_OFFSET STDCALL mysql_field_seek(MYSQL_RES *result, 482 MYSQL_FIELD_OFFSET offset); 483 MYSQL_ROW STDCALL mysql_fetch_row(MYSQL_RES *result); 484 unsigned long * STDCALL mysql_fetch_lengths(MYSQL_RES *result); 485 MYSQL_FIELD * STDCALL mysql_fetch_field(MYSQL_RES *result); 486 MYSQL_RES * STDCALL mysql_list_fields(MYSQL *mysql, const char *table, 487 const char *wild); 488 unsigned long STDCALL mysql_escape_string(char *to,const char *from, 489 unsigned long from_length); 490 unsigned long STDCALL mysql_hex_string(char *to,const char *from, 491 unsigned long from_length); 492 unsigned long STDCALL mysql_real_escape_string(MYSQL *mysql, 493 char *to,const char *from, 494 unsigned long length); 495 unsigned long STDCALL mysql_real_escape_string_quote(MYSQL *mysql, 496 char *to, const char *from, 497 unsigned long length, char quote); 498 void STDCALL mysql_debug(const char *debug); 499 void STDCALL myodbc_remove_escape(MYSQL *mysql,char *name); 500 unsigned int STDCALL mysql_thread_safe(void); 501 my_bool STDCALL mysql_embedded(void); 502 my_bool STDCALL mysql_read_query_result(MYSQL *mysql); 503 int STDCALL mysql_reset_connection(MYSQL *mysql); 504 505 /* 506 The following definitions are added for the enhanced 507 client-server protocol 508 */ 509 510 /* statement state */ 511 enum enum_mysql_stmt_state 512 { 513 MYSQL_STMT_INIT_DONE= 1, MYSQL_STMT_PREPARE_DONE, MYSQL_STMT_EXECUTE_DONE, 514 MYSQL_STMT_FETCH_DONE 515 }; 516 517 518 /* 519 This structure is used to define bind information, and 520 internally by the client library. 521 Public members with their descriptions are listed below 522 (conventionally `On input' refers to the binds given to 523 mysql_stmt_bind_param, `On output' refers to the binds given 524 to mysql_stmt_bind_result): 525 526 buffer_type - One of the MYSQL_* types, used to describe 527 the host language type of buffer. 528 On output: if column type is different from 529 buffer_type, column value is automatically converted 530 to buffer_type before it is stored in the buffer. 531 buffer - On input: points to the buffer with input data. 532 On output: points to the buffer capable to store 533 output data. 534 The type of memory pointed by buffer must correspond 535 to buffer_type. See the correspondence table in 536 the comment to mysql_stmt_bind_param. 537 538 The two above members are mandatory for any kind of bind. 539 540 buffer_length - the length of the buffer. You don't have to set 541 it for any fixed length buffer: float, double, 542 int, etc. It must be set however for variable-length 543 types, such as BLOBs or STRINGs. 544 545 length - On input: in case when lengths of input values 546 are different for each execute, you can set this to 547 point at a variable containining value length. This 548 way the value length can be different in each execute. 549 If length is not NULL, buffer_length is not used. 550 Note, length can even point at buffer_length if 551 you keep bind structures around while fetching: 552 this way you can change buffer_length before 553 each execution, everything will work ok. 554 On output: if length is set, mysql_stmt_fetch will 555 write column length into it. 556 557 is_null - On input: points to a boolean variable that should 558 be set to TRUE for NULL values. 559 This member is useful only if your data may be 560 NULL in some but not all cases. 561 If your data is never NULL, is_null should be set to 0. 562 If your data is always NULL, set buffer_type 563 to MYSQL_TYPE_NULL, and is_null will not be used. 564 565 is_unsigned - On input: used to signify that values provided for one 566 of numeric types are unsigned. 567 On output describes signedness of the output buffer. 568 If, taking into account is_unsigned flag, column data 569 is out of range of the output buffer, data for this column 570 is regarded truncated. Note that this has no correspondence 571 to the sign of result set column, if you need to find it out 572 use mysql_stmt_result_metadata. 573 error - where to write a truncation error if it is present. 574 possible error value is: 575 0 no truncation 576 1 value is out of range or buffer is too small 577 578 Please note that MYSQL_BIND also has internals members. 579 */ 580 581 typedef struct st_mysql_bind 582 { 583 unsigned long *length; /* output length pointer */ 584 my_bool *is_null; /* Pointer to null indicator */ 585 void *buffer; /* buffer to get/put data */ 586 /* set this if you want to track data truncations happened during fetch */ 587 my_bool *error; 588 unsigned char *row_ptr; /* for the current data position */ 589 void (*store_param_func)(NET *net, struct st_mysql_bind *param); 590 void (*fetch_result)(struct st_mysql_bind *, MYSQL_FIELD *, 591 unsigned char **row); 592 void (*skip_result)(struct st_mysql_bind *, MYSQL_FIELD *, 593 unsigned char **row); 594 /* output buffer length, must be set when fetching str/binary */ 595 unsigned long buffer_length; 596 unsigned long offset; /* offset position for char/binary fetch */ 597 unsigned long length_value; /* Used if length is 0 */ 598 unsigned int param_number; /* For null count and error messages */ 599 unsigned int pack_length; /* Internal length for packed data */ 600 enum enum_field_types buffer_type; /* buffer type */ 601 my_bool error_value; /* used if error is 0 */ 602 my_bool is_unsigned; /* set if integer type is unsigned */ 603 my_bool long_data_used; /* If used with mysql_send_long_data */ 604 my_bool is_null_value; /* Used if is_null is 0 */ 605 void *extension; 606 } MYSQL_BIND; 607 608 609 struct st_mysql_stmt_extension; 610 611 /* statement handler */ 612 typedef struct st_mysql_stmt 613 { 614 MEM_ROOT mem_root; /* root allocations */ 615 LIST list; /* list to keep track of all stmts */ 616 MYSQL *mysql; /* connection handle */ 617 MYSQL_BIND *params; /* input parameters */ 618 MYSQL_BIND *bind; /* output parameters */ 619 MYSQL_FIELD *fields; /* result set metadata */ 620 MYSQL_DATA result; /* cached result set */ 621 MYSQL_ROWS *data_cursor; /* current row in cached result */ 622 /* 623 mysql_stmt_fetch() calls this function to fetch one row (it's different 624 for buffered, unbuffered and cursor fetch). 625 */ 626 int (*read_row_func)(struct st_mysql_stmt *stmt, 627 unsigned char **row); 628 /* copy of mysql->affected_rows after statement execution */ 629 my_ulonglong affected_rows; 630 my_ulonglong insert_id; /* copy of mysql->insert_id */ 631 unsigned long stmt_id; /* Id for prepared statement */ 632 unsigned long flags; /* i.e. type of cursor to open */ 633 unsigned long prefetch_rows; /* number of rows per one COM_FETCH */ 634 /* 635 Copied from mysql->server_status after execute/fetch to know 636 server-side cursor status for this statement. 637 */ 638 unsigned int server_status; 639 unsigned int last_errno; /* error code */ 640 unsigned int param_count; /* input parameter count */ 641 unsigned int field_count; /* number of columns in result set */ 642 enum enum_mysql_stmt_state state; /* statement state */ 643 char last_error[MYSQL_ERRMSG_SIZE]; /* error message */ 644 char sqlstate[SQLSTATE_LENGTH+1]; 645 /* Types of input parameters should be sent to server */ 646 my_bool send_types_to_server; 647 my_bool bind_param_done; /* input buffers were supplied */ 648 unsigned char bind_result_done; /* output buffers were supplied */ 649 /* mysql_stmt_close() had to cancel this result */ 650 my_bool unbuffered_fetch_cancelled; 651 /* 652 Is set to true if we need to calculate field->max_length for 653 metadata fields when doing mysql_stmt_store_result. 654 */ 655 my_bool update_max_length; 656 struct st_mysql_stmt_extension *extension; 657 } MYSQL_STMT; 658 659 enum enum_stmt_attr_type 660 { 661 /* 662 When doing mysql_stmt_store_result calculate max_length attribute 663 of statement metadata. This is to be consistent with the old API, 664 where this was done automatically. 665 In the new API we do that only by request because it slows down 666 mysql_stmt_store_result sufficiently. 667 */ 668 STMT_ATTR_UPDATE_MAX_LENGTH, 669 /* 670 unsigned long with combination of cursor flags (read only, for update, 671 etc) 672 */ 673 STMT_ATTR_CURSOR_TYPE, 674 /* 675 Amount of rows to retrieve from server per one fetch if using cursors. 676 Accepts unsigned long attribute in the range 1 - ulong_max 677 */ 678 STMT_ATTR_PREFETCH_ROWS 679 }; 680 681 682 MYSQL_STMT * STDCALL mysql_stmt_init(MYSQL *mysql); 683 int STDCALL mysql_stmt_prepare(MYSQL_STMT *stmt, const char *query, 684 unsigned long length); 685 int STDCALL mysql_stmt_execute(MYSQL_STMT *stmt); 686 int STDCALL mysql_stmt_fetch(MYSQL_STMT *stmt); 687 int STDCALL mysql_stmt_fetch_column(MYSQL_STMT *stmt, MYSQL_BIND *bind_arg, 688 unsigned int column, 689 unsigned long offset); 690 int STDCALL mysql_stmt_store_result(MYSQL_STMT *stmt); 691 unsigned long STDCALL mysql_stmt_param_count(MYSQL_STMT * stmt); 692 my_bool STDCALL mysql_stmt_attr_set(MYSQL_STMT *stmt, 693 enum enum_stmt_attr_type attr_type, 694 const void *attr); 695 my_bool STDCALL mysql_stmt_attr_get(MYSQL_STMT *stmt, 696 enum enum_stmt_attr_type attr_type, 697 void *attr); 698 my_bool STDCALL mysql_stmt_bind_param(MYSQL_STMT * stmt, MYSQL_BIND * bnd); 699 my_bool STDCALL mysql_stmt_bind_result(MYSQL_STMT * stmt, MYSQL_BIND * bnd); 700 my_bool STDCALL mysql_stmt_close(MYSQL_STMT * stmt); 701 my_bool STDCALL mysql_stmt_reset(MYSQL_STMT * stmt); 702 my_bool STDCALL mysql_stmt_free_result(MYSQL_STMT *stmt); 703 my_bool STDCALL mysql_stmt_send_long_data(MYSQL_STMT *stmt, 704 unsigned int param_number, 705 const char *data, 706 unsigned long length); 707 MYSQL_RES *STDCALL mysql_stmt_result_metadata(MYSQL_STMT *stmt); 708 MYSQL_RES *STDCALL mysql_stmt_param_metadata(MYSQL_STMT *stmt); 709 unsigned int STDCALL mysql_stmt_errno(MYSQL_STMT * stmt); 710 const char *STDCALL mysql_stmt_error(MYSQL_STMT * stmt); 711 const char *STDCALL mysql_stmt_sqlstate(MYSQL_STMT * stmt); 712 MYSQL_ROW_OFFSET STDCALL mysql_stmt_row_seek(MYSQL_STMT *stmt, 713 MYSQL_ROW_OFFSET offset); 714 MYSQL_ROW_OFFSET STDCALL mysql_stmt_row_tell(MYSQL_STMT *stmt); 715 void STDCALL mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset); 716 my_ulonglong STDCALL mysql_stmt_num_rows(MYSQL_STMT *stmt); 717 my_ulonglong STDCALL mysql_stmt_affected_rows(MYSQL_STMT *stmt); 718 my_ulonglong STDCALL mysql_stmt_insert_id(MYSQL_STMT *stmt); 719 unsigned int STDCALL mysql_stmt_field_count(MYSQL_STMT *stmt); 720 721 my_bool STDCALL mysql_commit(MYSQL * mysql); 722 my_bool STDCALL mysql_rollback(MYSQL * mysql); 723 my_bool STDCALL mysql_autocommit(MYSQL * mysql, my_bool auto_mode); 724 my_bool STDCALL mysql_more_results(MYSQL *mysql); 725 int STDCALL mysql_next_result(MYSQL *mysql); 726 int STDCALL mysql_stmt_next_result(MYSQL_STMT *stmt); 727 void STDCALL mysql_close(MYSQL *sock); 728 729 730 /* status return codes */ 731 #define MYSQL_NO_DATA 100 732 #define MYSQL_DATA_TRUNCATED 101 733 734 #define mysql_reload(mysql) mysql_refresh((mysql),REFRESH_GRANT) 735 736 #define HAVE_MYSQL_REAL_CONNECT 737 738 #ifdef __cplusplus 739 } 740 #endif 741 742 #endif /* _mysql_h */ 743