Table of Contents

Message Line
Message Header
Message Body
Registration Messages

Request RRQ
Response RRQ
Response RCF
Response RRJ

Unregistration Message

Request URQ
Command URQ
Result URQ

Admission Messages

Request ARQ
Response ARQ
Response ACF
Response ARJ

Location Messages

Request LRQ
Response LRQ
Request LCF
Response LCF
Request LRJ
Response LRJ

Disengage Messages

Request DRQ

Resource Messages

Request RAI

Bandwidth Messages

Request BRQ
Response BRQ
Response BCF
Response BRJ

Progress Messages

Response RIP
Request IRR
Request ALV
Response ALV

Message Line
Message Header
Message Body
Register RRQ and RAI
Register URQ
Register ARQ, DRQ, IRR, and BRQ
Register LRQ
Register LCF
Register LRJ

GTD
AlternateGK
FromReplyAddress
ServiceControlSession
CallCapacity
CarrierInfo
TrunkGroupInfo
Alias-Address
PerCallInfo
RemoteZone
Transport-Address
ClearToken
CryptoToken

GKTMP Messages

This chapter describes GKTMP messages and contains the following sections:

The GKTMP messages are used for communication between the Cisco IOS Gatekeeper and the external application. There are two types of GKTMP messages:

GKTMP RAS Messages

The general format of all GKTMP RAS messages is as follows:

Message Line

Each GKTMP RAS message is either a request or a response. Requests are generated by the Cisco IOS Gatekeeper and responses are generated by the external application.

The first line of each GKTMP RAS message sent by the Cisco IOS Gatekeeper uses the format:

The first line of each GKTMP RAS message sent by the external application uses the format:

Possible RAS message types are as follows:

Message Header

The message line is immediately followed by the message header. Each message header contains a field name and a value, separated by a colon (field:value). Table 4-1 shows the possible fields:

The message header is followed immediately by a blank line.

Message Body

The message body follows the blank line. Each line in the message body contains a tag and a value, separated by an equal sign (tag=value). The tags are case-sensitive and denote an RAS message field. The possible tags depend on the GKTMP RAS message.

Note   If the message body is null, the message must terminate with a CRFL after the message header.

In some cases, depending on the field type, the value is preceded a value-type identifier followed by a colon (tag=type:value).

Possible field types are as follows:

This section describes the possible fields for each message. When the external application sends a response, it includes only the fields that it has altered. Unaltered fields must not be included.

Registration Messages

Registration messages are used to control which H.323 endpoints are in the gatekeeper's zone.

This section describes the following:

Request RRQ

This message is sent from the Cisco IOS Gatekeeper to the external application when an H.323 endpoint wants to join the zone. This message can be used to populate the external application's registration database. In this case, the request is sent as a notification only and no response is expected from the external application.

Table 4-2 shows the possible Request RRQ tags:

Response RRQ

This message is sent from the external application to the Cisco IOS Gatekeeper in response to a Request RRQ message. If the external application has no interest in the Request RRQ message, it returns a Response RRQ with a null body. Otherwise, the external application modifies the fields as appropriate and sends the response with the updated information to the Cisco IOS Gatekeeper for further processing.

For Response RRQ, the possible tags are shown in Table 4-3:

Response RCF

This message is sent from the external application to the Cisco IOS Gatekeeper in response to a Request RRQ. This message indicates that the external application has completed the processing of the request.

For Response RCF, the possible tags are shown in Table 4-4:

Response RRJ

This message is sent from the external application to the Cisco IOS Gatekeeper in response to a Request RRQ. It indicates that the Cisco IOS Gatekeeper should reject the request for the specified reason.

For Response RRJ, the possible tag is shown in Table 4-5:

Possible values for the rejectReason are:

Unregistration Message

Unregistration messages are used to remove an H.323 endpoint from a gatekeeper zone.

This section describes the following:

Request URQ

