xref: /PHP-8.2/ext/mysqlnd/mysqlnd.h (revision 885dca37)
1 /*
2   +----------------------------------------------------------------------+
3   | Copyright (c) The PHP Group                                          |
4   +----------------------------------------------------------------------+
5   | This source file is subject to version 3.01 of the PHP license,      |
6   | that is bundled with this package in the file LICENSE, and is        |
7   | available through the world-wide-web at the following url:           |
8   | https://www.php.net/license/3_01.txt                                 |
9   | If you did not receive a copy of the PHP license and are unable to   |
10   | obtain it through the world-wide-web, please send a note to          |
11   | license@php.net so we can mail you a copy immediately.               |
12   +----------------------------------------------------------------------+
13   | Authors: Andrey Hristov <andrey@php.net>                             |
14   |          Ulf Wendel <uw@php.net>                                     |
15   |          Georg Richter <georg@php.net>                               |
16   +----------------------------------------------------------------------+
17 */
18 
19 #ifndef MYSQLND_H
20 #define MYSQLND_H
21 
22 #define PHP_MYSQLND_VERSION "mysqlnd " PHP_VERSION
23 #define MYSQLND_VERSION_ID PHP_VERSION_ID
24 
25 #define MYSQLND_PLUGIN_API_VERSION 2
26 
27 /*
28   This force mysqlnd to do a single (or more depending on amount of data)
29   non-blocking read() calls before sending a command to the server. Useful
30   for debugging, if previous function hasn't consumed all the output sent
31   to it - like stmt_send_long_data() error because the data was larger that
32   max_allowed_packet_size, and COM_STMT_SEND_LONG_DATA by protocol doesn't
33   use response packets, thus letting the next command to fail miserably, if
34   the connector implementor is not aware of this deficiency. Should be off
35   on production systems, if of course measured performance degradation is not
36   minimal.
37 */
38 #if defined(A0) && PHP_DEBUG
39 #define MYSQLND_DO_WIRE_CHECK_BEFORE_COMMAND 1
40 #endif
41 
42 #if PHP_DEBUG
43 #define MYSQLND_DBG_ENABLED 1
44 #else
45 #define MYSQLND_DBG_ENABLED 0
46 #endif
47 
48 #ifdef ZTS
49 #include "TSRM.h"
50 #endif
51 
52 #include "mysqlnd_portability.h"
53 #include "mysqlnd_enum_n_def.h"
54 #include "mysqlnd_structs.h"
55 
56 #define MYSQLND_STR_W_LEN(str)  str, (sizeof(str) - 1)
57 
58 /* Library related */
59 PHPAPI void mysqlnd_library_init(void);
60 PHPAPI void mysqlnd_library_end(void);
61 
62 PHPAPI unsigned int mysqlnd_plugin_register(void);
63 PHPAPI unsigned int mysqlnd_plugin_register_ex(struct st_mysqlnd_plugin_header * plugin);
64 PHPAPI unsigned int mysqlnd_plugin_count(void);
65 PHPAPI void * mysqlnd_plugin_find(const char * const name);
66 
67 PHPAPI void mysqlnd_plugin_apply_with_argument(apply_func_arg_t apply_func, void * argument);
68 
69 #define mysqlnd_restart_psession(conn)	((conn)->data)->m->restart_psession((conn)->data)
70 #define mysqlnd_end_psession(conn)		((conn)->data)->m->end_psession((conn)->data)
71 PHPAPI void mysqlnd_minfo_print_hash(zval *values);
72 #define mysqlnd_thread_safe()	true
73 
74 PHPAPI const MYSQLND_CHARSET * mysqlnd_find_charset_nr(const unsigned int charsetno);
75 PHPAPI const MYSQLND_CHARSET * mysqlnd_find_charset_name(const char * const charsetname);
76 
77 
78 /* Connect */
79 #define mysqlnd_init(flags, persistent)		mysqlnd_connection_init((flags), (persistent), NULL /*use default factory*/)
80 #define mysqlnd_connect(conn, host, user, pass, pass_len, db, db_len, port, socket, mysql_flags, client_api_flags) \
81 			mysqlnd_connection_connect((conn), (host), (user), (pass), (pass_len), (db), (db_len), (port), (socket), (mysql_flags), (client_api_flags))
82 
83 PHPAPI MYSQLND * mysqlnd_connection_init(const size_t client_flags, const bool persistent, MYSQLND_CLASS_METHODS_TYPE(mysqlnd_object_factory) *object_factory);
84 PHPAPI MYSQLND * mysqlnd_connection_connect(MYSQLND * conn,
85 											const char * const host,
86 											const char * const user,
87 											const char * const passwd, unsigned int passwd_len,
88 											const char * const db, unsigned int db_len,
89 											unsigned int port,
90 											const char * const socket_or_pipe,
91 											unsigned int mysql_flags,
92 											unsigned int client_api_flags
93 										);
94 
95 #define mysqlnd_change_user(conn, user, passwd, db, silent)					((conn)->data)->m->change_user((conn)->data, (user), (passwd), (db), (silent), strlen((passwd)))
96 #define mysqlnd_change_user_ex(conn, user, passwd, db, silent, passwd_len)	((conn)->data)->m->change_user((conn)->data, (user), (passwd), (db), (silent), (passwd_len))
97 
98 PHPAPI void mysqlnd_debug(const char *mode);
99 
100 /* Query */
101 #define mysqlnd_fetch_into(result, flags, ret_val)	(result)->m.fetch_into((result), (flags), (ret_val) ZEND_FILE_LINE_CC)
102 #define mysqlnd_fetch_row_c(result)						(result)->m.fetch_row_c((result))
103 #define mysqlnd_fetch_row_zval(result, row_ptr, fetched) \
104 	(result)->m.fetch_row((result), (row_ptr), 0, (fetched))
105 #define mysqlnd_get_connection_stats(conn, values)		((conn)->data)->m->get_statistics((conn)->data,  (values) ZEND_FILE_LINE_CC)
106 #define mysqlnd_get_client_stats(values)				_mysqlnd_get_client_stats(mysqlnd_global_stats, (values) ZEND_FILE_LINE_CC)
107 
108 #define mysqlnd_close(conn,is_forced)					(conn)->m->close((conn), (is_forced))
109 #define mysqlnd_query(conn, query_str, query_len)		((conn)->data)->m->query((conn)->data, (query_str), (query_len))
110 #define mysqlnd_async_query(conn, query_str, query_len)	((conn)->data)->m->send_query((conn)->data, (query_str), (query_len), NULL, NULL)
111 #define mysqlnd_reap_async_query(conn)					((conn)->data)->m->reap_query((conn)->data)
112 
113 PHPAPI enum_func_status mysqlnd_poll(MYSQLND **r_array, MYSQLND **e_array, MYSQLND ***dont_poll, long sec, long usec, int * desc_num);
114 
115 #define mysqlnd_use_result(conn)		((conn)->data)->m->use_result((conn)->data)
116 #define mysqlnd_store_result(conn)		((conn)->data)->m->store_result((conn)->data)
117 #define mysqlnd_next_result(conn)		((conn)->data)->m->next_result((conn)->data)
118 #define mysqlnd_more_results(conn)		((conn)->data)->m->more_results((conn)->data)
119 #define mysqlnd_free_result(r,e_or_i)	((MYSQLND_RES*)r)->m.free_result(((MYSQLND_RES*)(r)), (e_or_i))
120 #define mysqlnd_data_seek(result, row)	(result)->m.seek_data((result), (row))
121 
122 /* Errors */
123 #define mysqlnd_errno(conn)				((conn)->data)->m->get_error_no((conn)->data)
124 #define mysqlnd_error(conn)				((conn)->data)->m->get_error_str((conn)->data)
125 #define mysqlnd_sqlstate(conn)			((conn)->data)->m->get_sqlstate((conn)->data)
126 
127 /* Charset */
128 #define mysqlnd_character_set_name(conn) ((conn)->data)->m->charset_name((conn)->data)
129 
130 /* Simple metadata */
131 #define mysqlnd_field_count(conn)		((conn)->data)->m->get_field_count((conn)->data)
132 #define mysqlnd_insert_id(conn)			((conn)->data)->m->get_last_insert_id((conn)->data)
133 #define mysqlnd_affected_rows(conn)		((conn)->data)->m->get_affected_rows((conn)->data)
134 #define mysqlnd_warning_count(conn)		((conn)->data)->m->get_warning_count((conn)->data)
135 #define mysqlnd_info(conn)				((conn)->data)->m->get_last_message((conn)->data)
136 #define mysqlnd_get_server_info(conn)	((conn)->data)->m->get_server_information((conn)->data)
137 #define mysqlnd_get_server_version(conn) ((conn)->data)->m->get_server_version((conn)->data)
138 #define mysqlnd_get_host_info(conn)		((conn)->data)->m->get_host_information((conn)->data)
139 #define mysqlnd_get_proto_info(conn)	((conn)->data)->m->get_protocol_information((conn)->data)
140 #define mysqlnd_thread_id(conn)			((conn)->data)->m->get_thread_id((conn)->data)
141 #define mysqlnd_get_server_status(conn)	((conn)->data)->m->get_server_status((conn)->data)
142 
143 #define mysqlnd_num_rows(result)		(result)->m.num_rows((result))
144 #define mysqlnd_num_fields(result)		(result)->m.num_fields((result))
145 
146 #define mysqlnd_fetch_lengths(result)	(result)->m.fetch_lengths((result))
147 
148 #define mysqlnd_field_seek(result, ofs)			(result)->m.seek_field((result), (ofs))
149 #define mysqlnd_field_tell(result)				(result)->m.field_tell((result))
150 #define mysqlnd_fetch_field(result)				(result)->m.fetch_field((result))
151 #define mysqlnd_fetch_field_direct(result,fnr)	(result)->m.fetch_field_direct((result), (fnr))
152 #define mysqlnd_fetch_fields(result)			(result)->m.fetch_fields((result))
153 
154 /* mysqlnd metadata */
155 PHPAPI const char *	mysqlnd_get_client_info(void);
156 PHPAPI unsigned long mysqlnd_get_client_version(void);
157 
158 #define mysqlnd_ssl_set(conn, key, cert, ca, capath, cipher) ((conn)->data)->m->ssl_set((conn)->data, (key), (cert), (ca), (capath), (cipher))
159 
160 /* PS */
161 #define mysqlnd_stmt_insert_id(stmt)		(stmt)->m->get_last_insert_id((stmt))
162 #define mysqlnd_stmt_affected_rows(stmt)	(stmt)->m->get_affected_rows((stmt))
163 #define mysqlnd_stmt_num_rows(stmt)			(stmt)->m->get_num_rows((stmt))
164 #define mysqlnd_stmt_param_count(stmt)		(stmt)->m->get_param_count((stmt))
165 #define mysqlnd_stmt_field_count(stmt)		(stmt)->m->get_field_count((stmt))
166 #define mysqlnd_stmt_warning_count(stmt)	(stmt)->m->get_warning_count((stmt))
167 #define mysqlnd_stmt_server_status(stmt)	(stmt)->m->get_server_status((stmt))
168 #define mysqlnd_stmt_errno(stmt)			(stmt)->m->get_error_no((stmt))
169 #define mysqlnd_stmt_error(stmt)			(stmt)->m->get_error_str((stmt))
170 #define mysqlnd_stmt_sqlstate(stmt)			(stmt)->m->get_sqlstate((stmt))
171 
172 
173 PHPAPI void mysqlnd_efree_param_bind_dtor(MYSQLND_PARAM_BIND * param_bind);
174 PHPAPI void mysqlnd_efree_result_bind_dtor(MYSQLND_RESULT_BIND * result_bind);
175 PHPAPI void mysqlnd_free_param_bind_dtor(MYSQLND_PARAM_BIND * param_bind);
176 PHPAPI void mysqlnd_free_result_bind_dtor(MYSQLND_RESULT_BIND * result_bind);
177 
178 
179 /* LOAD DATA LOCAL */
180 PHPAPI void mysqlnd_local_infile_default(MYSQLND_CONN_DATA * conn);
181 
182 /* Simple commands */
183 #define mysqlnd_autocommit(conn, mode)		((conn)->data)->m->set_autocommit((conn)->data, (mode))
184 #define mysqlnd_begin_transaction(conn,flags,name) ((conn)->data)->m->tx_begin((conn)->data, (flags), (name))
185 #define mysqlnd_commit(conn, flags, name)	((conn)->data)->m->tx_commit_or_rollback((conn)->data, true, (flags), (name))
186 #define mysqlnd_rollback(conn, flags, name)	((conn)->data)->m->tx_commit_or_rollback((conn)->data, false, (flags), (name))
187 #define mysqlnd_savepoint(conn, name)		((conn)->data)->m->tx_savepoint((conn)->data, (name))
188 #define mysqlnd_release_savepoint(conn, name) ((conn)->data)->m->tx_savepoint_release((conn)->data, (name))
189 #define mysqlnd_list_dbs(conn, wild)		((conn)->data)->m->list_method((conn)->data, wild? "SHOW DATABASES LIKE %s":"SHOW DATABASES", (wild), NULL)
190 #define mysqlnd_list_processes(conn)		((conn)->data)->m->list_method((conn)->data, "SHOW PROCESSLIST", NULL, NULL)
191 #define mysqlnd_list_tables(conn, wild)		((conn)->data)->m->list_method((conn)->data, wild? "SHOW TABLES LIKE %s":"SHOW TABLES", (wild), NULL)
192 #define mysqlnd_dump_debug_info(conn)		((conn)->data)->m->server_dump_debug_information((conn)->data)
193 #define mysqlnd_select_db(conn, db, db_len)	((conn)->data)->m->select_db((conn)->data, (db), (db_len))
194 #define mysqlnd_ping(conn)					((conn)->data)->m->ping((conn)->data)
195 #define mysqlnd_kill(conn, pid)				((conn)->data)->m->kill_connection((conn)->data, (pid))
196 #define mysqlnd_refresh(conn, options)		((conn)->data)->m->refresh_server((conn)->data, (options))
197 #define mysqlnd_shutdown(conn, level)		((conn)->data)->m->shutdown_server((conn)->data, (level))
198 #define mysqlnd_set_character_set(conn, cs)	((conn)->data)->m->set_charset((conn)->data, (cs))
199 #define mysqlnd_stat(conn, msg)				((conn)->data)->m->get_server_statistics(((conn)->data), (msg))
200 #define mysqlnd_options(conn, opt, value)	((conn)->data)->m->set_client_option((conn)->data, (opt), (value))
201 #define mysqlnd_options4(conn, opt, k, v)	((conn)->data)->m->set_client_option_2d((conn)->data, (opt), (k), (v))
202 #define mysqlnd_set_server_option(conn, op)	((conn)->data)->m->set_server_option((conn)->data, (op))
203 
204 /* Escaping */
205 #define mysqlnd_real_escape_string(conn, newstr, escapestr, escapestr_len) \
206 		((conn)->data)->m->escape_string((conn)->data, (newstr), (escapestr), (escapestr_len))
207 #define mysqlnd_escape_string(newstr, escapestr, escapestr_len) \
208 		mysqlnd_old_escape_string((newstr), (escapestr), (escapestr_len))
209 
210 PHPAPI zend_ulong mysqlnd_old_escape_string(char * newstr, const char * escapestr, size_t escapestr_len);
211 
212 
213 /* PS */
214 #define mysqlnd_stmt_init(conn)						((conn)->data)->m->stmt_init(((conn)->data))
215 #define mysqlnd_stmt_store_result(stmt)				(!mysqlnd_stmt_field_count((stmt)) ? PASS:((stmt)->m->store_result((stmt))? PASS:FAIL))
216 #define mysqlnd_stmt_get_result(stmt)				(stmt)->m->get_result((stmt))
217 #define mysqlnd_stmt_more_results(stmt)				(stmt)->m->more_results((stmt))
218 #define mysqlnd_stmt_next_result(stmt)				(stmt)->m->next_result((stmt))
219 #define mysqlnd_stmt_data_seek(stmt, row)			(stmt)->m->seek_data((stmt), (row))
220 #define mysqlnd_stmt_prepare(stmt, q, qlen)			(stmt)->m->prepare((stmt), (q), (qlen))
221 #define mysqlnd_stmt_execute(stmt) 					(stmt)->m->execute((stmt))
222 #define mysqlnd_stmt_send_long_data(stmt,p,d,l) 	(stmt)->m->send_long_data((stmt), (p), (d), (l))
223 #define mysqlnd_stmt_alloc_param_bind(stmt)			(stmt)->m->alloc_parameter_bind((stmt))
224 #define mysqlnd_stmt_free_param_bind(stmt,bind)		(stmt)->m->free_parameter_bind((stmt), (bind))
225 #define mysqlnd_stmt_bind_param(stmt,bind)			(stmt)->m->bind_parameters((stmt), (bind))
226 #define mysqlnd_stmt_bind_one_param(stmt,n,z,t)		(stmt)->m->bind_one_parameter((stmt), (n), (z), (t))
227 #define mysqlnd_stmt_refresh_bind_param(s)			(s)->m->refresh_bind_param((s))
228 #define mysqlnd_stmt_alloc_result_bind(stmt)		(stmt)->m->alloc_result_bind((stmt))
229 #define mysqlnd_stmt_free_result_bind(stmt,bind)	(stmt)->m->free_result_bind((stmt), (bind))
230 #define mysqlnd_stmt_bind_result(stmt,bind)			(stmt)->m->bind_result((stmt), (bind))
231 #define mysqlnd_stmt_bind_one_result(s,no)			(s)->m->bind_one_result((s), (no))
232 #define mysqlnd_stmt_result_metadata(stmt)			(stmt)->m->get_result_metadata((stmt))
233 
234 #define	mysqlnd_stmt_free_result(stmt)				(stmt)->m->free_result((stmt))
235 #define	mysqlnd_stmt_close(stmt, implicit)			(stmt)->m->dtor((stmt), (implicit))
236 #define	mysqlnd_stmt_reset(stmt)					(stmt)->m->reset((stmt))
237 #define	mysqlnd_stmt_flush(stmt)					(stmt)->m->flush((stmt))
238 
239 
240 #define mysqlnd_stmt_attr_get(stmt, attr, value)	(stmt)->m->get_attribute((stmt), (attr), (value))
241 #define mysqlnd_stmt_attr_set(stmt, attr, value)	(stmt)->m->set_attribute((stmt), (attr), (value))
242 
243 #define mysqlnd_stmt_fetch(stmt, fetched)	(stmt)->m->fetch((stmt), (fetched))
244 
245 
246 /* Performance statistics */
247 PHPAPI extern MYSQLND_STATS * mysqlnd_global_stats;
248 PHPAPI extern const MYSQLND_STRING mysqlnd_stats_values_names[];
249 PHPAPI void			_mysqlnd_get_client_stats(MYSQLND_STATS * stats, zval *return_value ZEND_FILE_LINE_DC);
250 
251 
252 #ifndef MYSQLND_CORE_STATISTICS_DISABLED
253 
254 #define MYSQLND_INC_GLOBAL_STATISTIC(statistic) \
255 	MYSQLND_INC_STATISTIC(MYSQLND_G(collect_statistics), mysqlnd_global_stats, (statistic))
256 
257 #define MYSQLND_DEC_GLOBAL_STATISTIC(statistic) \
258 	MYSQLND_DEC_STATISTIC(MYSQLND_G(collect_statistics), mysqlnd_global_stats, (statistic))
259 
260 #define MYSQLND_INC_GLOBAL_STATISTIC_W_VALUE2(statistic1, value1, statistic2, value2) \
261 	MYSQLND_INC_STATISTIC_W_VALUE2(MYSQLND_G(collect_statistics), mysqlnd_global_stats, (statistic1), (value1), (statistic2), (value2))
262 
263 #define MYSQLND_INC_CONN_STATISTIC(conn_stats, statistic) \
264 	MYSQLND_INC_STATISTIC(MYSQLND_G(collect_statistics), mysqlnd_global_stats, (statistic)); \
265 	MYSQLND_INC_STATISTIC(MYSQLND_G(collect_statistics), (conn_stats), (statistic));
266 
267 #define MYSQLND_INC_CONN_STATISTIC_W_VALUE(conn_stats, statistic, value) \
268 	MYSQLND_INC_STATISTIC_W_VALUE(MYSQLND_G(collect_statistics), mysqlnd_global_stats, (statistic), (value)); \
269 	MYSQLND_INC_STATISTIC_W_VALUE(MYSQLND_G(collect_statistics), (conn_stats), (statistic), (value));
270 
271 #define MYSQLND_INC_CONN_STATISTIC_W_VALUE2(conn_stats, statistic1, value1, statistic2, value2) \
272 	MYSQLND_INC_STATISTIC_W_VALUE2(MYSQLND_G(collect_statistics), mysqlnd_global_stats, (statistic1), (value1), (statistic2), (value2)); \
273 	MYSQLND_INC_STATISTIC_W_VALUE2(MYSQLND_G(collect_statistics), (conn_stats), (statistic1), (value1), (statistic2), (value2));
274 
275 #define MYSQLND_INC_CONN_STATISTIC_W_VALUE3(conn_stats, statistic1, value1, statistic2, value2, statistic3, value3) \
276 	MYSQLND_INC_STATISTIC_W_VALUE3(MYSQLND_G(collect_statistics), mysqlnd_global_stats, (statistic1), (value1), (statistic2), (value2), (statistic3), (value3)); \
277 	MYSQLND_INC_STATISTIC_W_VALUE3(MYSQLND_G(collect_statistics), (conn_stats), (statistic1), (value1), (statistic2), (value2), (statistic3), (value3));
278 
279 #else
280 
281 #define MYSQLND_INC_GLOBAL_STATISTIC(statistic)
282 #define MYSQLND_DEC_GLOBAL_STATISTIC(statistic)
283 #define MYSQLND_INC_GLOBAL_STATISTIC_W_VALUE2(statistic1, value1, statistic2, value2)
284 #define MYSQLND_INC_CONN_STATISTIC(conn_stats, statistic)
285 #define MYSQLND_INC_CONN_STATISTIC_W_VALUE(conn_stats, statistic, value)
286 #define MYSQLND_INC_CONN_STATISTIC_W_VALUE2(conn_stats, statistic1, value1, statistic2, value2)
287 #define MYSQLND_INC_CONN_STATISTIC_W_VALUE3(conn_stats, statistic1, value1, statistic2, value2, statistic3, value3)
288 
289 #endif /* MYSQLND_CORE_STATISTICS_DISABLED */
290 
291 
292 /* double check the class name to avoid naming conflicts when using these: */
293 #define MYSQLND_METHOD(class, method) 			mysqlnd_##class##_##method##_pub
294 #define MYSQLND_METHOD_PRIVATE(class, method)	mysqlnd_##class##_##method##_priv
295 
296 ZEND_BEGIN_MODULE_GLOBALS(mysqlnd)
297 	char *			debug;	/* The actual string */
298 	char *			trace_alloc_settings;	/* The actual string */
299 	MYSQLND_DEBUG *	dbg;	/* The DBG object for standard tracing */
300 	MYSQLND_DEBUG *	trace_alloc;	/* The DBG object for allocation tracing */
301 	zend_long		net_cmd_buffer_size;
302 	zend_long		net_read_buffer_size;
303 	zend_long		log_mask;
304 	zend_long		net_read_timeout;
305 	zend_long		mempool_default_size;
306 	char *			sha256_server_public_key;
307 	bool		collect_statistics;
308 	bool		collect_memory_statistics;
309 ZEND_END_MODULE_GLOBALS(mysqlnd)
310 
311 PHPAPI ZEND_EXTERN_MODULE_GLOBALS(mysqlnd)
312 #define MYSQLND_G(v) ZEND_MODULE_GLOBALS_ACCESSOR(mysqlnd, v)
313 
314 #if defined(ZTS) && defined(COMPILE_DL_MYSQLND)
315 ZEND_TSRMLS_CACHE_EXTERN()
316 #endif
317 
318 
319 PHPAPI void mysqlnd_minfo_print_hash(zval *values);
320 
321 #endif	/* MYSQLND_H */
322