<< Click to Display Table of Contents >> Navigation:  »No topics above this level« DbiRegisterCallBack

C syntax

DBIResult DBIFN DbiRegisterCallBack (hCursor, ecbType, iClientData, iCbBufLen, pCbBuf, pfCb);

Delphi syntax

function DbiRegisterCallBack (hCursor: hDBICur; ecbType: CBType; iClientData: Longint; iCbBufLen: Word; CbBuf: Pointer; pfCb: pfDBICallBack): DBIResult stdcall;

Description

DbiRegisterCallBack registers a callback function for the client application.

Parameters

hCursor                Type: hDBICur                (Input)
Specifies the cursor handle to which the callback is being registered. Optional. If hCursor is NULL, the callback is registered to the current session.

ecbType                Type: CBType                (Input)
Specifies the type of callback. ecbType can be cbGENPROGRESS, cbBATCHRESULT, cbRESTRUCTURE, cbINPUTREQ, cbTABLECHANGED, cbDELAYEDUPD, or cbDBASELOGIN. (See "Usage" below.)

iClientData                Type: UINT32                (Input)
Passthrough data specified by the client. This is used to help the client establish the context of the callback (such as a pointer to a client structure, a window handle, and so on.) This data is passed back to the client as a parameter to the callback function.

iCbBufLen                Type: UINT16                (Input)
Specifies the callback buffer length.

pCbBuf                Type: pVOID                (Input)
Pointer to the buffer where the callback data is to be returned. Points to an instantiated callback descriptor, which varies depending upon the type of callback. For example, the cbGENPROGRESS callback type creates a pointer to the CBPROGRESSDesc structure.

The data that is written to pCbBuf is the percentage completed or a message string.

pfCb                Type: pfDBICallBack                (Input)
Pointer to the desired callback function. Optional. If pfCb is NULL, DbiRegisterCallBack unregisters the previously registered callback function.

Usage

Callbacks are used when a client application needs clarification about a given BDE function before completing an operation or to return information to the client. DbiRegisterCallBack allows the client to instruct BDE about what further actions should be taken by BDE upon the occurrence of an event. BDE calls the client-registered function when the pertinent event occurs, and the client responds to the callback by telling BDE what to do with the appropriate return code (cbrABORT, cbrCONTINUE, and so on). Advantages of this mechanism are that clients do not have to check every return code on every function call, and BDE can get a user's response without interrupting the normal client process flow.

Callback function declarations and associated parameter lists, function return types, and callback data types are defined in the BDE header file for the particular BDE-using programming tool used (for Borland C, this header file is called IDAPI.H, for C++Builder, it is BDE.HPP, and for Delphi it is BDE.INT).

All callback functions use the following prototype:

typedef CBRType far *pCBRType;

typedef CBRType (DBIFN * pfDBICallBack)

(

 CBType ecbType,     // Callback type

 UINT32 iClientData, // Client callback data

 pVOID pCbInfo       // Call back info/Client

 Input

);

For each different callback type, the pCbInfo parameter serves a different purpose:

Prerequisites

The client application is responsible for the following actions:

Completion state

If a cursor is supplied, any previous callbacks for the given cursor are overwritten. All callbacks are applicable to the current session only. The callback is valid only while the cursor is open; when the cursor is closed, any cursor-specific callbacks are automatically unregistered. If hCursor is NULL, then the callback applies to all cursors in the current session that do not have an explicit callback of their own. Supplying a NULL function pointer unregisters the callback.

See also

DbiGetCallBack, DbiBatchMove, DbiDoRestructure, DbiForceReread