rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Tom Lane 2008-09-19 20:06:13 +00:00
parent 4e57668da4
commit 3290e6180f
4 changed files with 94 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
doc/src/sgml/libpq.sgml
View File

@ -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,10 +4592,11 @@ 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.
@ -4603,6 +4604,46 @@ char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
</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>

3
src/interfaces/libpq/exports.txt
View File

@ -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

34
src/interfaces/libpq/libpq-events.c
View File

@ -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;
}

15
src/interfaces/libpq/libpq-events.h
View File

@ -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