登録イベントはPQregisterEventProcが呼ばれたとき発生します。 イベントプロシージャが必要とするかもしれない任意のinstanceDataを初期化するために、これは理想的な機会です。 接続毎、イベントハンドラ毎でただ１つの登録イベントが発行されます。 イベントプロシージャが失敗する（ゼロが返される）と、登録はキャンセルされます。

typedef struct
{
    PGconn *conn;
} PGEventRegister;

PGEVT_REGISTERイベントが受け取られると、evtInfoポインタはPGEventRegister *にキャストされなければなりません。 この構造体はCONNECTION_OK状態ではなくてはならないPGconnを含んでいます。 そしてそれは、効果のあるPGconnを取得した直後、PQregisterEventProcを呼び出せば、保証されます。 失敗コードを返すとき、PGEVT_CONNDESTROYイベントが送られないので、すべての消去が実行されなければなりません。

接続初期化イベントはPQresetまたはPQresetPollの完了時点で発行されます。 どちらの場合も、初期化が成功したときのみ発行されます。 PostgreSQLv15以降では、イベントプロシージャの返り値は無視されます。 しかし、以前のバージョンでは、成功（ゼロ以外）を返すことが重要です。 そうしないと接続は中断されます。

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もしくは空文字列であってはなりません。 このname文字列はPGconnにコピーされますので、渡されたものは長寿命である必要がありません。 passThroughポインタはイベントが発生した時はいつでもprocに渡されます。 この引数はNULLであっても構いません。

procプロシージャに対するconn接続のinstanceDataをdataに設定します。 成功の場合非ゼロ、失敗の場合ゼロが返ります。 （connでprocが正しく登録されていない場合のみ失敗する可能性があります。）

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

procプロシージャに関連したconn接続のinstanceData、または存在しなければNULLを返します。

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

procに対する結果のinstanceDataをdataに設定します。 成功の場合非ゼロ、失敗の場合ゼロが返ります。 （結果でproc正しく登録されていない場合のみ失敗する可能性があります。）

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

dataで示された領域は、PQresultAllocを使って割り当てたのでない限り、PQresultMemorySizeでは考慮されないことに注意してください。 (結果を破棄する時に、領域を明示的に解放する必要がなくなりますので、PQresultAllocを使って割り当てるのがお勧めです。)

procに関連した結果のinstanceData、または存在しなければNULLを返します。

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