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