Add an "events" system to libpq, whereby applications can get callbacks that

enable them to manage private data associated with PGconns and PGresults.

Andrew Chernow and Merlin Moncure

9 files changed, 758 insertions, 38 deletions

diff --git a/src/interfaces/libpq/Makefile b/src/interfaces/libpq/Makefile
index 62885fbb5e0..7bace86345d 100644
--- a/src/interfaces/libpq/Makefile
+++ b/src/interfaces/libpq/Makefile
@@ -5,7 +5,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/Makefile,v 1.166 2008/04/16 14:19:56 adunstan Exp $
+# $PostgreSQL: pgsql/src/interfaces/libpq/Makefile,v 1.167 2008/09/17 04:31:08 tgl Exp $
 #
 #-------------------------------------------------------------------------
 
@@ -32,6 +32,7 @@ LIBS := $(LIBS:-lpgport=)
 
 OBJS=	fe-auth.o fe-connect.o fe-exec.o fe-misc.o fe-print.o fe-lobj.o \
 	fe-protocol2.o fe-protocol3.o pqexpbuffer.o pqsignal.o fe-secure.o \
+	libpq-events.o \
 	md5.o ip.o wchar.o encnames.o noblock.o pgstrcasecmp.o thread.o \
 	$(filter crypt.o getaddrinfo.o inet_aton.o open.o snprintf.o strerror.o strlcpy.o win32error.o, $(LIBOBJS))
 
@@ -106,6 +107,7 @@ $(top_builddir)/src/port/pg_config_paths.h:
 
 install: all installdirs install-lib
 	$(INSTALL_DATA) $(srcdir)/libpq-fe.h '$(DESTDIR)$(includedir)'
+	$(INSTALL_DATA) $(srcdir)/libpq-events.h '$(DESTDIR)$(includedir)'
 	$(INSTALL_DATA) $(srcdir)/libpq-int.h '$(DESTDIR)$(includedir_internal)'
 	$(INSTALL_DATA) $(srcdir)/pqexpbuffer.h '$(DESTDIR)$(includedir_internal)'
 	$(INSTALL_DATA) $(srcdir)/pg_service.conf.sample '$(DESTDIR)$(datadir)/pg_service.conf.sample'
@@ -114,7 +116,11 @@ installdirs: installdirs-lib
 	$(mkinstalldirs) '$(DESTDIR)$(includedir)' '$(DESTDIR)$(includedir_internal)'
 
 uninstall: uninstall-lib
-	rm -f '$(DESTDIR)$(includedir)/libpq-fe.h' '$(DESTDIR)$(includedir_internal)/libpq-int.h' '$(DESTDIR)$(includedir_internal)/pqexpbuffer.h' '$(DESTDIR)$(datadir)/pg_service.conf.sample'
+	rm -f '$(DESTDIR)$(includedir)/libpq-fe.h'
+	rm -f '$(DESTDIR)$(includedir)/libpq-events.h'
+	rm -f '$(DESTDIR)$(includedir_internal)/libpq-int.h'
+	rm -f '$(DESTDIR)$(includedir_internal)/pqexpbuffer.h'
+	rm -f '$(DESTDIR)$(datadir)/pg_service.conf.sample'
 
 clean distclean: clean-lib
 	rm -f $(OBJS) pg_config_paths.h crypt.c getaddrinfo.c inet_aton.c noblock.c open.c pgstrcasecmp.c snprintf.c strerror.c strlcpy.c thread.c md5.c ip.c encnames.c wchar.c win32error.c pgsleep.c pthread.h libpq.rc
diff --git a/src/interfaces/libpq/exports.txt b/src/interfaces/libpq/exports.txt
index f8809f841e4..c720efce4b9 100644
--- a/src/interfaces/libpq/exports.txt
+++ b/src/interfaces/libpq/exports.txt
@@ -1,4 +1,4 @@
-# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.19 2008/03/19 00:39:33 ishii Exp $
+# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.20 2008/09/17 04:31:08 tgl Exp $
 # Functions to be exported by libpq DLLs
 PQconnectdb               1
 PQsetdbLogin              2
@@ -140,4 +140,13 @@ lo_truncate               137
 PQconnectionUsedPassword  138
 pg_valid_server_encoding_id 139
 PQconnectionNeedsPassword 140
