Install or retrieve a Client-Library callback routine.
CS_RETCODE ct_callback(context, connection, action, type, func) CS_CONTEXT *context; CS_CONNECTION *connection; CS_INT action; CS_INT type; CS_VOID *func;
A pointer to a CS_CONTEXT structure. A CS_CONTEXT structure defines a Client-Library application context.
Either context or connection must be NULL:
If context is supplied, the callback is installed as a “default” callback for the specified context. Once installed, a default callback is inherited by all connections subsequently allocated within the context.
If context is NULL, the callback is installed for the individual connection specified by connection.
A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.
Either context or connection must be NULL:
If connection is supplied, the callback is installed for the specified connection.
If connection is NULL, the callback is installed for the application context specified by context.
One of the following symbolic values:
Value of action |
Meaning |
|---|---|
CS_SET |
Installs a callback |
CS_GET |
Retrieves the currently installed callback of this type |
The type of callback routine of interest. The following table lists the symbolic values for type:
Value of type |
Meaning |
|---|---|
CS_CLIENTMSG_CB |
A client message callback, as described in “Client message callbacks”. |
CS_COMPLETION_CB |
A completion callback, as described in “Completion callbacks”. |
CS_DS_LOOKUP_CB |
A directory callback, as described in “Directory callbacks”. |
CS_ENCRYPT_CB |
An encryption callback, as described in “Encryption callbacks”. |
CS_EXTENDED_ENCRYPT_CB |
An encryption callback, as described in “Encryption callbacks”. |
CS_CHALLENGE_CB |
A negotiation callback, as described in “Negotiation callbacks”. |
CS_NOTIF_CB |
A registered procedure notification callback, as described in “Notification callbacks”. |
CS_SECSESSION_CB |
A security session callback, as described in “Security session callbacks”. |
CS_SERVERMSG_CB |
A server message callback, as described in “Server message callbacks”. |
CS_SIGNAL_CB + signal_number |
A signal callback, as described in “Signal callbacks”. Signal callbacks are identified by adding the signal number of interest to the manifest constant CS_SIGNAL_CB. For example, to install a signal callback for a SIGALRM signal, pass type as CS_SIGNAL_CB + SIGALRM. |
CS_SSLVALIDATE_CB |
An SSL validation callback, as described in “SSL validation callbacks”. |
A pointer variable.
If a callback routine is being installed, func is the address of the callback routine to install.
If a callback routine is being retrieved, ct_callback sets *func to the address of the currently installed callback routine.
ct_callback returns the following values:
Return value |
Meaning |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
CS_BUSY |
An asynchronous operation is already pending for this connection. For more information, see “Asynchronous programming”. |
/*
** Install message and completion handlers.
*/
retstat = ct_callback(Ex_context, NULL, CS_SET,
CS_CLIENTMSG_CB,(CS_VOID *)ex_clientmsg_cb);
if (retstat != CS_SUCCEED)
{
ex_panic("ct_callback failed");
}
retstat = ct_callback(Ex_context, NULL, CS_SET,
CS_SERVERMSG_CB,(CS_VOID *)ex_servermsg_cb);
if (retstat != CS_SUCCEED)
{
ex_panic("ct_callback failed");
}
retstat = ct_callback(Ex_context, NULL, CS_SET,
CS_COMPLETION_CB,(CS_VOID *)CompletionCB);
if (retstat != CS_SUCCEED)
{
ex_panic("ct_callback failed");
}
This code excerpt is from the ex_amain.c sample program. For additional examples of using ct_callback, see the ex_alib.c and exutils.c sample programs.
A typical application will use ct_callback only to install callback routines. However, some applications may need to retrieve previously installed callbacks.
To install a callback routine, an application calls ct_callback with action as CS_SET and func as the address of the callback to install.
To retrieve the address of a previously installed callback, an application calls ct_callback with action as CS_GET and func as a pointer to a pointer. In this case, ct_callback sets *func to the address of the current callback of the specified type. An application can save this address for use again at a later time. Note that retrieving the address of a callback does not de-install it.
ct_callback can be used to install a callback routine either for a context or for a particular connection. To install a callback for a context, pass connection as NULL. To install a callback for a connection, pass context as NULL.
When a context is allocated, it has no callback routines installed. An application must specifically install any callbacks that are required.
When a connection is allocated, it picks up default callback routines from its parent context. An application can override these default callbacks by calling ct_callback to install new callbacks at the connection level.
To deinstall an existing callback routine, an application can call ct_callback with func as NULL. An application can also install a new callback routine at any time. The new callback automatically replaces any existing callback.
For most types of callbacks, if no callback of a particular type is installed for a connection, Client-Library discards callback information of that type.
The client message callback is an exception to this rule. When an error or informational message is generated for a connection that has no client message callback installed, Client-Library calls the connection’s parent context’s client message callback (if any) rather than discarding the message. If the context has no client message callback installed, then the message is discarded.
A connection picks up its parent context’s callback routines only once, when it is allocated. This has two important implications:
Existing connections are not affected by changes to their parent context’s callback routines.
If a callback routine of a particular type is de-installed for a connection, the connection does not pick up its parent context’s callback routine. Instead, the connection is considered to have no callback routine of this type installed.
An application can use the CS_USERDATA property to transfer information between a callback routine and the program code that triggered it. The CS_USERDATA property allows an application to save user data in internal Client-Library space and retrieve it later.
On Digital UNIX,
Client-Library uses interrupt-driven I/O for
all network I/O modes, including
synchronous mode. This affects the coding of some applications.
On Digital UNIX, Client-Library applications that require their own signal handler must install any needed signal handlers with ct_callback. Programs that make UNIX system calls should check for system-call failure caused by system interrupts, and reissue any interrupted system calls.
“Callbacks”, ct_capability, ct_config, ct_con_props, ct_connect
