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 /* Call this in MINIT to register the PDO driver specific class entry.
657 * Registering the driver specific class entry might fail and should be reported accordingly in MINIT.
658 * Unregistering the class entry is not necessary, since php_pdo_unregister_driver() takes care of it. */
659 PDO_API zend_result php_pdo_register_driver_specific_ce(const pdo_driver_t *driver, zend_class_entry *ce);
660
661 /* For the convenience of drivers, this function will parse a data source
662 * string, of the form "name=value; name2=value2" and populate variables
663 * according to the data you pass in and array of pdo_data_src_parser structures */
664 struct pdo_data_src_parser {
665 const char *optname;
666 char *optval;
667 int freeme;
668 };
669
670 PDO_API int php_pdo_parse_data_source(const char *data_source,
671 zend_ulong data_source_len, struct pdo_data_src_parser *parsed,
672 int nparams);
673
674 PDO_API zend_class_entry *php_pdo_get_dbh_ce(void);
675 PDO_API zend_class_entry *php_pdo_get_exception(void);
676
677 PDO_API int pdo_parse_params(pdo_stmt_t *stmt, zend_string *inquery, zend_string **outquery);
678
679 PDO_API void pdo_raise_impl_error(pdo_dbh_t *dbh, pdo_stmt_t *stmt,
680 pdo_error_type sqlstate, const char *supp);
681
682 PDO_API void php_pdo_dbh_addref(pdo_dbh_t *dbh);
683 PDO_API void php_pdo_dbh_delref(pdo_dbh_t *dbh);
684
685 PDO_API void php_pdo_free_statement(pdo_stmt_t *stmt);
686 PDO_API void php_pdo_stmt_set_column_count(pdo_stmt_t *stmt, int new_count);
687
688 /* Normalization for fetching long param for driver attributes */
689 PDO_API bool pdo_get_long_param(zend_long *lval, zval *value);
690 PDO_API bool pdo_get_bool_param(bool *bval, zval *value);
691
692 PDO_API void pdo_throw_exception(unsigned int driver_errcode, char *driver_errmsg, pdo_error_type *pdo_error);
693 #endif /* PHP_PDO_DRIVER_H */
694
