php_pdo_driver.h

技术管理量不要让站长把时间都花费在为您修正说明上。压缩包解压

/*
  +----------------------------------------------------------------------+
  | PHP Version 5                                                        |
  +----------------------------------------------------------------------+
  | Copyright (c) 1997-2006 The PHP Group                                |
  +----------------------------------------------------------------------+
  | This source file is subject to version 3.01 of the PHP license,      |
  | that is bundled with this package in the file LICENSE, and is        |
  | available through the world-wide-web at the following url:           |
  | http://www.php.net/license/3_01.txt                                  |
  | If you did not receive a copy of the PHP license and are unable to   |
  | obtain it through the world-wide-web, please send a note to          |
  | [e-mail] so we can mail you a copy immediately.               |
  +----------------------------------------------------------------------+
  | Author: Wez Furlong <[e-mail]>                                    |
  +----------------------------------------------------------------------+
*/

/* $Id: php_pdo_driver.h,v 1.66.2.11 2006/04/09 08:05:01 wez Exp $ */

#ifndef PHP_PDO_DRIVER_H
#define PHP_PDO_DRIVER_H

#include "php_pdo.h"

/* forward declarations */
typedef struct _pdo_dbh_t 	pdo_dbh_t;
typedef struct _pdo_stmt_t	pdo_stmt_t;
struct pdo_bound_param_data;

#ifdef PHP_WIN32
typedef __int64 pdo_int64_t;
typedef unsigned __int64 pdo_uint64_t;
#else
typedef long long int pdo_int64_t;
typedef unsigned long long int pdo_uint64_t;
#endif
PDO_API char *php_pdo_int64_to_str(pdo_int64_t i64 TSRMLS_DC);

#ifndef TRUE
# define TRUE 1
#endif
#ifndef FALSE
# define FALSE 0
#endif

#define PDO_DRIVER_API	20060409

enum pdo_param_type {
	PDO_PARAM_NULL,

	/* int as in long (the php native int type).
	 * If you mark a column as an int, PDO expects get_col to return
	 * a pointer to a long */
	PDO_PARAM_INT,

	/* get_col ptr should point to start of the string buffer */
	PDO_PARAM_STR,

	/* get_col: when len is 0 ptr should point to a php_stream *,
	 * otherwise it should behave like a string. Indicate a NULL field
	 * value by setting the ptr to NULL */
	PDO_PARAM_LOB,

	/* get_col: will expect the ptr to point to a new PDOStatement object handle,
	 * but this isn't wired up yet */
	PDO_PARAM_STMT, /* hierarchical result set */

	/* get_col ptr should point to a zend_bool */
	PDO_PARAM_BOOL,
};

/* magic flag to denote a parameter as being input/output */
#define	PDO_PARAM_INPUT_OUTPUT 	0x80000000	

#define PDO_PARAM_FLAGS			0xFFFF0000

#define PDO_PARAM_TYPE(x)		((x) & ~PDO_PARAM_FLAGS)

enum pdo_fetch_type {
	PDO_FETCH_USE_DEFAULT,
	PDO_FETCH_LAZY,
	PDO_FETCH_ASSOC,
	PDO_FETCH_NUM,
	PDO_FETCH_BOTH,
	PDO_FETCH_OBJ,
	PDO_FETCH_BOUND, /* return true/false only; rely on bound columns */
	PDO_FETCH_COLUMN,	/* fetch a numbered column only */
	PDO_FETCH_CLASS,	/* create an instance of named class, call ctor and set properties */
	PDO_FETCH_INTO,		/* fetch row into an existing object */
	PDO_FETCH_FUNC,		/* fetch into function and return its result */
	PDO_FETCH_NAMED,    /* like PDO_FETCH_ASSOC, but can handle duplicate names */
	PDO_FETCH__MAX /* must be last */
};

#define PDO_FETCH_FLAGS     0xFFFF0000  /* fetchAll() modes or'd to PDO_FETCH_XYZ */
#define PDO_FETCH_GROUP     0x00010000  /* fetch into groups */
#define PDO_FETCH_UNIQUE    0x00030000  /* fetch into groups assuming first col is unique */
#define PDO_FETCH_CLASSTYPE 0x00040000  /* fetch class gets its class name from 1st column */
#define PDO_FETCH_SERIALIZE 0x00080000  /* fetch class instances by calling serialize */

/* fetch orientation for scrollable cursors */
enum pdo_fetch_orientation {
	PDO_FETCH_ORI_NEXT,		/* default: fetch the next available row */
	PDO_FETCH_ORI_PRIOR,	/* scroll back to prior row and fetch that */
	PDO_FETCH_ORI_FIRST,	/* scroll to the first row and fetch that */
	PDO_FETCH_ORI_LAST,		/* scroll to the last row and fetch that */
	PDO_FETCH_ORI_ABS,		/* scroll to an absolute numbered row and fetch that */
	PDO_FETCH_ORI_REL		/* scroll relative to the current row, and fetch that */
};