This message is sent from the Cisco IOS Gatekeeper to the external application when the H.323 endpoint wants to leave the zone or when its registration expires. This request is sent as a notification only. No response is generated by the external application.

For Request URQ, the possible tag is shown in Table 4-6:

Command URQ

The Command URQ message is sent from the application server to the gatekeeper at any time to unregister an endpoint. The gatekeeper sends a URQ message to the endpoint and removes it from its registration database. The endpoint is identified by its call signaling address (IP address and port). The server can also specify an optional reason and alternate gatekeeper information.

Table 4-7 shows the new Command URQ tags:

Possible values for the reason are:

Result URQ

The Result URQ message is sent from the gatekeeper to the application server to report the result of a Command URQ transaction as long as the command did not specify Notification-Only: in the message header. The endpoint is identified by its call signaling address (IP address and port).

If the endpoint was found and unregistered, the message header indicates Status: success. Otherwise it indicates Status: invalidGKID or Status: invalidEndpoint.

Note   Success just means that a URQ message was sent to the endpoint and that it was removed from the gatekeeper registration database without error. It does not mean that a UCF message was received from the endpoint. The gatekeeper does not wait to receive a UCF message before sending the Result URQ message to the server.

Table 4-8 shows the new Result URQ tags:

Admission Messages

Admission messages are used to control which H.323 endpoints can participate in calls.

This section describes the following:

Request ARQ

This message is sent from the Cisco IOS Gatekeeper to the external application when an H.323 endpoint wants to initiate a call.

For Request ARQ, the possible tags are shown in Table 4-9:

Possible values for the redirectReason are:

CallingPartyNumOctet3a is from the Q.931 Setup octet 3a of calling party number.

When an H.323 endpoint sends an ARQ to the Cisco IOS Gatekeeper, it includes its endpointIdentifier. Because this value is local and has meaning to the Cisco IOS Gatekeeper only and not to the external application, the Cisco IOS Gatekeeper substitutes a more meaningful value of CallSignalAddress in its Request ARQ messages.

Response ARQ

This message is sent from the external application to the Cisco IOS Gatekeeper in response to a Request ARQ message. If the external application has no interest in the Request ARQ message, it returns a Response ARQ with a null body. Otherwise, it modifies the fields as appropriate and sends the response with the updated information to the Cisco IOS Gatekeeper for further processing.

For Response ARQ, the possible tags are shown in Table 4-10:

The external application has the option of reducing the bandwidth.

If this field is included, the Cisco IOS Gatekeeper sends LRQs to all the listed zones. The zone with the least cost and highest priority that returns and LCF is chosen for inclusion in the ACF that is sent to the endpoint.

If the message contains an alternateEndpoint field, the additional fields shown in Table 4-11 are included:

Response ACF

This message is sent from the external application to the Cisco IOS Gatekeeper in response to a Request ARQ. The message indicates that the external application has completed the processing of the request.

For Response ACF, the possible tags are shown in Table 4-12:

If the message contains an AlternateEndpoint field, the additional fields shown in Table 4-13 are included:

If the message contains an AlternateTransportAddr field, the additional field shown in Table 4-14 is included:

Response ARJ

This message is sent from the external application to the Cisco IOS Gatekeeper in response to a Request ARQ. The message indicates that the Cisco IOS Gatekeeper should reject the request for the specified reason.

For Response ARJ, the possible tag is shown in Table 4-15:

Possible values for rejectReason are:

Location Messages

Location messages are used by gatekeepers to communicate with each other to process interzone calls.

This section describes the following:

Request LRQ

This message is sent from the Cisco IOS Gatekeeper to the external application when the Cisco IOS Gatekeeper has received an interzone location request.

For Request LRQ, the possible tags are shown in Table 4-16:

Possible values for the redirectReason are:

CallingPartyNumOctet3a is from the Q.931 Setup octet 3a of calling party number.

Response LRQ

