|
|
|
You must register your callback functions before they are invoked by c-treeDB API code. The callback function is registered with a call to the ctdbSetCallback() function, passing the appropriate c-treeDB API handle, the callback function type and the address of a function to receive the callback calls.
CTDBRET ctdbSetCallback(CTHANDLE Handle, CTDB_CALLBACK_TYPE CallBackType,
ctdbCallbackFunction CallBackFunc);
c-treeDB API C API Example
/* allocate a new session handle */
CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTREE);
/* set table open callback */
if (ctdbSetCallback(hSession, CTDB_ON_TABLE_OPEN, OnTableOpen) != CTDBRET_OK)
printf("ctdbSetCallback failed\n");
You can register any of the defined callback functions using the session handle and every time a database, table or record handle is allocated, they will automatically inherit their callbacks from the session handle. Conversely, if you register callbacks with a database handle, every time a table or a record handle is allocated they will automatically inherit their callbacks from the database handle. Record handles will inherit any callbacks registered with the table handle.
You clear callbacks from a handle by calling either ctdbClearCallback() or ctdbClearAllCallback().
c-treeDB API C API Example
/* allocate a record handle */
CTHANDLE hRecord = ctdbAllocRecord(hTable);
/* make sure there are no callbacks */
ctdbClearAllCallback(hRecord);
You can check if a given callback has been registered with a session, database, table or record handle by calling the ctdbGetCallback() function. If a callback function was set, ctdbGetCallback() returns the address of the function. If a particular callback is not set, ctdbGetCallback() returns NULL.
c-treeDB API C API Example
/* allocate a table handle */
CTHANDLE hTable = ctdbAllocTable(hDatabase);
/* make sure CTDB_ON_TABLE_OPEN callback is set */
if (ctdbGetCallback(hTable, CTDB_ON_TABLE_OPEN) == NULL)
if (ctdbSetCallback(hTable, CTDB_ON_TABLE_OPEN, OnTableOpen) != CTDBRET_OK)
printf("ctdbSetCallback failed\n");
|
|
|
When a callback function is executed, it may need to allocate, re-allocate and release memory that was allocated by the c-treeDB API internal code. The callback function must use exactly the same memory allocation function that was used by the c-treeDB API code or a heap corruption, and most certainly a memory exception, will occur.
The c-treeDB API session handle has a function pointer called onAlloc that must be used by the callback functions to allocate memory. The onAlloc function pointer has the following type:
typedef pVOID (ctdbDECL* ctdbAllocFunc)(VRLEN size);
size is the number of bytes to be allocated. The returned value is a pointer to void.
The c-treeDB API session handle also has a function pointer called onFree that must be used by callback function to release memory. The onFree function pointer has the following type:
typedef void (ctdbDECL* ctdbFreeFunc)(pVOID ptr);
ptr points to memory to be released. No value is returned.
Please note that the c-treeDB API database, table and record handles have a member variable called pSession which points to the current session handle. You can use this pSession member variable to obtain the reference to the onAlloc and onFree function pointers. In some cases you should typecast the pSession member as a pointer to a CTDBSESSION structure.