enum pdo_attribute_type {
	PDO_ATTR_AUTOCOMMIT,	/* use to turn on or off auto-commit mode */
	PDO_ATTR_PREFETCH,		/* configure the prefetch size for drivers that support it. Size is in KB */
	PDO_ATTR_TIMEOUT,		/* connection timeout in seconds */
	PDO_ATTR_ERRMODE,		/* control how errors are handled */
	PDO_ATTR_SERVER_VERSION,	/* database server version */
	PDO_ATTR_CLIENT_VERSION,	/* client library version */
	PDO_ATTR_SERVER_INFO,		/* server information */
	PDO_ATTR_CONNECTION_STATUS,	/* connection status */
	PDO_ATTR_CASE,				/* control case folding for portability */
	PDO_ATTR_CURSOR_NAME,		/* name a cursor for use in "WHERE CURRENT OF <name>" */
	PDO_ATTR_CURSOR,			/* cursor type */
	PDO_ATTR_ORACLE_NULLS,		/* convert empty strings to NULL */
	PDO_ATTR_PERSISTENT,		/* pconnect style connection */
	PDO_ATTR_STATEMENT_CLASS,	/* array(classname, array(ctor_args)) to specify the class of the constructed statement */
	PDO_ATTR_FETCH_TABLE_NAMES, /* include table names in the column names, where available */
	PDO_ATTR_FETCH_CATALOG_NAMES, /* include the catalog/db name names in the column names, where available */
	PDO_ATTR_DRIVER_NAME,		  /* name of the driver (as used in the constructor) */
	PDO_ATTR_STRINGIFY_FETCHES,	/* converts integer/float types to strings during fetch */
	PDO_ATTR_MAX_COLUMN_LEN,	/* make database calculate maximum length of data found in a column */
	PDO_ATTR_EMULATE_PREPARES,  /* use query emulation rather than native */

	/* this defines the start of the range for driver specific options.
	 * Drivers should define their own attribute constants beginning with this
	 * value. */
	PDO_ATTR_DRIVER_SPECIFIC = 1000
};

enum pdo_cursor_type {
	PDO_CURSOR_FWDONLY,		/* forward only cursor (default) */
	PDO_CURSOR_SCROLL		/* scrollable cursor */
};

/* SQL-92 SQLSTATE error codes.

The character string value returned for an SQLSTATE consists of a two-character
class value followed by a three-character subclass value. A class value of 01
indicates a warning and is accompanied by a return code of
SQL_SUCCESS_WITH_INFO.

Class values other than '01', except for the class 'IM',
indicate an error and are accompanied by a return code of SQL_ERROR. The class
'IM' is specific to warnings and errors that derive from the implementation of
ODBC itself.

The subclass value '000' in any class indicates that there is no
subclass for that SQLSTATE. The assignment of class and subclass values is
defined by SQL-92.
*/

typedef char pdo_error_type[6]; /* SQLSTATE */


#define PDO_ERR_NONE				"00000"

enum pdo_error_mode {
	PDO_ERRMODE_SILENT,		/* just set error codes */
	PDO_ERRMODE_WARNING,	/* raise E_WARNING */
	PDO_ERRMODE_EXCEPTION	/* throw exceptions */
};

enum pdo_case_conversion {
	PDO_CASE_NATURAL,
	PDO_CASE_UPPER,
	PDO_CASE_LOWER
};

/* oracle interop settings */
enum pdo_null_handling {
	PDO_NULL_NATURAL = 0,
	PDO_NULL_EMPTY_STRING = 1,
	PDO_NULL_TO_STRING = 2,
};

/* {{{ utils for reading attributes set as driver_options */
static inline long pdo_attr_lval(zval *options, enum pdo_attribute_type option_name, long defval TSRMLS_DC)
{
	zval **v;

	if (options && SUCCESS == zend_hash_index_find(Z_ARRVAL_P(options), option_name, (void**)&v)) {
		convert_to_long_ex(v);
		return Z_LVAL_PP(v);
	}
	return defval;
}
static inline char *pdo_attr_strval(zval *options, enum pdo_attribute_type option_name, char *defval TSRMLS_DC)
{
	zval **v;

	if (options && SUCCESS == zend_hash_index_find(Z_ARRVAL_P(options), option_name, (void**)&v)) {
		convert_to_string_ex(v);
		return estrndup(Z_STRVAL_PP(v), Z_STRLEN_PP(v));
	}
	return defval ? estrdup(defval) : NULL;
}
/* }}} */

/* This structure is registered with PDO when a PDO driver extension is
 * initialized */
typedef struct {
	const char		*driver_name;
	unsigned long	driver_name_len;
	unsigned long	api_version; /* needs to be compatible with PDO */

#define PDO_DRIVER_HEADER(name)	\
	#name, sizeof(#name)-1, \
	PDO_DRIVER_API
	
	/* create driver specific portion of the database handle and stash it into
	 * the dbh.  dbh contains the data source string and flags for this
	 * instance.  You MUST respect dbh->is_persistent and pass that flag to
	 * pemalloc() for all allocations that are stored in the dbh or your instance
	 * data in the db, otherwise you will crash PHP when persistent connections
	 * are used.
	 */
	int (*db_handle_factory)(pdo_dbh_t *dbh, zval *driver_options TSRMLS_DC);

} pdo_driver_t;

