Annotation of embedaddon/php/ext/pdo/php_pdo_driver.h, revision 1.1
1.1 ! misho 1: /*
! 2: +----------------------------------------------------------------------+
! 3: | PHP Version 5 |
! 4: +----------------------------------------------------------------------+
! 5: | Copyright (c) 1997-2012 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 321634 2012-01-01 13:15:04Z felipe $ */
! 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: {
! 197: zval **v;
! 198:
! 199: if (options && SUCCESS == zend_hash_index_find(Z_ARRVAL_P(options), option_name, (void**)&v)) {
! 200: convert_to_long_ex(v);
! 201: return Z_LVAL_PP(v);
! 202: }
! 203: return defval;
! 204: }
! 205: static inline char *pdo_attr_strval(zval *options, enum pdo_attribute_type option_name, char *defval TSRMLS_DC)
! 206: {
! 207: zval **v;
! 208:
! 209: if (options && SUCCESS == zend_hash_index_find(Z_ARRVAL_P(options), option_name, (void**)&v)) {
! 210: convert_to_string_ex(v);
! 211: return estrndup(Z_STRVAL_PP(v), Z_STRLEN_PP(v));
! 212: }
! 213: 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: */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>