-lo_import_with_oid		  141
+lo_import_with_oid        141
+PQcopyResult              142
+PQsetResultAttrs          143
+PQsetvalue                144
+PQresultAlloc             145
+PQregisterEventProc       146
+PQinstanceData            147
+PQsetInstanceData         148
+PQresultInstanceData      149
+PQresultSetInstanceData   150
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index 5e687c15585..7e77c9a5c7a 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/interfaces/libpq/fe-connect.c,v 1.359 2008/05/29 22:02:44 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/interfaces/libpq/fe-connect.c,v 1.360 2008/09/17 04:31:08 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -1974,6 +1974,21 @@ makeEmptyPGconn(void)
 static void
 freePGconn(PGconn *conn)
 {
+	int			i;
+
+	/* let any event procs clean up their state data */
+	for (i = 0; i < conn->nEvents; i++)
+	{
+		PGEventConnDestroy evt;
+
+		evt.conn = conn;
+		(void) conn->events[i].proc(PGEVT_CONNDESTROY, &evt,
+									conn->events[i].passThrough);
+		free(conn->events[i].name);
+	}
+
+	if (conn->events)
+		free(conn->events);
 	if (conn->pghost)
 		free(conn->pghost);
 	if (conn->pghostaddr)
@@ -2155,8 +2170,30 @@ PQreset(PGconn *conn)
 	{
 		closePGconn(conn);
 
-		if (connectDBStart(conn))
-			(void) connectDBComplete(conn);
+		if (connectDBStart(conn) && connectDBComplete(conn))
+		{
+			/*
+			 * Notify event procs of successful reset.  We treat an event
+			 * proc failure as disabling the connection ... good idea?
+			 */
+			int i;
+
+			for (i = 0; i < conn->nEvents; i++)
+			{
+				PGEventConnReset evt;
+
+				evt.conn = conn;
+				if (!conn->events[i].proc(PGEVT_CONNRESET, &evt,
+										  conn->events[i].passThrough))
+				{
+					conn->status = CONNECTION_BAD;
+					printfPQExpBuffer(&conn->errorMessage,
+									  libpq_gettext("PGEventProc \"%s\" failed during PGEVT_CONNRESET event\n"),
+									  conn->events[i].name);
+					break;
+				}
+			}
+		}
 	}
 }
 
@@ -2190,7 +2227,36 @@ PostgresPollingStatusType
 PQresetPoll(PGconn *conn)
 {
 	if (conn)
-		return PQconnectPoll(conn);
+	{
+		PostgresPollingStatusType status = PQconnectPoll(conn);
+
+		if (status == PGRES_POLLING_OK)
+		{
+			/*
+			 * Notify event procs of successful reset.  We treat an event
+			 * proc failure as disabling the connection ... good idea?
+			 */
+			int i;
+
+			for (i = 0; i < conn->nEvents; i++)
+			{
+				PGEventConnReset evt;
+
+				evt.conn = conn;
+				if (!conn->events[i].proc(PGEVT_CONNRESET, &evt,
+										  conn->events[i].passThrough))
+				{
+					conn->status = CONNECTION_BAD;
+					printfPQExpBuffer(&conn->errorMessage,
+									  libpq_gettext("PGEventProc \"%s\" failed during PGEVT_CONNRESET event\n"),
+									  conn->events[i].name);
+					return PGRES_POLLING_FAILED;
+				}
+			}
+		}
+
+		return status;
+	}
 
 	return PGRES_POLLING_FAILED;
 }
diff --git a/src/interfaces/libpq/fe-exec.c b/src/interfaces/libpq/fe-exec.c
index 149a0b73f6b..7db303ce008 100644
--- a/src/interfaces/libpq/fe-exec.c
+++ b/src/interfaces/libpq/fe-exec.c
@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/interfaces/libpq/fe-exec.c,v 1.197 2008/09/10 17:01:07 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/interfaces/libpq/fe-exec.c,v 1.198 2008/09/17 04:31:08 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -48,6 +48,7 @@ static int	static_client_encoding = PG_SQL_ASCII;
 static bool static_std_strings = false;
 
 