/* {{{ methods for a database handle */

/* close or otherwise disconnect the database */
typedef int (*pdo_dbh_close_func)(pdo_dbh_t *dbh TSRMLS_DC);

/* prepare a statement and stash driver specific portion into stmt */
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);

/* execute a statement (that does not return a result set) */
typedef long (*pdo_dbh_do_func)(pdo_dbh_t *dbh, const char *sql, long sql_len TSRMLS_DC);

/* quote a string */
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);

/* transaction related */
typedef int (*pdo_dbh_txn_func)(pdo_dbh_t *dbh TSRMLS_DC);

/* setting of attributes */
typedef int (*pdo_dbh_set_attr_func)(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC);

/* return last insert id.  NULL indicates error condition, otherwise, the return value
 * MUST be an emalloc'd NULL terminated string. */
typedef char *(*pdo_dbh_last_id_func)(pdo_dbh_t *dbh, const char *name, unsigned int *len TSRMLS_DC);

/* fetch error information.  if stmt is not null, fetch information pertaining
 * to the statement, otherwise fetch global error information.  The driver
 * should add the following information to the array "info" in this order:
 * - native error code
 * - string representation of the error code ... any other optional driver
 *   specific data ...  */
typedef	int (*pdo_dbh_fetch_error_func)(pdo_dbh_t *dbh, pdo_stmt_t *stmt, zval *info TSRMLS_DC);

/* fetching of attributes */
typedef int (*pdo_dbh_get_attr_func)(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC);

/* checking/pinging persistent connections; return SUCCESS if the connection
 * is still alive and ready to be used, FAILURE otherwise.
 * You may set this handler to NULL, which is equivalent to returning SUCCESS. */
typedef int (*pdo_dbh_check_liveness_func)(pdo_dbh_t *dbh TSRMLS_DC);

/* called at request end for each persistent dbh; this gives the driver
 * the opportunity to safely release resources that only have per-request
 * scope */
typedef void (*pdo_dbh_request_shutdown)(pdo_dbh_t *dbh TSRMLS_DC);

/* for adding methods to the dbh or stmt objects 
pointer to a list of driver specific functions. The convention is
to prefix the function names using the PDO driver name; this will
reduce the chance of collisions with future functionality in the
PDO class or in user code (they can extend the PDO object).
*/
enum {
	PDO_DBH_DRIVER_METHOD_KIND_DBH = 0,
	PDO_DBH_DRIVER_METHOD_KIND_STMT,
	PDO_DBH_DRIVER_METHOD_KIND__MAX
};

typedef zend_function_entry *(*pdo_dbh_get_driver_methods_func)(pdo_dbh_t *dbh, int kind TSRMLS_DC);

struct pdo_dbh_methods {
	pdo_dbh_close_func		closer;
	pdo_dbh_prepare_func	preparer;
	pdo_dbh_do_func			doer;
	pdo_dbh_quote_func		quoter;
	pdo_dbh_txn_func		begin;
	pdo_dbh_txn_func		commit;
	pdo_dbh_txn_func		rollback;
	pdo_dbh_set_attr_func	set_attribute;
	pdo_dbh_last_id_func		last_id;
	pdo_dbh_fetch_error_func	fetch_err;
	pdo_dbh_get_attr_func   	get_attribute;
	pdo_dbh_check_liveness_func	check_liveness;
	pdo_dbh_get_driver_methods_func get_driver_methods;
	pdo_dbh_request_shutdown	persistent_shutdown;
};

/* }}} */

/* {{{ methods for a statement handle */

/* free the statement handle */
typedef int (*pdo_stmt_dtor_func)(pdo_stmt_t *stmt TSRMLS_DC);

/* start the query */
typedef int (*pdo_stmt_execute_func)(pdo_stmt_t *stmt TSRMLS_DC);

/* causes the next row in the set to be fetched; indicates if there are no
 * more rows.  The ori and offset params modify which row should be returned,
 * if the stmt represents a scrollable cursor */
typedef int (*pdo_stmt_fetch_func)(pdo_stmt_t *stmt, 
	enum pdo_fetch_orientation ori, long offset TSRMLS_DC);

/* queries information about the type of a column, by index (0 based).
 * Driver should populate stmt->columns[colno] with appropriate info */
typedef int (*pdo_stmt_describe_col_func)(pdo_stmt_t *stmt, int colno TSRMLS_DC);

/* retrieves pointer and size of the value for a column.
 * Note that PDO expects the driver to manage the lifetime of this data;
 * it will copy the value into a zval on behalf of the script.
 * If the driver sets caller_frees, ptr should point to emalloc'd memory
 * and PDO will free it as soon as it is done using it.
 */
typedef int (*pdo_stmt_get_col_data_func)(pdo_stmt_t *stmt, int colno, char **ptr, unsigned long *len, int *caller_frees TSRMLS_DC);