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