31.13. 事件系统

31.13.1. 事件类型

枚举PGEventId命名事件系统处理的事件的类型。所有的命名值都是从 PGEVT开始。对每个事件类型来说，有一个相应的事件信息结构， 用于传送传递给事件处理程序的参数。事件类型如下：

31.13.2. 事件回调过程

31.13.3. 事件支持函数

31.13.4. 事件例子

一个管理与libpq连接和结果相关的私有数据的例子：

/* <!-- required header for libpq events (note: includes libpq-fe.h) -->需要libpq事件的头文件 (注意：包括 libpq-fe.h) */
#include <libpq-events.h>

/* The instanceData */
typedef struct
{
    int n;
    char *str;
} mydata;

/* PGEventProc */
static int myEventProc(PGEventId evtId, void *evtInfo, void *passThrough);

int
main(void)
{
    mydata *data;
    PGresult *res;
    PGconn *conn = PQconnectdb("dbname = postgres");

    if (PQstatus(conn) != CONNECTION_OK)
    {
        fprintf(stderr, "Connection to database failed: %s",
                PQerrorMessage(conn));
        PQfinish(conn);
        return 1;
    }

    <!--
/* called once on any connection that should receive events.
     * Sends a PGEVT_REGISTER to myEventProc.
     */
 -->
 /* 在任何应该接收事件的连接上调用一次。
     * 发送一个 PGEVT_REGISTER 到 myEventProc。
     */

    if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL))
    {
        fprintf(stderr, "Cannot register PGEventProc\n");
        PQfinish(conn);
        return 1;
    }

    <!-- /* conn instanceData is available */ --> 
/* conn instanceData 是可用的 */
    data = PQinstanceData(conn, myEventProc);

    <!-- /* Sends a PGEVT_RESULTCREATE to myEventProc */ -->
/* 发送一个 PGEVT_RESULTCREATE 到 myEventProc */
    res = PQexec(conn, "SELECT 1 + 1");

    <!-- /* result instanceData is available */ -->
/* 结果 instanceData 是可用的 */
    data = PQresultInstanceData(res, myEventProc);

    <!-- /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ -->
 /* 如果使用了 PG_COPYRES_EVENTS，发送一个 PGEVT_RESULTCOPY到 myEventProc */
    res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS);

    <!--
/* result instanceData is available if PG_COPYRES_EVENTS was
     * used during the PQcopyResult call.
     */
 -->
 /* 结果 instanceData 是可用的，如果 PG_COPYRES_EVENTS 
     * 在PQcopyResult调用期间使用了的话。
     */
    data = PQresultInstanceData(res_copy, myEventProc);

    <!-- /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ -->
/* 两个clears都发送 PGEVT_RESULTDESTROY 到 myEventProc */
    PQclear(res);
    PQclear(res_copy);

    <!-- /* Sends a PGEVT_CONNDESTROY to myEventProc */ -->
/* 发送一个 PGEVT_CONNDESTROY 到 myEventProc */
    PQfinish(conn);

    return 0;
}

static int
myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
{
    switch (evtId)
    {
        case PGEVT_REGISTER:
        {
            PGEventRegister *e = (PGEventRegister *)evtInfo;
            mydata *data = get_mydata(e->conn);

            <!-- /* associate app specific data with connection */ -->
/* 将应用程序特定的数据与连接相关联 */
            PQsetInstanceData(e->conn, myEventProc, data);
            break;
        }

        case PGEVT_CONNRESET:
        {
            PGEventConnReset *e = (PGEventConnReset *)evtInfo;
            mydata *data = PQinstanceData(e->conn, myEventProc);

            if (data)
              memset(data, 0, sizeof(mydata));
            break;
        }

        case PGEVT_CONNDESTROY:
        {
            PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo;
            mydata *data = PQinstanceData(e->conn, myEventProc);

            <!-- /* free instance data because the conn is being destroyed */ -->
/* 释放实例数据，因为conn被破坏了 */
            if (data)
              free_mydata(data);
            break;
        }

        case PGEVT_RESULTCREATE:
        {
            PGEventResultCreate *e = (PGEventResultCreate *)evtInfo;
            mydata *conn_data = PQinstanceData(e->conn, myEventProc);
            mydata *res_data = dup_mydata(conn_data);

            <!-- /* associate app specific data with result (copy it from conn) */ -->
/* 将应用程序特定的数据与结果相关联 (从conn中拷贝) */
            PQsetResultInstanceData(e->result, myEventProc, res_data);
            break;
        }

        case PGEVT_RESULTCOPY:
        {
            PGEventResultCopy *e = (PGEventResultCopy *)evtInfo;
            mydata *src_data = PQresultInstanceData(e->src, myEventProc);
            mydata *dest_data = dup_mydata(src_data);

            <!-- /* associate app specific data with result (copy it from a result) */ -->
/*将应用程序特定的数据与结果相关联 (从结果中拷贝)*/
            PQsetResultInstanceData(e->dest, myEventProc, dest_data);
            break;
        }

        case PGEVT_RESULTDESTROY:
        {
            PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo;
            mydata *data = PQresultInstanceData(e->result, myEventProc);

            <!-- /* free instance data because the result is being destroyed */ -->
/* 释放实例数据，因为结果被破坏了 */
            if (data)
              free_mydata(data);
            break;
        }

        <!-- /* unknown event ID, just return TRUE. */ -->
/* 未知事件ID，只是返回TRUE。*/
        default:
            break;
    }

    return TRUE; /* <!-- event processing succeeded -->事件处理成功 */
}