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 libmysqlclient. 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 libmysqlclient (exactly, mysql_server_init() is called by mysql_init() so 351 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 libmysqlclient. We 355 intend to promote these aliases over the mysql_server* ones. 356 */ 357 #define mysql_library_init mysql_server_init 358 #define mysql_library_end mysql_server_end 359 360 361 /* 362 Set up and bring down a thread; these function should be called 363 for each thread in an application which opens at least one MySQL 364 connection. All uses of the connection(s) should be between these 365 function calls. 366 */ 367 my_bool STDCALL mysql_thread_init(void); 368 void STDCALL mysql_thread_end(void); 369 370 /* 371 Functions to get information from the MYSQL and MYSQL_RES structures 372 Should definitely be used if one uses shared libraries. 373 */ 374 375 my_ulonglong STDCALL mysql_num_rows(MYSQL_RES *res); 376 unsigned int STDCALL mysql_num_fields(MYSQL_RES *res); 377 my_bool STDCALL mysql_eof(MYSQL_RES *res); 378 MYSQL_FIELD *STDCALL mysql_fetch_field_direct(MYSQL_RES *res, 379 unsigned int fieldnr); 380 MYSQL_FIELD * STDCALL mysql_fetch_fields(MYSQL_RES *res); 381 MYSQL_ROW_OFFSET STDCALL mysql_row_tell(MYSQL_RES *res); 382 MYSQL_FIELD_OFFSET STDCALL mysql_field_tell(MYSQL_RES *res); 383 384 unsigned int STDCALL mysql_field_count(MYSQL *mysql); 385 my_ulonglong STDCALL mysql_affected_rows(MYSQL *mysql); 386 my_ulonglong STDCALL mysql_insert_id(MYSQL *mysql); 387 unsigned int STDCALL mysql_errno(MYSQL *mysql); 388 const char * STDCALL mysql_error(MYSQL *mysql); 389 const char *STDCALL mysql_sqlstate(MYSQL *mysql); 390 unsigned int STDCALL mysql_warning_count(MYSQL *mysql); 391 const char * STDCALL mysql_info(MYSQL *mysql); 392 unsigned long STDCALL mysql_thread_id(MYSQL *mysql); 393 const char * STDCALL mysql_character_set_name(MYSQL *mysql); 394 int STDCALL mysql_set_character_set(MYSQL *mysql, const char *csname); 395 396 MYSQL * STDCALL mysql_init(MYSQL *mysql); 397 my_bool STDCALL mysql_ssl_set(MYSQL *mysql, const char *key, 398 const char *cert, const char *ca, 399 const char *capath, const char *cipher); 400 const char * STDCALL mysql_get_ssl_cipher(MYSQL *mysql); 401 my_bool STDCALL mysql_change_user(MYSQL *mysql, const char *user, 402 const char *passwd, const char *db); 403 MYSQL * STDCALL mysql_real_connect(MYSQL *mysql, const char *host, 404 const char *user, 405 const char *passwd, 406 const char *db, 407 unsigned int port, 408 const char *unix_socket, 409 unsigned long clientflag); 410 int STDCALL mysql_select_db(MYSQL *mysql, const char *db); 411 int STDCALL mysql_query(MYSQL *mysql, const char *q); 412 int STDCALL mysql_send_query(MYSQL *mysql, const char *q, 413 unsigned long length); 414 int STDCALL mysql_real_query(MYSQL *mysql, const char *q, 415 unsigned long length); 416 MYSQL_RES * STDCALL mysql_store_result(MYSQL *mysql); 417 MYSQL_RES * STDCALL mysql_use_result(MYSQL *mysql); 418 419 void STDCALL mysql_get_character_set_info(MYSQL *mysql, 420 MY_CHARSET_INFO *charset); 421 422 int STDCALL mysql_session_track_get_first(MYSQL *mysql, 423 enum enum_session_state_type type, 424 const char **data, 425 size_t *length); 426 int STDCALL mysql_session_track_get_next(MYSQL *mysql, 427 enum enum_session_state_type type, 428 const char **data, 429 size_t *length); 430 /* local infile support */ 431 432 #define LOCAL_INFILE_ERROR_LEN 512 433 434 void 435 mysql_set_local_infile_handler(MYSQL *mysql, 436 int (*local_infile_init)(void **, const char *, 437 void *), 438 int (*local_infile_read)(void *, char *, 439 unsigned int), 440 void (*local_infile_end)(void *), 441 int (*local_infile_error)(void *, char*, 442 unsigned int), 443 void *); 444 445 void 446 mysql_set_local_infile_default(MYSQL *mysql); 447 448 int STDCALL mysql_shutdown(MYSQL *mysql, 449 enum mysql_enum_shutdown_level 450 shutdown_level); 451 int STDCALL mysql_dump_debug_info(MYSQL *mysql); 452 int STDCALL mysql_refresh(MYSQL *mysql, 453 unsigned int refresh_options); 454 int STDCALL mysql_kill(MYSQL *mysql,unsigned long pid); 455 int STDCALL mysql_set_server_option(MYSQL *mysql, 456 enum enum_mysql_set_option 457 option); 458 int STDCALL mysql_ping(MYSQL *mysql); 459 const char * STDCALL mysql_stat(MYSQL *mysql); 460 const char * STDCALL mysql_get_server_info(MYSQL *mysql); 461 const char * STDCALL mysql_get_client_info(void); 462 unsigned long STDCALL mysql_get_client_version(void); 463 const char * STDCALL mysql_get_host_info(MYSQL *mysql); 464 unsigned long STDCALL mysql_get_server_version(MYSQL *mysql); 465 unsigned int STDCALL mysql_get_proto_info(MYSQL *mysql); 466 MYSQL_RES * STDCALL mysql_list_dbs(MYSQL *mysql,const char *wild); 467 MYSQL_RES * STDCALL mysql_list_tables(MYSQL *mysql,const char *wild); 468 MYSQL_RES * STDCALL mysql_list_processes(MYSQL *mysql); 469 int STDCALL mysql_options(MYSQL *mysql,enum mysql_option option, 470 const void *arg); 471 int STDCALL mysql_options4(MYSQL *mysql,enum mysql_option option, 472 const void *arg1, const void *arg2); 473 int STDCALL mysql_get_option(MYSQL *mysql, enum mysql_option option, 474 const void *arg); 475 void STDCALL mysql_free_result(MYSQL_RES *result); 476 void STDCALL mysql_data_seek(MYSQL_RES *result, 477 my_ulonglong offset); 478 MYSQL_ROW_OFFSET STDCALL mysql_row_seek(MYSQL_RES *result, 479 MYSQL_ROW_OFFSET offset); 480 MYSQL_FIELD_OFFSET STDCALL mysql_field_seek(MYSQL_RES *result, 481 MYSQL_FIELD_OFFSET offset); 482 MYSQL_ROW STDCALL mysql_fetch_row(MYSQL_RES *result); 483 unsigned long * STDCALL mysql_fetch_lengths(MYSQL_RES *result); 484 MYSQL_FIELD * STDCALL mysql_fetch_field(MYSQL_RES *result); 485 MYSQL_RES * STDCALL mysql_list_fields(MYSQL *mysql, const char *table, 486 const char *wild); 487 unsigned long STDCALL mysql_escape_string(char *to,const char *from, 488 unsigned long from_length); 489 unsigned long STDCALL mysql_hex_string(char *to,const char *from, 490 unsigned long from_length); 491 unsigned long STDCALL mysql_real_escape_string(MYSQL *mysql, 492 char *to,const char *from, 493 unsigned long length); 494 unsigned long STDCALL mysql_real_escape_string_quote(MYSQL *mysql, 495 char *to, const char *from, 496 unsigned long length, char quote); 497 void STDCALL mysql_debug(const char *debug); 498 void STDCALL myodbc_remove_escape(MYSQL *mysql,char *name); 499 unsigned int STDCALL mysql_thread_safe(void); 500 my_bool STDCALL mysql_embedded(void); 501 my_bool STDCALL mysql_read_query_result(MYSQL *mysql); 502 int STDCALL mysql_reset_connection(MYSQL *mysql); 503 504 /* 505 The following definitions are added for the enhanced 506 client-server protocol 507 */ 508 509 /* statement state */ 510 enum enum_mysql_stmt_state 511 { 512 MYSQL_STMT_INIT_DONE= 1, MYSQL_STMT_PREPARE_DONE, MYSQL_STMT_EXECUTE_DONE, 513 MYSQL_STMT_FETCH_DONE 514 }; 515 516 517 /* 518 This structure is used to define bind information, and 519 internally by the client library. 520 Public members with their descriptions are listed below 521 (conventionally `On input' refers to the binds given to 522 mysql_stmt_bind_param, `On output' refers to the binds given 523 to mysql_stmt_bind_result): 524 525 buffer_type - One of the MYSQL_* types, used to describe 526 the host language type of buffer. 527 On output: if column type is different from 528 buffer_type, column value is automatically converted 529 to buffer_type before it is stored in the buffer. 530 buffer - On input: points to the buffer with input data. 531 On output: points to the buffer capable to store 532 output data. 533 The type of memory pointed by buffer must correspond 534 to buffer_type. See the correspondence table in 535 the comment to mysql_stmt_bind_param. 536 537 The two above members are mandatory for any kind of bind. 538 539 buffer_length - the length of the buffer. You don't have to set 540 it for any fixed length buffer: float, double, 541 int, etc. It must be set however for variable-length 542 types, such as BLOBs or STRINGs. 543 544 length - On input: in case when lengths of input values 545 are different for each execute, you can set this to 546 point at a variable containining value length. This 547 way the value length can be different in each execute. 548 If length is not NULL, buffer_length is not used. 549 Note, length can even point at buffer_length if 550 you keep bind structures around while fetching: 551 this way you can change buffer_length before 552 each execution, everything will work ok. 553 On output: if length is set, mysql_stmt_fetch will 554 write column length into it. 555 556 is_null - On input: points to a boolean variable that should 557 be set to TRUE for NULL values. 558 This member is useful only if your data may be 559 NULL in some but not all cases. 560 If your data is never NULL, is_null should be set to 0. 561 If your data is always NULL, set buffer_type 562 to MYSQL_TYPE_NULL, and is_null will not be used. 563 564 is_unsigned - On input: used to signify that values provided for one 565 of numeric types are unsigned. 566 On output describes signedness of the output buffer. 567 If, taking into account is_unsigned flag, column data 568 is out of range of the output buffer, data for this column 569 is regarded truncated. Note that this has no correspondence 570 to the sign of result set column, if you need to find it out 571 use mysql_stmt_result_metadata. 572 error - where to write a truncation error if it is present. 573 possible error value is: 574 0 no truncation 575 1 value is out of range or buffer is too small 576 577 Please note that MYSQL_BIND also has internals members. 578 */ 579 580 typedef struct st_mysql_bind 581 { 582 unsigned long *length; /* output length pointer */ 583 my_bool *is_null; /* Pointer to null indicator */ 584 void *buffer; /* buffer to get/put data */ 585 /* set this if you want to track data truncations happened during fetch */ 586 my_bool *error; 587 unsigned char *row_ptr; /* for the current data position */ 588 void (*store_param_func)(NET *net, struct st_mysql_bind *param); 589 void (*fetch_result)(struct st_mysql_bind *, MYSQL_FIELD *, 590 unsigned char **row); 591 void (*skip_result)(struct st_mysql_bind *, MYSQL_FIELD *, 592 unsigned char **row); 593 /* output buffer length, must be set when fetching str/binary */ 594 unsigned long buffer_length; 595 unsigned long offset; /* offset position for char/binary fetch */ 596 unsigned long length_value; /* Used if length is 0 */ 597 unsigned int param_number; /* For null count and error messages */ 598 unsigned int pack_length; /* Internal length for packed data */ 599 enum enum_field_types buffer_type; /* buffer type */ 600 my_bool error_value; /* used if error is 0 */ 601 my_bool is_unsigned; /* set if integer type is unsigned */ 602 my_bool long_data_used; /* If used with mysql_send_long_data */ 603 my_bool is_null_value; /* Used if is_null is 0 */ 604 void *extension; 605 } MYSQL_BIND; 606 607 608 struct st_mysql_stmt_extension; 609 610 /* statement handler */ 611 typedef struct st_mysql_stmt 612 { 613 MEM_ROOT mem_root; /* root allocations */ 614 LIST list; /* list to keep track of all stmts */ 615 MYSQL *mysql; /* connection handle */ 616 MYSQL_BIND *params; /* input parameters */ 617 MYSQL_BIND *bind; /* output parameters */ 618 MYSQL_FIELD *fields; /* result set metadata */ 619 MYSQL_DATA result; /* cached result set */ 620 MYSQL_ROWS *data_cursor; /* current row in cached result */ 621 /* 622 mysql_stmt_fetch() calls this function to fetch one row (it's different 623 for buffered, unbuffered and cursor fetch). 624 */ 625 int (*read_row_func)(struct st_mysql_stmt *stmt, 626 unsigned char **row); 627 /* copy of mysql->affected_rows after statement execution */ 628 my_ulonglong affected_rows; 629 my_ulonglong insert_id; /* copy of mysql->insert_id */ 630 unsigned long stmt_id; /* Id for prepared statement */ 631 unsigned long flags; /* i.e. type of cursor to open */ 632 unsigned long prefetch_rows; /* number of rows per one COM_FETCH */ 633 /* 634 Copied from mysql->server_status after execute/fetch to know 635 server-side cursor status for this statement. 636 */ 637 unsigned int server_status; 638 unsigned int last_errno; /* error code */ 639 unsigned int param_count; /* input parameter count */ 640 unsigned int field_count; /* number of columns in result set */ 641 enum enum_mysql_stmt_state state; /* statement state */ 642 char last_error[MYSQL_ERRMSG_SIZE]; /* error message */ 643 char sqlstate[SQLSTATE_LENGTH+1]; 644 /* Types of input parameters should be sent to server */ 645 my_bool send_types_to_server; 646 my_bool bind_param_done; /* input buffers were supplied */ 647 unsigned char bind_result_done; /* output buffers were supplied */ 648 /* mysql_stmt_close() had to cancel this result */ 649 my_bool unbuffered_fetch_cancelled; 650 /* 651 Is set to true if we need to calculate field->max_length for 652 metadata fields when doing mysql_stmt_store_result. 653 */ 654 my_bool update_max_length; 655 struct st_mysql_stmt_extension *extension; 656 } MYSQL_STMT; 657 658 enum enum_stmt_attr_type 659 { 660 /* 661 When doing mysql_stmt_store_result calculate max_length attribute 662 of statement metadata. This is to be consistent with the old API, 663 where this was done automatically. 664 In the new API we do that only by request because it slows down 665 mysql_stmt_store_result sufficiently. 666 */ 667 STMT_ATTR_UPDATE_MAX_LENGTH, 668 /* 669 unsigned long with combination of cursor flags (read only, for update, 670 etc) 671 */ 672 STMT_ATTR_CURSOR_TYPE, 673 /* 674 Amount of rows to retrieve from server per one fetch if using cursors. 675 Accepts unsigned long attribute in the range 1 - ulong_max 676 */ 677 STMT_ATTR_PREFETCH_ROWS 678 }; 679 680 681 MYSQL_STMT * STDCALL mysql_stmt_init(MYSQL *mysql); 682 int STDCALL mysql_stmt_prepare(MYSQL_STMT *stmt, const char *query, 683 unsigned long length); 684 int STDCALL mysql_stmt_execute(MYSQL_STMT *stmt); 685 int STDCALL mysql_stmt_fetch(MYSQL_STMT *stmt); 686 int STDCALL mysql_stmt_fetch_column(MYSQL_STMT *stmt, MYSQL_BIND *bind_arg, 687 unsigned int column, 688 unsigned long offset); 689 int STDCALL mysql_stmt_store_result(MYSQL_STMT *stmt); 690 unsigned long STDCALL mysql_stmt_param_count(MYSQL_STMT * stmt); 691 my_bool STDCALL mysql_stmt_attr_set(MYSQL_STMT *stmt, 692 enum enum_stmt_attr_type attr_type, 693 const void *attr); 694 my_bool STDCALL mysql_stmt_attr_get(MYSQL_STMT *stmt, 695 enum enum_stmt_attr_type attr_type, 696 void *attr); 697 my_bool STDCALL mysql_stmt_bind_param(MYSQL_STMT * stmt, MYSQL_BIND * bnd); 698 my_bool STDCALL mysql_stmt_bind_result(MYSQL_STMT * stmt, MYSQL_BIND * bnd); 699 my_bool STDCALL mysql_stmt_close(MYSQL_STMT * stmt); 700 my_bool STDCALL mysql_stmt_reset(MYSQL_STMT * stmt); 701 my_bool STDCALL mysql_stmt_free_result(MYSQL_STMT *stmt); 702 my_bool STDCALL mysql_stmt_send_long_data(MYSQL_STMT *stmt, 703 unsigned int param_number, 704 const char *data, 705 unsigned long length); 706 MYSQL_RES *STDCALL mysql_stmt_result_metadata(MYSQL_STMT *stmt); 707 MYSQL_RES *STDCALL mysql_stmt_param_metadata(MYSQL_STMT *stmt); 708 unsigned int STDCALL mysql_stmt_errno(MYSQL_STMT * stmt); 709 const char *STDCALL mysql_stmt_error(MYSQL_STMT * stmt); 710 const char *STDCALL mysql_stmt_sqlstate(MYSQL_STMT * stmt); 711 MYSQL_ROW_OFFSET STDCALL mysql_stmt_row_seek(MYSQL_STMT *stmt, 712 MYSQL_ROW_OFFSET offset); 713 MYSQL_ROW_OFFSET STDCALL mysql_stmt_row_tell(MYSQL_STMT *stmt); 714 void STDCALL mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset); 715 my_ulonglong STDCALL mysql_stmt_num_rows(MYSQL_STMT *stmt); 716 my_ulonglong STDCALL mysql_stmt_affected_rows(MYSQL_STMT *stmt); 717 my_ulonglong STDCALL mysql_stmt_insert_id(MYSQL_STMT *stmt); 718 unsigned int STDCALL mysql_stmt_field_count(MYSQL_STMT *stmt); 719 720 my_bool STDCALL mysql_commit(MYSQL * mysql); 721 my_bool STDCALL mysql_rollback(MYSQL * mysql); 722 my_bool STDCALL mysql_autocommit(MYSQL * mysql, my_bool auto_mode); 723 my_bool STDCALL mysql_more_results(MYSQL *mysql); 724 int STDCALL mysql_next_result(MYSQL *mysql); 725 int STDCALL mysql_stmt_next_result(MYSQL_STMT *stmt); 726 void STDCALL mysql_close(MYSQL *sock); 727 728 729 /* status return codes */ 730 #define MYSQL_NO_DATA 100 731 #define MYSQL_DATA_TRUNCATED 101 732 733 #define mysql_reload(mysql) mysql_refresh((mysql),REFRESH_GRANT) 734 735 #define HAVE_MYSQL_REAL_CONNECT 736 737 #ifdef __cplusplus 738 } 739 #endif 740 741 #endif /* _mysql_h */ 742