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