This message is sent from the external application to the Cisco IOS Gatekeeper in response to a Request LRQ message. If the external application has no interest in the Request LRQ message, it returns a Response LRQ with a null body. Otherwise, it modifies the fields as appropriate and sends the response with the updated information to the Cisco IOS Gatekeeper for further processing.

For Response LRQ, the possible tags are shown in Table 4-17:

If the message contains an alternateEndpoint field, the additional fields shown in Table 4-18 are included:

Request LCF

This message is sent from the Cisco IOS Gatekeeper to the external application when the Cisco IOS Gatekeeper has received an LCF from the remote Cisco IOS Gatekeeper. This gives the external application an opportunity to accept (Response LCF), modify (Response LCF), or reject (Response LRJ) the information contained in the LCF.

For Request LCF, the possible tags are shown in Table 4-19:

The destinationInfo from the LCF is used if one is available. Otherwise, the destinationInfo from the LRQ is used.

If the message contains an AlternateTransportAddr field, the following additional field shown in Table 4-20 is included:

Response LCF

This message is sent from the external application to the Cisco IOS Gatekeeper in response to a Request LRQ. The message indicates that the external application has completed the processing of the request.

This message can also be sent to the Cisco IOS Gatekeeper from the external application in response to a Request LCF or a Request LRJ. In the case of a Request LCF, the response can contain:

In the case of a Request LRJ, the response contains an alternate destination.

For Response LCF, the possible tags are shown in Table 4-21:

Note   The D and r are not required if the Response LCF is being sent in reply to a Request LCF.

If the message contains an AlternateTransportAddr field, the additional field shown in Table 4-22 included:

Request LRJ

This message is sent from the Cisco IOS Gatekeeper to the external application when the Cisco IOS Gatekeeper has received an LRJ from a remote Cisco IOS Gatekeeper. This gives the Cisco IOS Gatekeeper the opportunity to accept the rejection (Response LRJ) or propose an alternative destination (Response LCF).

For Request LRJ, the possible tags are shown in Table 4-23:

Response LRJ

This message is sent from the external application to the Cisco IOS Gatekeeper in response to a Request LRQ. The message indicates that the Cisco IOS Gatekeeper should reject the request for the specified reason.

This message can also be sent to the Cisco IOS Gatekeeper from the external application in response to a Request LCF or a Request LRJ. In the case of a Request LCF, this response rejects the information provided in the LCF for the specified reason. In the case of a Request LRJ, this response acknowledges the rejection. The reason is optional when the Response LRJ is sent due to a Request LRJ.

For Response LRJ, the possible tag is shown in Table 4-24:

Possible values for rejectReason are:

Disengage Messages

Disengage messages are used to indicate that a party wants to end the call.

Request DRQ

This message is sent from the Cisco IOS Gatekeeper to the external application to indicate that an endpoint wants to end the call.

For Request DRQ, the possible tags are shown in Table 4-25:

Possible values for the DRQ-reason are:

Resource Messages

Resource messages are used to indicate the current call capacity of the gateway.

Request RAI

This message is sent from the Cisco IOS Gatekeeper to the external application to indicate the call capacity and data rate of the gateway for H.323 calls.

For Request RAI, the possible tags are shown in Table 4-26:

Note   All Request RAI messages must contain Notification-only in the header. No response to this message is sent.

Bandwidth Messages

Bandwidth messages are used to request a change in bandwidth.

This section describes the following:

Request BRQ

This message is sent from the Cisco IOS Gatekeeper to the external application to request that an endpoint be allowed to change (increase or decrease) its bandwidth.

For Request BRQ, the possible tags are shown in Table 4-27:

Note   When sending a BRQ message, an endpoint identifies itself to the gatekeeper using the endpointIdentifier that it received from the gatekeeper in the RCF. Because this endpointIdentifier has only local significance to the gatekeeper and no significance to the server, the endpoint's CallSignalAddress is used here as an identifier.

Response BRQ

