1/* Copyright (c) 2000, 2018, 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 __cplusplus
42extern "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
49typedef 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
64typedef 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
78extern unsigned int mysql_port;
79extern 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
95typedef 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
119typedef char **MYSQL_ROW; /* return data as array of strings */
120typedef unsigned int MYSQL_FIELD_OFFSET; /* offset to current field */
121
122#ifndef MY_GLOBAL_INCLUDED
123#if defined (_WIN32)
124typedef unsigned __int64 my_ulonglong;
125#else
126typedef 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
137typedef 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
143typedef MYSQL_ROWS *MYSQL_ROW_OFFSET; /* offset to current row */
144
145#include "my_alloc.h"
146
147typedef struct embedded_query_result EMBEDDED_QUERY_RESULT;
148typedef 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
158enum 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*/
189struct st_mysql_options_extention;
190
191struct 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
239enum mysql_status
240{
241 MYSQL_STATUS_READY, MYSQL_STATUS_GET_RESULT, MYSQL_STATUS_USE_RESULT,
242 MYSQL_STATUS_STATEMENT_GET_RESULT
243};
244
245enum mysql_protocol_type
246{
247 MYSQL_PROTOCOL_DEFAULT, MYSQL_PROTOCOL_TCP, MYSQL_PROTOCOL_SOCKET,
248 MYSQL_PROTOCOL_PIPE, MYSQL_PROTOCOL_MEMORY
249};
250
251enum 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
257typedef 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
269struct st_mysql_methods;
270struct st_mysql_stmt;
271
272typedef 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
317typedef 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*/
345int STDCALL mysql_server_init(int argc, char **argv, char **groups);
346void 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*/
367my_bool STDCALL mysql_thread_init(void);
368void 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
375my_ulonglong STDCALL mysql_num_rows(MYSQL_RES *res);
376unsigned int STDCALL mysql_num_fields(MYSQL_RES *res);
377my_bool STDCALL mysql_eof(MYSQL_RES *res);
378MYSQL_FIELD *STDCALL mysql_fetch_field_direct(MYSQL_RES *res,
379 unsigned int fieldnr);
380MYSQL_FIELD * STDCALL mysql_fetch_fields(MYSQL_RES *res);
381MYSQL_ROW_OFFSET STDCALL mysql_row_tell(MYSQL_RES *res);
382MYSQL_FIELD_OFFSET STDCALL mysql_field_tell(MYSQL_RES *res);
383
384unsigned int STDCALL mysql_field_count(MYSQL *mysql);
385my_ulonglong STDCALL mysql_affected_rows(MYSQL *mysql);
386my_ulonglong STDCALL mysql_insert_id(MYSQL *mysql);
387unsigned int STDCALL mysql_errno(MYSQL *mysql);
388const char * STDCALL mysql_error(MYSQL *mysql);
389const char *STDCALL mysql_sqlstate(MYSQL *mysql);
390unsigned int STDCALL mysql_warning_count(MYSQL *mysql);
391const char * STDCALL mysql_info(MYSQL *mysql);
392unsigned long STDCALL mysql_thread_id(MYSQL *mysql);
393const char * STDCALL mysql_character_set_name(MYSQL *mysql);
394int STDCALL mysql_set_character_set(MYSQL *mysql, const char *csname);
395
396MYSQL * STDCALL mysql_init(MYSQL *mysql);
397my_bool STDCALL mysql_ssl_set(MYSQL *mysql, const char *key,
398 const char *cert, const char *ca,
399 const char *capath, const char *cipher);
400const char * STDCALL mysql_get_ssl_cipher(MYSQL *mysql);
401my_bool STDCALL mysql_change_user(MYSQL *mysql, const char *user,
402 const char *passwd, const char *db);
403MYSQL * 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);
410int STDCALL mysql_select_db(MYSQL *mysql, const char *db);
411int STDCALL mysql_query(MYSQL *mysql, const char *q);
412int STDCALL mysql_send_query(MYSQL *mysql, const char *q,
413 unsigned long length);
414int STDCALL mysql_real_query(MYSQL *mysql, const char *q,
415 unsigned long length);
416MYSQL_RES * STDCALL mysql_store_result(MYSQL *mysql);
417MYSQL_RES * STDCALL mysql_use_result(MYSQL *mysql);
418
419void STDCALL mysql_get_character_set_info(MYSQL *mysql,
420 MY_CHARSET_INFO *charset);
421
422int STDCALL mysql_session_track_get_first(MYSQL *mysql,
423 enum enum_session_state_type type,
424 const char **data,
425 size_t *length);
426int 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
434void
435mysql_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
445void
446mysql_set_local_infile_default(MYSQL *mysql);
447
448int STDCALL mysql_shutdown(MYSQL *mysql,
449 enum mysql_enum_shutdown_level
450 shutdown_level);
451int STDCALL mysql_dump_debug_info(MYSQL *mysql);
452int STDCALL mysql_refresh(MYSQL *mysql,
453 unsigned int refresh_options);
454int STDCALL mysql_kill(MYSQL *mysql,unsigned long pid);
455int STDCALL mysql_set_server_option(MYSQL *mysql,
456 enum enum_mysql_set_option
457 option);
458int STDCALL mysql_ping(MYSQL *mysql);
459const char * STDCALL mysql_stat(MYSQL *mysql);
460const char * STDCALL mysql_get_server_info(MYSQL *mysql);
461const char * STDCALL mysql_get_client_info(void);
462unsigned long STDCALL mysql_get_client_version(void);
463const char * STDCALL mysql_get_host_info(MYSQL *mysql);
464unsigned long STDCALL mysql_get_server_version(MYSQL *mysql);
465unsigned int STDCALL mysql_get_proto_info(MYSQL *mysql);
466MYSQL_RES * STDCALL mysql_list_dbs(MYSQL *mysql,const char *wild);
467MYSQL_RES * STDCALL mysql_list_tables(MYSQL *mysql,const char *wild);
468MYSQL_RES * STDCALL mysql_list_processes(MYSQL *mysql);
469int STDCALL mysql_options(MYSQL *mysql,enum mysql_option option,
470 const void *arg);
471int STDCALL mysql_options4(MYSQL *mysql,enum mysql_option option,
472 const void *arg1, const void *arg2);
473int STDCALL mysql_get_option(MYSQL *mysql, enum mysql_option option,
474 const void *arg);
475void STDCALL mysql_free_result(MYSQL_RES *result);
476void STDCALL mysql_data_seek(MYSQL_RES *result,
477 my_ulonglong offset);
478MYSQL_ROW_OFFSET STDCALL mysql_row_seek(MYSQL_RES *result,
479 MYSQL_ROW_OFFSET offset);
480MYSQL_FIELD_OFFSET STDCALL mysql_field_seek(MYSQL_RES *result,
481 MYSQL_FIELD_OFFSET offset);
482MYSQL_ROW STDCALL mysql_fetch_row(MYSQL_RES *result);
483unsigned long * STDCALL mysql_fetch_lengths(MYSQL_RES *result);
484MYSQL_FIELD * STDCALL mysql_fetch_field(MYSQL_RES *result);
485MYSQL_RES * STDCALL mysql_list_fields(MYSQL *mysql, const char *table,
486 const char *wild);
487unsigned long STDCALL mysql_escape_string(char *to,const char *from,
488 unsigned long from_length);
489unsigned long STDCALL mysql_hex_string(char *to,const char *from,
490 unsigned long from_length);
491unsigned long STDCALL mysql_real_escape_string(MYSQL *mysql,
492 char *to,const char *from,
493 unsigned long length);
494unsigned long STDCALL mysql_real_escape_string_quote(MYSQL *mysql,
495 char *to, const char *from,
496 unsigned long length, char quote);
497void STDCALL mysql_debug(const char *debug);
498void STDCALL myodbc_remove_escape(MYSQL *mysql,char *name);
499unsigned int STDCALL mysql_thread_safe(void);
500my_bool STDCALL mysql_embedded(void);
501my_bool STDCALL mysql_read_query_result(MYSQL *mysql);
502int 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 */
510enum 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
580typedef 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
608struct st_mysql_stmt_extension;
609
610/* statement handler */
611typedef 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
658enum 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
681MYSQL_STMT * STDCALL mysql_stmt_init(MYSQL *mysql);
682int STDCALL mysql_stmt_prepare(MYSQL_STMT *stmt, const char *query,
683 unsigned long length);
684int STDCALL mysql_stmt_execute(MYSQL_STMT *stmt);
685int STDCALL mysql_stmt_fetch(MYSQL_STMT *stmt);
686int STDCALL mysql_stmt_fetch_column(MYSQL_STMT *stmt, MYSQL_BIND *bind_arg,
687 unsigned int column,
688 unsigned long offset);
689int STDCALL mysql_stmt_store_result(MYSQL_STMT *stmt);
690unsigned long STDCALL mysql_stmt_param_count(MYSQL_STMT * stmt);
691my_bool STDCALL mysql_stmt_attr_set(MYSQL_STMT *stmt,
692 enum enum_stmt_attr_type attr_type,
693 const void *attr);
694my_bool STDCALL mysql_stmt_attr_get(MYSQL_STMT *stmt,
695 enum enum_stmt_attr_type attr_type,
696 void *attr);
697my_bool STDCALL mysql_stmt_bind_param(MYSQL_STMT * stmt, MYSQL_BIND * bnd);
698my_bool STDCALL mysql_stmt_bind_result(MYSQL_STMT * stmt, MYSQL_BIND * bnd);
699my_bool STDCALL mysql_stmt_close(MYSQL_STMT * stmt);
700my_bool STDCALL mysql_stmt_reset(MYSQL_STMT * stmt);
701my_bool STDCALL mysql_stmt_free_result(MYSQL_STMT *stmt);
702my_bool STDCALL mysql_stmt_send_long_data(MYSQL_STMT *stmt,
703 unsigned int param_number,
704 const char *data,
705 unsigned long length);
706MYSQL_RES *STDCALL mysql_stmt_result_metadata(MYSQL_STMT *stmt);
707MYSQL_RES *STDCALL mysql_stmt_param_metadata(MYSQL_STMT *stmt);
708unsigned int STDCALL mysql_stmt_errno(MYSQL_STMT * stmt);
709const char *STDCALL mysql_stmt_error(MYSQL_STMT * stmt);
710const char *STDCALL mysql_stmt_sqlstate(MYSQL_STMT * stmt);
711MYSQL_ROW_OFFSET STDCALL mysql_stmt_row_seek(MYSQL_STMT *stmt,
712 MYSQL_ROW_OFFSET offset);
713MYSQL_ROW_OFFSET STDCALL mysql_stmt_row_tell(MYSQL_STMT *stmt);
714void STDCALL mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset);
715my_ulonglong STDCALL mysql_stmt_num_rows(MYSQL_STMT *stmt);
716my_ulonglong STDCALL mysql_stmt_affected_rows(MYSQL_STMT *stmt);
717my_ulonglong STDCALL mysql_stmt_insert_id(MYSQL_STMT *stmt);
718unsigned int STDCALL mysql_stmt_field_count(MYSQL_STMT *stmt);
719
720my_bool STDCALL mysql_commit(MYSQL * mysql);
721my_bool STDCALL mysql_rollback(MYSQL * mysql);
722my_bool STDCALL mysql_autocommit(MYSQL * mysql, my_bool auto_mode);
723my_bool STDCALL mysql_more_results(MYSQL *mysql);
724int STDCALL mysql_next_result(MYSQL *mysql);
725int STDCALL mysql_stmt_next_result(MYSQL_STMT *stmt);
726void 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