add a caller_frees parameter to get_col() to allow drivers that need

to allocate data on demand to do so without worrying about cleaning it up.

Spec out how LOB parameters are returned.

1 files changed, 20 insertions, 3 deletions

diff --git a/ext/pdo/php_pdo_driver.h b/ext/pdo/php_pdo_driver.h
index b054611328..4644ff8c63 100755
--- a/ext/pdo/php_pdo_driver.h
+++ b/ext/pdo/php_pdo_driver.h
@@ -35,14 +35,29 @@ struct pdo_bound_param_data;
 # define FALSE 0
 #endif
 
-#define PDO_DRIVER_API	20050205
+#define PDO_DRIVER_API	20050206
 
 enum pdo_param_type {
 	PDO_PARAM_NULL,
-	PDO_PARAM_INT,	/* int as in long, the php native int type */
+
+	/* 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
 };
 
@@ -275,8 +290,10 @@ 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 TSRMLS_DC);
+typedef int (*pdo_stmt_get_col_data_func)(pdo_stmt_t *stmt, int colno, char **ptr, unsigned long *len, int *caller_frees TSRMLS_DC);
 
 /* hook for bound params */
 enum pdo_param_event {