The server may modify the fields shown in Table 4-28 in the BRQ.

Response BCF

This message is sent from the external application to the Cisco IOS Gatekeeper to confirm the request to allow an endpoint to change (increase or decrease) its bandwidth. This response gives the external application the opportunity to modify the Bandwidth field of a received LCF, but because the Cisco IOS Gatekeeper is not prepared to make changes in its bandwidth, any change in the BCF will automatically generate a BRJ back to the endpoint.

For Response BCF, the possible tag is shown in Table 4-29:

Response BRJ

This message is sent from the external application the Cisco IOS Gatekeeper to deny the request to allow an endpoint to change (increase or decrease) its bandwidth.

For Response BRJ, the possible tag is shown in Table 4-30:

Possible values for rejectReason are:

Progress Messages

Progress messages provide information about the progress of a request. Progress messages include:

Response RIP

This message is sent from the external application to the Cisco IOS Gatekeeper when the external application cannot immediately process the request. This message indicates that the request is in progress (RIP) and that additional time is needed. When the Cisco IOS Gatekeeper receives this message, it forwards a request to the H.323 endpoint indicating that an extension of the timeout is required. The external application can send more that one Response RIP as is needed to process the request.

For Response RIP, the possible tag is shown in Table 4-31:

Possible values of the delay are 1 through 65535 milliseconds.

Request IRR

This message is sent to the GK and contains details for the call after a successful connect. A Request IRR message is sent at both the originating and terminating side of the call. If both legs reference the same GK, only one Request IRR is sent. The GK sends information for only one call in each Request IRR message.

Table 4-32 shows the new Request IRR tags:

Request ALV

The REQUEST ALV is sent from the Gatekeeper to a GKTMP server on the detection of slower response or server failure.

This message does not contain any parameters in its body.

Response ALV

This message is returned in response to a REQUEST ALV message and does not contain any parameters in its body.

Trigger Registration Messages

Trigger registration messages are used by external applications to inform the Cisco IOS Gatekeeper which RAS messages are interesting to the external application. Interesting RAS messages trip a trigger in the Cisco IOS Gatekeeper and cause the Cisco IOS Gatekeeper to send a GKTMP RAS message to the external application.

As with the GKTMP RAS messages, trigger registration messages have the following format:

Message Line

There are two types of trigger registration messages: register and unregister.

The first line of each trigger registration request/response message uses the format:

The first line of each trigger unregistration request/response message uses the format:

Possible RAS message types are as follows:

Message Header

The message line is immediately followed by the message header. Each message header contains a field name and a value, separated by a colon (field:value). Possible fields are shown in Table 4-33:

The message header is followed immediately by a blank line.

Message Body

The message body follows the blank line. Only trigger registration requests contain a message body. Trigger registration responses, unregistration requests, and unregistration responses end after the blank line.

The message body in a trigger registration request can be used to narrow the circumstances under which the Cisco IOS Gatekeeper sends a REQUEST xxx to the external application. In this case, the external application includes tags and values in the message body that if matched will trigger the Cisco IOS Gatekeeper to generate a REQUEST xxx.

The tags that can be included vary depending on the RAS message type, and are a subset of the types that can be included in GKTMP RAS messages.

For the field type of Alias-Address, trailing wildcards can be used with E.164 addresses. An asterisk can be used to indicate a string of characters (for example, 1800*). A period can be used to indicate a single character (for example, 1800.......).

Note   Wildcards cannot be used at the beginning or in the midst of a value, only at the end. If you include a wildcard at the beginning or in the midst of a value, it will be interpreted as a literal character.

Register RRQ and RAI

For Register RRQ and RAI, the tags shown in Table 4-34 can be used to filter messages:

Register URQ

For Register URQ, the tags shown in Table 4-35 can be used to filter messages:

Register ARQ, DRQ, IRR, and BRQ

For Register ARQ, DRQ, IRR, and BRQ the tags shown in Table 4-36 can be used to filter messages:

