Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Callbacks

Callbacks

Callbacks are user-supplied routines that are automatically called by Client-Library when certain triggering events, known as callback events, occur.

Some callback events are the result of a server response arriving for an application. For example, a notification callback event occurs when a registered procedure notification arrives from an Open Server.

Other callback events occur at the internal Client-Library level. For example, a client message callback event occurs when Client-Library generates an error message.

When Client-Library recognizes a callback event, it calls the appropriate callback routine.

Client-Library must be actively engaged in reading from the network to recognize some callback events. Most callback events of this type are raised automatically when Client-Library is reading results from the network.

However, for applications that use Client-Library's asynchronous modes, or that use Open Server registered procedure notifications, two types of callback events may require special handling:

• The completion callback event, which occurs in asynchronous mode applications when an asynchronous Client-Library routine completes. Depending on the operating system, applications either receive completions automatically or by polling. See "Completions".

• The notification callback event, which occurs when an Open Server notification arrives for an application. Applications must take special steps to ensure that they receive notification events. See "Receiving notifications asynchronously".

Because some types of callback routines are executed from within a system interrupt handler or from a Client-Library worker thread, you must code applications so that data accessed by both the application's mainline code and the callbacks is safely shared.

Callback types

Callbacks are not always supported

Installing a callback routine

When a callback event occurs

Retrieving and replacing callback routines

Restrictions on Client-Library calls in callbacks

Declare callbacks with CS_PUBLIC

Client message callbacks

Defining a client message callback

Client message callback example

Completion callbacks

Defining a completion callback

Directory callbacks

Defining a directory callback

Directory search results processing

Callback invocation sequence

Directory callback example

Encryption callbacks

Defining an encryption callback

Negotiation callbacks

Challenge/response security handshakes

Defining a negotiation callback

Notification callbacks

Defining a notification callback

Retrieving notification parameters

Security session callbacks

Establishing a direct security session

Defining a security session callback

Server message callbacks

Defining a server message callback

Server message callback example

Handling specific messages

Signal callbacks

Defining a signal callback

Installing a signal callback