Define or retrieve capability information on a client connection.
CS_RETCODE srv_capability_info(spp, cmd, type,
capability, valp)
SRV_PROC *spp; CS_INT cmd; CS_INT type; CS_INT capability; CS_VOID *valp;
A pointer to an internal thread control structure.
Indicates whether the Open Server application is defining or retrieving the capability information. The following table describes the legal values for cmd:
Value |
Meaning |
|---|---|
CS_SET |
The Open Server application is defining capability information. |
CS_GET |
The Open Server application is retrieving capability information from the client. |
The capability group type. The following table summarizes the two legal types:
Value |
Meaning |
|---|---|
CS_CAP_REQUEST |
The possible commands a client may want to send. |
CS_CAP_RESPONSE |
The possible responses a client may want an Open Server application to withhold. |
Specifies the capability item of interest. To set or get the bitmap for all capability items in a type category, set capability to CS_ALL_CAPS. See “Capabilities” for a list of all request and response capabilities.
A pointer to a program variable. When sending information to a client (CS_SET), the application sets the capability value in this variable. When retrieving information from a client, (CS_GET), Open Server places the capability value in this variable. valp should be a CS_BOOL pointer when the application is defining or retrieving individual capability items, and a CS_CAP_TYPE pointer when the application is defining or retrieving the full bitmap for all capability items (that is, capability is CS_ALL_CAPS).
Returns |
To indicate |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
#include <ospublic.h>
CS_RETCODE ex_srv_capability_info PROTOTYPE((
SRV_PROC *spp
));
/*
** EX_SRV_CAPABILITY_INFO
**
** Example routine to retrieve and define capability
** information on a client connection.
**
** This routine must called in the context of the connect
** handler, so that it is legal to negotiate capabilities.
**
** Arguments:
** spp A pointer to an internal thread control structure.
**
** Returns:
** CS_SUCCEED - Successfully retrieved and bound capability
** information.
** CS_FAIL - An error was detected.
**
*/
CS_RETCODE ex_srv_capability_info(spp)
SRV_PROC *spp;
{
CS_RETCODE retval; /* Return value from Open */
/* Server API calls. */
CS_CAP_TYPE capabilities; /* Our bit mask. */
CS_BOOL value; /* Set to CS_TRUE or CS_FALSE */
/* for individual capabilities. */
/*
** In this example, we don’t want to support text or image,
** so we’ll see first if the client has requested this.
** We’ll do this by getting the entire bit mask.
*/
retval = srv_capability_info(spp, CS_GET, CS_CAP_REQUEST,
CS_ALL_CAPS, (CS_VOID *)&capabilities);
if (retval == CS_FAIL)
{
return (CS_FAIL);
}
/*
** Turn off text and image.
**
** The other way to do this is to just clear the
** CS_DATA_TEXT and CS_DATA_IMAGE bits in the capabilities
** bit mask, and then call srv_capability_info() with
** CS_ALL_CAPS for the “type” parameter and the altered
** bit mask as the value.
*/
if (CS_TST_CAPMASK(&capabilities, CS_DATA_TEXT) == CS_TRUE)
{
value = CS_FALSE;
retval = srv_capability_info(spp, CS_SET,
CS_CAP_REQUEST, CS_DATA_TEXT, (CS_VOID *)&value);
if (retval == CS_FAIL)
{
return (CS_FAIL);
}
}
if (CS_TST_CAPMASK(&capabilities, CS_DATA_IMAGE) == CS_TRUE)
{
value = CS_FALSE;
retval = srv_capability_info(spp, CS_SET,
CS_CAP_REQUEST, CS_DATA_IMAGE, (CS_VOID*)
&value);
if (retval == CS_FAIL)
{
return (CS_FAIL);
}
}
return (CS_SUCCEED);
}
An Open Server application and a client must agree on what requests the client can issue and what responses the Open Server application will return. A client/server connection’s capabilities determine the types of client requests and server responses permitted for that connection.
Open Server assigns a default set of capabilities for all connections. An Open Server application that does not want the default set of capabilities to apply to a given connection can call srv_capability_info to negotiate explicitly a different set of capabilities.
See “Capabilities” for a list of the default set of requests and response capabilities.
Response capabilities indicate the kinds of responses
the client does not want to receive.
Open Server has two types of capabilities: platform capabilities and protocol capabilities. The srv_capability routine pertains to platform capabilities. The srv_capability_info routine pertains to protocol capabilities. For more information on srv_capability, see srv_capability.
