A client-message callback is a C function that is defined as follows:
CS_RETCODE clientmsg_cb(context, connection, message)
CS_CONTEXT *context;
CS_CONNECTION *connection;
CS_CLIENTMSG *message;
where:
context is a pointer to the CS_CONTEXT structure for which the message occurred.
connection is a pointer to the CS_CONNECTION structure for which the message occurred. connection can be NULL.
message is a pointer to a CS_CLIENTMSG structure containing Client-Library message information. For information about the CS_CLIENTMSG structure, see the “CS_CLIENTMSG Structure” topics page in the Open Client Client-Library/C Reference Manual.
message can have a new value each time the client-message callback is called.
Like other callbacks, a client-message callback is limited as to which Client-Library routines it can call. A client-message callback can call only the following routines:
ct_config, to retrieve information only
ct_con_props, to retrieve information or to set the CS_USERDATA property only
ct_cmd_props, to retrieve information or to set the CS_USERDATA property only
ct_cancel(CS_CANCEL_ATTN)
A client-message callback must return one of the following return codes:
CS_SUCCEED, to instruct Client-Library to continue any processing that is occurring on this connection. In the case of timeout errors, CS_SUCCEED causes Client-Library to wait for one additional timeout period. At the end of this period, Client-Library calls the client-message callback again.
CS_FAIL, to instruct Client-Library to terminate any processing that is currently occurring on this connection. A return of CS_FAIL results in the connection being marked as dead. To continue using the connection, the application must close the connection and then reopen it.