+static PGEvent *dupEvents(PGEvent *events, int count);
 static bool PQsendQueryStart(PGconn *conn);
 static int PQsendQueryGuts(PGconn *conn,
 				const char *command,
@@ -63,6 +64,7 @@ static bool PQexecStart(PGconn *conn);
 static PGresult *PQexecFinish(PGconn *conn);
 static int PQsendDescribe(PGconn *conn, char desc_type,
 			   const char *desc_target);
+static int check_field_number(const PGresult *res, int field_num);
 
 
 /* ----------------
@@ -128,13 +130,8 @@ static int PQsendDescribe(PGconn *conn, char desc_type,
  * PQmakeEmptyPGresult
  *	 returns a newly allocated, initialized PGresult with given status.
  *	 If conn is not NULL and status indicates an error, the conn's
- *	 errorMessage is copied.
- *
- * Note this is exported --- you wouldn't think an application would need
- * to build its own PGresults, but this has proven useful in both libpgtcl
- * and the Perl5 interface, so maybe it's not so unreasonable.
+ *	 errorMessage is copied.  Also, any PGEvents are copied from the conn.
  */
-
 PGresult *
 PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status)
 {
@@ -154,6 +151,8 @@ PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status)
 	result->resultStatus = status;
 	result->cmdStatus[0] = '\0';
 	result->binary = 0;
+	result->events = NULL;
+	result->nEvents = 0;
 	result->errMsg = NULL;
 	result->errFields = NULL;
 	result->null_field[0] = '\0';
@@ -181,6 +180,18 @@ PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status)
 				pqSetResultError(result, conn->errorMessage.data);
 				break;
 		}
