|
This chapter describes the API functions and structures that an external application must use to exchange messages with the Cisco IOS Gatekeeper. The external application links with the object code, which contains the API functions. The header file contains API prototypes and type definitions.
This section describes the functions provided with the API. These functions should be used by the external application to gather information from and provide information to the Cisco IOS Gatekeeper. The functions described in this section are:
This function sets up the socket for the application to communicate as a client with the Cisco IOS Gatekeeper. In this situation, the application is the client and the Gatekeeper is the server, which means the application must initiate the communication with the Cisco IOS Gatekeeper.
The input to this function is:
The return for this function is an integer. If the client socket connection has been set up successfully or is in progress, a connection handle is returned. This connection handle is the socket descriptor that the application uses to wait on a connection completion or read socket event. If an error occurs while setting up the client connection, the value -1 is returned. In this case, the error information is provided in the STATUS_TYPE.
This function sets up the socket for the application to communicate as a server with the Cisco IOS Gatekeeper. In this situation, the application is the server and the Gatekeeper is the client, which means that the application will accept incoming connections from Cisco IOS Gatekeeper clients.
The return for this function is an integer. If the client socket connection has been set up successfully or is in progress, a connection handle is returned. This connection handle is the socket descriptor that the application uses to wait on a connection completion or read socket event. If an error occurs while setting up the client connection, the value -1 is returned. In this case, the error information is provided in the STATUS_TYPE.
This function must be called by the application to indicate that a select event for a connect complete has occurred.
The input to this function is
The return for this function is an integer. If the socket connection has been set up successfully or is in progress, a connection handle is returned. This connection handle is the socket descriptor that the application uses to wait on a connection completion or read socket event. If an error occurs while setting up the client connection, the value -1 is returned. In this case, the error information is provided in the STATUS_TYPE.
This function must be called by the application (when it is running in the server mode) to indicate that a select event for an incoming connection has occurred.
The input to this function is
The return for this function is an integer. If the socket connection has been set up successfully or is in progress, a connection handle is returned. This connection handle is the socket descriptor that the application uses to wait on a connection completion or read socket event. If an error occurs while setting up the client connection, the value -1 is returned. In this case, the error information is provided in the STATUS_TYPE.
Applications can use this function to obtain the GKTMP version used by the API and the gatekeeper. The version number consists of a major number (gk_major) and a minor number (gk_minor). For example, version 1 is represented as 100.
The input to this function is
The return for this function is an integer. The integer indicates one of the following status codes:
This function closes the TCP connection between the external application and the Cisco IOS Gatekeeper. It is called under error circumstances and when the external application no longer wants to maintain a relationship with the Cisco IOS Gatekeeper.
The input for this function is a pointer to the GKAPI_SOCK_INFO structure.
There is no return for this function.
This function allocates memory for the size of GK_READ_MSG structure. This structure is used to store messages received from the Cisco IOS Gatekeeper. It contains an enumeration of the messages that can be received (REQUEST messages from the Cisco IOS Gatekeeper for RRQ, ARQ, LRQ, LCF, LRJ, as well as registration and unregistration responses from the Cisco IOS Gatekeeper for ARQ, RRQ, URQ, LRQ, LCF, LRJ messages) and a union of structures for the different messages.
There is no input to this function.
The return for this function is a pointer to the GK_READ_MSG structure. If the memory allocation fails, this pointer will be NULL.
This function reads a message from the TCP socket and should be called when the external application has detected a read event on the socket. This function stores the message type into the structure. The parameters received in the message are stored in the structure that corresponds with the message type.
Upon reading a message, this function sets the message type and populates the appropriate structure. For example, if an ARQ message has been received from the Cisco IOS Gatekeeper, the msgType parameter is set to ARQ_REQUEST_MSG and the ARQ_REQUEST_MSG structure will be populated.
Because some parameters are optional, these parameters might not be received for a particular message. Structure members that are character pointers are initialized to NULL. Integers and enumerations are set to their initialization values. Therefore, the API can assume that if a structure member has a pointer set to NULL or to it's initialization value, that particular parameter has not been received.
The following initialization values indicate that the parameter was not received from the Cisco IOS Gatekeeper:
The input for this function is:
The return for this function is the STATUS_TYPE. Possible values for STATUS_TYPE are:
This function frees memory that was allocated by the call to GetReadMsgBuffer and ReadMsgBuffer. This function must be called after processing the information returned by ReadMsgBuffer.
The input for this function is a pointer to the GK_READ_MSG structure.
There is no return for this function.
This function writes a response message to the Cisco IOS Gatekeeper. This structure contains RESPONSE_MSG_TYPE, which is an enumeration of the response messages that can be sent to the Cisco IOS Gatekeeper.
The calling function must set the message type and populate the appropriate structure within the union. For example, if a response RCF needs to be sent to the Cisco IOS Gatekeeper, the application should set the msgType to RCF_RESPONSE_MSG and populate the RCF_RESPONSE_MSG structure.
The following rules apply to responses sent by the external application to the Cisco IOS Gatekeeper:
Only changed or new fields should be populated and sent to the Cisco IOS Gatekeeper. Parameters that are not to be sent to the Cisco IOS Gatekeeper must either be set to their initialization value or to NULL (for pointers). The API will assume that if a structure member is set to it's initialization value or has a pointer set to NULL, that parameter should not be sent to the Cisco IOS Gatekeeper.
The following initialization values indicate that the parameter should not be sent to the Cisco IOS Gatekeeper:
The input for this function is:
The return for this function is the STATUS_TYPE. Possible values for STATUS_TYPE are:
This function sends a registration message to the Cisco IOS Gatekeeper. In allows triggers to be dynamically registered with the Cisco IOS Gatekeeper. This structure, REGISTER_MSG_TYPE, contains an enumeration of messages that can be registered with the GateKeeper.
The REGISTER_REQUEST_HEADER structure must include the "from", "to", "priority", and "notification-only" fields.
The input for this function is:
The return for this function is the STATUS_TYPE. Possible values for STATUS_TYPE are:
This function sends an unregister message to the Cisco IOS Gatekeeper when the application no longer wants to receive a particular message. This structure contains REGISTER_MSG_TYPE, which is an enumeration of messages that can be unregistered with the Cisco IOS Gatekeeper.
The input for this function is:
The return for this function is the STATUS_TYPE. Possible values for STATUS_TYPE are:
This function allows the application to control the type of debug messages that the Gatekeeper API provides and the location of the debug output.
The input for this function is:
There is no return for this function.
This function returns the current debug setting for the Gatekeeper API.
There is no input for this function.
The return for this function is an integer that indicates they type of debugging being performed by the Gatekeeper API.
The Gatekeeper API stores all data received from the Cisco IOS Gatekeeper in structures. The structures point to character strings, integers, and often enumerations (which are lists of possible values for a specific field). The structures used by the Gatekeeper API are:
The GKAPI_SOCK_INFO structure is used by several API functions to identify the connection to the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
TCPPort | Integer | The TCP port of the Cisco IOS Gatekeeper that is establishing the incoming connection to the application. |
IPAddress | Character string | The IP address of the Cisco IOS Gatekeeper that is establishing the incoming connection to the application. |
gkHandle | Integer | Handle to the Cisco IOS Gatekeeper function. |
serverHandle | Integer | Handle to the server function. |
TCPPort and IPAddress are provided by the calling function. The API writes the handle into gkHandle and serverHandle when the connection is established. If an error is encountered in the handle creation or in the connection, the gkHandle will be set to -1. The external application is responsible for storing the handle and using it to read, write, and close the connection.
The GKAPI_TCP_ADDR_INFO structure is used to store the TCP Port and IP address. This structure contains the following:
Field | Field Type | Description |
---|---|---|
TCPPort | Integer | The TCP port that the Cisco IOS Gatekeeper uses for handling GKTMP messages. For GkapiSetupServer, this is the TCP port that the application uses for interacting with the Gatekeeper. |
IPAddress | Unsigned long | For GkapiSetupClient, this is the IP address that the Cisco IOS Gatekeeper uses for handling GKTMP messages. For GkapiSetupServer, this is the IP address that the application uses for interacting with the Gatekeeper. |
The GKAPI_VERSION_INFO structure is used to store the major and minor version numbers of the gatekeeper TMP and API. This structure contains the following:
Field | Field Type | Description |
---|---|---|
gkapi_major | Integer | The major number identifying the version of the API. |
gkapi_minor | Integer | The minor number identifying the version of the API. |
gktmp_major | Integer | The major number identifying the version of the TMP. |
gktmp_minor | Integer | The minor number identifying the version of the TMP. |
GKAPI_MAX_VER_STR_LEN | Character string | The build date and target operating system of the protocol. |
gkapi_release_num | Integer | The release number of the gatekeeper API. |
The GK_REGISTER_MSG structure is used to send registration messages to the Cisco IOS Gatekeeper. This structure contains:
Field | Field Type | Description |
---|---|---|
msgType | Enumeration | See REGISTER_MSG_TYPE. |
rrqRegMsg | Structure | See RRQ_REGISTER_MSG. |
urqRegMsg | Structure | See URQ_REGISTER_MSG. |
arqRegMsg | Structure | See ARQ_REGISTER_MSG. |
lrqRegMsg | Structure | See LRQ_REGISTER_MSG. |
lcfRegMsg | Structure | See LCF_REGISTER_MSG. |
lrjRegMsg | Structure | See LRJ_REGISTER_MSG. |
The GK_UNREGISTER_MSG structure is used to send unregistration messages to the Cisco IOS Gatekeeper. This structure contains:
Field | Field Type | Description |
---|---|---|
unregisterMsg | Enumeration | See REGISTER_MSG_TYPE. |
versionId | Integer | Identifier of the version of GKTMP being used. For the initial release, the only possible value is 1. |
from | Character string | Originator of the message. For requests from the Cisco IOS Gatekeeper, this field contains the gatekeeper ID. For responses from the external application, this field contains the server ID. The limit of this field is MAX_ENDPOINT_LENGTH + 1. |
to | Character string | Receiver of the message. For requests from the Cisco IOS Gatekeeper, this field contains the server ID. For responses from the external application, this field contains the ID of the gatekeeper that initiated the request. The limit of this field is MAX_ENDPOINT_LENGTH + 1. |
priority | Integer | Priority of the filter. Possible values are 1 through 20. 1 is the highest priority. |
The REG_UNREG_RESP_MSG structure is used to process registration and unregistration responses from the Cisco IOS Gatekeeper. This structure contains:
Field | Field Type | Description |
---|---|---|
regHeader | Structure |
The REGISTER_REQUEST_HEADER structure is used when a registration request is to be sent to Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
versionId | Integer | Identifier of the version of GKTMP being used. For the initial release, the only possible value is 1. |
from | Character string | Originator of the message, which for registration requests is the server ID. The limit of this field is MAX_ENDPOINT_LENGTH+1. |
to | Character string | Receiver of the message, which for registration requests is the gatekeeper ID The limit of this field is MAX_ENDPOINT_LENGTH+1. |
priority | Integer | Priority of the filter. Possible values are 1 through 20. 1 is the highest priority. |
notificationOnly | Boolean | Whether the registration request is for notifications only. If this field is set to True, messages that match the specified trigger parameters will be sent on a notification-only basis. |
The REGISTER_RESPONSE_HEADER structure is used when a registration or unregistration response is received from the Cisco IOS Gatekeeper. The registration or unregistration response is received after the application sends a registration or unregistration request to the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
Version-id | Integer | Identifier of the version of GKTMP being used. For the initial release, the only possible value is 1. |
from | Character string | Originator of the message, which for registration responses is the gatekeeper ID. The limit of this field is MAX_ENDPOINT_LENGTH+1. |
to | Character string | Receiver of the message, which for registration responses is the server ID. The limit of this field is MAX_ENDPOINT_LENGTH+1. |
priority | Integer | Priority of the filter. Possible values are 1 through 20. 1 is the highest priority. |
regStatus | Enumeration | See REG_STATUS_TYPE. |
The ARQ_REGISTER_MSG structure is used to send registrations for ARQ requests to the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. The limit of this field is MAX_NUM_ARQ_DEST_INFO. |
redirectReason | Enumeration | Taken from the Q.931 Setup Redirecting Number IE. See REDIRECT_REASON_TYPE. The limit of this field is MAX_NUM_ARQ_REDIRECT_REASON. |
The RRQ_REGISTER_MSG structure is used to send registrations for RRQ requests to the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | |
terminalType | Enumeration | Type of endpoint being registered. See ENDPOINT_TYPE. The limit of this field is MAX_NUM_ENDPOINT_TYPES. |
supportedPrefix | Character string | Prefix associated with the supported protocol. The limit of this field is MAX_NUM_SUPPORTED_PREFIX. |
The URQ_REGISTER_MSG structure is used to send registrations for URQ requests to the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | |
terminalType | Enumeration | Type of endpoint being unregistered. See ENDPOINT_TYPE. The limit of this field is MAX_NUM_ENDPOINT_TYPES. |
supportedPrefix | Character string | Prefix associated with the supported protocol. The limit of this field is MAX_NUM_SUPPORTED_PREFIX. |
The LRQ_REGISTER_MSG structure is used to send registrations for LRQ requests to the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. The limit of this field is MAX_NUM_LRQ_DEST_INFO. |
redirectReason | Enumeration | Taken from the Q.931 Setup Redirecting Number IE. See REDIRECT_REASON_TYPE. The limit of this field is MAX_NUM_LRQ_REDIRECT_REASON. |
The LCF_REGISTER_MSG structure is used to send registrations for LCF requests to the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. The limit of this field is MAX_NUM_LCF_DEST_INFO. |
rmotExtensionAddr | Character String | Alias address of a called endpoint, present in cases where this information is required to traverse multiple gateways. The limit of this field is MAX_NUM_LCF_RMOT_EXTENSION_ADDR. |
The LRJ_REGISTER_MSG structure is used to send registrations for LRJ requests to the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. The limit of this field is MAX_NUM_LRJ_DEST_INFO. |
The GK_READ_MSG structure is used process REQUEST messages from the Cisco IOS Gatekeeper for RRQ, ARQ, LRQ, LCF, LRJ, as well as registration and unregistration responses from the Cisco IOS Gatekeeper for ARQ, RRQ, URQ, LRQ, LCF, LRJ messages. This structure contains:
Field | Field Type | Description |
---|---|---|
msgType | Enumeration | See REQUEST_MSG_TYPE. |
rrqReqMsg | Structure | See RRQ_REQUEST_MSG. |
urqReqMsg | Structure | See URQ_REQUEST_MSG. |
arqReqMsg | Structure | See ARQ_REQUEST_MSG. |
lrqReqMsg | Structure | See LRQ_REQUEST_MSG. |
lcfReqMsg | Structure | See LCF_REQUEST_MSG. |
lrjReqMsg | Structure | See LRJ_REQUEST_MSG. |
unsupportedMsg | Structure | See UNSUPPORTED_MSG. |
regUnregRespMsg | Structure | See REG_UNREG_RESP_MSG. |
If the message received from the Cisco IOS Gatekeeper is a RAS message that is not supported by the API function, the msgType will be set to MSG_NOT_SUPPORTED. If a response is required, an appropriate response will be constructed by the API function and sent to the Cisco IOS Gatekeeper. The header information in the UNSUPPORTED_MSG structure will be filled in by the API function. This situation could occur if the Cisco IOS Gatekeeper has been upgraded to support new messages but the API function has not been correspondingly upgraded.
If the message received from the Cisco IOS Gatekeeper, is not recognized by the API function, the msgType will be set to UNKNOWN_MSG and the STATUS_TYPE will be set to MSG_READ_ERROR. In this case, the external application should close the connection to the Cisco IOS Gatekeeper by calling the CloseGateKeeperConnection function.
The HEADER_INFO structure is used to process header information sent from the Cisco IOS Gatekeeper or information that is sent by the application to the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
versionId | Integer | Identifier of the version of GKTMP being used. For the initial release, the only possible value is 1. |
from | Character string | Originator of the message. For requests from the Cisco IOS Gatekeeper, this field contains the gatekeeper ID. For responses from the external application, this field contains the server ID. The limit of this field is MAX_ENDPOINT_LENGTH + 1. |
to | Character string | Receiver of the message. For requests from the Cisco IOS Gatekeeper, this field contains the server ID. For responses from the external application, this field contains the ID of the gatekeeper that initiated the request. The limit of this field is MAX_ENDPOINT_LENGTH+1. |
transactionID | Character string | Identifier of the transaction. If this field is present in the request from the Cisco IOS Gatekeeper, it must be echoed in the response from the external application. The limit of this field is MAX_TRANSACTION_ID_LENGTH + 1. |
notification | Boolean | Whether the message is for notification purposes only. This field is used only in REQUEST messages that are received from the Cisco IOS Gatekeeper. |
The ARQ_REQUEST_MSG structure is used to process ARQ requests from the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
srcInfo | Character string | Sequence of alias addresses for the source endpoint. |
srcCallSignalAddress | Character string | Transport address used at the source for call signaling. |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. |
destCallSignalAddress | Character string | Transport address used at the destination for call signaling. |
destExtraCallInfo | Character string | External addresses for multiple calls. |
bandWidthPresent | Boolean | Whether a specified bandwidth is present in the request. |
bandWidth | Unsigned integer | Bandwidth (in 100 kbps) requested for the bi-directional call. |
answerCall | Integer | Indicates to the Cisco IOS Gatekeeper that the call is incoming. |
callIdentifier | Character string | A unique call identifier (set by the originating endpoint), which can be used to associate RAS signaling with the modified Q.931 signaling used in H.225.0. |
conferenceID | Character string | A unique conference identifier. |
canMapAlias | Integer | Whether the endpoint can copy information from the resulting ACF into the destinationAddress, destExtraCallInfo and remoteExtensionAddress fields of the SETUP message. |
redirectNumber | Character string | Taken from the Number Digits field of Q.931 Setup Redirecting Number IE. |
redirectReason | Enumeration | Taken from the Q.931 Setup Redirecting Number IE. See REDIRECT_REASON_TYPE. |
callingOctet3a | Character String | Whether the calling number information can be displayed. |
displayIE | Character String | Taken from the Q.931 Setup, display IE. |
endPointCallSignalAddress | Character String | Call signaling transport address of the endpoint sending the ARQ. |
cryptoToken | Pointer | See CRYPTO_H323_TOKEN. |
clearToken | Pointer | See CLEAR_TOKEN. |
The RRQ_REQUEST_MSG structure is used to process RRQ requests from the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
callSignalAddress | Character string | Call signaling transport address for this endpoint. |
rasAddress | Character string | Registration and status transport address for this endpoint. |
terminalAlias | Character string | List of alias addresses by which other terminals can identify this terminal. |
terminalType | Enumeration | Type of endpoint being registered. See ENDPOINT_TYPE. |
supportedPrefix | Character string | Prefix associated with the supported protocol. |
cryptoToken | Pointer | See CRYPTO_H323_TOKEN. |
clearToken | Pointer | See CLEAR_TOKEN. |
The URQ_REQUEST_MSG structure is used to process URQ requests from the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
callSignalAddress | Character string | Call signaling transport address for this endpoint. |
The LRQ_REQUEST_MSG structure is used to process LRQ requests from the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
srcInfo | Character string | Sequence of alias addresses for the source endpoint. |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. |
redirectNumber | Character string | Taken from the Number Digits field of Q.931 Setup Redirecting Number IE. |
redirectReason | Enumeration | Taken from the Q.931 Setup Redirecting Number IE. See REDIRECT_REASON_TYPE. |
callingOctet3a | Character String | Whether the calling number information can be displayed. |
displayIE | Character String | Taken from the Q.931 Setup, display IE. |
callingPartyNum | Character String | Taken from the Q.931. |
The LCF_REQUEST_MSG structure is used to process LCF requests from the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
srcInfo | Character string | Sequence of alias addresses for the source endpoint. |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. |
callSignalAddress | Character string | Call signaling transport address for this endpoint. |
destExtraCallInfo | Character string | External addresses for multiple calls. |
redirectNumber | Character string | Taken from the Number Digits field of Q.931 Setup Redirecting Number IE. |
redirectReason | Enumeration | Taken from the Q.931 Setup Redirecting Number IE. See REDIRECT_REASON_TYPE. |
callingOctet3a | Character String | Whether the calling number information can be displayed. |
callingPartyNum | Character String | Taken from the Q.931. |
displayIE | Character String | Taken from the Q.931 Setup, display IE. |
rasAddress | Character String | Registration and status transport address for this endpoint. |
rmotExtensionAddr | Character String | Alias address of a called endpoint, present in cases where this information is required to traverse multiple gateways. |
destinationType | Enumeration | Type of destination endpoint. See ENDPOINT_TYPE. |
The LRJ_REQUEST_MSG structure is used to process LRJ requests from the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
srcInfo | Character string | Sequence of alias addresses for the source endpoint. |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. |
redirectNumber | Character string | Taken from the Number Digits field of Q.931 Setup Redirecting Number IE. |
redirectReason | Enumeration | Taken from the Q.931 Setup Redirecting Number IE. See REDIRECT_REASON_TYPE. |
callingOctet3a | Character String | Whether the calling number information can be displayed. |
displayIE | Character String | Taken from the Q.931 Setup, display IE. |
callingPartyNum | Character String | Taken from the Q.931. |
rejectReason | Enumeration | Reason for the rejection of the request. See LRJ_REJECT_REASON_TYPE. |
The GK_WRITE_MSG structure is used to process responses from the external application to the Cisco IOS Gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
msgType | Enumeration | See RESPONSE_MSG_TYPE. |
arqRespMsg | Structure | See ARQ_RESPONSE_MSG. |
acfRespMsg | Structure | See ACF_RESPONSE_MSG. |
arjRespMsg | Structure | See ARJ_RESPONSE_MSG. |
rrqRespMsg | Structure | See RRQ_RESPONSE_MSG. |
rrjRespMsg | Structure | See RRJ_RESPONSE_MSG. |
rcfRespMsg | Structure | See RCF_RESPONSE_MSG. |
lrqRespMsg | Structure | See LRQ_RESPONSE_MSG. |
lcfRespMsg | Structure | See LCF_RESPONSE_MSG. |
lrjRespMsg | Structure | See LRJ_RESPONSE_MSG. |
ripRespMsg | Structure | See RIP_RESPONSE_MSG. |
The ARQ_RESPONSE_MSG structure is used to process ARQ responses from the external application. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. |
destCallSignalAddress | Character string | Transport address used at the destination for call signaling. |
destExtraCallInfo | Character string | External addresses for multiple calls. |
bandWidthPresent | Boolean | Whether a specified bandwidth is present in the request. |
bandWidth | Unsigned integer | Bandwidth (in 100 kbps) requested for the bi-directional call. |
redirectNumber | Character string | Taken from the Number Digits field of Q.931 Setup Redirecting Number IE. |
redirectReason | Enumeration | Taken from the Q.931 Setup Redirecting Number IE. See REDIRECT_REASON_TYPE. |
displayIE | Character String | Taken from the Q.931 Setup, display IE. |
The ACF_RESPONSE_MSG structure is used to process ACF responses from the external application. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. |
destCallSignalAddress | Character string | Transport address used at the destination for call signaling. |
destExtraCallInfo | Character string | External addresses for multiple calls. |
rmotExtensionAddr | Character string | Alias address of a called endpoint, present in cases where this information is required to traverse multiple gateways. |
bandWidthPresent | Boolean | Whether a specified bandwidth is present in the request. |
bandWidth | Unsigned integer | Bandwidth (in 100 kbps) requested for the bi-directional call. |
destinationType | Enumeration | Type of destination endpoint. See ENDPOINT_TYPE. |
altEndpt | Structure | See ALTERNATE_ENDPOINT. |
clearToken | Pointer | See CLEAR_TOKEN. |
The ARJ_RESPONSE_MSG structure is used to process ARJ responses from the external application. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
rejectReason | Enumeration | Reason the request was rejected. See ARJ_REJECT_REASON_TYPE. |
The RRQ_RESPONSE_MSG structure is used to process RRQ responses from the external application. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
terminalAlias | Character string | List of alias addresses by which other terminals can identify this terminal. |
supportedPrefix | Character string | Prefix associated with the supported protocol. |
The RCF_RESPONSE_MSG structure is used to process RCF responses from the external application. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
terminalAlias | Character string | List of alias addresses by which other terminals can identify this terminal. |
supportedPrefix | Character string | Prefix associated with the supported protocol. |
alternateGK | Structure | See ALTERNATE_GK. |
The RRJ_RESPONSE_MSG structure is used to process RRJ responses from the external application. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
rejectReason | Enumeration | Reason the request was rejected. See RRJ_REJECT_REASON_TYPE. |
The LRQ_RESPONSE_MSG structure is used to process LRQ responses from the external application. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. |
The LCF_RESPONSE_MSG structure is used to process LCF responses from the external application. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
destinationInfo | Character string | Sequence of alias addresses for the destination endpoint. |
destExtraCallInfo | Character string | External addresses for multiple calls. |
callSignalAddress | Character string | Call signaling transport address for this endpoint. |
rasAddress | Character String | Registration and status transport address for this endpoint. |
rmotExtensionAddr | Character String | Alias address of a called endpoint, present in cases where this information is required to traverse multiple gateways. |
destinationType | Enumeration | Type of destination endpoint. See ENDPOINT_TYPE. |
The LRJ_RESPONSE_MSG structure is used to process LRJ responses from the external application. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
rejectReason | Enumeration | Reason the request was rejected. See LRJ_REJECT_REASON_TYPE. |
The CRYPTO_H323_TOKEN structure is used to process cryptoTokens. This structure contains the following:
Field | Field Type | Description |
---|---|---|
token_type | Enumeration | |
cryptoEPPwdHash | Structure | See CRYPTO_EP_PWD_HASH. |
cryptoEPPwdEncr | Structure | See CRYPTO_EP_PWD_ENCR. |
cryptoEPCert | Structure | See CRYPTO_EP_CERT. |
The CRYPTO_EP_PWD_HASH structure is used to process cryptoTokens. This structure contains the following:
Field | Field Type | Description |
---|---|---|
alias | Character string | Registration and status transport address for this endpoint. |
timestamp | Character string | 32-bit integer that represents UTC time. |
token | Character string | 16 octet IA5String that represents the MD5 hashed encoded PwdCertToken. |
The CRYPTO_EP_PWD_ENCR structure is used to process the encrypted data of a cryptoToken. This structure contains the following:
Field | Field Type | Description |
---|---|---|
paramS | Character string | Any runtime parameters. |
encryptedData | Character string | Encrypted data from the cryptoToken. |
The CRYPTO_EP_CERT structure is used to process the authentication certificate of a cryptoToken. This structure contains the following:
Field | Field Type | Description |
---|---|---|
toBeSigned | Character string | Whether the certificate requires a signature. |
signature | Character string | Digital signature assigned to the authentication certificate. |
The CLEAR_TOKEN structure is used to process the clear tokens field. This structure contains the following:
Field | Field Type | Description |
---|---|---|
objectIdentifier | Character string | Object identifier. |
password | Character string | Secret character string that is used to authenticate a user or H.323 endpoint. |
timestamp | Character string | 32-bit integer that represents UTC time. |
challengeString | Character string | Challenge string used for authentication. |
random | Character string | Integer value, for example a monotonically increasing sequence number. |
generalID | Character string | Character string that uniquely identifies either the sender or receiver. |
nonstd_objectID | Character string | Object identifier that is used to indicate the type and format of the nonstandard data being sent in the clear token. |
nonstd_data | Character string | Nonstandard data in the clear tokens field. |
The ALTERNATE_GK structure is used to process information about an alternate gatekeeper. This structure contains the following:
Field | Field Type | Description |
---|---|---|
rasAddress | Character string | Registration and status transport address for this endpoint. |
gkIdentifier | Character string | Identifier of the gatekeeper. |
needToRegister | Boolean | Whether there is a need to register with this gatekeeper. |
priority | Integer | Priority of this gatekeeper. Possible values are 1 through 127. |
The ALTERNATE_ENDPOINT structure is used to process information about an alternate H.323 endpoint. This structure contains the following:
Field | Field Type | Description |
---|---|---|
callSignalAddress | Character string | Registration and status transport address for this endpoint. |
tokenP | Structure | See CLEAR_TOKEN. |
The RIP_RESPONSE_MSG structure is used to process requests from the external application for additional time. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
delay | Integer | Amount of time, in milliseconds (1 through 65536), that the endpoint should wait before retrying the request. |
The UNSUPPORTED_MSG structure is used to process requests from the Cisco IOS Gatekeeper that contain a RAS message type that is not supported by the API. This structure contains the following:
Field | Field Type | Description |
---|---|---|
headerInfo | Structure | See HEADER_INFO. |
Some of the API structures contain enumerations. An enumeration is simply a list of possible values. This section lists the enumerations used by the structures.
The STATUS_TYPE enumeration lists the possible return values from calls to read, write, register and unregister functions. The possible values are:
The REG_STATUS_TYPE enumeration lists the possible status values for registration and unregistration responses received from the Cisco IOS Gatekeeper. The possible values are:
The ENDPOINT_TYPE enumeration lists the possible types of end points. The possible values are:
The REDIRECT_REASON_TYPE enumeration lists the possible reasons that a call might be redirected. The possible values are:
The LRJ_REJECT_REASON_TYPE enumeration lists the possible reasons that an LRQ request might be rejected. The possible values are:
The REQUEST_MSG_TYPE enumeration lists the possible messages that can be received from the Cisco IOS Gatekeeper. The possible values are:
The RRJ_REJECT_REASON_TYPE enumeration lists the possible reasons that an RRQ request might be rejected. The possible values are:
The ARJ_REJECT_REASON_TYPE enumeration lists the possible reasons that an ARQ request might be rejected. The possible values are:
The RESPONSE_MSG_TYPE enumeration lists the possible messages that the external application can send to the Cisco IOS Gatekeeper. The possible values are:
The REGISTER_MSG_TYPE enumeration lists the possible registration messages that the external application can send to the Cisco IOS Gatekeeper. The possible values are:
The REPORT_DEST_T enumeration lists the possible destinations for the Gatekeeper API debug output. The possible values are:
The CRYPTO_H323_TOKEN_TYPE_S enumeration lists the possible types of cryptoTokens. The possible values are:
Some of the fields are limited in size. The limits are set using variables in the header file. The limits as set in the default header file are as follows:
Variable | Initial Value |
---|---|
MAX_IP_ADDR_LENGTH | 15 |
MAX_VERSION_ID_LENGTH | 4 |
MAX_ENDPOINT_LENGTH | 128 |
MAX_TRANSACTION_ID_LENGTH | 24 |
MAX_NUM_ENDPOINT_TYPES | 7 |
MAX_NUM_SUPPORTED_PREFIX | 10 |
MAX_NUM_ARQ_DEST_INFO | 20 |
MAX_NUM_ARQ_REDIRECT_REASON | 7 |
MAX_NUM_LRQ_DEST_INFO | 20 |
MAX_NUM_LRQ_REDIRECT_REASON | 7 |
MAX_NUM_LCF_DEST_INFO | 20 |
MAX_NUM_LCF_RMOT_EXTENSION_ADDR | 20 |
MAX_NUM_LRJ_DEST_INFO | 20 |
MAX_CRYPTO_TOKEN_FIELDS | 5 |
Posted: Fri Sep 27 04:42:08 PDT 2002
All contents are Copyright © 1992--2002 Cisco Systems, Inc. All rights reserved.
Important Notices and Privacy Statement.