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, the registration is aborted.

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. If the event procedure fails, the entire connection reset will fail; thePGconn is put intoCONNECTION_BAD status andPQresetPoll will returnPGRES_POLLING_FAILED.

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 the event procedure fails, the result will be cleared and the failure will be propagated. The event procedure must not try toPQclear the result object for itself. When returning a failure code, all cleanup must be performed as noPGEVT_RESULTDESTROY event will be sent.

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 the event procedure fails, the entire copy operation will fail and thedest result will be cleared. When returning a failure code, all cleanup must be performed as noPGEVT_RESULTDESTROY event will be sent for the destination result.

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);

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

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