+
+		/* copy events last; result must be valid if we need to PQclear */
+		if (conn->nEvents > 0)
+		{
+			result->events = dupEvents(conn->events, conn->nEvents);
+			if (!result->events)
+			{
+				PQclear(result);
+				return NULL;
+			}
+			result->nEvents = conn->nEvents;
+		}
 	}
 	else
 	{
@@ -196,6 +207,301 @@ PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status)
 }
 
 /*
+ * PQsetResultAttrs
+ *
+ * Set the attributes for a given result.  This function fails if there are
+ * already attributes contained in the provided result.  The call is
+ * ignored if numAttributes is is zero or attDescs is NULL.  If the
+ * function fails, it returns zero.  If the function succeeds, it
+ * returns a non-zero value.
+ */
+int
+PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs)
+{
+	int i;
+
+	/* If attrs already exist, they cannot be overwritten. */
+	if (!res || res->numAttributes > 0)
+		return FALSE;
+
+	/* ignore no-op request */
+	if (numAttributes <= 0 || !attDescs)
+		return TRUE;
+
+	res->attDescs = (PGresAttDesc *)
+		PQresultAlloc(res, numAttributes * sizeof(PGresAttDesc));
+
+	if (!res->attDescs)
+		return FALSE;
+
+	res->numAttributes = numAttributes;
+	memcpy(res->attDescs, attDescs, numAttributes * sizeof(PGresAttDesc));
+
+	/* deep-copy the attribute names, and determine format */
+	res->binary = 1;
+	for (i = 0; i < res->numAttributes; i++)
+	{
+		if (res->attDescs[i].name)
+			res->attDescs[i].name = pqResultStrdup(res, res->attDescs[i].name);
+		else
+			res->attDescs[i].name = res->null_field;
+
+		if (!res->attDescs[i].name)
+			return FALSE;
+
+		if (res->attDescs[i].format == 0)
+			res->binary = 0;
+	}
+
+	return TRUE;
+}
+
+/*
+ * PQcopyResult
+ *
+ * Returns a deep copy of the provided 'src' PGresult, which cannot be NULL.
+ * The 'flags' argument controls which portions of the result will or will
+ * NOT be copied.  The created result is always put into the
+ * PGRES_TUPLES_OK status.  The source result error message is not copied,
+ * although cmdStatus is.
+ *
+ * To set custom attributes, use PQsetResultAttrs.  That function requires
+ * that there are no attrs contained in the result, so to use that
+ * function you cannot use the PG_COPYRES_ATTRS or PG_COPYRES_TUPLES
+ * options with this function.
+ *
+ * Options:
+ *   PG_COPYRES_ATTRS - Copy the source result's attributes
+ *
+ *   PG_COPYRES_TUPLES - Copy the source result's tuples.  This implies
+ *   copying the attrs, seeeing how the attrs are needed by the tuples.
+ *
+ *   PG_COPYRES_EVENTS - Copy the source result's events.
+ *
+ *   PG_COPYRES_NOTICEHOOKS - Copy the source result's notice hooks.
+ */
+PGresult *
+PQcopyResult(const PGresult *src, int flags)
+{
+	PGresult *dest;
+	int i;
+
+	if (!src)
+		return NULL;
+
+	dest = PQmakeEmptyPGresult(NULL, PGRES_TUPLES_OK);
+	if (!dest)
+		return NULL;
+
+	/* Always copy these over.  Is cmdStatus really useful here? */
+	dest->client_encoding = src->client_encoding;
+	strcpy(dest->cmdStatus, src->cmdStatus);
+
+	/* Wants attrs? */
+	if (flags & (PG_COPYRES_ATTRS | PG_COPYRES_TUPLES))
+	{
+		if (!PQsetResultAttrs(dest, src->numAttributes, src->attDescs))
+		{
+			PQclear(dest);
+			return NULL;
+		}
+	}
+
+	/* Wants to copy tuples? */
+	if (flags & PG_COPYRES_TUPLES)
+	{
+		int tup, field;
+
+		for (tup = 0; tup < src->ntups; tup++)
+		{
+			for (field = 0; field < src->numAttributes; field++)
+			{
+				if (!PQsetvalue(dest, tup, field,
+								src->tuples[tup][field].value,
+								src->tuples[tup][field].len))
+				{
+					PQclear(dest);
+					return NULL;
+				}
+			}
+		}
+	}
+
+	/* Wants to copy notice hooks? */
+	if (flags & PG_COPYRES_NOTICEHOOKS)
+		dest->noticeHooks = src->noticeHooks;
+
+	/*
+	 * Wants to copy PGEvents?  NB: this should be last, as we don't want
+	 * to trigger RESULTDESTROY events on a useless PGresult.
+	 */
+	if ((flags & PG_COPYRES_EVENTS) && src->nEvents > 0)
+	{
+		dest->events = dupEvents(src->events, src->nEvents);
+		if (!dest->events)
+		{
+			PQclear(dest);
+			return NULL;
+		}
+		dest->nEvents = src->nEvents;
+	}
+
+	/* Okay, trigger PGEVT_RESULTCOPY event */
+	for (i = 0; i < dest->nEvents; i++)
+	{
+		PGEventResultCopy evt;
+
+		evt.src = src;
+		evt.dest = dest;
+		if (!dest->events[i].proc(PGEVT_RESULTCOPY, &evt,
+								  dest->events[i].passThrough))
+		{
+			PQclear(dest);
+			return NULL;
+		}
+	}
+
+	return dest;
+}
+
+/*
+ * Copy an array of PGEvents (with no extra space for more)
+ * Does not duplicate the event instance data, sets this to NULL
+ */
+static PGEvent *
+dupEvents(PGEvent *events, int count)
+{
+	PGEvent *newEvents;
+	int i;
+
+	if (!events || count <= 0)
+		return NULL;
+
+	newEvents = (PGEvent *) malloc(count * sizeof(PGEvent));
+	if (!newEvents)
+		return NULL;
+
+	memcpy(newEvents, events, count * sizeof(PGEvent));
+
+	/* NULL out the data pointers and deep copy names */
+	for (i = 0; i < count; i++)
+	{
+		newEvents[i].data = NULL;
+		newEvents[i].name = strdup(newEvents[i].name);
+		if (!newEvents[i].name)
+		{
+			while (--i >= 0)
+				free(newEvents[i].name);
+			free(newEvents);
+			return NULL;
+		}
+	}
+
+	return newEvents;
+}
+
+
+/*
+ * Sets the value for a tuple field.  The tup_num must be less than or
+ * equal to PQntuples(res).  If it is equal, a new tuple is created and
+ * added to the result.
+ * Returns a non-zero value for success and zero for failure.
+ */
+int
+PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len)
+{
+	PGresAttValue *attval;
+
+	if (!check_field_number(res, field_num))
+		return FALSE;
+
+	/* Invalid tup_num, must be <= ntups */
+	if (tup_num < 0 || tup_num > res->ntups)
+		return FALSE;
+
+	/* need to grow the tuple table? */
+	if (res->ntups >= res->tupArrSize)
+	{
+		int n = res->tupArrSize ? res->tupArrSize * 2 : 128;
+		PGresAttValue **tups;
+
+		if (res->tuples)
+			tups = (PGresAttValue **) realloc(res->tuples, n * sizeof(PGresAttValue *));
+		else
+			tups = (PGresAttValue **) malloc(n * sizeof(PGresAttValue *));
+
+		if (!tups)
+			return FALSE;
+
+		memset(tups + res->tupArrSize, 0,
+			   (n - res->tupArrSize) * sizeof(PGresAttValue *));
+		res->tuples = tups;
+		res->tupArrSize = n;
+	}
+
+	/* need to allocate a new tuple? */
+	if (tup_num == res->ntups && !res->tuples[tup_num])
+	{
+		PGresAttValue *tup;
+		int i;
+
+		tup = (PGresAttValue *)
+			pqResultAlloc(res, res->numAttributes * sizeof(PGresAttValue),
+						  TRUE);
+
+		if (!tup)
+			return FALSE;
+
+		/* initialize each column to NULL */
+		for (i = 0; i < res->numAttributes; i++)
+		{
+			tup[i].len = NULL_LEN;
+			tup[i].value = res->null_field;
+		}
+
+		res->tuples[tup_num] = tup;
+		res->ntups++;
+	}
+
+	attval = &res->tuples[tup_num][field_num];
+
+	/* treat either NULL_LEN or NULL value pointer as a NULL field */
+	if (len == NULL_LEN || value == NULL)
+	{
+		attval->len = NULL_LEN;
+		attval->value = res->null_field;
+	}
+	else if (len <= 0)
+	{
+		attval->len = 0;
+		attval->value = res->null_field;
+	}
+	else
+	{
+		attval->value = (char *) pqResultAlloc(res, len + 1, TRUE);
+		if (!attval->value)
+			return FALSE;
+		attval->len = len;
+		memcpy(attval->value, value, len);
+		attval->value[len] = '\0';
+	}
+
+	return TRUE;
+}
+
+/*
+ * pqResultAlloc - exported routine to allocate local storage in a PGresult.
+ *
+ * We force all such allocations to be maxaligned, since we don't know
+ * whether the value might be binary.
+ */
+void *
+PQresultAlloc(PGresult *res, size_t nBytes)
+{
+	return pqResultAlloc(res, nBytes, TRUE);
+}
+
+/*
  * pqResultAlloc -
  *		Allocate subsidiary storage for a PGresult.
  *
@@ -353,10 +659,24 @@ void
 PQclear(PGresult *res)
 {
 	PGresult_data *block;
+	int i;
 
 	if (!res)
 		return;
 
+	for (i = 0; i < res->nEvents; i++)
+	{
+		PGEventResultDestroy evt;
+
+		evt.result = res;
+		(void) res->events[i].proc(PGEVT_RESULTDESTROY, &evt,
+								   res->events[i].passThrough);
+		free(res->events[i].name);
+	}
+
+	if (res->events)
+		free(res->events);
+
 	/* Free all the subsidiary blocks */
 	while ((block = res->curBlock) != NULL)
 	{
@@ -373,6 +693,8 @@ PQclear(PGresult *res)
 	res->tuples = NULL;
 	res->paramDescs = NULL;
 	res->errFields = NULL;
+	res->events = NULL;
+	res->nEvents = 0;
 	/* res->curBlock was zeroed out earlier */
 
 	/* Free the PGresult structure itself */
@@ -1270,6 +1592,29 @@ PQgetResult(PGconn *conn)
 			break;
 	}
 
