注册事件在 PQregisterEventProc 被调用时发生。 这是初始化任何事件过程可能需要的 instanceData 的理想时机。 每个事件处理器对每条连接只会被触发一次注册事件。 如果事件过程失败 （返回零）， 注册会被取消。

typedef struct
{
    PGconn *conn;
} PGEventRegister;

当收到一个 PGEVT_REGISTER 事件时， evtInfo 指针应当被转换为 PGEventRegister *。 这个结构包含一个应当处于 CONNECTION_OK 状态的 PGconn； 如果在获得一条良好的 PGconn 之后立即调用 PQregisterEventProc， 则这一点是有保证的。 在返回失败码时， 必须执行所有清理， 因为不会再发送 PGEVT_CONNDESTROY 事件。

连接重置事件在 PQreset 或 PQresetPoll 完成时被触发。 在这两种情况下， 只有当重置成功时该事件才会被触发。 在 PostgreSQL v15 及更高版本中， 事件过程的返回值会被忽略。 然而在更早的版本中， 返回成功（非零）很重要， 否则连接将被中止。

typedef struct
{
    PGconn *conn;
} PGEventConnReset;

当收到一个 PGEVT_CONNRESET 事件时， evtInfo 指针应当被转换为 PGEventConnReset *。 虽然其中包含的 PGconn 刚刚被重置， 但所有事件数据保持不变。 这个事件应当被用来重置/重新加载/重新查询任何关联的 instanceData。 注意，即使事件过程未能处理 PGEVT_CONNRESET， 它仍然会在连接被关闭时收到一个 PGEVT_CONNDESTROY 事件。

连接销毁事件作为对 PQfinish 的响应被触发。 由于 libpq 没有能力管理这块内存， 正确地清理它的事件数据是事件过程的责任。 未能清理将导致内存泄漏。

typedef struct
{
    PGconn *conn;
} PGEventConnDestroy;

当收到一个 PGEVT_CONNDESTROY 事件时， evtInfo 指针应当被转换为 PGEventConnDestroy *。 这个事件会在 PQfinish 执行任何其他清理之前被触发。 事件过程的返回值会被忽略， 因为 PQfinish 没有任何方式指示失败。 此外， 事件过程的失败也不应当中止清理不需要的内存的过程。

结果创建事件作为对任何产生结果的查询执行函数的响应被触发， 包括 PQgetResult。 这个事件只会在结果被成功创建之后被触发。

typedef struct
{
    PGconn *conn;
    PGresult *result;
} PGEventResultCreate;

当收到一个 PGEVT_RESULTCREATE 事件时， evtInfo 指针应当被转换为 PGEventResultCreate *。 conn 是用来产生该结果的连接。 这是初始化任何需要与结果关联的 instanceData 的理想位置。 如果一个事件过程失败 （返回零）， 那么在该结果剩余的生命周期内， 该事件过程将被忽略； 也就是说， 对于这个结果以及从它复制的结果， 它将不会收到 PGEVT_RESULTCOPY 或 PGEVT_RESULTDESTROY 事件。

结果复制事件作为对 PQcopyResult 的响应被触发。 这个事件只会在复制完成之后被触发。 只有成功地为源结果处理过 PGEVT_RESULTCREATE 或 PGEVT_RESULTCOPY 事件的事件过程， 才会收到 PGEVT_RESULTCOPY 事件。

typedef struct
{
    const PGresult *src;
    PGresult *dest;
} PGEventResultCopy;

当收到一个 PGEVT_RESULTCOPY 事件时， evtInfo 指针应当被转换为 PGEventResultCopy *。 src 结果是被复制的对象， 而 dest 结果是复制的目的地。 这个事件可用于提供 instanceData 的深拷贝， 因为 PQcopyResult 做不到这一点。 如果一个事件过程失败 （返回零）， 那么在新结果剩余的生命周期内， 该事件过程将被忽略； 也就是说， 对于那个结果以及从它复制的结果， 它将不会收到 PGEVT_RESULTCOPY 或 PGEVT_RESULTDESTROY 事件。

结果销毁事件作为对一个 PQclear 的响应被触发。 由于 libpq 没有能力管理这块内存， 正确地清理它的事件数据是事件过程的责任。 未能清理将导致内存泄漏。

typedef struct
{
    PGresult *result;
} PGEventResultDestroy;

当收到一个 PGEVT_RESULTDESTROY 事件时， evtInfo 指针应当被转换为 PGEventResultDestroy *。 这个事件会在 PQclear 执行任何其他清理之前被触发。 事件过程的返回值会被忽略， 因为 PQclear 没有任何方式指示失败。 此外， 事件过程的失败也不应当中止清理不需要的内存的过程。

PGEventProc 是一个指向事件过程的指针的 typedef， 也就是接收来自 libpq 事件的用户回调函数。 事件过程的签名必须是

int eventproc(PGEventId evtId, void *evtInfo, void *passThrough)

evtId 参数指示发生了哪个 PGEVT 事件。 evtInfo 指针必须被转换为相应的结构类型， 以获得关于该事件的更多信息。 passThrough 参数是在事件过程被注册时提供给 PQregisterEventProc 的指针。 如果成功， 该函数应当返回一个非零值， 失败则返回零。

一个特定的事件过程在任何一条 PGconn 中只能被注册一次。 这是因为该过程的地址被用作查找键来标识相关联的实例数据。

向 libpq 注册一个事件回调过程。

int PQregisterEventProc(PGconn *conn, PGEventProc proc,
                        const char *name, void *passThrough);

你希望从其接收事件的每条 PGconn 上都必须注册一次事件过程。 可以在一条连接上注册的事件过程的数量没有限制 （内存除外）。 如果成功， 该函数返回一个非零值， 失败则返回零。

当一个 libpq 事件被触发时， proc 参数会被调用。 它的内存地址也被用来查找 instanceData。 name 参数用于在错误消息中指代该事件过程。 这个值不能是 NULL 或零长度字符串。 名字字符串会被复制到 PGconn 中， 因此传入的东西不必长寿命。 每当一个事件发生时， passThrough 指针都会被传递给 proc。 这个参数可以是 NULL。

把连接 conn 中过程 proc 的 instanceData 设置为 data。 成功时返回非零， 失败时返回零。 （只有当 proc 没有被正确地注册在 conn 中时才可能失败。）

int PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data);

返回连接 conn 中与过程 proc 关联的 instanceData， 如果没有则返回 NULL。

void *PQinstanceData(const PGconn *conn, PGEventProc proc);

把结果中 proc 的 instanceData 设置为 data。 成功时返回非零， 失败时返回零。 （只有当 proc 没有被正确地注册在该结果中时才可能失败。）

int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data);

注意，由 data 表示的任何存储都不会被 PQresultMemorySize 计入， 除非它是用 PQresultAlloc 分配的。 （推荐这样做， 因为它消除了在结果被销毁时显式释放这类存储的需要。）

返回结果中与 proc 关联的 instanceData， 如果没有则返回 NULL。

void *PQresultInstanceData(const PGresult *res, PGEventProc proc);