Add a PQfireResultCreateEvents function to allow applications to mimic the

sequence of operations that libpq goes through while creating a PGresult.
Also, remove ill-considered "const" decoration on parameters passed to
event procedures.

Author: tglsfdc

doc/src/sgml/libpq.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.262 2008/09/19 16:40:40 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.263 2008/09/19 20:06:13 tgl Exp $ -->
 
 <chapter id="libpq">
  <title><application>libpq</application> - C Library</title>
@@ -4592,17 +4592,58 @@ char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
       <parameter>conn</parameter> is not null and <parameter>status</>
       indicates an error, the current error message of the specified
       connection is copied into the <structname>PGresult</structname>.
-      Also, if <parameter>conn</parameter> is not null, any event handlers
+      Also, if <parameter>conn</parameter> is not null, any event procedures
       registered in the connection are copied into the
-      <structname>PGresult</structname> (but they don't get
-      <literal>PGEVT_RESULTCREATE</> calls).
+      <structname>PGresult</structname>.  (They do not get
+      <literal>PGEVT_RESULTCREATE</> calls, but see
+      <function>PQfireResultCreateEvents</function>.)
       Note that <function>PQclear</function> should eventually be called
       on the object, just as with a <structname>PGresult</structname>
       returned by <application>libpq</application> itself.
      </para>
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term>
+     <function>PQfireResultCreateEvents</function>
+     <indexterm>
+      <primary>PQfireResultCreateEvents</primary>
+     </indexterm>
+    </term>
+    <listitem>
+     <para>
+      Fires a <literal>PGEVT_RESULTCREATE</literal> event (see <xref
+      linkend="libpq-events">) for each event procedure registered in the
+      <structname>PGresult</structname> object.  Returns non-zero for success,
+      zero if any event procedure fails.
+
+      <synopsis>
+       int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
+      </synopsis>
+     </para>
+
+     <para>
+      The <literal>conn</> argument is passed through to event procedures
+      but not used directly.  It can be <literal>NULL</> if the event
+      procedures won't use it.
+     </para>
+
+     <para>
+      Event procedures that have already received a
+      <literal>PGEVT_RESULTCREATE</> or <literal>PGEVT_RESULTCOPY</> event
+      for this object are not fired again.
+     </para>
+
+     <para>
+      The main reason that this function is separate from
+      <function>PQmakeEmptyPGResult</function> is that it is often appropriate
+      to create a <structname>PGresult</structname> and fill it with data
+      before invoking the event procedures.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term>
      <function>PQcopyResult</function>
@@ -4904,7 +4945,7 @@ defaultNoticeProcessor(void *arg, const char *message)
       <synopsis>
 typedef struct
 {
-    const PGconn *conn;
+    PGconn *conn;
 } PGEventRegister;
       </synopsis>
 
@@ -4937,7 +4978,7 @@ typedef struct
       <synopsis>
 typedef struct
 {
-    const PGconn *conn;
+    PGconn *conn;
 } PGEventConnReset;
       </synopsis>
 
@@ -4967,7 +5008,7 @@ typedef struct
       <synopsis>
 typedef struct
 {
-    const PGconn *conn;
+    PGconn *conn;
 } PGEventConnDestroy;
       </synopsis>
 
@@ -4995,7 +5036,7 @@ typedef struct
       <synopsis>
 typedef struct
 {
-    const PGconn *conn;
+    PGconn *conn;
     PGresult *result;
 } PGEventResultCreate;
       </synopsis>
@@ -5063,7 +5104,7 @@ typedef struct
       <synopsis>
 typedef struct
 {
-    const PGresult *result;
+    PGresult *result;
 } PGEventResultDestroy;
       </synopsis>
 

src/interfaces/libpq/exports.txt

@@ -1,4 +1,4 @@
-# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.20 2008/09/17 04:31:08 tgl Exp $
+# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.21 2008/09/19 20:06:13 tgl Exp $
 # Functions to be exported by libpq DLLs
 PQconnectdb               1
 PQsetdbLogin              2
@@ -150,3 +150,4 @@ PQinstanceData            147
 PQsetInstanceData         148
 PQresultInstanceData      149
 PQresultSetInstanceData   150
+PQfireResultCreateEvents  151

src/interfaces/libpq/libpq-events.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/interfaces/libpq/libpq-events.c,v 1.2 2008/09/19 16:40:40 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/interfaces/libpq/libpq-events.c,v 1.3 2008/09/19 20:06:13 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -175,3 +175,35 @@ PQresultInstanceData(const PGresult *result, PGEventProc proc)
 
 	return NULL;
 }
+
+/*
+ * Fire RESULTCREATE events for an application-created PGresult.
+ *
+ * The conn argument can be NULL if event procedures won't use it.
+ */
+int
+PQfireResultCreateEvents(PGconn *conn, PGresult *res)
+{
+	int i;
+
+	if (!res)
+		return FALSE;
+
+	for (i = 0; i < res->nEvents; i++)
+	{
+		if (!res->events[i].resultInitialized)
+		{
+			PGEventResultCreate evt;
+
+			evt.conn = conn;
+			evt.result = res;
+			if (!res->events[i].proc(PGEVT_RESULTCREATE, &evt,
+									 res->events[i].passThrough))
+				return FALSE;
+
+			res->events[i].resultInitialized = TRUE;
+		}
+	}
+
+	return TRUE;
+}

src/interfaces/libpq/libpq-events.h

@@ -8,7 +8,7 @@
  * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-events.h,v 1.1 2008/09/17 04:31:08 tgl Exp $
+ * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-events.h,v 1.2 2008/09/19 20:06:13 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -36,22 +36,22 @@ typedef enum
 
 typedef struct
 {
-	const PGconn *conn;
+	PGconn *conn;
 } PGEventRegister;
 
 typedef struct
 {
-	const PGconn *conn;
+	PGconn *conn;
 } PGEventConnReset;
 
 typedef struct
 {
-	const PGconn *conn;
+	PGconn *conn;
 } PGEventConnDestroy;
 
 typedef struct
 {
-	const PGconn *conn;
+	PGconn *conn;
 	PGresult *result;
 } PGEventResultCreate;
 
@@ -63,7 +63,7 @@ typedef struct
 
 typedef struct
 {
-	const PGresult *result;
+	PGresult *result;
 } PGEventResultDestroy;
 
 typedef int (*PGEventProc) (PGEventId evtId, void *evtInfo, void *passThrough);
@@ -84,6 +84,9 @@ extern int	PQresultSetInstanceData(PGresult *result, PGEventProc proc, void *dat
 /* Gets the PGresult instance data for the provided proc. */
 extern void *PQresultInstanceData(const PGresult *result, PGEventProc proc);
 
+/* Fires RESULTCREATE events for an application-created PGresult. */
+extern int	PQfireResultCreateEvents(PGconn *conn, PGresult *res);
+
 #ifdef __cplusplus
 }
 #endif