+	if (res)
+	{
+		int i;
+
+		for (i = 0; i < res->nEvents; i++)
+		{
+			PGEventResultCreate evt;
+
+			evt.conn = conn;
+			evt.result = res;
+			if (!res->events[i].proc(PGEVT_RESULTCREATE, &evt,
+									 res->events[i].passThrough))
+			{
+				printfPQExpBuffer(&conn->errorMessage,
+								  libpq_gettext("PGEventProc \"%s\" failed during PGEVT_RESULTCREATE event\n"),
+								  res->events[i].name);
+				pqSetResultError(res, conn->errorMessage.data);
+				res->resultStatus = PGRES_FATAL_ERROR;
+				break;
+			}
+		}
+	}
+
 	return res;
 }
 
diff --git a/src/interfaces/libpq/libpq-events.c b/src/interfaces/libpq/libpq-events.c
new file mode 100644
index 00000000000..7d3d1cb26c1
--- /dev/null
+++ b/src/interfaces/libpq/libpq-events.c
@@ -0,0 +1,176 @@
+/*-------------------------------------------------------------------------
+ *
+ * libpq-events.c
+ *	  functions for supporting the libpq "events" API
+ *
+ * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ *
+ * IDENTIFICATION
+ *	  $PostgreSQL: pgsql/src/interfaces/libpq/libpq-events.c,v 1.1 2008/09/17 04:31:08 tgl Exp $
+ *
+ *-------------------------------------------------------------------------
+ */
+#include "postgres_fe.h"
+
+#include "libpq-fe.h"
+#include "libpq-int.h"
+
+
+/*
+ * Registers an event proc with the given PGconn.
+ *
+ * The same proc can't be registered more than once in a PGconn.  This
+ * restriction is required because we use the proc address to identify
+ * the event for purposes such as PQinstanceData().
+ *
+ * The name argument is used within error messages to aid in debugging.
+ * A name must be supplied, but it needn't be unique.  The string is
+ * copied, so the passed value needn't be long-lived.
+ *
+ * The passThrough argument is an application specific pointer and can be set
+ * to NULL if not required.  It is passed through to the event proc whenever
+ * the event proc is called, and is not otherwise touched by libpq.
+ *
+ * The function returns a non-zero if successful.  If the function fails,
+ * zero is returned.
+ */
+int
+PQregisterEventProc(PGconn *conn, PGEventProc proc,
+					const char *name, void *passThrough)
+{
+	int i;
+	PGEventRegister regevt;
+
+	if (!proc || !conn || !name || !*name)
+		return FALSE;			/* bad arguments */
+
+	for (i = 0; i < conn->nEvents; i++)
+	{
+		if (conn->events[i].proc == proc)
+			return FALSE;		/* already registered */
+	}
+
+	if (conn->nEvents >= conn->eventArraySize)
+	{
+		PGEvent *e;
+		int newSize;
+
+		newSize = conn->eventArraySize ? conn->eventArraySize * 2 : 8;
+		if (conn->events)
+			e = (PGEvent *) realloc(conn->events, newSize * sizeof(PGEvent));
+		else
+			e = (PGEvent *) malloc(newSize * sizeof(PGEvent));
+
+		if (!e)
+			return FALSE;
+
+		conn->eventArraySize = newSize;
+		conn->events = e;
+	}
+
+	conn->events[conn->nEvents].proc = proc;
+	conn->events[conn->nEvents].name = strdup(name);
+	if (!conn->events[conn->nEvents].name)
+		return FALSE;
+	conn->events[conn->nEvents].passThrough = passThrough;
+	conn->events[conn->nEvents].data = NULL;
+	conn->nEvents++;
+
+	regevt.conn = conn;
+	if (!proc(PGEVT_REGISTER, &regevt, passThrough))
+	{
+		conn->nEvents--;
+		free(conn->events[conn->nEvents].name);
+		return FALSE;
+	}
+
+	return TRUE;
+}
+
+/*
+ * Set some "instance data" for an event within a PGconn.
+ * Returns nonzero on success, zero on failure.
+ */
+int
+PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data)
+{
+	int i;
+
+	if (!conn || !proc)
+		return FALSE;
+
+	for (i = 0; i < conn->nEvents; i++)
+	{
+		if (conn->events[i].proc == proc)
+		{
+			conn->events[i].data = data;
+			return TRUE;
+		}
+	}
+
+	return FALSE;
+}
+
+/*
+ * Obtain the "instance data", if any, for the event.
+ */
+void *
+PQinstanceData(const PGconn *conn, PGEventProc proc)
+{
+	int i;
+
+	if (!conn || !proc)
+		return NULL;
+
+	for (i = 0; i < conn->nEvents; i++)
+	{
+		if (conn->events[i].proc == proc)
+			return conn->events[i].data;
+	}
+
+	return NULL;
+}
+
+/*
+ * Set some "instance data" for an event within a PGresult.
+ * Returns nonzero on success, zero on failure.
+ */
+int
+PQresultSetInstanceData(PGresult *result, PGEventProc proc, void *data)
+{
+	int i;
+
+	if (!result || !proc)
+		return FALSE;
+
+	for (i = 0; i < result->nEvents; i++)
+	{
+		if (result->events[i].proc == proc)
+		{
+			result->events[i].data = data;
+			return TRUE;
+		}
+	}
+
+	return FALSE;
+}
+
+/*
+ * Obtain the "instance data", if any, for the event.
+ */
+void *
+PQresultInstanceData(const PGresult *result, PGEventProc proc)
+{
+	int i;
+
+	if (!result || !proc)
+		return NULL;
+
+	for (i = 0; i < result->nEvents; i++)
+		if (result->events[i].proc == proc)
+			return result->events[i].data;
+
+	return NULL;
+}
diff --git a/src/interfaces/libpq/libpq-events.h b/src/interfaces/libpq/libpq-events.h
new file mode 100644
index 00000000000..33e2d5b046c
--- /dev/null
+++ b/src/interfaces/libpq/libpq-events.h
@@ -0,0 +1,91 @@
+/*-------------------------------------------------------------------------
+ *
+ * libpq-events.h
+ *	  This file contains definitions that are useful to applications
+ *	  that invoke the libpq "events" API, but are not interesting to
+ *	  ordinary users of libpq.
+ *
+ * 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 $
+ *
+ *-------------------------------------------------------------------------
+ */
+
+#ifndef LIBPQ_EVENTS_H
+#define LIBPQ_EVENTS_H
+
+#include "libpq-fe.h"
+
+#ifdef __cplusplus
+extern		"C"
+{
+#endif
+
+/* Callback Event Ids */
+typedef enum
+{
+	PGEVT_REGISTER,
+	PGEVT_CONNRESET,
+	PGEVT_CONNDESTROY,
+	PGEVT_RESULTCREATE,
+	PGEVT_RESULTCOPY,
+	PGEVT_RESULTDESTROY
+} PGEventId;
+
+typedef struct
+{
+	const PGconn *conn;
+} PGEventRegister;
+
+typedef struct
+{
+	const PGconn *conn;
+} PGEventConnReset;
+
+typedef struct
+{
+	const PGconn *conn;
+} PGEventConnDestroy;
+
+typedef struct
+{
+	const PGconn *conn;
+	PGresult *result;
+} PGEventResultCreate;
+
+typedef struct
+{
+	const PGresult *src;
+	PGresult *dest;
+} PGEventResultCopy;
+
+typedef struct
+{
+	const PGresult *result;
+} PGEventResultDestroy;
+
+typedef int (*PGEventProc) (PGEventId evtId, void *evtInfo, void *passThrough);
+
+/* Registers an event proc with the given PGconn. */
+extern int	PQregisterEventProc(PGconn *conn, PGEventProc proc,
+								const char *name, void *passThrough);
+
+/* Sets the PGconn instance data for the provided proc to data. */
+extern int	PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data);
+
+/* Gets the PGconn instance data for the provided proc. */
+extern void *PQinstanceData(const PGconn *conn, PGEventProc proc);
+
+/* Sets the PGresult instance data for the provided proc to data. */
+extern int	PQresultSetInstanceData(PGresult *result, PGEventProc proc, void *data);
+
+/* Gets the PGresult instance data for the provided proc. */
+extern void *PQresultInstanceData(const PGresult *result, PGEventProc proc);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* LIBPQ_EVENTS_H */
diff --git a/src/interfaces/libpq/libpq-fe.h b/src/interfaces/libpq/libpq-fe.h
index 53d79b059f6..f923b968408 100644
--- a/src/interfaces/libpq/libpq-fe.h
+++ b/src/interfaces/libpq/libpq-fe.h
@@ -7,7 +7,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-fe.h,v 1.142 2008/03/19 00:39:33 ishii Exp $
+ * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-fe.h,v 1.143 2008/09/17 04:31:08 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -28,6 +28,14 @@ extern		"C"
  */
 #include "postgres_ext.h"
 
