RFC 3435
Media Gateway Control Protocol (MGCP) Version 1.0
2.3.11 AuditConnection
The AuditConnection command can be used by the Call Agent to retrieve the parameters attached to a connection. ReturnCode, [CallId,] [NotifiedEntity,] [LocalConnectionOptions,] [Mode,] [RemoteConnectionDescriptor,] [LocalConnectionDescriptor,] [ConnectionParameters,] [PackageList] <-- AuditConnection(EndpointId, ConnectionId, RequestedInfo) The EndpointId parameter specifies the endpoint that handles the connection. The wildcard conventions SHALL NOT be used. The ConnectionId parameter is the identifier of the audited connection, within the context of the specified endpoint. The (possibly empty) RequestedInfo describes the information that is requested for the ConnectionId within the EndpointId specified. The following connection info can be audited with this command: CallId, NotifiedEntity, LocalConnectionOptions, Mode, RemoteConnectionDescriptor, LocalConnectionDescriptor, ConnectionParameters The AuditConnection response will in turn include information about each of the items auditing info was requested for: * CallId, the CallId for the call the connection belongs to. * NotifiedEntity, the current "notified entity" for the Connection. Note this is the same as the "notified entity" for the endpoint (included here for backwards compatibility).
* LocalConnectionOptions, the most recent LocalConnectionOptions
parameters that was actually supplied for the connection (omitting
LocalConnectionOptions from a command thus does not change this
value). Note that default parameters omitted from the most recent
LocalConnectionOptions will not be included.
LocalConnectionOptions that retain their value across
ModifyConnection commands and which have been included in a
previous command for the connection are also included, regardless
of whether they were supplied in the most recent
LocalConnectionOptions or not.
* Mode, the current mode of the connection.
* RemoteConnectionDescriptor, the RemoteConnectionDescriptor that was
supplied to the gateway for the connection.
* LocalConnectionDescriptor, the LocalConnectionDescriptor the
gateway supplied for the connection.
* ConnectionParameters, the current values of the connection
parameters for the connection.
If no info was requested and the EndpointId is valid, the gateway
simply checks that the connection exists, and if so returns a
positive acknowledgement. Note, that by definition, the endpoint
must be in-service for this to happen, as out-of-service endpoints do
not have any connections.
ReturnCode is a parameter returned by the gateway. It indicates the
outcome of the command and consists of an integer number optionally
followed by commentary.
PackageList is a list of supported packages that MAY be included with
error code 518 (unsupported package).
2.3.12 RestartInProgress
The RestartInProgress command is used by the gateway to signal that
an endpoint, or a group of endpoints, is put in-service or out-of-
service.
ReturnCode,
[NotifiedEntity,]
[PackageList]
<-- RestartInProgress(EndPointId,
RestartMethod,
[RestartDelay,]
[ReasonCode])
The EndPointId identifies the endpoint(s) that are put in-service or
out-of-service. The "all of" wildcard convention may be used to
apply the command to a group of endpoints managed by the same Call
Agent, such as for example all endpoints that are attached to a
specified interface, or even all endpoints that are attached to a
given gateway. The "any of" wildcard convention SHALL NOT be used.
The RestartMethod parameter specifies the type of restart. The
following values have been defined:
* A "graceful" restart method indicates that the specified endpoints
will be taken out-of-service after the specified delay. The
established connections are not yet affected, but the Call Agent
SHOULD refrain from establishing new connections, and SHOULD try to
gracefully tear down the existing connections.
* A "forced" restart method indicates that the specified endpoints
are taken abruptly out-of-service. The established connections, if
any, are lost.
* A "restart" method indicates that service will be restored on the
endpoints after the specified "restart delay", i.e., the endpoints
will be in-service. The endpoints are in their clean default state
and there are no connections that are currently established on the
endpoints.
* A "disconnected" method indicates that the endpoint has become
disconnected and is now trying to establish connectivity (see
Section 4.4.7). The "restart delay" specifies the number of
seconds the endpoint has been disconnected. Established
connections are not affected.
* A "cancel-graceful" method indicates that a gateway is canceling a
previously issued "graceful" restart command. The endpoints are
still in-service.
The list of restart methods may be extended.
The optional "restart delay" parameter is expressed as a number of
seconds. If the number is absent, the delay value MUST be considered
null (i.e., zero). In the case of the "graceful" method, a null
delay indicates that the Call Agent SHOULD simply wait for the
natural termination of the existing connections, without establishing
new connections. The restart delay is always considered null in the
case of the "forced" and "cancel-graceful" methods, and hence the
"restart delay" parameter MUST NOT be used with these restart
methods. When the gateway sends a "restart" or "graceful"
RestartInProgress message with a non-zero restart delay, the gateway SHOULD send an updated RestartInProgress message after the "restart delay" has passed. A restart delay of null for the "restart" method indicates that service has already been restored. This typically will occur after gateway startup/reboot. To mitigate the effects of a gateway IP address change as a result of a re-boot, the Call Agent MAY wish to either flush its DNS cache for the gateway's domain name or resolve the gateway's domain name by querying the DNS regardless of the TTL of a current DNS resource record for the restarted gateway. The optional reason code parameter indicates the cause of the restart. Gateways SHOULD send a "graceful" or "forced" RestartInProgress message (for the relevant endpoints) as a courtesy to the Call Agent when they are taken out-of-service, e.g., by being shutdown, or taken out-of-service by a network management system, however the Call Agent cannot rely on always receiving such a message. Gateways MUST send a "restart" RestartInProgress message (for the relevant endpoints) with a null delay to their Call Agent when they are back in-service according to the restart procedure specified in Section 4.4.6 - Call Agents can rely on receiving this message. Also, gateways MUST send a "disconnected" RestartInProgress message (for the relevant endpoints) to their current "notified entity" according to the "disconnected" procedure specified in Section 4.4.7. The RestartInProgress message will be sent to the current "notified entity" for the EndpointId in question. It is expected that a default Call Agent, i.e., "notified entity", has been provisioned so that after a reboot/restart, the default Call Agent will always be the "notified entity" for the endpoint. Gateways SHOULD take full advantage of wild-carding to minimize the number of RestartInProgress messages generated when multiple endpoints in a gateway restart and the endpoints are managed by the same Call Agent. ReturnCode is a parameter returned by the Call Agent. It indicates the outcome of the command and consists of an integer number optionally followed by commentary. A NotifiedEntity may additionally be returned with the response to the RestartInProgress from the Call Agent - this SHOULD normally only be done in response to "restart" or "disconnected" (see also Section 4.4.6 and 4.4.7):
* If the response indicated success (return code 200 - transaction
executed), the restart in question completed successfully, and the
NotifiedEntity returned is the new "notified entity" for the
endpoint(s).
* If the response from the Call Agent indicated an error, the restart
in question did not complete successfully. If a NotifiedEntity
parameter was included in the response returned, it specifies a new
"notified entity" for the endpoint(s), which MUST be used when
retrying the restart in question (as a new transaction). This
SHOULD only be done with error code 521 (endpoint redirected).
Note that the above behavior for returning a NotifiedEntity in the
response is only defined for RestartInProgress responses and SHOULD
NOT be done for responses to other commands. Any other behavior is
undefined.
PackageList is a list of supported packages that MAY be included with
error code 518 (unsupported package).
2.4 Return Codes and Error Codes
All MGCP commands are acknowledged. The acknowledgment carries a
return code, which indicates the status of the command. The return
code is an integer number, for which the following ranges of values
have been defined:
* values between 000 and 099 indicate a response acknowledgement
* values between 100 and 199 indicate a provisional response
* values between 200 and 299 indicate a successful completion
* values between 400 and 499 indicate a transient error
* values between 500 and 599 indicate a permanent error
* values between 800 and 899 are package specific response codes.
A broad description of transient errors (4XX error codes) versus
permanent errors (5XX error codes) is as follows:
* If a Call Agent receives a transient error, there is the
expectation of the possibility that a future similar request will
be honored by the endpoint. In some cases, this may require some
state change in the environment of the endpoint (e.g., hook state
as in the case of error codes 401 or 402; resource availability as
in the case of error code 403, or bandwidth availability as in the
case of error code 404).
* Permanent errors (error codes 500 to 599) indicate one or more
permanent conditions either due to protocol error or
incompatibility between the endpoint and the Call Agent, or because
of some error condition over which the Call Agent has no control.
Examples are protocol errors, requests for endpoint capabilities
that do not exist, errors on interfaces associated with the
endpoint, missing or incorrect information in the request or any
number of other conditions which will simply not disappear with
time.
The values that have been already defined are the following:
000 Response Acknowledgement.
100 The transaction is currently being executed. An actual
completion message will follow later.
101 The transaction has been queued for execution. An actual
completion message will follow later.
200 The requested transaction was executed normally. This return
code can be used for a successful response to any command.
250 The connection was deleted. This return code can only be used
for a successful response to a DeleteConnection command.
400 The transaction could not be executed, due to some unspecified
transient error.
401 The phone is already off hook.
402 The phone is already on hook.
403 The transaction could not be executed, because the endpoint does
not have sufficient resources at this time.
404 Insufficient bandwidth at this time.
405 The transaction could not be executed, because the endpoint is
"restarting".
406 Transaction time-out. The transaction did not complete in a
reasonable period of time and has been aborted.
407 Transaction aborted. The transaction was aborted by some
external action, e.g., a ModifyConnection command aborted by a
DeleteConnection command.
409 The transaction could not be executed because of internal
overload.
410 No endpoint available. A valid "any of" wildcard was used,
however there was no endpoint available to satisfy the request.
500 The transaction could not be executed, because the endpoint is
unknown.
501 The transaction could not be executed, because the endpoint is
not ready. This includes the case where the endpoint is out-of-
service.
502 The transaction could not be executed, because the endpoint does
not have sufficient resources (permanent condition).
503 "All of" wildcard too complicated.
504 Unknown or unsupported command.
505 Unsupported RemoteConnectionDescriptor. This SHOULD be used when
one or more mandatory parameters or values in the
RemoteConnectionDescriptor is not supported.
506 Unable to satisfy both LocalConnectionOptions and
RemoteConnectionDescriptor. This SHOULD be used when the
LocalConnectionOptions and RemoteConnectionDescriptor contain one
or more mandatory parameters or values that conflict with each
other and/or cannot be supported at the same time (except for
codec negotiation failure - see error code 534).
507 Unsupported functionality. Some unspecified functionality
required to carry out the command is not supported. Note that
several other error codes have been defined for specific areas of
unsupported functionality (e.g. 508, 511, etc.), and this error
code SHOULD only be used if there is no other more specific error
code for the unsupported functionality.
508 Unknown or unsupported quarantine handling.
509 Error in RemoteConnectionDescriptor. This SHOULD be used when
there is a syntax or semantic error in the
RemoteConnectionDescriptor.
510 The transaction could not be executed, because some unspecified
protocol error was detected. Automatic recovery from such an
error will be very difficult, and hence this code SHOULD only be
used as a last resort.
511 The transaction could not be executed, because the command
contained an unrecognized extension. This code SHOULD be used
for unsupported critical parameter extensions ("X+").
512 The transaction could not be executed, because the gateway is not
equipped to detect one of the requested events.
513 The transaction could not be executed, because the gateway is not
equipped to generate one of the requested signals.
514 The transaction could not be executed, because the gateway cannot
send the specified announcement.
515 The transaction refers to an incorrect connection-id (may have
been already deleted).
516 The transaction refers to an unknown call-id, or the call-id
supplied is incorrect (e.g., connection-id not associated with
this call-id).
517 Unsupported or invalid mode.
518 Unsupported or unknown package. It is RECOMMENDED to include a
PackageList parameter with the list of supported packages in the
response, especially if the response is generated by the Call
Agent.
519 Endpoint does not have a digit map.
520 The transaction could not be executed, because the endpoint is
"restarting". In most cases this would be a transient error, in
which case, error code 405 SHOULD be used instead. The error
code is only included here for backwards compatibility.
521 Endpoint redirected to another Call Agent. The associated
redirection behavior is only well-defined when this response is
issued for a RestartInProgress command.
522 No such event or signal. The request referred to an event or
signal that is not defined in the relevant package (which could
be the default package).
523 Unknown action or illegal combination of actions.
524 Internal inconsistency in LocalConnectionOptions.
525 Unknown extension in LocalConnectionOptions. This code SHOULD be
used for unsupported mandatory vendor extensions ("x+").
526 Insufficient bandwidth. In cases where this is a transient
error, error code 404 SHOULD be used instead.
527 Missing RemoteConnectionDescriptor.
528 Incompatible protocol version.
529 Internal hardware failure.
530 CAS signaling protocol error.
531 Failure of a grouping of trunks (e.g., facility failure).
532 Unsupported value(s) in LocalConnectionOptions.
533 Response too large.
534 Codec negotiation failure.
535 Packetization period not supported.
536 Unknown or unsupported RestartMethod.
537 Unknown or unsupported digit map extension.
538 Event/signal parameter error (e.g., missing, erroneous,
unsupported, unknown, etc.).
539 Invalid or unsupported command parameter. This code SHOULD only
be used when the parameter is neither a package or vendor
extension parameter.
540 Per endpoint connection limit exceeded.
541 Invalid or unsupported LocalConnectionOptions. This code SHOULD
only be used when the LocalConnectionOptions is neither a package
nor a vendor extension LocalConnectionOptions.
The set of return codes may be extended in a future version of the protocol. Implementations that receive an unknown or unsupported return code SHOULD treat the return code as follows: * Unknown 0xx code treated as 000. * Unknown 1xx code treated as 100. * Unknown 2xx code treated as 200. * Unknown 3xx code treated as 521. * Unknown 4xx code treated as 400. * Unknown 5xx-9xx code treated as 510.2.5 Reason Codes
Reason codes are used by the gateway when deleting a connection to inform the Call Agent about the reason for deleting the connection. They may also be used in a RestartInProgress command to inform the Call Agent of the reason for the RestartInProgress. The reason code is an integer number, and the following values have been defined: 000 Endpoint state is normal (this code is only used in response to audit requests). 900 Endpoint malfunctioning. 901 Endpoint taken out-of-service. 902 Loss of lower layer connectivity (e.g., downstream sync). 903 QoS resource reservation was lost. 904 Manual intervention. 905 Facility failure (e.g., DS-0 failure). The set of reason codes can be extended.
2.6 Use of Local Connection Options and Connection Descriptors
As indicated previously, the normal sequence in setting up a bi- directional connection involves at least 3 steps: 1) The Call Agent asks the first gateway to "create a connection" on an endpoint. The gateway allocates resources to that connection, and responds to the command by providing a "session description" (referred to as its LocalConnectionDescriptor). The session description contains the information necessary for another party to send packets towards the newly created connection. 2) The Call Agent then asks the second gateway to "create a connection" on an endpoint. The command carries the "session description" provided by the first gateway (now referred to as the RemoteConnectionDescriptor). The gateway allocates resources to that connection, and responds to the command by providing its own "session description" (LocalConnectionDescriptor). 3) The Call Agent uses a "modify connection" command to provide this second "session description" (now referred to as the RemoteConnectionDescriptor ) to the first endpoint. Once this is done, communication can proceed in both directions. When the Call Agent issues a Create or Modify Connection command, there are thus three parameters that determine the media supported by that connection: * LocalConnectionOptions: Supplied by the Call Agent to control the media parameters used by the gateway for the connection. When supplied, the gateway MUST conform to these media parameters until either the connection is deleted, or a ModifyConnection command with new media parameters (LocalConnectionOptions or RemoteConnectionDescriptor) is received. * RemoteConnectionDescriptor: Supplied by the Call Agent to convey the media parameters supported by the other side of the connection. When supplied, the gateway MUST conform to these media parameters until either the connection is deleted, or a ModifyConnection command with new media parameters (LocalConnectionOptions or RemoteConnectionDescriptor) is received. * LocalConnectionDescriptor: Supplied by the gateway to the Call Agent to convey the media parameters it supports for the connection. When supplied, the gateway MUST honor the media parameters until either the connection is deleted, or the gateway issues a new LocalConnectionDescriptor for that connection.
In determining which codec(s) to provide in the
LocalConnectionDescriptor, there are three lists of codecs that a
gateway needs to consider:
* A list of codecs allowed by the LocalConnectionOptions in the
current command (either explicitly by encoding method or implicitly
by bandwidth and/or packetization period).
* A list of codecs in the RemoteConnectionDescriptor in the current
command.
* An internal list of codecs that the gateway can support for the
connection. A gateway MAY support one or more codecs for a given
connection.
Codec selection (including all relevant media parameters) can then be
described by the following steps:
1. An approved list of codecs is formed by taking the intersection of
the internal list of codecs and codecs allowed by the
LocalConnectionOptions. If LocalConnectionOptions were not
provided in the current command, the approved list of codecs thus
contains the internal list of codecs.
2. If the approved list of codecs is empty, a codec negotiation
failure has occurred and an error response is generated (error
code 534 - codec negotiation failure, is RECOMMENDED).
3. Otherwise, a negotiated list of codecs is formed by taking the
intersection of the approved list of codecs and codecs allowed by
the RemoteConnectionDescriptor. If a RemoteConnectionDescriptor
was not provided in the current command, the negotiated list of
codecs thus contains the approved list of codecs.
4. If the negotiated list of codecs is empty, a codec negotiation
failure has occurred and an error response is generated (error
code 534 - codec negotiation failure, is RECOMMENDED).
5. Otherwise, codec negotiation has succeeded, and the negotiated
list of codecs is returned in the LocalConnectionDescriptor.
Note that both LocalConnectionOptions and the
RemoteConnectionDescriptor can contain a list of codecs ordered by
preference. When both are supplied in the current command, the
gateway MUST adhere to the preferences provided in the
LocalConnectionOptions.
2.7 Resource Reservations
The gateways can be instructed to perform a reservation, for example using RSVP, on a given connection. When a reservation is needed, the call agent will specify the reservation profile to be used, which is either "controlled load" or "guaranteed service". The absence of reservation can be indicated by asking for the "best effort" service, which is the default value of this parameter in a CreateConnection command. For a ModifyConnection command, the default is simply to retain the current value. When reservation has been asked on a connection, the gateway will: * start emitting RSVP "PATH" messages if the connection is in "send- only", "send-receive", "conference", "network loop back" or "network continuity test" mode (if a suitable remote connection descriptor has been received,). * start emitting RSVP "RESV" messages as soon as it receives "PATH" messages if the connection is in "receive-only", "send-receive", "conference", "network loop back" or "network continuity test" mode. The RSVP filters will be deduced from the characteristics of the connection. The RSVP resource profiles will be deduced from the connection's codecs, bandwidth and packetization period.3. Media Gateway Control Protocol
The Media Gateway Control Protocol (MGCP) implements the media gateway control interface as a set of transactions. The transactions are composed of a command and a mandatory response. There are nine commands: * EndpointConfiguration * CreateConnection * ModifyConnection * DeleteConnection * NotificationRequest * Notify * AuditEndpoint * AuditConnection
* RestartInProgress The first five commands are sent by the Call Agent to a gateway. The Notify command is sent by the gateway to the Call Agent. The gateway may also send a DeleteConnection as defined in Section 2.3.8. The Call Agent may send either of the Audit commands to the gateway, and the gateway may send a RestartInProgress command to the Call Agent.3.1 General Description
All commands are composed of a Command header, optionally followed by a session description. All responses are composed of a Response header, optionally followed by session description information. Headers and session descriptions are encoded as a set of text lines, separated by a carriage return and line feed character (or, optionally, a single line-feed character). The session descriptions are preceded by an empty line. MGCP uses a transaction identifier to correlate commands and responses. The transaction identifier is encoded as a component of the command header and repeated as a component of the response header (see sections 3.2.1.2 and 3.3). Note that an ABNF grammar for MGCP is provided in Appendix A. Commands and responses SHALL be encoded in accordance with the grammar, which, per RFC 2234, is case-insensitive except for the SDP part. Similarly, implementations SHALL be capable of decoding commands and responses that follow the grammar. Additionally, it is RECOMMENDED that implementations tolerate additional linear white space. Some productions allow for use of quoted strings, which can be necessary to avoid syntax problems. Where the quoted string form is used, the contents will be UTF-8 encoded [20], and the actual value provided is the unquoted string (UTF-8 encoded). Where both a quoted and unquoted string form is allowed, either form can be used provided it does not otherwise violate the grammar. In the following, we provide additional detail on the format of MGCP commands and responses.
3.2 Command Header
The command header is composed of: * A command line, identifying the requested action or verb, the transaction identifier, the endpoint towards which the action is requested, and the MGCP protocol version, * A set of zero or more parameter lines, composed of a parameter name followed by a parameter value. Unless otherwise noted or dictated by other referenced standards (e.g., SDP), each component in the command header is case insensitive. This goes for verbs as well as parameters and values, and hence all comparisons MUST treat upper and lower case as well as combinations of these as being equal.3.2.1 Command Line
The command line is composed of: * The name of the requested verb, * The identification of the transaction, * The name of the endpoint(s) that are to execute the command (in notifications or restarts, the name of the endpoint(s) that is issuing the command), * The protocol version. These four items are encoded as strings of printable ASCII characters, separated by white spaces, i.e., the ASCII space (0x20) or tabulation (0x09) characters. It is RECOMMENDED to use exactly one ASCII space separator. However, MGCP entities MUST be able to parse messages with additional white space characters.
3.2.1.1 Coding of the Requested Verb
The verbs that can be requested are encoded as four letter upper or lower case ASCII codes (comparisons SHALL be case insensitive) as defined in the following table: ----------------------------- | Verb | Code | |----------------------|------| | EndpointConfiguration| EPCF | | CreateConnection | CRCX | | ModifyConnection | MDCX | | DeleteConnection | DLCX | | NotificationRequest | RQNT | | Notify | NTFY | | AuditEndpoint | AUEP | | AuditConnection | AUCX | | RestartInProgress | RSIP | ----------------------------- The transaction identifier is encoded as a string of up to 9 decimal digits. In the command line, it immediately follows the coding of the verb. New verbs may be defined in further versions of the protocol. It may be necessary, for experimentation purposes, to use new verbs before they are sanctioned in a published version of this protocol. Experimental verbs MUST be identified by a four letter code starting with the letter X, such as for example XPER.3.2.1.2 Transaction Identifiers
MGCP uses a transaction identifier to correlate commands and responses. A gateway supports two separate transaction identifier name spaces: * a transaction identifier name space for sending transactions, and * a transaction identifier name space for receiving transactions. At a minimum, transaction identifiers for commands sent to a given gateway MUST be unique for the maximum lifetime of the transactions within the collection of Call Agents that control that gateway. Thus, regardless of the sending Call Agent, gateways can always detect duplicate transactions by simply examining the transaction identifier. The coordination of these transaction identifiers between Call Agents is outside the scope of this specification though.
Transaction identifiers for all commands sent from a given gateway MUST be unique for the maximum lifetime of the transactions regardless of which Call Agent the command is sent to. Thus, a Call Agent can always detect a duplicate transaction from a gateway by the combination of the domain-name of the endpoint and the transaction identifier. The transaction identifier is encoded as a string of up to nine decimal digits. In the command lines, it immediately follows the coding of the verb. Transaction identifiers have values between 1 and 999,999,999 (both included). Transaction identifiers SHOULD NOT use any leading zeroes, although equality is based on numerical value, i.e., leading zeroes are ignored. An MGCP entity MUST NOT reuse a transaction identifier more quickly than three minutes after completion of the previous command in which the identifier was used.3.2.1.3 Coding of the Endpoint Identifiers and Entity Names
The endpoint identifiers and entity names are encoded as case insensitive e-mail addresses, as defined in RFC 821, although with some syntactic restrictions on the local part of the name. Furthermore, both the local endpoint name part and the domain name part can each be up to 255 characters. In these addresses, the domain name identifies the system where the endpoint is attached, while the left side identifies a specific endpoint or entity on that system. Examples of such addresses are: ------------------------------------------------------------------ | hrd4/56@gw23.example.net | Circuit number 56 in | | | interface "hrd4" of the Gateway | | | 23 of the "Example" network | | Call-agent@ca.example.net | Call Agent for the | | | "example" network | | Busy-signal@ann12.example.net| The "busy signal" virtual | | | endpoint in the announcement | | | server number 12. | ------------------------------------------------------------------ The name of a notified entity is expressed with the same syntax, with the possible addition of a port number as in: Call-agent@ca.example.net:5234
In case the port number is omitted from the notified entity, the default MGCP Call Agent port (2727) MUST be used.3.2.1.4 Coding of the Protocol Version
The protocol version is coded as the keyword MGCP followed by a white space and the version number, and optionally followed by a profile name. The version number is composed of a major version, coded by a decimal number, a dot, and a minor version number, coded as a decimal number. The version described in this document is version 1.0. The profile name, if present, is represented by white-space separated strings of visible (printable) characters extending to the end of the line. Profile names may be defined for user communities who want to apply restrictions or other profiling to MGCP. In the initial messages, the version will be coded as: MGCP 1.0 An entity that receives a command with a protocol version it does not support, MUST respond with an error (error code 528 - incompatible protocol version, is RECOMMENDED). Note that this applies to unsupported profiles as well.3.2.2 Parameter Lines
Parameter lines are composed of a parameter name, which in most cases is composed of one or two characters, followed by a colon, optional white space(s) and the parameter value. The parameters that can be present in commands are defined in the following table:
------------------------------------------------------------------
|Parameter name | Code | Parameter value |
|----------------------|------|------------------------------------|
|BearerInformation | B | See description (3.2.2.1). |
|CallId | C | See description (3.2.2.2). |
|Capabilities | A | See description (3.2.2.3). |
|ConnectionId | I | See description (3.2.2.5). |
|ConnectionMode | M | See description (3.2.2.6). |
|ConnectionParameters | P | See description (3.2.2.7). |
|DetectEvents | T | See description (3.2.2.8). |
|DigitMap | D | A text encoding of a digit map. |
|EventStates | ES | See description (3.2.2.9). |
|LocalConnectionOptions| L | See description (3.2.2.10). |
|MaxMGCPDatagram | MD | See description (3.2.2.11). |
|NotifiedEntity | N | An identifier, in RFC 821 format, |
| | | composed of an arbitrary string |
| | | and of the domain name of the |
| | | requesting entity, possibly com- |
| | | pleted by a port number, as in: |
| | | Call-agent@ca.example.net:5234 |
| | | See also Section 3.2.1.3. |
|ObservedEvents | O | See description (3.2.2.12). |
|PackageList | PL | See description (3.2.2.13). |
|QuarantineHandling | Q | See description (3.2.2.14). |
|ReasonCode | E | A string with a 3 digit integer |
| | | optionally followed by a set of |
| | | arbitrary characters (3.2.2.15). |
|RequestedEvents | R | See description (3.2.2.16). |
|RequestedInfo | F | See description (3.2.2.17). |
|RequestIdentifier | X | See description (3.2.2.18). |
|ResponseAck | K | See description (3.2.2.19). |
|RestartDelay | RD | A number of seconds, encoded as |
| | | a decimal number. |
|RestartMethod | RM | See description (3.2.2.20). |
|SecondConnectionId | I2 | Connection Id. |
|SecondEndpointId | Z2 | Endpoint Id. |
|SignalRequests | S | See description (3.2.2.21). |
|SpecificEndPointId | Z | An identifier, in RFC 821 format, |
| | | composed of an arbitrary string, |
| | | followed by an "@" followed by |
| | | the domain name of the gateway to |
| | | which this endpoint is attached. |
| | | See also Section 3.2.1.3. |
|----------------------|------|------------------------------------|
|RemoteConnection- | RC | Session Description. |
| Descriptor | | |
|LocalConnection- | LC | Session Description. |
| Descriptor | | |
------------------------------------------------------------------
The parameters are not necessarily present in all commands. The
following table provides the association between parameters and
commands. The letter M stands for mandatory, O for optional and F
for forbidden. Unless otherwise specified, a parameter MUST NOT be
present more than once.
------------------------------------------------------------------
| Parameter name | EP | CR | MD | DL | RQ | NT | AU | AU | RS |
| | CF | CX | CX | CX | NT | FY | EP | CX | IP |
|---------------------|----|----|----|----|----|----|----|----|----|
| BearerInformation | O*| O | O | O | O | F | F | F | F |
| CallId | F | M | M | O | F | F | F | F | F |
| Capabilities | F | F | F | F | F | F | F | F | F |
| ConnectionId | F | F | M | O | F | F | F | M | F |
| ConnectionMode | F | M | O | F | F | F | F | F | F |
| Connection- | F | F | F | O*| F | F | F | F | F |
| Parameters | | | | | | | | | |
| DetectEvents | F | O | O | O | O | F | F | F | F |
| DigitMap | F | O | O | O | O | F | F | F | F |
| EventStates | F | F | F | F | F | F | F | F | F |
| LocalConnection- | F | O | O | F | F | F | F | F | F |
| Options | | | | | | | | | |
| MaxMGCPDatagram | F | F | F | F | F | F | F | F | F |
| NotifiedEntity | F | O | O | O | O | O | F | F | F |
| ObservedEvents | F | F | F | F | F | M | F | F | F |
| PackageList | F | F | F | F | F | F | F | F | F |
| QuarantineHandling | F | O | O | O | O | F | F | F | F |
| ReasonCode | F | F | F | O | F | F | F | F | O |
| RequestedEvents | F | O | O | O | O*| F | F | F | F |
| RequestIdentifier | F | O*| O*| O*| M | M | F | F | F |
| RequestedInfo | F | F | F | F | F | F | O | M | F |
| ResponseAck | O | O | O | O | O | O | O | O | O |
| RestartDelay | F | F | F | F | F | F | F | F | O |
| RestartMethod | F | F | F | F | F | F | F | F | M |
| SecondConnectionId | F | F | F | F | F | F | F | F | F |
| SecondEndpointId | F | O | F | F | F | F | F | F | F |
| SignalRequests | F | O | O | O | O*| F | F | F | F |
| SpecificEndpointId | F | F | F | F | F | F | F | F | F |
|---------------------|----|----|----|----|----|----|----|----|----|
| RemoteConnection- | F | O | O | F | F | F | F | F | F |
| Descriptor | | | | | | | | | |
| LocalConnection- | F | F | F | F | F | F | F | F | F |
| Descriptor | | | | | | | | | |
------------------------------------------------------------------
Notes (*):
* The BearerInformation parameter is only conditionally optional as
explained in Section 2.3.2.
* The RequestIdentifier parameter is optional in connection creation,
modification and deletion commands, however it becomes REQUIRED if
the command contains an encapsulated notification request.
* The RequestedEvents and SignalRequests parameters are optional in
the NotificationRequest. If these parameters are omitted the
corresponding lists will be considered empty.
* The ConnectionParameters parameter is only valid in a
DeleteConnection request sent by the gateway.
The set of parameters can be extended in two different ways:
* Package Extension Parameters (preferred)
* Vendor Extension Parameters
Package Extension Parameters are defined in packages which provides
the following benefits:
* a registration mechanism (IANA) for the package name.
* a separate name space for the parameters.
* a convenient grouping of the extensions.
* a simple way to determine support for them through auditing.
The package extension mechanism is the preferred extension method.
Vendor extension parameters can be used if implementers need to
experiment with new parameters, for example when developing a new
application of MGCP. Vendor extension parameters MUST be identified
by names that start with the string "X-" or "X+", such as for
example:
X-Flower: Daisy
Parameter names that start with "X+" are critical parameter
extensions. An MGCP entity that receives a critical parameter
extension that it cannot understand MUST refuse to execute the
command. It SHOULD respond with error code 511 (unrecognized
extension).
Parameter names that start with "X-" are non-critical parameter
extensions. An MGCP entity that receives a non-critical parameter
extension that it cannot understand MUST simply ignore that
parameter.
Note that vendor extension parameters use an unmanaged name space, which implies a potential for name clashing. Vendors are consequently encouraged to include some vendor specific string, e.g., vendor name, in their vendor extensions.3.2.2.1 BearerInformation
The values of the bearer information are encoded as a comma separated list of attributes, which are represented by an attribute name, and possibly followed by a colon and an attribute value. The only attribute that is defined is the "encoding" (code "e") attribute, which MUST have one of the values "A" (A-law) or "mu" (mu-law). An example of bearer information encoding is: B: e:mu The set of bearer information attributes may be extended through packages.3.2.2.2 CallId
The Call Identifier is encoded as a hexadecimal string, at most 32 characters in length. Call Identifiers are compared as strings rather than numerical values.3.2.2.3 Capabilities
Capabilities inform the Call Agent about endpoints' capabilities when audited. The encoding of capabilities is based on the Local Connection Options encoding for the parameters that are common to both, although a different parameter line code is used ("A"). In addition, capabilities can also contain a list of supported packages, and a list of supported modes. The parameters used are: A list of supported codecs. The following parameters will apply to all codecs specified in this list. If there is a need to specify that some parameters, such as e.g., silence suppression, are only compatible with some codecs, then the gateway will return several Capability parameters; one for each set of codecs. Packetization Period: A range may be specified.
Bandwidth:
A range corresponding to the range for packetization periods may
be specified (assuming no silence suppression). If absent, the
values will be deduced from the codec type.
Echo Cancellation:
"on" if echo cancellation is supported, "off" otherwise. The
default is support.
Silence Suppression:
"on" if silence suppression is supported for this codec, "off"
otherwise. The default is support.
Gain Control:
"0" if gain control is not supported, all other values indicate
support for gain control. The default is support.
Type of Service:
The value "0" indicates no support for type of service, all other
values indicate support for type of service. The default is
support.
Resource Reservation Service:
The parameter indicates the reservation services that are
supported, in addition to best effort. The value "g" is encoded
when the gateway supports both the guaranteed and the controlled
load service, "cl" when only the controlled load service is
supported. The default is "best effort".
Encryption Key:
Encoding any value indicates support for encryption. Default is
no support which is implied by omitting the parameter.
Type of network:
The keyword "nt", followed by a colon and a semicolon separated
list of supported network types. This parameter is optional.
Packages:
The packages supported by the endpoint encoded as the keyword "v",
followed by a colon and a character string. If a list of values
is specified, these values will be separated by a semicolon. The
first value specified will be the default package for the
endpoint.
Modes:
The modes supported by this endpoint encoded as the keyword "m",
followed by a colon and a semicolon-separated list of supported
connection modes for this endpoint.
Lack of support for a capability can also be indicated by excluding
the parameter from the capability set.
An example capability is:
A: a:PCMU;G728, p:10-100, e:on, s:off, t:1, v:L,
m:sendonly;recvonly;sendrecv;inactive
The carriage return above is included for formatting reasons only and
is not permissible in a real implementation.
If multiple capabilities are to be returned, each will be returned as
a separate capability line.
Since Local Connection Options can be extended, the list of
capability parameters can also be extended. Individual extensions
may define how they are reported as capabilities. If no such
definition is provided, the following defaults apply:
* Package Extension attributes: The individual attributes are not
reported. Instead, the name of the package is simply reported in
the list of supported packages.
* Vendor Extension attributes: The name of the attribute is reported
without any value.
* Other Extension attributes: The name of the attribute is reported
without any value.
3.2.2.4 Coding of Event Names
Event names are composed of an optional package name, separated by a
slash (/) from the name of the actual event (see Section 2.1.7). The
wildcard character star ("*") can be use to refer to all packages.
The event name can optionally be followed by an at sign (@) and the
identifier of a connection (possibly using a wildcard) on which the
event should be observed. Event names are used in the
RequestedEvents, SignalRequests, ObservedEvents, DetectEvents, and
EventStates parameters.
Events and signals may be qualified by parameters defined for the
event/signal. Such parameters may be enclosed in double-quotes (in
fact, some parameters MUST be enclosed in double-quotes due to
syntactic restrictions) in which case they are UTF-8 encoded [20].
The parameter name "!" (exclamation point) is reserved for future use
for both events and signals.
Each signal has one of the following signal-types associated with it:
On/Off (OO), Time-out (TO), or Brief (BR). (These signal types are
specified in the package definitions, and are not present in the
messages.) On/Off signals can be parameterized with a "+" to turn the
signal on, or a "-" to turn the signal off. If an on/off signal is
not parameterized, the signal is turned on. Both of the following
will turn the vmwi signal (from the line package "L") on:
L/vmwi(+)
L/vmwi
In addition to "!", "+" and "-", the signal parameter "to" is
reserved as well. It can be used with Time-Out signals to override
the default time-out value for the current request. A decimal value
in milliseconds will be supplied. The individual signal and/or
package definition SHOULD indicate if this parameter is supported for
one or more TO signals in the package. If not indicated, TO signals
in package version zero are assumed to not support it, whereas TO
signals in package versions one or higher are assumed to support it.
By default, a supplied time-out value MAY be rounded to the nearest
non-zero value divisible by 1000, i.e., whole second. The individual
signal and/or package definition may define other rounding rules. All
new package and TO signal definitions are strongly encouraged to
support the "to" signal parameter.
The following example illustrates how the "to" parameter can be used
to apply a signal for 6 seconds:
L/rg(to=6000)
L/rg(to(6000))
The following are examples of event names:
-----------------------------------------------------------
| L/hu | on-hook transition, in the line package |
| F/0 | digit 0 in the MF package |
| hf | Hook-flash, assuming that the line package|
| | is the default package for the endpoint. |
| G/rt@0A3F58 | Ring back signal on connection "0A3F58" |
-----------------------------------------------------------
In addition, the range and wildcard notation of events can be used,
instead of individual names, in the RequestedEvents and DetectEvents
parameters. The event code "all" is reserved and refers to all
events or signals in a package. The star sign ("*") can be used to
denote "all connections", and the dollar sign ("$") can be used to
denote the "current" connection (see Section 2.1.7 for details).
The following are examples of such notations:
---------------------------------------------------------
| M/[0-9] | Digits 0 to 9 in the MF package. |
| hf | Hook-flash, assuming that the line package|
| | is a default package for the endpoint. |
| [0-9*#A-D]| All digits and letters in the DTMF |
| | packages (default for endpoint). |
| T/all | All events in the trunk package. |
| R/qa@* | The quality alert event on all |
| | connections. |
| G/rt@$ | Ringback on current connection. |
---------------------------------------------------------
3.2.2.5 ConnectionId
The Connection Identifier is encoded as a hexadecimal string, at most
32 characters in length. Connection Identifiers are compared as
strings rather than numerical values.
3.2.2.6 ConnectionMode
The connection mode describes the mode of operation of the
connection. The possible values are:
--------------------------------------------------------
| Mode | Meaning |
|-------------|------------------------------------------|
| M: sendonly | The gateway should only send packets |
| M: recvonly | The gateway should only receive packets |
| M: sendrecv | The gateway should send |
| | and receive packets |
| M: confrnce | The gateway should place |
| | the connection in conference mode |
| M: inactive | The gateway should neither |
| | send nor receive packets |
| M: loopback | The gateway should place |
| | the circuit in loopback mode. |
| M: conttest | The gateway should place |
| | the circuit in test mode. |
| M: netwloop | The gateway should place |
| | the connection in network loopback mode.|
| M: netwtest | The gateway should place the connection |
| | in network continuity test mode. |
--------------------------------------------------------
Note that irrespective of the connection mode, signals applied to the connection will still result in packets being sent (see Section 2.3.1). The set of connection modes can be extended through packages.3.2.2.7 ConnectionParameters
Connection parameters are encoded as a string of type and value pairs, where the type is either a two-letter identifier of the parameter or an extension type, and the value a decimal integer. Types are separated from value by an '=' sign. Parameters are separated from each other by a comma. Connection parameter values can contain up to nine digits. If the maximum value is reached, the counter is no longer updated, i.e., it doesn't wrap or overflow. The connection parameter types are specified in the following table: ----------------------------------------------------------------- | Connection parameter| Code | Connection parameter | | name | | value | |---------------------|------|------------------------------------| | Packets sent | PS | The number of packets that | | | | were sent on the connection. | | Octets sent | OS | The number of octets that | | | | were sent on the connection. | | Packets received | PR | The number of packets that | | | | were received on the connection. | | Octets received | OR | The number of octets that | | | | were received on the connection. | | Packets lost | PL | The number of packets that | | | | were lost on the connection | | | | as deduced from gaps in the | | | | RTP sequence number. | | Jitter | JI | The average inter-packet arrival | | | | jitter, in milliseconds, | | | | expressed as an integer number. | | Latency | LA | Average latency, in milliseconds, | | | | expressed as an integer number. | ----------------------------------------------------------------- The set of connection parameters can be extended in two different ways: * Package Extension Parameters (preferred) * Vendor Extension Parameters
Package Extension Connection Parameters are defined in packages which
provides the following benefits:
* A registration mechanism (IANA) for the package name.
* A separate name space for the parameters.
* A convenient grouping of the extensions.
* A simple way to determine support for them through auditing.
The package extension mechanism is the preferred extension method.
Vendor extension parameters names are composed of the string "X-"
followed by a two or more letters extension parameter name.
Call agents that receive unrecognized package or vendor connection
parameter extensions SHALL silently ignore these parameters.
An example of connection parameter encoding is:
P: PS=1245, OS=62345, PR=0, OR=0, PL=0, JI=0, LA=48
3.2.2.8 DetectEvents
The DetectEvents parameter is encoded as a comma separated list of
events (see Section 3.2.2.4), such as for example:
T: L/hu,L/hd,L/hf,D/[0-9#*]
It should be noted, that no actions can be associated with the
events, however event parameters may be provided.
3.2.2.9 EventStates
The EventStates parameter is encoded as a comma separated list of
events (see Section 3.2.2.4), such as for example:
ES: L/hu
It should be noted, that no actions can be associated with the
events, however event parameters may be provided.
3.2.2.10 LocalConnectionOptions
The local connection options describe the operational parameters that
the Call Agent provides to the gateway in connection handling
commands. These include:
* The allowed codec(s), encoded as the keyword "a", followed by a
colon and a character string. If the Call Agent specifies a list
of values, these values will be separated by a semicolon. For RTP,
audio codecs SHALL be specified by using encoding names defined in
the RTP AV Profile [4] or its replacement, or by encoding names
registered with the IANA. Non-audio media registered as a MIME
type MUST use the "<MIME type>/<MIME subtype>" form, as in
"image/t38".
* The packetization period in milliseconds, encoded as the keyword
"p", followed by a colon and a decimal number. If the Call Agent
specifies a range of values, the range will be specified as two
decimal numbers separated by a hyphen (as specified for the "ptime"
parameter for SDP).
* The bandwidth in kilobits per second (1000 bits per second),
encoded as the keyword "b", followed by a colon and a decimal
number. If the Call Agent specifies a range of values, the range
will be specified as two decimal numbers separated by a hyphen.
* The type of service parameter, encoded as the keyword "t", followed
by a colon and the value encoded as two hexadecimal digits. When
the connection is transmitted over an IP network, the parameters
encode the 8-bit type of service value parameter of the IP header
(a.k.a. DiffServ field). The left-most "bit" in the parameter
corresponds to the least significant bit in the IP header.
* The echo cancellation parameter, encoded as the keyword "e",
followed by a colon and the value "on" or "off".
* The gain control parameter, encoded as the keyword "gc", followed
by a colon and a value which can be either the keyword "auto" or a
decimal number (positive or negative) representing the number of
decibels of gain.
* The silence suppression parameter, encoded as the keyword "s",
followed by a colon and the value "on" or "off".
* The resource reservation parameter, encoded as the keyword "r",
followed by a colon and the value "g" (guaranteed service), "cl"
(controlled load) or "be" (best effort).
* The encryption key, encoded as the keyword "k" followed by a colon
and a key specification, as defined for the parameter "K" in SDP
(RFC 2327).
* The type of network, encoded as the keyword "nt" followed by a
colon and the type of network encoded as the keyword "IN"
(internet), "ATM", "LOCAL" (for a local connection), or possibly
another type of network registered with the IANA as per SDP (RFC
2327).
* The resource reservation parameter, encoded as the keyword "r",
followed by a colon and the value "g" (guaranteed service), "cl"
(controlled load) or "be" (best effort).
The encoding of the first three attributes, when they are present,
will be compatible with the SDP and RTP profiles. Note that each of
the attributes is optional. When several attributes are present,
they are separated by a comma.
Examples of local connection options are:
L: p:10, a:PCMU
L: p:10, a:G726-32
L: p:10-20, b:64
L: b:32-64, e:off
The set of Local Connection Options attributes can be extended in
three different ways:
* Package Extension attributes (preferred)
* Vendor Extension attributes
* Other Extension attributes
Package Extension Local Connection Options attributes are defined in
packages which provides the following benefits:
* A registration mechanism (IANA) for the package name.
* A separate name space for the attributes.
* A convenient grouping of the extensions.
* A simple way to determine support for them through auditing.
The package extension mechanism is the preferred extension method.
Vendor extension attributes are composed of an attribute name, and possibly followed by a colon and an attribute value. The attribute name MUST start with the two characters "x+", for a mandatory extension, or "x-", for a non-mandatory extension. If a gateway receives a mandatory extension attribute that it does not recognize, it MUST reject the command (error code 525 - unknown extension in LocalConnectionOptions, is RECOMMENDED). Note that vendor extension attributes use an unmanaged name space, which implies a potential for name clashing. Vendors are consequently encouraged to include some vendor specific string, e.g., vendor name, in their vendor extensions. Finally, for backwards compatibility with some existing implementations, MGCP allows for other extension attributes as well (see grammar in Appendix A). Note however, that these attribute extensions do not provide the package extension attribute benefits. Use of this mechanism for new extensions is discouraged.3.2.2.11 MaxMGCPDatagram
The MaxMGCPDatagram can only be used for auditing, i.e., it is a valid RequestedInfo code and can be provided as a response parameter. In responses, the MaxMGCPDatagram value is encoded as a string of up to nine decimal digits -- leading zeroes are not permitted. The following example illustrates the use of this parameter: MD: 81003.2.2.12 ObservedEvents
The observed events parameter provides the list of events that have been observed. The event codes are the same as those used in the NotificationRequest. Events that have been accumulated according to the digit map may be grouped in a single string, however such practice is discouraged; they SHOULD be reported as lists of isolated events if other events were detected during the digit accumulation. Examples of observed events are: O: L/hu O: D/8295555T O: D/8,D/2,D/9,D/5,D/5,L/hf,D/5,D/5,D/T O: L/hf, L/hf, L/hu
3.2.2.13 PackageList
The Package List can only be used for auditing, i.e., it is a valid RequestedInfo code and can be provided as a response parameter. The response parameter will consist of a comma separated list of packages supported. The first package returned in the list is the default package. Each package in the list consists of the package name followed by a colon, and the highest version number of the package supported. An example of a package list is: PL: L:1,G:1,D:0,FOO:2,T:1 Note that for backwards compatibility, support for this parameter is OPTIONAL.3.2.2.14 QuarantineHandling
The quarantine handling parameter contains a list of comma separated keywords: * The keyword "process" or "discard" to indicate the treatment of quarantined and observed events. If neither "process" or "discard" is present, "process" is assumed. * The keyword "step" or "loop" to indicate whether at most one notification per NotificationRequest is allowed, or whether multiple notifications per NotificationRequest are allowed. If neither "step" nor "loop" is present, "step" is assumed. The following values are valid examples: Q: loop Q: process Q: loop,discard3.2.2.15 ReasonCode
Reason codes are three-digit numeric values. The reason code is optionally followed by a white space and commentary, e.g.: E: 900 Endpoint malfunctioning A list of reason codes can be found in Section 2.5. The set of reason codes can be extended through packages.
3.2.2.16 RequestedEvents
The RequestedEvents parameter provides the list of events that are requested. The event codes are described in Section 3.2.2.4. Each event can be qualified by a requested action, or by a list of actions. The actions, when specified, are encoded as a list of keywords, enclosed in parenthesis and separated by commas. The codes for the various actions are: ------------------------------------- | Action | Code | |------------------------------|------| | Notify immediately | N | | Accumulate | A | | Treat according to digit map | D | | Swap | S | | Ignore | I | | Keep Signal(s) active | K | | Embedded Notification Request| E | ------------------------------------- When no action is specified, the default action is to notify the event. This means that, for example, ft and ft(N) are equivalent. Events that are not listed are ignored (unless they are persistent). The digit-map action SHOULD only be specified for the digits, letters and interdigit timers in packages that define the encoding of digits, letters, and timers (including extension digit map letters). The requested events list is encoded on a single line, with event/action groups separated by commas. Examples of RequestedEvents encodings are: R: L/hu(N), L/hf(S,N) R: L/hu(N), D/[0-9#T](D) In the case of the "Embedded Notification Request" action, the embedded notification request parameters are encoded as a list of up to three parameter groups separated by commas. Each group starts by a one letter identifier, followed by a list of parameters enclosed between parentheses. The first optional parameter group, identified by the letter "R", is the value of the embedded RequestedEvents parameter. The second optional group, identified by the letter "S", is the embedded value of the SignalRequests parameter. The third
optional group, identified by the letter "D", is the embedded value
of the DigitMap. (Note that some existing implementations and
profiles may encode these three components in a different order.
Implementers are encouraged to accept such encodings, but they SHOULD
NOT generate them.)
If the RequestedEvents parameter is not present, the parameter will
be set to a null value. If the SignalRequests parameter is not
present, the parameter will be set to a null value. If the DigitMap
is absent, the current value MUST be used. The following are valid
examples of embedded requests:
R: L/hd(E(R(D/[0-9#T](D),L/hu(N)),S(L/dl),D([0-9].[#T])))
R: L/hd(E(R(D/[0-9#T](D),L/hu(N)),S(L/dl)))
Some events can be qualified by additional event parameters. Such
event parameters will be separated by commas and enclosed within
parentheses. Event parameters may be enclosed in double-quotes (in
fact, some event parameters MUST be enclosed in double-quotes due to
syntactic restrictions), in which case the quoted string itself is
UTF-8 encoded. Please refer to Section 3.2.2.4 for additional detail
on event parameters.
The following example shows the foobar event with an event parameter
"epar":
R: X/foobar(N)(epar=2)
Notice that the Action was included even though it is the default
Notify action - this is required by the grammar.
3.2.2.17 RequestedInfo
The RequestedInfo parameter contains a comma separated list of
parameter codes, as defined in Section 3.2.2. For example, if one
wants to audit the value of the NotifiedEntity, RequestIdentifier,
RequestedEvents, SignalRequests, DigitMap, QuarantineHandling and
DetectEvents parameters, the value of the RequestedInfo parameter
will be:
F: N,X,R,S,D,Q,T
Note that extension parameters in general can be audited as well.
The individual extension will define the auditing operation.
The capabilities request, in the AuditEndPoint command, is encoded by
the parameter code "A", as in:
F: A
3.2.2.18 RequestIdentifier
The request identifier correlates a Notify command with the
NotificationRequest that triggered it. A RequestIdentifier is a
hexadecimal string, at most 32 characters in length.
RequestIdentifiers are compared as strings rather than numerical
value. The string "0" is reserved for reporting of persistent events
in the case where a NotificationRequest has not yet been received
after restart.
3.2.2.19 ResponseAck
The response acknowledgement parameter is used to manage the "at-
most-once" facility described in Section 3.5. It contains a comma
separated list of "confirmed transaction-id ranges".
Each "confirmed transaction-id range" is composed of either one
decimal number, when the range includes exactly one transaction, or
two decimal numbers separated by a single hyphen, describing the
lower and higher transaction identifiers included in the range.
An example of a response acknowledgement is:
K: 6234-6255, 6257, 19030-19044
3.2.2.20 RestartMethod
The RestartMethod parameter is encoded as one of the keywords
"graceful", "forced", "restart", "disconnected" or "cancel-graceful"
as for example:
RM: restart
The set of restart methods can be extended through packages.
3.2.2.21 SignalRequests
The SignalRequests parameter provides the name of the signal(s) that
have been requested. Each signal is identified by a name, as
described in Section 3.2.2.4.
Some signals, such as for example announcement or ADSI display, can
be qualified by additional parameters, e.g.:
* the name and parameters of the announcement,
* the string that should be displayed.
Such parameters will be separated by commas and enclosed within
parenthesis, as in:
S: L/adsi("123456 Francois Gerard")
S: A/ann(http://ann.example.net/no-such-number.au, 1234567)
When a quoted-string is provided, the string itself is UTF-8 encoded
[20].
When several signals are requested, their codes are separated by a
comma, as in:
S: L/adsi("123456 Your friend"), L/rg
Please refer to Section 3.2.2.4 for additional detail on signal
parameters.
(page 101 continued on part 5)
