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