+/*
+ * Option flags for PQcopyResult
+ */
+#define PG_COPYRES_ATTRS          0x01
+#define PG_COPYRES_TUPLES         0x02		/* Implies PG_COPYRES_ATTRS */
+#define PG_COPYRES_EVENTS         0x04
+#define PG_COPYRES_NOTICEHOOKS    0x08
+
 /* Application-visible enum types */
 
 typedef enum
@@ -193,6 +201,21 @@ typedef struct
 } PQArgBlock;
 
 /* ----------------
+ * PGresAttDesc -- Data about a single attribute (column) of a query result
+ * ----------------
+ */
+typedef struct pgresAttDesc
+{
+	char	   *name;			/* column name */
+	Oid			tableid;		/* source table, if known */
+	int			columnid;		/* source column, if known */
+	int			format;			/* format code for value (text/binary) */
+	Oid			typid;			/* type id */
+	int			typlen;			/* type size */
+	int			atttypmod;		/* type-specific modifier info */
+} PGresAttDesc;
+
+/* ----------------
  * Exported functions of libpq
  * ----------------
  */
@@ -430,13 +453,12 @@ extern void PQfreemem(void *ptr);
 /* Note: depending on this is deprecated; use PQconnectionNeedsPassword(). */
 #define PQnoPasswordSupplied	"fe_sendauth: no password supplied\n"
 
