Callback types

The following table lists the types of callbacks, and when they are called:

**Table 2-1: Types of callbacks**
Callback type	When called	How called
Client message	In response to a Client-Library error or informational message	When Client-Library generates an error or informational message, Client-Library automatically triggers the client message callback. See “Client message callbacks”.
Completion	When an asynchronous Client-Library routine completes	An asynchronous routine completion can occur at any time. On platforms that support signal- or thread-driven I/O, the completion callback is called automatically when the completion occurs. On platforms that do not support signal- or thread-driven I/O, an application must use ct_poll to find out if any routines have completed. See “Completion callbacks”.
Directory	During a directory search that began when the application called ct_ds_lookup	Called automatically by Client-Library to pass the application the directory objects that were found in the search. On an asynchronous connection, called before the completion callback. On a synchronous connection, called before ct_ds_lookup returns. Client-Library invokes the callback repeatedly until: The callback has received all directory objects found in the lookup operation, or The callback returns CS_SUCCEED. See “Directory callbacks”.
Encryption	During the connection process, in response to a server request for an encrypted password	If password encryption is enabled and an encryption callback is installed, then Client-Library automatically triggers the encryption callback when a server requests an encrypted password during a connection attempt. If encryption is enabled and an encryption callback is not installed, then Client-Library performs the default password encryption. For details, see “Encryption callbacks”.
Negotiation	During the connection process: In response to a server request for login security labels In response to a server challenge	If a connection’s CS_SEC_NEGOTIATE property is CS_TRUE, then Client-Library automatically triggers the negotiation callback when a server requests login security labels during a connection attempt. If a connection’s CS_SEC_CHALLENGE property is CS_TRUE, then Client-Library automatically triggers the negotiation callback when a server issues a challenge during a connection attempt. For details, see “Negotiation callbacks”.
Notification	When an Open Server notification arrives	An Open Server notification can arrive at any time. Client-Library reads the notification information and calls the applications’s notification callback. The CS_ASYNC_NOTIFS property determines how the notification callback is triggered. See the description of this property under “Asynchronous notifications” and “Notification callbacks”.
Security session	During the connection process, when the connection uses network-based security services	Invoked automatically by ct_connect in response to a security session challenge from the target server. For details, see “Security session callbacks”. Security session callbacks are required only in gateway applications that set up direct security sessions between their own client and a remote server.
Server message	In response to a server error or informational message	Server messages occur as the result of specific commands. When an application processes the results of a command, Client-Library reads any error or informational messages related to the command, automatically triggering the server message callback. For details, see “Server message callbacks”.
Signal	In response to an operating-system signal	When a signal handler has been installed with ct_callback and a signal arrives, Client-Library’s own signal handler automatically calls the signal callback. On platforms that support signals, applications must call ct_callback to install any needed signal handlers. For details on signal callbacks, see “Signal callbacks”.

Table 2-1: Types of callbacks

Callback type

When called

How called

Client message

In response to a Client-Library error or informational message

When Client-Library generates an error or informational message, Client-Library automatically triggers the client message callback.

See “Client message callbacks”.

Completion

When an asynchronous Client-Library routine completes

An asynchronous routine completion can occur at any time.

On platforms that support signal- or thread-driven I/O, the completion callback is called automatically when the completion occurs. On platforms that do not support signal- or thread-driven I/O, an application must use ct_poll to find out if any routines have completed.

See “Completion callbacks”.

Directory

During a directory search that began when the application called ct_ds_lookup

Called automatically by Client-Library to pass the application the directory objects that were found in the search. On an asynchronous connection, called before the completion callback. On a synchronous connection, called before ct_ds_lookup returns. Client-Library invokes the callback repeatedly until:

The callback has received all directory objects found in the lookup operation, or
The callback returns CS_SUCCEED.

See “Directory callbacks”.

Encryption

During the connection process, in response to a server request for an encrypted password

If password encryption is enabled and an encryption callback is installed, then Client-Library automatically triggers the encryption callback when a server requests an encrypted password during a connection attempt.

If encryption is enabled and an encryption callback is not installed, then Client-Library performs the default password encryption.

For details, see “Encryption callbacks”.

Negotiation

During the connection process:

In response to a server request for login security labels
In response to a server challenge

If a connection’s CS_SEC_NEGOTIATE property is CS_TRUE, then Client-Library automatically triggers the negotiation callback when a server requests login security labels during a connection attempt.

If a connection’s CS_SEC_CHALLENGE property is CS_TRUE, then Client-Library automatically triggers the negotiation callback when a server issues a challenge during a connection attempt.

For details, see “Negotiation callbacks”.

Notification

When an Open Server notification arrives

An Open Server notification can arrive at any time. Client-Library reads the notification information and calls the applications’s notification callback.

The CS_ASYNC_NOTIFS property determines how the notification callback is triggered. See the description of this property under “Asynchronous notifications” and “Notification callbacks”.

Security session

During the connection process, when the connection uses network-based security services

Invoked automatically by ct_connect in response to a security session challenge from the target server.

For details, see “Security session callbacks”.

Security session callbacks are required only in gateway applications that set up direct security sessions between their own client and a remote server.

Server message

In response to a server error or informational message

Server messages occur as the result of specific commands. When an application processes the results of a command, Client-Library reads any error or informational messages related to the command, automatically triggering the server message callback.

For details, see “Server message callbacks”.

Signal

In response to an operating-system signal

When a signal handler has been installed with ct_callback and a signal arrives, Client-Library’s own signal handler automatically calls the signal callback.

On platforms that support signals, applications must call ct_callback to install any needed signal handlers.

For details on signal callbacks, see “Signal callbacks”.