Movatterモバイル変換

The register event occurs whenPQregisterEventProc is called. It is the ideal time to initialize anyinstanceData an event procedure may need. Only one register event will be fired per event handler per connection. If the event procedure fails (returns zero), the registration is cancelled.

typedef struct{    PGconn *conn;} PGEventRegister;

When aPGEVT_REGISTER event is received, theevtInfo pointer should be cast to aPGEventRegister *. This structure contains aPGconn that should be in theCONNECTION_OK status; guaranteed if one callsPQregisterEventProc right after obtaining a goodPGconn. When returning a failure code, all cleanup must be performed as noPGEVT_CONNDESTROY event will be sent.

The connection reset event is fired on completion ofPQreset orPQresetPoll. In both cases, the event is only fired if the reset was successful. The return value of the event procedure is ignored inPostgres Pro v15 and later. With earlier versions, however, it's important to return success (nonzero) or the connection will be aborted.

typedef struct{    PGconn *conn;} PGEventConnReset;

When aPGEVT_CONNRESET event is received, theevtInfo pointer should be cast to aPGEventConnReset *. Although the containedPGconn was just reset, all event data remains unchanged. This event should be used to reset/reload/requery any associatedinstanceData. Note that even if the event procedure fails to processPGEVT_CONNRESET, it will still receive aPGEVT_CONNDESTROY event when the connection is closed.

The connection destroy event is fired in response toPQfinish. It is the event procedure's responsibility to properly clean up its event data as libpq has no ability to manage this memory. Failure to clean up will lead to memory leaks.

typedef struct{    PGconn *conn;} PGEventConnDestroy;

When aPGEVT_CONNDESTROY event is received, theevtInfo pointer should be cast to aPGEventConnDestroy *. This event is fired prior toPQfinish performing any other cleanup. The return value of the event procedure is ignored since there is no way of indicating a failure fromPQfinish. Also, an event procedure failure should not abort the process of cleaning up unwanted memory.

The result creation event is fired in response to any query execution function that generates a result, includingPQgetResult. This event will only be fired after the result has been created successfully.

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

When aPGEVT_RESULTCREATE event is received, theevtInfo pointer should be cast to aPGEventResultCreate *. Theconn is the connection used to generate the result. This is the ideal place to initialize anyinstanceData that needs to be associated with the result. If an event procedure fails (returns zero), that event procedure will be ignored for the remaining lifetime of the result; that is, it will not receivePGEVT_RESULTCOPY orPGEVT_RESULTDESTROY events for this result or results copied from it.

The result copy event is fired in response toPQcopyResult. This event will only be fired after the copy is complete. Only event procedures that have successfully handled thePGEVT_RESULTCREATE orPGEVT_RESULTCOPY event for the source result will receivePGEVT_RESULTCOPY events.

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

When aPGEVT_RESULTCOPY event is received, theevtInfo pointer should be cast to aPGEventResultCopy *. Thesrc result is what was copied while thedest result is the copy destination. This event can be used to provide a deep copy ofinstanceData, sincePQcopyResult cannot do that. If an event procedure fails (returns zero), that event procedure will be ignored for the remaining lifetime of the new result; that is, it will not receivePGEVT_RESULTCOPY orPGEVT_RESULTDESTROY events for that result or results copied from it.

The result destroy event is fired in response to aPQclear. It is the event procedure's responsibility to properly clean up its event data as libpq has no ability to manage this memory. Failure to clean up will lead to memory leaks.

typedef struct{    PGresult *result;} PGEventResultDestroy;

When aPGEVT_RESULTDESTROY event is received, theevtInfo pointer should be cast to aPGEventResultDestroy *. This event is fired prior toPQclear performing any other cleanup. The return value of the event procedure is ignored since there is no way of indicating a failure fromPQclear. Also, an event procedure failure should not abort the process of cleaning up unwanted memory.

PGEventProc is a typedef for a pointer to an event procedure, that is, the user callback function that receives events from libpq. The signature of an event procedure must be

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

TheevtId parameter indicates whichPGEVT event occurred. TheevtInfo pointer must be cast to the appropriate structure type to obtain further information about the event. ThepassThrough parameter is the pointer provided toPQregisterEventProc when the event procedure was registered. The function should return a non-zero value if it succeeds and zero if it fails.

A particular event procedure can be registered only once in anyPGconn. This is because the address of the procedure is used as a lookup key to identify the associated instance data.

Registers an event callback procedure with libpq.

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

An event procedure must be registered once on eachPGconn you want to receive events about. There is no limit, other than memory, on the number of event procedures that can be registered with a connection. The function returns a non-zero value if it succeeds and zero if it fails.

Theproc argument will be called when a libpq event is fired. Its memory address is also used to lookupinstanceData. Thename argument is used to refer to the event procedure in error messages. This value cannot beNULL or a zero-length string. The name string is copied into thePGconn, so what is passed need not be long-lived. ThepassThrough pointer is passed to theproc whenever an event occurs. This argument can beNULL.

Sets the connectionconn'sinstanceData for procedureproc todata. This returns non-zero for success and zero for failure. (Failure is only possible ifproc has not been properly registered inconn.)

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

Returns the connectionconn'sinstanceData associated with procedureproc, orNULL if there is none.

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

Sets the result'sinstanceData forproc todata. This returns non-zero for success and zero for failure. (Failure is only possible ifproc has not been properly registered in the result.)

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

Beware that any storage represented bydata will not be accounted for byPQresultMemorySize, unless it is allocated usingPQresultAlloc. (Doing so is recommendable because it eliminates the need to free such storage explicitly when the result is destroyed.)

Returns the result'sinstanceData associated withproc, orNULL if there is none.

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