1 : /*
2 : +----------------------------------------------------------------------+
3 : | PHP Version 5 |
4 : +----------------------------------------------------------------------+
5 : | Copyright (c) 1997-2009 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: php_pdo_driver.h 272370 2008-12-31 11:15:49Z sebastian $ */
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 :
78 : /* magic flag to denote a parameter as being input/output */
79 : #define PDO_PARAM_INPUT_OUTPUT 0x80000000
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 */
195 : static inline long pdo_attr_lval(zval *options, enum pdo_attribute_type option_name, long defval TSRMLS_DC)
196 2769 : {
197 : zval **v;
198 :
199 2769 : if (options && SUCCESS == zend_hash_index_find(Z_ARRVAL_P(options), option_name, (void**)&v)) {
200 37 : convert_to_long_ex(v);
201 37 : return Z_LVAL_PP(v);
202 : }
203 2732 : return defval;
204 : }
205 : static inline char *pdo_attr_strval(zval *options, enum pdo_attribute_type option_name, char *defval TSRMLS_DC)
206 25 : {
207 : zval **v;
208 :
209 25 : if (options && SUCCESS == zend_hash_index_find(Z_ARRVAL_P(options), option_name, (void**)&v)) {
210 4 : convert_to_string_ex(v);
211 4 : return estrndup(Z_STRVAL_PP(v), Z_STRLEN_PP(v));
212 : }
213 21 : return defval ? estrdup(defval) : NULL;
214 : }
215 : /* }}} */
216 :
217 : /* This structure is registered with PDO when a PDO driver extension is
218 : * initialized */
219 : typedef struct {
220 : const char *driver_name;
221 : unsigned long driver_name_len;
222 : unsigned long api_version; /* needs to be compatible with PDO */
223 :
224 : #define PDO_DRIVER_HEADER(name) \
225 : #name, sizeof(#name)-1, \
226 : PDO_DRIVER_API
227 :
228 : /* create driver specific portion of the database handle and stash it into
229 : * the dbh. dbh contains the data source string and flags for this
230 : * instance. You MUST respect dbh->is_persistent and pass that flag to
231 : * pemalloc() for all allocations that are stored in the dbh or your instance
232 : * data in the db, otherwise you will crash PHP when persistent connections
233 : * are used.
234 : */
235 : int (*db_handle_factory)(pdo_dbh_t *dbh, zval *driver_options TSRMLS_DC);
236 :
237 : } pdo_driver_t;
238 :
239 : /* {{{ methods for a database handle */
240 :
241 : /* close or otherwise disconnect the database */
242 : typedef int (*pdo_dbh_close_func)(pdo_dbh_t *dbh TSRMLS_DC);
243 :
244 : /* prepare a statement and stash driver specific portion into stmt */
245 : typedef int (*pdo_dbh_prepare_func)(pdo_dbh_t *dbh, const char *sql, long sql_len, pdo_stmt_t *stmt, zval *driver_options TSRMLS_DC);
246 :
247 : /* execute a statement (that does not return a result set) */
248 : typedef long (*pdo_dbh_do_func)(pdo_dbh_t *dbh, const char *sql, long sql_len TSRMLS_DC);
249 :
250 : /* quote a string */
251 : 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);
252 :
253 : /* transaction related */
254 : typedef int (*pdo_dbh_txn_func)(pdo_dbh_t *dbh TSRMLS_DC);
255 :
256 : /* setting of attributes */
257 : typedef int (*pdo_dbh_set_attr_func)(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC);
258 :
259 : /* return last insert id. NULL indicates error condition, otherwise, the return value
260 : * MUST be an emalloc'd NULL terminated string. */
261 : typedef char *(*pdo_dbh_last_id_func)(pdo_dbh_t *dbh, const char *name, unsigned int *len TSRMLS_DC);
262 :
263 : /* fetch error information. if stmt is not null, fetch information pertaining
264 : * to the statement, otherwise fetch global error information. The driver
265 : * should add the following information to the array "info" in this order:
266 : * - native error code
267 : * - string representation of the error code ... any other optional driver
268 : * specific data ... */
269 : typedef int (*pdo_dbh_fetch_error_func)(pdo_dbh_t *dbh, pdo_stmt_t *stmt, zval *info TSRMLS_DC);
270 :
271 : /* fetching of attributes */
272 : typedef int (*pdo_dbh_get_attr_func)(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC);
273 :
274 : /* checking/pinging persistent connections; return SUCCESS if the connection
275 : * is still alive and ready to be used, FAILURE otherwise.
276 : * You may set this handler to NULL, which is equivalent to returning SUCCESS. */
277 : typedef int (*pdo_dbh_check_liveness_func)(pdo_dbh_t *dbh TSRMLS_DC);
278 :
279 : /* called at request end for each persistent dbh; this gives the driver
280 : * the opportunity to safely release resources that only have per-request
281 : * scope */
282 : typedef void (*pdo_dbh_request_shutdown)(pdo_dbh_t *dbh TSRMLS_DC);
283 :
284 : /* for adding methods to the dbh or stmt objects
285 : pointer to a list of driver specific functions. The convention is
286 : to prefix the function names using the PDO driver name; this will
287 : reduce the chance of collisions with future functionality in the
288 : PDO class or in user code (they can extend the PDO object).
289 : */
290 : enum {
291 : PDO_DBH_DRIVER_METHOD_KIND_DBH = 0,
292 : PDO_DBH_DRIVER_METHOD_KIND_STMT,
293 : PDO_DBH_DRIVER_METHOD_KIND__MAX
294 : };
295 :
296 : typedef const zend_function_entry *(*pdo_dbh_get_driver_methods_func)(pdo_dbh_t *dbh, int kind TSRMLS_DC);
297 :
298 : struct pdo_dbh_methods {
299 : pdo_dbh_close_func closer;
300 : pdo_dbh_prepare_func preparer;
301 : pdo_dbh_do_func doer;
302 : pdo_dbh_quote_func quoter;
303 : pdo_dbh_txn_func begin;
304 : pdo_dbh_txn_func commit;
305 : pdo_dbh_txn_func rollback;
306 : pdo_dbh_set_attr_func set_attribute;
307 : pdo_dbh_last_id_func last_id;
308 : pdo_dbh_fetch_error_func fetch_err;
309 : pdo_dbh_get_attr_func get_attribute;
310 : pdo_dbh_check_liveness_func check_liveness;
311 : pdo_dbh_get_driver_methods_func get_driver_methods;
312 : pdo_dbh_request_shutdown persistent_shutdown;
313 : };
314 :
315 : /* }}} */
316 :
317 : /* {{{ methods for a statement handle */
318 :
319 : /* free the statement handle */
320 : typedef int (*pdo_stmt_dtor_func)(pdo_stmt_t *stmt TSRMLS_DC);
321 :
322 : /* start the query */
323 : typedef int (*pdo_stmt_execute_func)(pdo_stmt_t *stmt TSRMLS_DC);
324 :
325 : /* causes the next row in the set to be fetched; indicates if there are no
326 : * more rows. The ori and offset params modify which row should be returned,
327 : * if the stmt represents a scrollable cursor */
328 : typedef int (*pdo_stmt_fetch_func)(pdo_stmt_t *stmt,
329 : enum pdo_fetch_orientation ori, long offset TSRMLS_DC);
330 :
331 : /* queries information about the type of a column, by index (0 based).
332 : * Driver should populate stmt->columns[colno] with appropriate info */
333 : typedef int (*pdo_stmt_describe_col_func)(pdo_stmt_t *stmt, int colno TSRMLS_DC);
334 :
335 : /* retrieves pointer and size of the value for a column.
336 : * Note that PDO expects the driver to manage the lifetime of this data;
337 : * it will copy the value into a zval on behalf of the script.
338 : * If the driver sets caller_frees, ptr should point to emalloc'd memory
339 : * and PDO will free it as soon as it is done using it.
340 : */
341 : typedef int (*pdo_stmt_get_col_data_func)(pdo_stmt_t *stmt, int colno, char **ptr, unsigned long *len, int *caller_frees TSRMLS_DC);
342 :
343 : /* hook for bound params */
344 : enum pdo_param_event {
345 : PDO_PARAM_EVT_ALLOC,
346 : PDO_PARAM_EVT_FREE,
347 : PDO_PARAM_EVT_EXEC_PRE,
348 : PDO_PARAM_EVT_EXEC_POST,
349 : PDO_PARAM_EVT_FETCH_PRE,
350 : PDO_PARAM_EVT_FETCH_POST,
351 : PDO_PARAM_EVT_NORMALIZE,
352 : };
353 :
354 : 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);
355 :
356 : /* setting of attributes */
357 : typedef int (*pdo_stmt_set_attr_func)(pdo_stmt_t *stmt, long attr, zval *val TSRMLS_DC);
358 :
359 : /* fetching of attributes */
360 : typedef int (*pdo_stmt_get_attr_func)(pdo_stmt_t *stmt, long attr, zval *val TSRMLS_DC);
361 :
362 : /* retrieves meta data for a numbered column.
363 : * Returns SUCCESS/FAILURE.
364 : * On SUCCESS, fill in return_value with an array with the following fields.
365 : * If a particular field is not supported, then the driver simply does not add it to
366 : * the array, so that scripts can use isset() to check for it.
367 : *
368 : * ### this is just a rough first cut, and subject to change ###
369 : *
370 : * these are added by PDO itself, based on data from the describe handler:
371 : * name => the column name
372 : * len => the length/size of the column
373 : * precision => precision of the column
374 : * pdo_type => an integer, one of the PDO_PARAM_XXX values
375 : *
376 : * scale => the floating point scale
377 : * table => the table for that column
378 : * type => a string representation of the type, mapped to the PHP equivalent type name
379 : * native_type => a string representation of the type, native style, if different from
380 : * the mapped name.
381 : * flags => an array of flags including zero or more of the following:
382 : * primary_key, not_null, unique_key, multiple_key, unsigned, auto_increment, blob
383 : *
384 : * Any driver specific data should be returned using a prefixed key or value.
385 : * Eg: custom data for the mysql driver would use either
386 : * 'mysql:foobar' => 'some data' // to add a new key to the array
387 : * or
388 : * 'flags' => array('not_null', 'mysql:some_flag'); // to add data to an existing key
389 : */
390 : typedef int (*pdo_stmt_get_column_meta_func)(pdo_stmt_t *stmt, long colno, zval *return_value TSRMLS_DC);
391 :
392 : /* advances the statement to the next rowset of the batch.
393 : * If it returns 1, PDO will tear down its idea of columns
394 : * and meta data. If it returns 0, PDO will indicate an error
395 : * to the caller. */
396 : typedef int (*pdo_stmt_next_rowset_func)(pdo_stmt_t *stmt TSRMLS_DC);
397 :
398 : /* closes the active cursor on a statement, leaving the prepared
399 : * statement ready for re-execution. Useful to explicitly state
400 : * that you are done with a given rowset, without having to explicitly
401 : * fetch all the rows. */
402 : typedef int (*pdo_stmt_cursor_closer_func)(pdo_stmt_t *stmt TSRMLS_DC);
403 :
404 : struct pdo_stmt_methods {
405 : pdo_stmt_dtor_func dtor;
406 : pdo_stmt_execute_func executer;
407 : pdo_stmt_fetch_func fetcher;
408 : pdo_stmt_describe_col_func describer;
409 : pdo_stmt_get_col_data_func get_col;
410 : pdo_stmt_param_hook_func param_hook;
411 : pdo_stmt_set_attr_func set_attribute;
412 : pdo_stmt_get_attr_func get_attribute;
413 : pdo_stmt_get_column_meta_func get_column_meta;
414 : pdo_stmt_next_rowset_func next_rowset;
415 : pdo_stmt_cursor_closer_func cursor_closer;
416 : };
417 :
418 : /* }}} */
419 :
420 : enum pdo_placeholder_support {
421 : PDO_PLACEHOLDER_NONE=0,
422 : PDO_PLACEHOLDER_NAMED=1,
423 : PDO_PLACEHOLDER_POSITIONAL=2
424 : };
425 :
426 : /* represents a connection to a database */
427 : struct _pdo_dbh_t {
428 : /* these items must appear in this order at the beginning of the
429 : struct so that this can be cast as a zend_object. we need this
430 : to allow the extending class to escape all the custom handlers
431 : that PDO declares.
432 : */
433 : zend_class_entry *ce;
434 : HashTable *properties;
435 : unsigned int in_get:1;
436 : unsigned int in_set:1;
437 :
438 : /* driver specific methods */
439 : struct pdo_dbh_methods *methods;
440 : /* driver specific data */
441 : void *driver_data;
442 :
443 : /* credentials */
444 : char *username, *password;
445 :
446 : /* if true, then data stored and pointed at by this handle must all be
447 : * persistently allocated */
448 : unsigned is_persistent:1;
449 :
450 : /* if true, driver should act as though a COMMIT were executed between
451 : * each executed statement; otherwise, COMMIT must be carried out manually
452 : * */
453 : unsigned auto_commit:1;
454 :
455 : /* if true, the handle has been closed and will not function anymore */
456 : unsigned is_closed:1;
457 :
458 : /* if true, the driver requires that memory be allocated explicitly for
459 : * the columns that are returned */
460 : unsigned alloc_own_columns:1;
461 :
462 : /* if true, commit or rollBack is allowed to be called */
463 : unsigned in_txn:1;
464 :
465 : /* max length a single character can become after correct quoting */
466 : unsigned max_escaped_char_length:3;
467 :
468 : /* oracle compat; see enum pdo_null_handling */
469 : unsigned oracle_nulls:2;
470 :
471 : /* when set, convert int/floats to strings */
472 : unsigned stringify:1;
473 :
474 : /* the sum of the number of bits here and the bit fields preceeding should
475 : * equal 32 */
476 : unsigned _reserved_flags:21;
477 :
478 : /* data source string used to open this handle */
479 : const char *data_source;
480 : unsigned long data_source_len;
481 :
482 : /* the global error code. */
483 : pdo_error_type error_code;
484 :
485 : enum pdo_error_mode error_mode;
486 :
487 : enum pdo_case_conversion native_case, desired_case;
488 :
489 : /* persistent hash key associated with this handle */
490 : const char *persistent_id;
491 : int persistent_id_len;
492 : unsigned int refcount;
493 :
494 : /* driver specific "class" methods for the dbh and stmt */
495 : HashTable *cls_methods[PDO_DBH_DRIVER_METHOD_KIND__MAX];
496 :
497 : pdo_driver_t *driver;
498 :
499 : zend_class_entry *def_stmt_ce;
500 :
501 : zval *def_stmt_ctor_args;
502 :
503 : /* when calling PDO::query(), we need to keep the error
504 : * context from the statement around until we next clear it.
505 : * This will allow us to report the correct error message
506 : * when PDO::query() fails */
507 : pdo_stmt_t *query_stmt;
508 : zval query_stmt_zval;
509 :
510 : /* defaults for fetches */
511 : enum pdo_fetch_type default_fetch_type;
512 : };
513 :
514 : /* describes a column */
515 : struct pdo_column_data {
516 : char *name;
517 : int namelen;
518 : unsigned long maxlen;
519 : enum pdo_param_type param_type;
520 : unsigned long precision;
521 :
522 : /* don't touch this unless your name is dbdo */
523 : void *dbdo_data;
524 : };
525 :
526 : /* describes a bound parameter */
527 : struct pdo_bound_param_data {
528 : long paramno; /* if -1, then it has a name, and we don't know the index *yet* */
529 : char *name;
530 : int namelen;
531 :
532 : long max_value_len; /* as a hint for pre-allocation */
533 :
534 : zval *parameter; /* the variable itself */
535 : enum pdo_param_type param_type; /* desired or suggested type */
536 :
537 : zval *driver_params; /* optional parameter(s) for the driver */
538 : void *driver_data;
539 :
540 : pdo_stmt_t *stmt; /* for convenience in dtor */
541 : int is_param; /* parameter or column ? */
542 : };
543 :
544 : /* represents a prepared statement */
545 : struct _pdo_stmt_t {
546 : /* these items must appear in this order at the beginning of the
547 : struct so that this can be cast as a zend_object. we need this
548 : to allow the extending class to escape all the custom handlers
549 : that PDO declares.
550 : */
551 : zend_class_entry *ce;
552 : HashTable *properties;
553 : unsigned int in_get:1;
554 : unsigned int in_set:1;
555 :
556 : /* driver specifics */
557 : struct pdo_stmt_methods *methods;
558 : void *driver_data;
559 :
560 : /* if true, we've already successfully executed this statement at least
561 : * once */
562 : unsigned executed:1;
563 : /* if true, the statement supports placeholders and can implement
564 : * bindParam() for its prepared statements, if false, PDO should
565 : * emulate prepare and bind on its behalf */
566 : unsigned supports_placeholders:2;
567 :
568 : unsigned _reserved:29;
569 :
570 : /* the number of columns in the result set; not valid until after
571 : * the statement has been executed at least once. In some cases, might
572 : * not be valid until fetch (at the driver level) has been called at least once.
573 : * */
574 : int column_count;
575 : struct pdo_column_data *columns;
576 :
577 : /* we want to keep the dbh alive while we live, so we own a reference */
578 : zval database_object_handle;
579 : pdo_dbh_t *dbh;
580 :
581 : /* keep track of bound input parameters. Some drivers support
582 : * input/output parameters, but you can't rely on that working */
583 : HashTable *bound_params;
584 : /* When rewriting from named to positional, this maps positions to names */
585 : HashTable *bound_param_map;
586 : /* keep track of PHP variables bound to named (or positional) columns
587 : * in the result set */
588 : HashTable *bound_columns;
589 :
590 : /* not always meaningful */
591 : long row_count;
592 :
593 : /* used to hold the statement's current query */
594 : char *query_string;
595 : int query_stringlen;
596 :
597 : /* the copy of the query with expanded binds ONLY for emulated-prepare drivers */
598 : char *active_query_string;
599 : int active_query_stringlen;
600 :
601 : /* the cursor specific error code. */
602 : pdo_error_type error_code;
603 :
604 : /* for lazy fetches, we always return the same lazy object handle.
605 : * Let's keep it here. */
606 : zval lazy_object_ref;
607 : unsigned long refcount;
608 :
609 : /* defaults for fetches */
610 : enum pdo_fetch_type default_fetch_type;
611 : union {
612 : int column;
613 : struct {
614 : zend_class_entry *ce;
615 : zval *ctor_args; /* freed */
616 : zval *retval_ptr;
617 : zend_fcall_info fci;
618 : zend_fcall_info_cache fcc;
619 : } cls;
620 : struct {
621 : zval *function;
622 : zval *fetch_args; /* freed */
623 : zval *object;
624 : zend_fcall_info fci;
625 : zend_fcall_info_cache fcc;
626 : zval **values; /* freed */
627 : } func;
628 : zval *into;
629 : } fetch;
630 :
631 : /* used by the query parser for driver specific
632 : * parameter naming (see pgsql driver for example) */
633 : const char *named_rewrite_template;
634 : };
635 :
636 : /* call this in MINIT to register your PDO driver */
637 : PDO_API int php_pdo_register_driver(pdo_driver_t *driver);
638 : /* call this in MSHUTDOWN to unregister your PDO driver */
639 : PDO_API void php_pdo_unregister_driver(pdo_driver_t *driver);
640 :
641 : /* For the convenience of drivers, this function will parse a data source
642 : * string, of the form "name=value; name2=value2" and populate variables
643 : * according to the data you pass in and array of pdo_data_src_parser structures */
644 : struct pdo_data_src_parser {
645 : const char *optname;
646 : char *optval;
647 : int freeme;
648 : };
649 :
650 : PDO_API int php_pdo_parse_data_source(const char *data_source,
651 : unsigned long data_source_len, struct pdo_data_src_parser *parsed,
652 : int nparams);
653 :
654 : PDO_API zend_class_entry *php_pdo_get_dbh_ce(void);
655 : PDO_API zend_class_entry *php_pdo_get_exception(void);
656 :
657 : PDO_API int pdo_parse_params(pdo_stmt_t *stmt, char *inquery, int inquery_len,
658 : char **outquery, int *outquery_len TSRMLS_DC);
659 :
660 : PDO_API void pdo_raise_impl_error(pdo_dbh_t *dbh, pdo_stmt_t *stmt,
661 : const char *sqlstate, const char *supp TSRMLS_DC);
662 :
663 : PDO_API void php_pdo_dbh_addref(pdo_dbh_t *dbh TSRMLS_DC);
664 : PDO_API void php_pdo_dbh_delref(pdo_dbh_t *dbh TSRMLS_DC);
665 :
666 : PDO_API void php_pdo_stmt_addref(pdo_stmt_t *stmt TSRMLS_DC);
667 : PDO_API void php_pdo_stmt_delref(pdo_stmt_t *stmt TSRMLS_DC);
668 :
669 :
670 : #endif /* PHP_PDO_DRIVER_H */
671 : /*
672 : * Local variables:
673 : * tab-width: 4
674 : * c-basic-offset: 4
675 : * End:
676 : * vim600: noet sw=4 ts=4 fdm=marker
677 : * vim<600: noet sw=4 ts=4
678 : */
|
