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

source code of include/mysql/mysql.h