-/*
- * Make an empty PGresult with given status (some apps find this
- * useful). If conn is not NULL and status indicates an error, the
- * conn's errorMessage is copied.
- */
+/* Create and manipulate PGresults */
 extern PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
-
+extern PGresult *PQcopyResult(const PGresult *src, int flags);
+extern int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
+extern void *PQresultAlloc(PGresult *res, size_t nBytes);
+extern int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
 
 /* Quoting strings before inclusion in queries. */
 extern size_t PQescapeStringConn(PGconn *conn,
diff --git a/src/interfaces/libpq/libpq-int.h b/src/interfaces/libpq/libpq-int.h
index fd94952f180..fd29c092148 100644
--- a/src/interfaces/libpq/libpq-int.h
+++ b/src/interfaces/libpq/libpq-int.h
@@ -12,7 +12,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-int.h,v 1.131 2008/05/29 22:02:44 tgl Exp $
+ * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-int.h,v 1.132 2008/09/17 04:31:08 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -22,6 +22,7 @@
 
 /* We assume libpq-fe.h has already been included. */
 #include "postgres_fe.h"
+#include "libpq-events.h"
 
 #include <time.h>
 #include <sys/types.h>
@@ -100,19 +101,6 @@ union pgresult_data
 	char		space[1];		/* dummy for accessing block as bytes */
 };
 