Register LRQ

For Register LRQ, the tags shown in Table 4-37 can be used to filter messages:

Note   A gatekeeper might not be the final destination of the LRQ messages that it receives. If the queried address in an LRQ is in another Gatekeeper's zone, the LRQ is forwarded to that gatekeeper and is not resolved locally. This means that there might not be a local zone that can be associated with the LRQ. To address this situation, the gatekeeper arbitrarily uses the server registrations for the first configured local zone. Because the order in which configured zones appear can change with deletions and additions, servers should send identical LRQ registrations to all zones (all logical gatekeepers) on the same router.

Register LCF

For Register LCF, the tags shown in Table 4-38 can be used to filter messages:

Register LRJ

For Register LRJ, the tag shown in Table 4-39 can be used to filter messages:

Additional Messages

GTD

The Generic Transparency Descriptor (GTD) field type is a structure comprising of two sub-fields: length and data. This field type is required for values that contain <cr><lf> pairs in its body. The length (B) sub-field indicates the size of the data sub-field and indicates to the parser that any occurrence of <cr><lf> within the data sub-field is not a <tag>=<value> delimiter.

Table 4-40 shows the new GTD tags:

Usage Notes

The GTD field type is different from other GKTMP fields in that <cr><lf> does not indicate the end of the GTD line. The following rules must be followed in processing the GTD field type:

Format

Example

AlternateGK

A message body line containing a field of type AlternateGK contains a set of fields enclosed within curly braces "{ }". Each of the fields within the curly braces are identified by a tag, with each field separated by SP (ascii space, 0x20) characters.

Table 4-41 shows the AlternateGK tags:

FromReplyAddress

The from IP address is the address from which an LRQ message was received. The reply-to address is the mandatory IP address specified in the RAS LRQ message replyAddress field. A GKTMP application can use these fields to authenticate the source of LRQ message.

Table 4-42 shows the FromReplyAddress tags:

ServiceControlSession

Table 4-43 shows the new Service Control Session tags:

CallCapacity

The CallCapacity message indicates the ability of the gateway to accept each type of call the gateway supports, such as voice calls.

Table 4-44 shows the CallCapacity tags:

CarrierInfo

The gatekeeper sends incoming carrier information received in a RAS ARQ message from the gateway to an external GKTMP application. This information allows the application to select an outbound carrier and remote zones that the carrier may exist in. The gatekeeper uses this outbound carrier and zone information to query for the egress gateway.

Table 4-45 shows the new Carrier Information tags:

TrunkGroupInfo

Table 4-46 shows the new Trunk Group Information tags:

Alias-Address

A field of type Alias-Address contains a sequence of aliases separated by SP (ascii space, 0x20) characters. Each alias is prefixed by one of the following type characters, followed by a colon:

For example, in an RRQ message, a terminal alias containing the sequence of an H.323-ID of "John Smith", an E164 address of 4085551212, and an email-id of "jsmith@somewhere.com" is indicated by the line: a=H:"John Smith" E:4085551212 M:jsmith@somewhere.com

PerCallInfo

If the message contains a PerCallInfo field, the following fields shown in Table 4-47 are included:

RemoteZone

Table 4-48 shows the remoteZone field tags:

Transport-Address

The only type of transport address currently supported by the gatekeeper is IP version 4. However, a type prefix is defined for future extensibility. For example, I: IP version 4 address.

The address is specified in the usual dotted string form, followed by a colon and port number. For example, the callSignalAddress in an RRQ message may be specified as: c=I:172.21.137.4:1720.

ClearToken

If the message contains a clearToken field, the fields shown in Table 4-49 are included:

CryptoToken

If the message contains a cryptoToken field, the additional fields shown in Table 4-50 are included:

Posted: Mon Mar 17 00:19:22 PST 2003
All contents are Copyright © 1992--2002 Cisco Systems, Inc. All rights reserved.
Important Notices and Privacy Statement.