xref: /PHP-8.1/ext/pdo/php_pdo_driver.h (revision 1e012ecb)
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   | Author: Wez Furlong <wez@php.net>                                    |
14   +----------------------------------------------------------------------+
15 */
16 
17 #ifndef PHP_PDO_DRIVER_H
18 #define PHP_PDO_DRIVER_H
19 
20 #include "php_pdo.h"
21 
22 /* forward declarations */
23 typedef struct _pdo_dbh_t 		 pdo_dbh_t;
24 typedef struct _pdo_dbh_object_t pdo_dbh_object_t;
25 typedef struct _pdo_stmt_t		 pdo_stmt_t;
26 typedef struct _pdo_row_t		 pdo_row_t;
27 struct pdo_bound_param_data;
28 
29 #ifndef TRUE
30 # define TRUE 1
31 #endif
32 #ifndef FALSE
33 # define FALSE 0
34 #endif
35 
36 #define PDO_DRIVER_API	20170320
37 
38 /* Doctrine hardcodes these constants, avoid changing their values. */
39 enum pdo_param_type {
40 	PDO_PARAM_NULL = 0,
41 	PDO_PARAM_BOOL = 5,
42 	PDO_PARAM_INT = 1,
43 	PDO_PARAM_STR = 2,
44 	PDO_PARAM_LOB = 3,
45 
46 	/* get_col: Not supported (yet?) */
47 	PDO_PARAM_STMT = 4, /* hierarchical result set */
48 
49 	/* magic flag to denote a parameter as being input/output */
50 	PDO_PARAM_INPUT_OUTPUT = 0x80000000,
51 
52 	/* magic flag to denote a string that uses the national character set
53 	   see section 4.2.1 of SQL-92: http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt
54 	 */
55 	PDO_PARAM_STR_NATL = 0x40000000,
56 
57 	/* magic flag to denote a string that uses the regular character set */
58 	PDO_PARAM_STR_CHAR = 0x20000000,
59 };
60 
61 #define PDO_PARAM_FLAGS			0xFFFF0000
62 
63 #define PDO_PARAM_TYPE(x)		((x) & ~PDO_PARAM_FLAGS)
64 
65 enum pdo_fetch_type {
66 	PDO_FETCH_USE_DEFAULT,
67 	PDO_FETCH_LAZY,
68 	PDO_FETCH_ASSOC,
69 	PDO_FETCH_NUM,
70 	PDO_FETCH_BOTH,
71 	PDO_FETCH_OBJ,
72 	PDO_FETCH_BOUND, /* return true/false only; rely on bound columns */
73 	PDO_FETCH_COLUMN,	/* fetch a numbered column only */
74 	PDO_FETCH_CLASS,	/* create an instance of named class, call ctor and set properties */
75 	PDO_FETCH_INTO,		/* fetch row into an existing object */
76 	PDO_FETCH_FUNC,		/* fetch into function and return its result */
77 	PDO_FETCH_NAMED,    /* like PDO_FETCH_ASSOC, but can handle duplicate names */
78 	PDO_FETCH_KEY_PAIR,	/* fetch into an array where the 1st column is a key and all subsequent columns are values */
79 	PDO_FETCH__MAX /* must be last */
80 };
81 
82 #define PDO_FETCH_FLAGS     0xFFFF0000  /* fetchAll() modes or'd to PDO_FETCH_XYZ */
83 #define PDO_FETCH_GROUP     0x00010000  /* fetch into groups */
84 #define PDO_FETCH_UNIQUE    0x00030000  /* fetch into groups assuming first col is unique */
85 #define PDO_FETCH_CLASSTYPE 0x00040000  /* fetch class gets its class name from 1st column */
86 #define PDO_FETCH_SERIALIZE 0x00080000  /* fetch class instances by calling serialize */
87 #define PDO_FETCH_PROPS_LATE 0x00100000  /* fetch props after calling ctor */
88 
89 /* fetch orientation for scrollable cursors */
90 enum pdo_fetch_orientation {
91 	PDO_FETCH_ORI_NEXT,		/* default: fetch the next available row */
92 	PDO_FETCH_ORI_PRIOR,	/* scroll back to prior row and fetch that */
93 	PDO_FETCH_ORI_FIRST,	/* scroll to the first row and fetch that */
94 	PDO_FETCH_ORI_LAST,		/* scroll to the last row and fetch that */
95 	PDO_FETCH_ORI_ABS,		/* scroll to an absolute numbered row and fetch that */
96 	PDO_FETCH_ORI_REL		/* scroll relative to the current row, and fetch that */
97 };
98 
99 enum pdo_attribute_type {
100 	PDO_ATTR_AUTOCOMMIT,	/* use to turn on or off auto-commit mode */
101 	PDO_ATTR_PREFETCH,		/* configure the prefetch size for drivers that support it. Size is in KB */
102 	PDO_ATTR_TIMEOUT,		/* connection timeout in seconds */
103 	PDO_ATTR_ERRMODE,		/* control how errors are handled */
104 	PDO_ATTR_SERVER_VERSION,	/* database server version */
105 	PDO_ATTR_CLIENT_VERSION,	/* client library version */
106 	PDO_ATTR_SERVER_INFO,		/* server information */
107 	PDO_ATTR_CONNECTION_STATUS,	/* connection status */
108 	PDO_ATTR_CASE,				/* control case folding for portability */
109 	PDO_ATTR_CURSOR_NAME,		/* name a cursor for use in "WHERE CURRENT OF <name>" */
110 	PDO_ATTR_CURSOR,			/* cursor type */
111 	PDO_ATTR_ORACLE_NULLS,		/* convert empty strings to NULL */
112 	PDO_ATTR_PERSISTENT,		/* pconnect style connection */
113 	PDO_ATTR_STATEMENT_CLASS,	/* array(classname, array(ctor_args)) to specify the class of the constructed statement */
114 	PDO_ATTR_FETCH_TABLE_NAMES, /* include table names in the column names, where available */
115 	PDO_ATTR_FETCH_CATALOG_NAMES, /* include the catalog/db name names in the column names, where available */
116 	PDO_ATTR_DRIVER_NAME,		  /* name of the driver (as used in the constructor) */
117 	PDO_ATTR_STRINGIFY_FETCHES,	/* converts integer/float types to strings during fetch */
118 	PDO_ATTR_MAX_COLUMN_LEN,	/* make database calculate maximum length of data found in a column */
119 	PDO_ATTR_DEFAULT_FETCH_MODE, /* Set the default fetch mode */
120 	PDO_ATTR_EMULATE_PREPARES,  /* use query emulation rather than native */
121 	PDO_ATTR_DEFAULT_STR_PARAM, /* set the default string parameter type (see the PDO::PARAM_STR_* magic flags) */
122 
123 	/* this defines the start of the range for driver specific options.
124 	 * Drivers should define their own attribute constants beginning with this
125 	 * value. */
126 	PDO_ATTR_DRIVER_SPECIFIC = 1000
127 };
128 
129 enum pdo_cursor_type {
130 	PDO_CURSOR_FWDONLY,		/* forward only cursor (default) */
131 	PDO_CURSOR_SCROLL		/* scrollable cursor */
132 };
133 
134 /* SQL-92 SQLSTATE error codes.
135 
136 The character string value returned for an SQLSTATE consists of a two-character
137 class value followed by a three-character subclass value. A class value of 01
138 indicates a warning and is accompanied by a return code of
139 SQL_SUCCESS_WITH_INFO.
140 
141 Class values other than '01', except for the class 'IM',
142 indicate an error and are accompanied by a return code of SQL_ERROR. The class
143 'IM' is specific to warnings and errors that derive from the implementation of
144 ODBC itself.
145 
146 The subclass value '000' in any class indicates that there is no
147 subclass for that SQLSTATE. The assignment of class and subclass values is
148 defined by SQL-92.
149 */
150 
151 typedef char pdo_error_type[6]; /* SQLSTATE */
152 
153 
154 #define PDO_ERR_NONE				"00000"
155 
156 enum pdo_error_mode {
157 	PDO_ERRMODE_SILENT,		/* just set error codes */
158 	PDO_ERRMODE_WARNING,	/* raise E_WARNING */
159 	PDO_ERRMODE_EXCEPTION	/* throw exceptions */
160 };
161 
162 enum pdo_case_conversion {
163 	PDO_CASE_NATURAL,
164 	PDO_CASE_UPPER,
165 	PDO_CASE_LOWER
166 };
167 
168 /* oracle interop settings */
169 enum pdo_null_handling {
170 	PDO_NULL_NATURAL = 0,
171 	PDO_NULL_EMPTY_STRING = 1,
172 	PDO_NULL_TO_STRING = 2
173 };
174 
175 /* {{{ utils for reading attributes set as driver_options */
pdo_attr_lval(zval * options,unsigned option_name,zend_long defval)176 static inline zend_long pdo_attr_lval(zval *options, unsigned option_name, zend_long defval)
177 {
178 	zval *v;
179 
180 	if (options && (v = zend_hash_index_find(Z_ARRVAL_P(options), option_name))) {
181 		return zval_get_long(v);
182 	}
183 	return defval;
184 }
pdo_attr_strval(zval * options,unsigned option_name,zend_string * defval)185 static inline zend_string *pdo_attr_strval(zval *options, unsigned option_name, zend_string *defval)
186 {
187 	zval *v;
188 
189 	if (options && (v = zend_hash_index_find(Z_ARRVAL_P(options), option_name))) {
190 		return zval_try_get_string(v);
191 	}
192 	return defval ? zend_string_copy(defval) : NULL;
193 }
194 /* }}} */
195 
196 /* This structure is registered with PDO when a PDO driver extension is
197  * initialized */
198 typedef struct {
199 	const char	*driver_name;
200 	size_t		driver_name_len;
201 	zend_ulong	api_version; /* needs to be compatible with PDO */
202 
203 #define PDO_DRIVER_HEADER(name)	\
204 	#name, sizeof(#name)-1, \
205 	PDO_DRIVER_API
206 
207 	/* create driver specific portion of the database handle and stash it into
208 	 * the dbh.  dbh contains the data source string and flags for this
209 	 * instance.  You MUST respect dbh->is_persistent and pass that flag to
210 	 * pemalloc() for all allocations that are stored in the dbh or your instance
211 	 * data in the db, otherwise you will crash PHP when persistent connections
212 	 * are used.
213 	 */
214 	int (*db_handle_factory)(pdo_dbh_t *dbh, zval *driver_options);
215 
216 } pdo_driver_t;
217 
218 /* {{{ methods for a database handle */
219 
220 /* close or otherwise disconnect the database */
221 typedef void (*pdo_dbh_close_func)(pdo_dbh_t *dbh);
222 
223 /* prepare a statement and stash driver specific portion into stmt
224  * return true on success, false otherwise */
225 typedef bool (*pdo_dbh_prepare_func)(pdo_dbh_t *dbh, zend_string *sql, pdo_stmt_t *stmt, zval *driver_options);
226 
227 /* execute a statement (that does not return a result set)
228  * Return -1 on failure, otherwise the number of affected rows */
229 typedef zend_long (*pdo_dbh_do_func)(pdo_dbh_t *dbh, const zend_string *sql);
230 
231 /* quote a string */
232 typedef zend_string* (*pdo_dbh_quote_func)(pdo_dbh_t *dbh, const zend_string *unquoted, enum pdo_param_type paramtype);
233 
234 /* transaction related (beingTransaction(), commit, rollBack, inTransaction)
235  * Return true if currently inside a transaction, false otherwise. */
236 typedef bool (*pdo_dbh_txn_func)(pdo_dbh_t *dbh);
237 
238 /* setting of attributes
239  * Return true on success and false in case of failure */
240 typedef bool (*pdo_dbh_set_attr_func)(pdo_dbh_t *dbh, zend_long attr, zval *val);
241 
242 /* return last insert id.  NULL indicates error condition.
243  * name MIGHT be NULL */
244 typedef zend_string *(*pdo_dbh_last_id_func)(pdo_dbh_t *dbh, const zend_string *name);
245 
246 /* Fetch error information.
247  * If stmt is not null, fetch information pertaining to the statement,
248  * otherwise fetch global error information.
249  * info is an initialized PHP array, if there are no messages leave it empty.
250  * The driver should add the following information to the array "info" in this order:
251  * - native error code
252  * - string representation of the error code ... any other optional driver
253  *   specific data ...
254  * PDO takes care of normalizing the array. */
255 typedef void (*pdo_dbh_fetch_error_func)(pdo_dbh_t *dbh, pdo_stmt_t *stmt, zval *info);
256 
257 /* fetching of attributes
258  * There are 3 return states:
259  * * -1 for errors while retrieving a valid attribute
260  * * 0 for attempting to retrieve an attribute which is not supported by the driver
261  * * any other value for success, *val must be set to the attribute value */
262 typedef int (*pdo_dbh_get_attr_func)(pdo_dbh_t *dbh, zend_long attr, zval *val);
263 
264 /* checking/pinging persistent connections; return SUCCESS if the connection
265  * is still alive and ready to be used, FAILURE otherwise.
266  * You may set this handler to NULL, which is equivalent to returning SUCCESS. */
267 typedef zend_result (*pdo_dbh_check_liveness_func)(pdo_dbh_t *dbh);
268 
269 /* called at request end for each persistent dbh; this gives the driver
270  * the opportunity to safely release resources that only have per-request
271  * scope */
272 typedef void (*pdo_dbh_request_shutdown)(pdo_dbh_t *dbh);
273 
274 /* Called when the PDO handle is scanned for GC. Should populate the get_gc buffer
275  * with any zvals in the driver_data that would be freed if the handle is destroyed. */
276 typedef void (*pdo_dbh_get_gc_func)(pdo_dbh_t *dbh, zend_get_gc_buffer *buffer);
277 
278 /* for adding methods to the dbh or stmt objects
279 pointer to a list of driver specific functions. The convention is
280 to prefix the function names using the PDO driver name; this will
281 reduce the chance of collisions with future functionality in the
282 PDO class or in user code (they can extend the PDO object).
283 */
284 enum {
285 	PDO_DBH_DRIVER_METHOD_KIND_DBH = 0,
286 	PDO_DBH_DRIVER_METHOD_KIND_STMT,
287 	PDO_DBH_DRIVER_METHOD_KIND__MAX
288 };
289 
290 typedef const zend_function_entry *(*pdo_dbh_get_driver_methods_func)(pdo_dbh_t *dbh, int kind);
291 
292 struct pdo_dbh_methods {
293 	pdo_dbh_close_func		closer;
294 	pdo_dbh_prepare_func	preparer;
295 	pdo_dbh_do_func			doer;
296 	pdo_dbh_quote_func		quoter;
297 	pdo_dbh_txn_func		begin;
298 	pdo_dbh_txn_func		commit;
299 	pdo_dbh_txn_func		rollback;
300 	pdo_dbh_set_attr_func	set_attribute;
301 	pdo_dbh_last_id_func		last_id;
302 	pdo_dbh_fetch_error_func	fetch_err;
303 	pdo_dbh_get_attr_func   	get_attribute;
304 	pdo_dbh_check_liveness_func	check_liveness;
305 	pdo_dbh_get_driver_methods_func get_driver_methods;
306 	pdo_dbh_request_shutdown	persistent_shutdown;
307 	/* if defined to NULL, PDO will use its internal transaction tracking state */
308 	pdo_dbh_txn_func		in_transaction;
309 	pdo_dbh_get_gc_func		get_gc;
310 };
311 
312 /* }}} */
313 
314 /* {{{ methods for a statement handle */
315 
316 /* free the statement handle */
317 typedef int (*pdo_stmt_dtor_func)(pdo_stmt_t *stmt);
318 
319 /* start the query */
320 typedef int (*pdo_stmt_execute_func)(pdo_stmt_t *stmt);
321 
322 /* causes the next row in the set to be fetched; indicates if there are no
323  * more rows.  The ori and offset params modify which row should be returned,
324  * if the stmt represents a scrollable cursor */
325 typedef int (*pdo_stmt_fetch_func)(pdo_stmt_t *stmt,
326 	enum pdo_fetch_orientation ori, zend_long offset);
327 
328 /* queries information about the type of a column, by index (0 based).
329  * Driver should populate stmt->columns[colno] with appropriate info */
330 typedef int (*pdo_stmt_describe_col_func)(pdo_stmt_t *stmt, int colno);
331 
332 /* Retrieves zval value of a column. If type is non-NULL, then this specifies the type which
333  * the user requested through bindColumn(). The driver does not need to check this argument,
334  * as PDO will perform any necessary conversions itself. However, it might be used to fetch
335  * a value more efficiently into the final type, or make the behavior dependent on the requested
336  * type. */
337 typedef int (*pdo_stmt_get_col_data_func)(
338 	pdo_stmt_t *stmt, int colno, zval *result, enum pdo_param_type *type);
339 
340 /* hook for bound params */
341 enum pdo_param_event {
342 	PDO_PARAM_EVT_ALLOC,
343 	PDO_PARAM_EVT_FREE,
344 	PDO_PARAM_EVT_EXEC_PRE,
345 	PDO_PARAM_EVT_EXEC_POST,
346 	PDO_PARAM_EVT_FETCH_PRE,
347 	PDO_PARAM_EVT_FETCH_POST,
348 	PDO_PARAM_EVT_NORMALIZE
349 };
350 
351 typedef int (*pdo_stmt_param_hook_func)(pdo_stmt_t *stmt, struct pdo_bound_param_data *param, enum pdo_param_event event_type);
352 
353 /* setting of attributes */
354 typedef int (*pdo_stmt_set_attr_func)(pdo_stmt_t *stmt, zend_long attr, zval *val);
355 
356 /* fetching of attributes */
357 typedef int (*pdo_stmt_get_attr_func)(pdo_stmt_t *stmt, zend_long attr, zval *val);
358 
359 /* retrieves meta data for a numbered column.
360  * Returns SUCCESS/FAILURE.
361  * On SUCCESS, fill in return_value with an array with the following fields.
362  * If a particular field is not supported, then the driver simply does not add it to
363  * the array, so that scripts can use isset() to check for it.
364  *
365  * ### this is just a rough first cut, and subject to change ###
366  *
367  * these are added by PDO itself, based on data from the describe handler:
368  *   name => the column name
369  *   len => the length/size of the column
370  *   precision => precision of the column
371  *
372  *   pdo_type => an integer, one of the PDO_PARAM_XXX values
373  *   scale => the floating point scale
374  *   table => the table for that column
375  *   type => a string representation of the type, mapped to the PHP equivalent type name
376  *   native_type => a string representation of the type, native style, if different from
377  *                  the mapped name.
378  *   flags => an array of flags including zero or more of the following:
379  *            primary_key, not_null, unique_key, multiple_key, unsigned, auto_increment, blob
380  *
381  * Any driver specific data should be returned using a prefixed key or value.
382  * Eg: custom data for the mysql driver would use either
383  *   'mysql:foobar' => 'some data' // to add a new key to the array
384  * or
385  *   'flags' => array('not_null', 'mysql:some_flag'); // to add data to an existing key
386  */
387 typedef int (*pdo_stmt_get_column_meta_func)(pdo_stmt_t *stmt, zend_long colno, zval *return_value);
388 
389 /* advances the statement to the next rowset of the batch.
390  * If it returns 1, PDO will tear down its idea of columns
391  * and meta data.  If it returns 0, PDO will indicate an error
392  * to the caller. */
393 typedef int (*pdo_stmt_next_rowset_func)(pdo_stmt_t *stmt);
394 
395 /* closes the active cursor on a statement, leaving the prepared
396  * statement ready for re-execution.  Useful to explicitly state
397  * that you are done with a given rowset, without having to explicitly
398  * fetch all the rows. */
399 typedef int (*pdo_stmt_cursor_closer_func)(pdo_stmt_t *stmt);
400 
401 struct pdo_stmt_methods {
402 	pdo_stmt_dtor_func			dtor;
403 	pdo_stmt_execute_func		executer;
404 	pdo_stmt_fetch_func			fetcher;
405 	pdo_stmt_describe_col_func	describer;
406 	pdo_stmt_get_col_data_func	get_col;
407 	pdo_stmt_param_hook_func	param_hook;
408 	pdo_stmt_set_attr_func		set_attribute;
409 	pdo_stmt_get_attr_func		get_attribute;
410 	pdo_stmt_get_column_meta_func get_column_meta;
411 	pdo_stmt_next_rowset_func		next_rowset;
412 	pdo_stmt_cursor_closer_func 	cursor_closer;
413 };
414 
415 /* }}} */
416 
417 enum pdo_placeholder_support {
418 	PDO_PLACEHOLDER_NONE=0,
419 	PDO_PLACEHOLDER_NAMED=1,
420 	PDO_PLACEHOLDER_POSITIONAL=2
421 };
422 
423 struct _pdo_dbh_t {
424 	/* driver specific methods */
425 	const struct pdo_dbh_methods *methods;
426 	/* driver specific data */
427 	void *driver_data;
428 
429 	/* credentials */
430 	char *username, *password;
431 
432 	/* if true, then data stored and pointed at by this handle must all be
433 	 * persistently allocated */
434 	unsigned is_persistent:1;
435 
436 	/* if true, driver should act as though a COMMIT were executed between
437 	 * each executed statement; otherwise, COMMIT must be carried out manually
438 	 * */
439 	unsigned auto_commit:1;
440 
441 	/* if true, the handle has been closed and will not function anymore */
442 	unsigned is_closed:1;
443 
444 	/* if true, the driver requires that memory be allocated explicitly for
445 	 * the columns that are returned */
446 	unsigned alloc_own_columns:1;
447 
448 	/* if true, commit or rollBack is allowed to be called */
449 	bool in_txn:1;
450 
451 	/* max length a single character can become after correct quoting */
452 	unsigned max_escaped_char_length:3;
453 
454 	/* oracle compat; see enum pdo_null_handling */
455 	unsigned oracle_nulls:2;
456 
457 	/* when set, convert int/floats to strings */
458 	unsigned stringify:1;
459 
460 	/* bitmap for pdo_param_event(s) to skip in dispatch_param_event */
461 	unsigned skip_param_evt:7;
462 
463 	/* the sum of the number of bits here and the bit fields preceding should
464 	 * equal 32 */
465 	unsigned _reserved_flags:14;
466 
467 	/* data source string used to open this handle */
468 	const char *data_source;
469 	size_t data_source_len;
470 
471 	/* the global error code. */
472 	pdo_error_type error_code;
473 
474 	enum pdo_error_mode error_mode;
475 
476 	enum pdo_case_conversion native_case, desired_case;
477 
478 	/* persistent hash key associated with this handle */
479 	const char *persistent_id;
480 	size_t persistent_id_len;
481 	unsigned int refcount;
482 
483 	/* driver specific "class" methods for the dbh and stmt */
484 	HashTable *cls_methods[PDO_DBH_DRIVER_METHOD_KIND__MAX];
485 
486 	pdo_driver_t *driver;
487 
488 	zend_class_entry *def_stmt_ce;
489 
490 	zval def_stmt_ctor_args;
491 
492 	/* when calling PDO::query(), we need to keep the error
493 	 * context from the statement around until we next clear it.
494 	 * This will allow us to report the correct error message
495 	 * when PDO::query() fails */
496 	pdo_stmt_t *query_stmt;
497 	zval query_stmt_zval;
498 
499 	/* defaults for fetches */
500 	enum pdo_fetch_type default_fetch_type;
501 };
502 
503 /* represents a connection to a database */
504 struct _pdo_dbh_object_t {
505 	pdo_dbh_t *inner;
506 	/* these items must appear in this order at the beginning of the
507        struct so that this can be cast as a zend_object.  we need this
508        to allow the extending class to escape all the custom handlers
509 	   that PDO declares.
510     */
511 	zend_object std;
512 };
513 
php_pdo_dbh_fetch_inner(zend_object * obj)514 static inline pdo_dbh_t *php_pdo_dbh_fetch_inner(zend_object *obj) {
515 	return (pdo_dbh_t *)(((pdo_dbh_object_t *)((char*)(obj) - XtOffsetOf(pdo_dbh_object_t, std)))->inner);
516 }
517 
php_pdo_dbh_fetch_object(zend_object * obj)518 static inline pdo_dbh_object_t *php_pdo_dbh_fetch_object(zend_object *obj) {
519 	return (pdo_dbh_object_t *)((char*)(obj) - XtOffsetOf(pdo_dbh_object_t, std));
520 }
521 
522 #define Z_PDO_DBH_P(zv) php_pdo_dbh_fetch_inner(Z_OBJ_P((zv)))
523 #define Z_PDO_OBJECT_P(zv) php_pdo_dbh_fetch_object(Z_OBJ_P((zv)))
524 
525 /* describes a column */
526 struct pdo_column_data {
527 	zend_string *name;
528 	size_t maxlen;
529 	zend_ulong precision;
530 };
531 
532 /* describes a bound parameter */
533 struct pdo_bound_param_data {
534 	zval parameter;				/* the variable itself */
535 
536 	zval driver_params;			/* optional parameter(s) for the driver */
537 
538 	zend_long paramno; /* if -1, then it has a name, and we don't know the index *yet* */
539 	zend_string *name;
540 
541 	zend_long max_value_len;	/* as a hint for pre-allocation */
542 
543 	void *driver_data;
544 
545 	pdo_stmt_t *stmt;	/* for convenience in dtor */
546 
547 	enum pdo_param_type param_type; /* desired or suggested variable type */
548 
549 	int is_param;		/* parameter or column ? */
550 };
551 
552 /* represents a prepared statement */
553 struct _pdo_stmt_t {
554 	/* driver specifics */
555 	const struct pdo_stmt_methods *methods;
556 	void *driver_data;
557 
558 	/* if true, we've already successfully executed this statement at least
559 	 * once */
560 	unsigned executed:1;
561 	/* if true, the statement supports placeholders and can implement
562 	 * bindParam() for its prepared statements, if false, PDO should
563 	 * emulate prepare and bind on its behalf */
564 	unsigned supports_placeholders:2;
565 
566 	unsigned _reserved:29;
567 
568 	/* the number of columns in the result set; not valid until after
569 	 * the statement has been executed at least once.  In some cases, might
570 	 * not be valid until fetch (at the driver level) has been called at least once.
571 	 * */
572 	int column_count;
573 	struct pdo_column_data *columns;
574 
575 	/* we want to keep the dbh alive while we live, so we own a reference */
576 	zval database_object_handle;
577 	pdo_dbh_t *dbh;
578 
579 	/* keep track of bound input parameters.  Some drivers support
580 	 * input/output parameters, but you can't rely on that working */
581 	HashTable *bound_params;
582 	/* When rewriting from named to positional, this maps positions to names */
583 	HashTable *bound_param_map;
584 	/* keep track of PHP variables bound to named (or positional) columns
585 	 * in the result set */
586 	HashTable *bound_columns;
587 
588 	/* not always meaningful */
589 	zend_long row_count;
590 
591 	/* used to hold the statement's current query */
592 	zend_string *query_string;
593 
594 	/* the copy of the query with expanded binds ONLY for emulated-prepare drivers */
595 	zend_string *active_query_string;
596 
597 	/* the cursor specific error code. */
598 	pdo_error_type error_code;
599 
600 	/* for lazy fetches, we always return the same lazy object handle.
601 	 * Let's keep it here. */
602 	zval lazy_object_ref;
603 	zend_ulong refcount;
604 
605 	/* defaults for fetches */
606 	enum pdo_fetch_type default_fetch_type;
607 	union {
608 		int column;
609 		struct {
610 			zval ctor_args;            /* freed */
611 			zend_fcall_info fci;
612 			zend_fcall_info_cache fcc;
613 			zval retval;
614 			zend_class_entry *ce;
615 		} cls;
616 		struct {
617 			zval fetch_args;           /* freed */
618 			zend_fcall_info fci;
619 			zend_fcall_info_cache fcc;
620 			zval object;
621 			zval function;
622 			zval *values;              /* freed */
623 		} func;
624 		zval into;
625 	} fetch;
626 
627 	/* used by the query parser for driver specific
628 	 * parameter naming (see pgsql driver for example) */
629 	const char *named_rewrite_template;
630 
631 	/* these items must appear in this order at the beginning of the
632        struct so that this can be cast as a zend_object.  we need this
633        to allow the extending class to escape all the custom handlers
634 	   that PDO declares.
635     */
636 	zend_object std;
637 };
638 
php_pdo_stmt_fetch_object(zend_object * obj)639 static inline pdo_stmt_t *php_pdo_stmt_fetch_object(zend_object *obj) {
640 	return (pdo_stmt_t *)((char*)(obj) - XtOffsetOf(pdo_stmt_t, std));
641 }
642 
643 #define Z_PDO_STMT_P(zv) php_pdo_stmt_fetch_object(Z_OBJ_P((zv)))
644 
645 struct _pdo_row_t {
646 	zend_object std;
647 	pdo_stmt_t *stmt;
648 };
649 
650 /* Call this in MINIT to register the PDO driver.
651  * Registering the driver might fail and should be reported accordingly in MINIT. */
652 PDO_API zend_result php_pdo_register_driver(const pdo_driver_t *driver);
653 /* call this in MSHUTDOWN to unregister your PDO driver */
654 PDO_API void php_pdo_unregister_driver(const pdo_driver_t *driver);
655 
656 /* For the convenience of drivers, this function will parse a data source
657  * string, of the form "name=value; name2=value2" and populate variables
658  * according to the data you pass in and array of pdo_data_src_parser structures */
659 struct pdo_data_src_parser {
660 	const char *optname;
661 	char *optval;
662 	int freeme;
663 };
664 
665 PDO_API int php_pdo_parse_data_source(const char *data_source,
666 		zend_ulong data_source_len, struct pdo_data_src_parser *parsed,
667 		int nparams);
668 
669 PDO_API zend_class_entry *php_pdo_get_dbh_ce(void);
670 PDO_API zend_class_entry *php_pdo_get_exception(void);
671 
672 PDO_API int pdo_parse_params(pdo_stmt_t *stmt, zend_string *inquery, zend_string **outquery);
673 
674 PDO_API void pdo_raise_impl_error(pdo_dbh_t *dbh, pdo_stmt_t *stmt,
675 	const char *sqlstate, const char *supp);
676 
677 PDO_API void php_pdo_dbh_addref(pdo_dbh_t *dbh);
678 PDO_API void php_pdo_dbh_delref(pdo_dbh_t *dbh);
679 
680 PDO_API void php_pdo_free_statement(pdo_stmt_t *stmt);
681 PDO_API void php_pdo_stmt_set_column_count(pdo_stmt_t *stmt, int new_count);
682 
683 /* Normalization for fetching long param for driver attributes */
684 PDO_API bool pdo_get_long_param(zend_long *lval, zval *value);
685 PDO_API bool pdo_get_bool_param(bool *bval, zval *value);
686 
687 PDO_API void pdo_throw_exception(unsigned int driver_errcode, char *driver_errmsg, pdo_error_type *pdo_error);
688 #endif /* PHP_PDO_DRIVER_H */
689