-/* Data about a single attribute (column) of a query result */
-
-typedef struct pgresAttDesc
-{
-	char	   *name;			/* column name */
-	Oid			tableid;		/* source table, if known */
-	int			columnid;		/* source column, if known */
-	int			format;			/* format code for value (text/binary) */
-	Oid			typid;			/* type id */
-	int			typlen;			/* type size */
-	int			atttypmod;		/* type-specific modifier info */
-} PGresAttDesc;
-
 /* Data about a single parameter of a prepared statement */
 typedef struct pgresParamDesc
 {
@@ -162,6 +150,14 @@ typedef struct
 	void	   *noticeProcArg;
 } PGNoticeHooks;
 
+typedef struct PGEvent
+{
+	PGEventProc	proc;			/* the function to call on events */
+	char	   *name;			/* used only for error messages */
+	void	   *passThrough;	/* pointer supplied at registration time */
+	void	   *data;			/* optional state (instance) data */
+} PGEvent;
+
 struct pg_result
 {
 	int			ntups;
@@ -182,6 +178,8 @@ struct pg_result
 	 * on the PGresult don't have to reference the PGconn.
 	 */
 	PGNoticeHooks noticeHooks;
+	PGEvent	   *events;
+	int			nEvents;
 	int			client_encoding;	/* encoding id */
 
 	/*
@@ -303,6 +301,11 @@ struct pg_conn
 	/* Callback procedures for notice message processing */
 	PGNoticeHooks noticeHooks;
 
+	/* Event procs registered via PQregisterEventProc */
+	PGEvent	   *events;			/* expandable array of event data */
+	int			nEvents;		/* number of active events */
+	int			eventArraySize;	/* allocated array size */
+
 	/* Status indicators */
 	ConnStatusType status;
 	PGAsyncStatusType asyncStatus;
diff --git a/src/tools/msvc/Install.pm b/src/tools/msvc/Install.pm
index 4355ec9a28b..dcbe5b5e01b 100644
--- a/src/tools/msvc/Install.pm
+++ b/src/tools/msvc/Install.pm
@@ -3,7 +3,7 @@ package Install;
 #
 # Package that provides 'make install' functionality for msvc builds
 #
-# $PostgreSQL: pgsql/src/tools/msvc/Install.pm,v 1.30 2008/09/05 16:54:39 momjian Exp $
+# $PostgreSQL: pgsql/src/tools/msvc/Install.pm,v 1.31 2008/09/17 04:31:08 tgl Exp $
 #
 use strict;
 use warnings;
@@ -393,7 +393,9 @@ sub CopyIncludeFiles
     lcopy('src/include/libpq/libpq-fs.h', $target . '/include/libpq/')
       || croak 'Could not copy libpq-fs.h';
 
-    CopyFiles('Libpq headers', $target . '/include/', 'src/interfaces/libpq/', 'libpq-fe.h');
+    CopyFiles('Libpq headers',
+	      $target . '/include/', 'src/interfaces/libpq/',
+	      'libpq-fe.h', 'libpq-events.h');
     CopyFiles(
         'Libpq internal headers',
         $target .'/include/internal/',