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