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