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

source code of include/mysql/mysql.h