tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 3435

 
 
 

Media Gateway Control Protocol (MGCP) Version 1.0

Part 4 of 8, p. 65 to 101
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 65 
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).

Top      Up      ToC       Page 66 
   * 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])

Top      Up      ToC       Page 67 
   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"

Top      Up      ToC       Page 68 
   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):

Top      Up      ToC       Page 69 
   * 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:

Top      Up      ToC       Page 70 
   * 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".

Top      Up      ToC       Page 71 
   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.

Top      Up      ToC       Page 72 
   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.

Top      Up      ToC       Page 73 
   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.

Top      Up      ToC       Page 74 
   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.

Top      Up      ToC       Page 75 
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.

Top      Up      ToC       Page 76 
   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.

Top      Up      ToC       Page 77 
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

Top      Up      ToC       Page 78 
   * 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.

Top      Up      ToC       Page 79 
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.

Top      Up      ToC       Page 80 
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.

Top      Up      ToC       Page 81 
   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

Top      Up      ToC       Page 82 
   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:

Top      Up      ToC       Page 83 
    ------------------------------------------------------------------
   |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.         |
   |----------------------|------|------------------------------------|

Top      Up      ToC       Page 84 
   |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.

Top      Up      ToC       Page 85 
    ------------------------------------------------------------------
   | 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.

Top      Up      ToC       Page 86 
   * 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.

Top      Up      ToC       Page 87 
   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.

Top      Up      ToC       Page 88 
   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.

Top      Up      ToC       Page 89 
   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.

Top      Up      ToC       Page 90 
   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).

Top      Up      ToC       Page 91 
   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.        |
      --------------------------------------------------------

Top      Up      ToC       Page 92 
   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

Top      Up      ToC       Page 93 
   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:

Top      Up      ToC       Page 94 
   * 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).

Top      Up      ToC       Page 95 
   * 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.

Top      Up      ToC       Page 96 
   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: 8100

3.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

Top      Up      ToC       Page 97 
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,discard

3.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.

Top      Up      ToC       Page 98 
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

Top      Up      ToC       Page 99 
   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.

Top      Up      ToC       Page 100 
   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.:

Top      Up      ToC       Page 101 
   * 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)

Next RFC Part