libpq 的事件系統旨在通知已註冊的事件處理程式有關 libpq 的重要事件，例如 PGconn 和 PGresult 物件的建立或銷燬。主要用例是，這允許應用程式將自己的資料與 PGconn 或 PGresult 關聯起來，並確保在適當的時間釋放這些資料。
每個已註冊的事件處理程式都與兩部分資料相關聯，在 libpq 中僅作為不透明的 void * 指標。有一個“傳遞”（pass-through）指標，在將事件處理程式註冊到 PGconn 時由應用程式提供。此傳遞指標在 PGconn 的整個生命週期及其生成的所有 PGresult 中都不會改變；因此，如果使用，它必須指向長期存在的資料。此外，還有一個“例項資料”（instance data）指標，在每個 PGconn 和 PGresult 中初始值為 NULL。此指標可以使用 PQinstanceData、PQsetInstanceData、PQresultInstanceData 和 PQresultSetInstanceData 函式進行操作。請注意，與傳遞指標不同，由 PGconn 建立的 PGresult 不會自動繼承 PGconn 的例項資料。 libpq 不知道傳遞指標和例項資料指標（如果它們指向任何東西）指向何處，也不會嘗試釋放它們——這由事件處理程式負責。
列舉 PGEventId 命名了事件系統處理的事件型別。它的所有值都以 PGEVT 開頭。對於每種事件型別，都有一個相應的事件資訊結構，它攜帶傳遞給事件處理程式的引數。事件型別是：
PGEVT_REGISTER #當呼叫 PQregisterEventProc 時會發生註冊事件。這是初始化事件過程可能需要的任何 instanceData 的理想時機。每個連線每個事件處理程式只觸發一次註冊事件。如果事件過程失敗（返回零），則註冊將被取消。
typedef struct
{
PGconn *conn;
} PGEventRegister;
收到 PGEVT_REGISTER 事件時，應將 evtInfo 指標強制轉換為 PGEventRegister *。此結構包含一個 PGconn，它應該處於 CONNECTION_OK 狀態；如果呼叫 PQregisterEventProc 緊接著獲得一個有效的 PGconn，則可以保證這一點。返回失敗程式碼時，必須執行所有清理工作，因為不會發送 PGEVT_CONNDESTROY 事件。
PGEVT_CONNRESET #連線重置事件在 PQreset 或 PQresetPoll 完成時觸發。在這兩種情況下，只有在重置成功時才會觸發事件。在 PostgreSQL v15 及更高版本中，事件過程的返回值將被忽略。然而，在早期版本中，返回成功（非零）很重要，否則連線將被中止。
typedef struct
{
PGconn *conn;
} PGEventConnReset;
收到 PGEVT_CONNRESET 事件時，應將 evtInfo 指標強制轉換為 PGEventConnReset *。儘管包含的 PGconn 剛剛被重置，但所有事件資料都保持不變。此事件應用於重置/重新載入/重新查詢任何關聯的 instanceData。請注意，即使事件過程未能處理 PGEVT_CONNRESET，當連線關閉時，它仍然會收到 PGEVT_CONNDESTROY 事件。
PGEVT_CONNDESTROY #連線銷燬事件在響應 PQfinish 時觸發。事件過程負責正確清理其事件資料，因為 libpq 沒有管理此記憶體的能力。未能清理將導致記憶體洩漏。
typedef struct
{
PGconn *conn;
} PGEventConnDestroy;
收到 PGEVT_CONNDESTROY 事件時，應將 evtInfo 指標強制轉換為 PGEventConnDestroy *。此事件在 PQfinish 執行任何其他清理之前觸發。事件過程的返回值將被忽略，因為無法從 PQfinish 指示失敗。此外，事件過程的失敗不應中止清理不需要記憶體的過程。
PGEVT_RESULTCREATE #結果建立事件在響應任何生成結果的查詢執行函式（包括 PQgetResult）時觸發。此事件僅在結果成功建立後觸發。
typedef struct
{
PGconn *conn;
PGresult *result;
} PGEventResultCreate;
收到 PGEVT_RESULTCREATE 事件時，應將 evtInfo 指標強制轉換為 PGEventResultCreate *。conn 是用於生成結果的連線。這是初始化需要與結果關聯的任何 instanceData 的理想位置。如果事件過程失敗（返回零），則該事件過程在結果的剩餘生命週期中將被忽略；也就是說，它不會收到此結果或從中複製的結果的 PGEVT_RESULTCOPY 或 PGEVT_RESULTDESTROY 事件。
PGEVT_RESULTCOPY #結果複製事件在響應 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 事件。
PGEVT_RESULTDESTROY #結果銷燬事件在響應 PQclear 時觸發。事件過程負責正確清理其事件資料，因為 libpq 沒有管理此記憶體的能力。未能清理將導致記憶體洩漏。
typedef struct
{
PGresult *result;
} PGEventResultDestroy;
收到 PGEVT_RESULTDESTROY 事件時，應將 evtInfo 指標強制轉換為 PGEventResultDestroy *。此事件在 PQclear 執行任何其他清理之前觸發。事件過程的返回值將被忽略，因為無法從 PQclear 指示失敗。此外，事件過程的失敗不應中止清理不需要記憶體的過程。
PGEventProc #PGEventProc 是事件過程指標的 typedef，即接收 libpq 事件的使用者回撥函式。事件過程的簽名必須是：
int eventproc(PGEventId evtId, void *evtInfo, void *passThrough)
evtId 引數指示發生了哪個 PGEVT 事件。evtInfo 指標必須強制轉換為適當的結構型別，以獲取有關事件的進一步資訊。passThrough 引數是在註冊事件過程時傳遞給 PQregisterEventProc 的指標。如果函式成功，則應返回一個非零值，如果失敗，則返回零。
一個特定的事件過程只能在一個 PGconn 中註冊一次。這是因為過程的地址用作查詢鍵來標識關聯的例項資料。
在 Windows 上，函式可以有兩個不同的地址：一個在 DLL 外部可見，另一個在 DLL 內部可見。應謹慎確保只有一個地址與 libpq 的事件過程函式一起使用，否則會導致混淆。要編寫可行的程式碼，最簡單的規則是確保事件過程宣告為 static。如果過程的地址必須在原始檔外部可用，請公開一個單獨的函式來返回該地址。
PQregisterEventProc #將事件回撥過程註冊到 libpq。
int PQregisterEventProc(PGconn *conn, PGEventProc proc,
const char *name, void *passThrough);
每個要接收事件的 PGconn 都必須註冊一次事件過程。可以註冊到連線的事件過程數量沒有限制，除了記憶體限制。如果成功，函式將返回一個非零值，如果失敗，則返回零。
proc 引數將在 libpq 事件觸發時被呼叫。其記憶體地址也用於查詢 instanceData。name 引數用於在錯誤訊息中引用事件過程。此值不能為空 NULL 或零長度字串。名稱字串會被複制到 PGconn 中，因此傳遞的值不必是長期存在的。passThrough 指標在事件發生時會傳遞給 proc。此引數可以是 NULL。
PQsetInstanceData #將連線 conn 的 instanceData 對於過程 proc 設定為 data。此函式返回非零表示成功，零表示失敗。（只有當 proc 未能在 conn 中正確註冊時才可能失敗。）
int PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data);
PQinstanceData #返回連線 conn 的與過程 proc 關聯的 instanceData，如果沒有則返回 NULL。
void *PQinstanceData(const PGconn *conn, PGEventProc proc);
PQresultSetInstanceData #將結果的 instanceData 對於 proc 設定為 data。此函式返回非零表示成功，零表示失敗。（只有當 proc 未能在結果中正確註冊時才可能失敗。）
int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data);
請注意，data 所代表的任何儲存都不會被 PQresultMemorySize 統計，除非它是使用 PQresultAlloc 分配的。（這樣做是推薦的，因為它消除了在結果銷燬時顯式釋放此類儲存的需要。）
PQresultInstanceData #返回結果的與 proc 關聯的 instanceData，如果沒有則返回 NULL。
void *PQresultInstanceData(const PGresult *res, PGEventProc proc);
這是一個管理與 libpq 連線和結果關聯的私有資料的骨架示例。
/* required header for libpq events (note: includes 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 options=-csearch_path=");
if (PQstatus(conn) != CONNECTION_OK)
{
/* PQerrorMessage's result includes a trailing newline */
fprintf(stderr, "%s", PQerrorMessage(conn));
PQfinish(conn);
return 1;
}
/* called once on any connection that should receive events.
* Sends a PGEVT_REGISTER to myEventProc.
*/
if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL))
{
fprintf(stderr, "Cannot register PGEventProc\n");
PQfinish(conn);
return 1;
}
/* conn instanceData is available */
data = PQinstanceData(conn, myEventProc);
/* Sends a PGEVT_RESULTCREATE to myEventProc */
res = PQexec(conn, "SELECT 1 + 1");
/* result instanceData is available */
data = PQresultInstanceData(res, myEventProc);
/* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to 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.
*/
data = PQresultInstanceData(res_copy, myEventProc);
/* Both clears send a PGEVT_RESULTDESTROY to myEventProc */
PQclear(res);
PQclear(res_copy);
/* Sends a PGEVT_CONNDESTROY to 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 */
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) */
PQresultSetInstanceData(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) */
PQresultSetInstanceData(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. */
default:
break;
}
return true; /* event processing succeeded */
}
如果您在文件中發現任何不正確之處、與您對特定功能的實際體驗不符或需要進一步澄清的地方，請使用 此表格 報告文件問題。