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 3 of 8, p. 33 to 65
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 33 
2.2 Usage of SDP

   The Call Agent uses the MGCP to provide the endpoint with the
   description of connection parameters such as IP addresses, UDP port
   and RTP profiles.  These descriptions will follow the conventions
   delineated in the Session Description Protocol which is now an IETF
   proposed standard, documented in RFC 2327.

2.3 Gateway Control Commands

2.3.1 Overview of Commands

   This section describes the commands of the MGCP.  The service
   consists of connection handling and endpoint handling commands.
   There are currently nine commands in the protocol:

   * The Call Agent can issue an EndpointConfiguration command to a
     gateway, instructing the gateway about the coding characteristics
     expected by the "line-side" of the endpoint.

   * The Call Agent can issue a NotificationRequest command to a
     gateway, instructing the gateway to watch for specific events such
     as hook actions or DTMF tones on a specified endpoint.

   * The gateway will then use the Notify command to inform the Call
     Agent when the requested events occur.

   * The Call Agent can use the CreateConnection command to create a
     connection that terminates in an "endpoint" inside the gateway.

   * The Call Agent can use the ModifyConnection command to change the
     parameters associated with a previously established connection.

   * The Call Agent can use the DeleteConnection command to delete an
     existing connection.  The DeleteConnection command may also be used
     by a gateway to indicate that a connection can no longer be
     sustained.

   * The Call Agent can use the AuditEndpoint and AuditConnection
     commands to audit the status of an "endpoint" and any connections
     associated with it.  Network management beyond the capabilities
     provided by these commands is generally desirable.  Such
     capabilities are expected to be supported by the use of the Simple
     Network Management Protocol (SNMP) and definition of a MIB which is
     outside the scope of this specification.

Top      Up      ToC       Page 34 
   * The Gateway can use the RestartInProgress command to notify the
     Call Agent that a group of endpoints managed by the gateway is
     being taken out-of-service or is being placed back in-service.

   These services allow a controller (normally, the Call Agent) to
   instruct a gateway on the creation of connections that terminate in
   an "endpoint" attached to the gateway, and to be informed about
   events occurring at the endpoint.  An endpoint may be for example:

   * A specific trunk circuit, within a trunk group terminating in a
     gateway,

   * A specific announcement handled by an announcement server.

   Connections are logically grouped into "calls" (the concept of a
   "call" has however little semantic meaning in MGCP itself).  Several
   connections, that may or may not belong to the same call, can
   terminate in the same endpoint.  Each connection is qualified by a
   "mode" parameter, which can be set to "send only" (sendonly),
   "receive only" (recvonly), "send/receive" (sendrecv), "conference"
   (confrnce), "inactive" (inactive), "loopback", "continuity test"
   (conttest), "network loop back" (netwloop) or "network continuity
   test" (netwtest).

   Media generated by the endpoint is sent on connections whose mode is
   either "send only", "send/receive", or "conference", unless the
   endpoint has a connection in "loopback" or "continuity test" mode.
   However, media generated by applying a signal to a connection is
   always sent on the connection, regardless of the mode.

   The handling of the media streams received on connections is
   determined by the mode parameters:

   * Media streams received through connections in "receive",
     "conference" or "send/receive" mode are mixed and sent to the
     endpoint, unless the endpoint has another connection in "loopback"
     or "continuity test" mode.

   * Media streams originating from the endpoint are transmitted over
     all the connections whose mode is "send", "conference" or
     "send/receive", unless the endpoint has another connection in
     "loopback" or "continuity test" mode.

   * In addition to being sent to the endpoint, a media stream received
     through a connection in "conference" mode is forwarded to all the
     other connections whose mode is "conference".  This also applies

Top      Up      ToC       Page 35 
     when the endpoint has a connection in "loopback" or "continuity
     test" mode.  The details of this forwarding, e.g., RTP translator
     or mixer, is outside the scope of this document.

   Note that in order to detect events on a connection, the connection
   must by default be in one of the modes "receive", "conference",
   "send/receive", "network loopback" or "network continuity test".  The
   event detection only applies to the incoming media.  Connections in
   "sendonly", "inactive", "loopback", or "continuity test" mode will
   thus normally not detect any events, although requesting to do so is
   not considered an error.

   The "loopback" and "continuity test" modes are used during
   maintenance and continuity test operations.  An endpoint may have
   more than one connection in either "loopback" or "continuity test"
   mode.  As long as there is one connection in that particular mode,
   and no other connection on the endpoint is placed in a different
   maintenance or test mode, the maintenance or test operation shall
   continue undisturbed.  There are two flavors of continuity test, one
   specified by ITU and one used in the US.  In the first case, the test
   is a loopback test.  The originating switch will send a tone (the go
   tone) on the bearer circuit and expects the terminating switch to
   loopback the tone.  If the originating switch sees the same tone
   returned (the return tone), the COT has passed.  If not, the COT has
   failed.  In the second case, the go and return tones are different.
   The originating switch sends a certain go tone.  The terminating
   switch detects the go tone, it asserts a different return tone in the
   backwards direction.  When the originating switch detects the return
   tone, the COT is passed.  If the originating switch never detects the
   return tone, the COT has failed.

   If the mode is set to "loopback", the gateway is expected to return
   the incoming signal from the endpoint back into that same endpoint.
   This procedure will be used, typically, for testing the continuity of
   trunk circuits according to the ITU specifications.  If the mode is
   set to "continuity test", the gateway is informed that the other end
   of the circuit has initiated a continuity test procedure according to
   the GR specification (see [22]).  The gateway will place the circuit
   in the transponder mode required for dual-tone continuity tests.

   If the mode is set to "network loopback", the audio signals received
   from the connection will be echoed back on the same connection.  The
   media is not forwarded to the endpoint.

   If the mode is set to "network continuity test", the gateway will
   process the packets received from the connection according to the
   transponder mode required for dual-tone continuity test, and send the
   processed signal back on the connection.  The media is not forwarded

Top      Up      ToC       Page 36 
   to the endpoint.  The "network continuity test" mode is included for
   backwards compatibility only and use of it is discouraged.

2.3.2 EndpointConfiguration

   The EndpointConfiguration command can be used to specify the encoding
   of the signals that will be received by the endpoint.  For example,
   in certain international telephony configurations, some calls will
   carry mu-law encoded audio signals, while others will use A-law.  The
   Call Agent can use the EndpointConfiguration command to pass this
   information to the gateway.  The configuration may vary on a call by
   call basis, but can also be used in the absence of any connection.

         ReturnCode,
         [PackageList]
         <-- EndpointConfiguration(EndpointId,
                                   [BearerInformation])

   EndpointId is the name of the endpoint(s) in the gateway where
   EndpointConfiguration executes.  The "any of" wildcard convention
   MUST NOT be used.  If the "all of" wildcard convention is used, the
   command applies to all the endpoints whose name matches the wildcard.

   BearerInformation is a parameter defining the coding of the data sent
   to and received from the line side.  The information is encoded as a
   list of sub-parameters.  The only sub-parameter defined in this
   version of the specification is the bearer encoding, whose value can
   be set to "A-law" or "mu-law".  The set of sub-parameters may be
   extended.

   In order to allow for extensibility, while remaining backwards
   compatible, the BearerInformation parameter is conditionally optional
   based on the following conditions:

   * if Extension Parameters (vendor, package or other) are not used,
     the BearerInformation parameter is REQUIRED,

   * otherwise, the BearerInformation parameter is OPTIONAL.

   When omitted, BearerInformation MUST retain its current value.

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

Top      Up      ToC       Page 37 
2.3.3 NotificationRequest

   The NotificationRequest command is used to request the gateway to
   send notifications upon the occurrence of specified events in an
   endpoint.  For example, a notification may be requested for when a
   gateway detects that an endpoint is receiving tones associated with
   fax communication.  The entity receiving this notification may then
   decide to specify use of a different type of encoding method in the
   connections bound to this endpoint and instruct the gateway
   accordingly with a ModifyConnection Command.

         ReturnCode,
         [PackageList]
         <-- NotificationRequest(EndpointId,
                                 [NotifiedEntity,]
                                 [RequestedEvents,]
                                 RequestIdentifier,
                                 [DigitMap,]
                                 [SignalRequests,]
                                 [QuarantineHandling,]
                                 [DetectEvents,]
                                 [encapsulated EndpointConfiguration])

   EndpointId is the identifier for the endpoint(s) in the the gateway
   where the NotificationRequest executes.  The "any of" wildcard MUST
   NOT be used.

   NotifiedEntity is an optional parameter that specifies a new
   "notified entity" for the endpoint.

   RequestIdentifier is used to correlate this request with the
   notifications that it triggers.  It will be repeated in the
   corresponding Notify command.

   RequestedEvents is a list of events, possibly qualified by event
   parameters (see Section 3.2.2.4), that the gateway is requested to
   detect and report.  Such events may include, for example, fax tones,
   continuity tones, or on-hook transition.  Unless otherwise specified,
   events are detected on the endpoint, however some events can be
   detected on a connection.  A given event MUST NOT appear more than
   once in a RequestedEvents.  If the parameter is omitted, it defaults
   to empty.

   To each event is associated one or more actions, which can be:

   * Notify the event immediately, together with the accumulated list of
     observed events,

Top      Up      ToC       Page 38 
   * Swap audio,

   * Accumulate the event in an event buffer, but don't notify yet,

   * Accumulate according to Digit Map,

   * Keep Signal(s) active,

   * Process the Embedded Notification Request,

   * Ignore the event.

   Support for Notify, Accumulate, Keep Signal(s) Active, Embedded
   Notification Request, and Ignore is REQUIRED.  Support for Accumulate
   according to Digit Map is REQUIRED on any endpoint capable of
   detecting DTMF.  Support for any other action is OPTIONAL.  The set
   of actions can be extended.

   A given action can by default be specified for any event, although
   some actions will not make sense for all events.  For example, an
   off-hook event with the Accumulate according to Digit Map action is
   valid, but will of course immediately trigger a digit map mismatch
   when the off-hook event occurs.  Needless to say, such practice is
   discouraged.

   Some actions can be combined as shown in the table below, where "Y"
   means the two actions can be combined, and "N" means they cannot:

       --------------------------------------------------------------
      |       | Notif | Swap | Accum | AccDi | KeSiA | EmbNo | Ignor |
      |--------------------------------------------------------------|
      | Notif |   N   |   Y  |   N   |   N   |   Y   |   Y*  |   N   |
      | Swap  |   -   |   N  |   Y   |   N   |   N   |   N   |   Y   |
      | Accum |   -   |   -  |   N   |   N   |   Y   |   Y   |   N   |
      | AccDi |   -   |   -  |   -   |   N   |   Y   |   N   |   N   |
      | KeSiA |   -   |   -  |   -   |   -   |   N   |   Y   |   Y   |
      | EmbNo |   -   |   -  |   -   |   -   |   -   |   N   |   N   |
      | Ignor |   -   |   -  |   -   |   -   |   -   |   -   |   N   |
       --------------------------------------------------------------

      Note (*):  The "Embedded Notification Request" can only be
      combined with "Notify", if the gateway is allowed to issue more
      than one Notify command per Notification request (see below and
      Section 4.4.1).

   If no action is specified, the Notify action will be applied.  If one
   or more actions are specified, only those actions apply.  When two or
   more actions are specified, each action MUST be combinable with all

Top      Up      ToC       Page 39 
   the other actions as defined by the table above - the individual
   actions are assumed to occur simultaneously.

   If a client receives a request with an invalid or unsupported action
   or an illegal combination of actions, it MUST return an error to the
   Call Agent (error code 523 - unknown or illegal combination of
   actions, is RECOMMENDED).

   In addition to the RequestedEvents parameter specified in the
   command, some MGCP packages may contain "persistent events" (this is
   generally discouraged though - see Appendix B for an alternative).
   Persistent events in a given package are always detected on an
   endpoint that implements that package.  If a persistent event is not
   included in the list of RequestedEvents, and the event occurs, the
   event will be detected anyway and processed like all other events, as
   if the persistent event had been requested with a Notify action.  A
   NotificationRequest MUST still be in place for a persistent event to
   trigger a Notify though. Thus, informally, persistent events can be
   viewed as always being implicitly included in the list of
   RequestedEvents with an action to Notify, although no glare
   detection, etc., will be performed.

   Non-persistent events are those events that need to be explicitly
   included in the RequestedEvents list. The (possibly empty) list of
   requested events completely replaces the previous list of requested
   events.  In addition to the persistent events, only the events
   specified in the requested events list will be detected by the
   endpoint.  If a persistent event is included in the RequestedEvents
   list, the action specified will replace the default action associated
   with the event for the life of the RequestedEvents list, after which
   the default action is restored.  For example, if "off-hook"was a
   persistent event, the "Ignore off-hook" action was specified, and a
   new request without any off-hook instructions were received, the
   default "Notify off-hook" operation would be restored.

   The gateway will detect the union of the persistent events and the
   requested events.  If an event is not included in either list, it
   will be ignored.

   The Call Agent can send a NotificationRequest with an empty (or
   omitted) RequestedEvents list to the gateway.  The Call Agent can do
   so, for example, to a gateway when it does not want to collect any
   more DTMF digits.  However, persistent events will still be detected
   and notified.

   The Swap Audio action can be used when a gateway handles more than
   one connection on an endpoint.  This will be the case for call
   waiting, and possibly other feature scenarios.  In order to avoid the

Top      Up      ToC       Page 40 
   round-trip to the Call Agent when just changing which connection is
   attached to the audio functions of the endpoint, the
   NotificationRequest can map an event (usually hook flash, but could
   be some other event) to a local swap audio function, which selects
   the "next" connection in a round robin fashion.  If there is only one
   connection, this action is effectively a no-op.  If there are more
   than two connections, the order is undefined.  If the endpoint has
   exactly two connections, one of which is "inactive", the other of
   which is in "send/receive" mode, then swap audio will attempt to make
   the "send/receive" connection "inactive", and vice versa.  This
   specification intentionally does not provide any additional detail on
   the swap audio action.

   If signal(s) are desired to start when an event being looked for
   occurs, the "Embedded NotificationRequest" action can be used.  The
   embedded NotificationRequest may include a new list of
   RequestedEvents, SignalRequests and a new digit map as well.  The
   semantics of the embedded NotificationRequest is as if a new
   NotificationRequest was just received with the same NotifiedEntity,
   RequestIdentifier, QuarantineHandling and DetectEvents.  When the
   "Embedded NotificationRequest" is activated, the "current dial
   string" will be cleared; however the list of observed events and the
   quarantine buffer will be unaffected (if combined with a Notify, the
   Notify will clear the list of observed events though - see Section
   4.4.1).  Note, that the Embedded NotificationRequest action does not
   accumulate the triggering event, however it can be combined with the
   Accumulate action to achieve that.  If the Embedded
   NotificationRequest fails, an Embedded NotificationRequest failure
   event SHOULD be generated (see Appendix B).

   MGCP implementations SHALL be able to support at least one level of
   embedding.  An embedded NotificationRequest that respects this
   limitation MUST NOT contain another Embedded NotificationRequest.

   DigitMap is an optional parameter that allows the Call Agent to
   provision the endpoint with a digit map according to which digits
   will be accumulated.  If this optional parameter is absent, the
   previously defined value is retained.  This parameter MUST be
   defined, either explicitly or through a previous command, if the
   RequestedEvents parameter contains a request to "accumulate according
   to the digit map".  The collection of these digits will result in a
   digit string.  The digit string is initialized to a null string upon
   reception of the NotificationRequest, so that a subsequent
   notification only returns the digits that were collected after this
   request.  Digits that were accumulated according to the digit map are
   reported as any other accumulated event, in the order in which they
   occur.  It is therefore possible that other events accumulated are

Top      Up      ToC       Page 41 
   found in between the list of digits.  If the gateway is requested to
   "accumulate according to digit map" and the gateway currently does
   not have a digit map for the endpoint in question, the gateway MUST
   return an error (error code 519 - endpoint does not have a digit map,
   is RECOMMENDED).

   SignalRequests is an optional parameter that contains the set of
   signals that the gateway is asked to apply.  When omitted, it
   defaults to empty.  When multiple signals are specified, the signals
   MUST be applied in parallel.  Unless otherwise specified, signals are
   applied to the endpoint.  However some signals can be applied to a
   connection.  Signals are identified by their name, which is an event
   name, and may be qualified by signal parameters (see Section
   3.2.2.4).  The following are examples of signals:

   * Ringing,

   * Busy tone,

   * Call waiting tone,

   * Off hook warning tone,

   * Ringback tones on a connection.

   Names and descriptions of signals are defined in the appropriate
   package.

   Signals are, by default, applied to endpoints.  If a signal applied
   to an endpoint results in the generation of a media stream (audio,
   video, etc.), then by default the media stream MUST NOT be forwarded
   on any connection associated with that endpoint, regardless of the
   mode of the connection.  For example, if a call-waiting tone is
   applied to an endpoint involved in an active call, only the party
   using the endpoint in question will hear the call-waiting tone.
   However, individual signals may define a different behavior.

   When a signal is applied to a connection that has received a
   RemoteConnectionDescriptor, the media stream generated by that signal
   will be forwarded on the connection regardless of the current mode of
   the connection (including loopback and continuity test).  If a
   RemoteConnectionDescriptor has not been received, the gateway MUST
   return an error (error code 527 - missing RemoteConnectionDescriptor,
   is RECOMMENDED).  Note that this restriction does not apply to
   detecting events on a connection.

Top      Up      ToC       Page 42 
   When a (possibly empty) list of signal(s) is supplied, this list
   completely replaces the current list of active time-out signals.
   Currently active time-out signals that are not provided in the new
   list MUST be stopped and the new signal(s) provided will now become
   active.  Currently active time-out signals that are provided in the
   new list of signals MUST remain active without interruption, thus the
   timer for such time-out signals will not be affected.  Consequently,
   there is currently no way to restart the timer for a currently active
   time-out signal without turning the signal off first.  If the time-
   out signal is parameterized, the original set of parameters MUST
   remain in effect, regardless of what values are provided
   subsequently.  A given signal MUST NOT appear more than once in a
   SignalRequests.  Note that applying a signal S to an endpoint,
   connection C1 and connection C2, constitutes three different and
   independent signals.

   The action triggered by the SignalRequests is synchronized with the
   collection of events specified in the RequestedEvents parameter.  For
   example, if the NotificationRequest mandates "ringing" and the
   RequestedEvents asks to look for an "off-hook" event, the ringing
   SHALL stop as soon as the gateway detects an off-hook event.  The
   formal definition is that the generation of all "Time Out" signals
   SHALL stop as soon as one of the requested events is detected, unless
   the "Keep signals active" action is associated to the detected event.
   The RequestedEvents and SignalRequests may refer to the same event
   definitions.  In one case, the gateway is asked to detect the
   occurrence of the event, and in the other case it is asked to
   generate it.  The specific events and signals that a given endpoint
   can detect or perform are determined by the list of packages that are
   supported by that endpoint.  Each package specifies a list of events
   and signals that can be detected or performed.  A gateway that is
   requested to detect or perform an event belonging to a package that
   is not supported by the specified endpoint MUST return an error
   (error code 518 - unsupported or unknown package, is RECOMMENDED).
   When the event name is not qualified by a package name, the default
   package name for the endpoint is assumed.  If the event name is not
   registered in this default package, the gateway MUST return an error
   (error code 522 - no such event or signal, is RECOMMENDED).

   The Call Agent can send a NotificationRequest whose requested signal
   list is empty.  It will do so for example when a time-out signal(s)
   should stop.

   If signal(s) are desired to start as soon as a "looked-for" event
   occurs, the "Embedded NotificationRequest" action can be used.  The
   embedded NotificationRequest may include a new list of
   RequestedEvents, SignalRequests and a new Digit Map as well.  The
   embedded NotificationRequest action allows the Call Agent to set up a

Top      Up      ToC       Page 43 
   "mini-script" to be processed by the gateway immediately following
   the detection of the associated event.  Any SignalRequests specified
   in the embedded NotificationRequest will start immediately.
   Considerable care must be taken to prevent discrepancies between the
   Call Agent and the gateway.  However, long-term discrepancies should
   not occur as a new SignalRequests completely replaces the old list of
   active time-out signals, and BR-type signals always stop on their
   own.  Limiting the number of On/Off-type signals is encouraged.  It
   is considered good practice for a Call Agent to occasionally turn on
   all On/Off signals that should be on, and turn off all On/Off signals
   that should be off.

   The Ignore action can be used to ignore an event, e.g., to prevent a
   persistent event from being notified.  However, the synchronization
   between the event and an active time-out signal will still occur by
   default (e.g., a time-out dial-tone signal will stop when an off-hook
   occurs even if off-hook was a requested event with action "Ignore").
   To prevent this synchronization from happening, the "Keep Signal(s)
   Active" action will have to be specified as well.

   The optional QuarantineHandling parameter specifies the handling of
   "quarantine" events, i.e., events that have been detected by the
   gateway before the arrival of this NotificationRequest command, but
   have not yet been notified to the Call Agent.  The parameter provides
   a set of handling options (see Section 4.4.1 for details):

   * whether the quarantined events should be processed or discarded
     (the default is to process them).

   * whether the gateway is expected to generate at most one
     notification (step by step), or multiple notifications (loop), in
     response to this request (the default is at most one).

   When the parameter is absent, the default value is assumed.

   We should note that the quarantine-handling parameter also governs
   the handling of events that were detected and processed but not yet
   notified when the command is received.

   DetectEvents is an optional parameter, possibly qualified by event
   parameters, that specifies a list of events that the gateway is
   requested to detect during the quarantine period.  When this
   parameter is absent, the events to be detected in the quarantine
   period are those listed in the last received DetectEvents list.  In
   addition, the gateway will also detect persistent events and the
   events specified in the RequestedEvents list, including those for
   which the "ignore" action is specified.

Top      Up      ToC       Page 44 
   Some events and signals, such as the in-line ringback or the quality
   alert, are performed or detected on connections terminating in the
   endpoint rather than on the endpoint itself.  The structure of the
   event names (see Section 2.1.7) allows the Call Agent to specify the
   connection(s) on which the events should be performed or detected.

   The NotificationRequest command may carry an encapsulated
   EndpointConfiguration command, that will apply to the same
   endpoint(s).  When this command is present, the parameters of the
   EndpointConfiguration command are included with the normal parameters
   of the NotificationRequest, with the exception of the EndpointId,
   which is not replicated.

   The encapsulated EndpointConfiguration command shares the fate of the
   NotificationRequest command.  If the NotificationRequest is rejected,
   the EndpointConfiguration is not executed.

   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.4 Notify

   Notifications with the observed events are sent by the gateway via
   the Notify command when a triggering event occurs.

         ReturnCode,
         [PackageList]
         <-- Notify(EndpointId,
                    [NotifiedEntity,]
                    RequestIdentifier,
                    ObservedEvents)

   EndpointId is the name for the endpoint in the gateway which is
   issuing the Notify command.  The identifier MUST be a fully qualified
   endpoint identifier, including the domain name of the gateway.  The
   local part of the name MUST NOT use any of the wildcard conventions.

   NotifiedEntity is a parameter that identifies the entity which
   requested the notification.  This parameter is equal to the
   NotifiedEntity parameter of the NotificationRequest that triggered
   this notification.  The parameter is absent if there was no such
   parameter in the triggering request.  Regardless of the value of the
   NotifiedEntity parameter, the notification MUST be sent to the
   current "notified entity" for the endpoint.

Top      Up      ToC       Page 45 
   RequestIdentifier is a parameter that repeats the RequestIdentifier
   parameter of the NotificationRequest that triggered this
   notification.  It is used to correlate this notification with the
   request that triggered it.  Persistent events will be viewed here as
   if they had been included in the last NotificationRequest.  An
   implicit NotificationRequest MAY be in place right after restart -
   the RequestIdentifier used for it will be zero ("0") - see Section
   4.4.1 for details.

   ObservedEvents is a list of events that the gateway detected and
   accumulated.  A single notification may report a list of events that
   will be reported in the order in which they were detected (FIFO).

   The list will only contain the identification of events that were
   requested in the RequestedEvents parameter of the triggering
   NotificationRequest.  It will contain the events that were either
   accumulated (but not notified) or treated according to digit map (but
   no match yet), and the final event that triggered the notification or
   provided a final match in the digit map.  It should be noted that
   digits MUST be added to the list of observed events as they are
   accumulated, irrespective of whether they are accumulated according
   to the digit map or not.  For example, if a user enters the digits
   "1234" and some event E is accumulated between the digits "3" and "4"
   being entered, the list of observed events would be "1, 2, 3, E, 4".
   Events that were detected on a connection SHALL include the name of
   that connection as in "R/qa@0A3F58" (see Section 2.1.7).

   If the list of ObservedEvents reaches the capacity of the endpoint,
   an ObservedEvents Full event (see Appendix B) SHOULD be generated
   (the endpoint shall ensure it has capacity to include this event in
   the list of ObservedEvents).  If the ObservedEvents Full event is not
   used to trigger a Notify, event processing continues as before
   (including digit map matching); however, the subsequent events will
   not be included in the list of ObservedEvents.

   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.

   PackageList is a list of supported packages that MAY be included with
   error code 518 (unsupported package).

Top      Up      ToC       Page 46 
2.3.5 CreateConnection

   This command is used to create a connection between two endpoints.

         ReturnCode,
         [ConnectionId,]
         [SpecificEndPointId,]
         [LocalConnectionDescriptor,]
         [SecondEndPointId,]
         [SecondConnectionId,]
         [PackageList]
         <-- CreateConnection(CallId,
                              EndpointId,
                              [NotifiedEntity,]
                              [LocalConnectionOptions,]
                              Mode,
                              [{RemoteConnectionDescriptor |
                              SecondEndpointId}, ]
                              [Encapsulated NotificationRequest,]
                              [Encapsulated EndpointConfiguration])

   A connection is defined by its endpoints.  The input parameters in
   CreateConnection provide the data necessary to build a gateway's
   "view" of a connection.

   CallId is a parameter that identifies the call (or session) to which
   this connection belongs.  This parameter SHOULD, at a minimum, be
   unique within the collection of Call Agents that control the same
   gateways.  Connections that belong to the same call SHOULD share the
   same call-id.  The call-id has little semantic meaning in the
   protocol; however it can be used to identify calls for reporting and
   accounting purposes.  It does not affect the handling of connections
   by the gateway.

   EndpointId is the identifier for the connection endpoint in the
   gateway where CreateConnection executes.  The EndpointId can be
   fully-specified by assigning a value to the parameter EndpointId in
   the function call or it may be under-specified by using the "any of"
   wildcard convention.  If the endpoint is underspecified, the endpoint
   identifier SHALL be assigned by the gateway and its complete value
   returned in the SpecificEndPointId parameter of the response.  When
   the "any of" wildcard is used, the endpoint assigned MUST be in-
   service and MUST NOT already have any connections on it.  If no such
   endpoint is available, error code 410 (no endpoint available) SHOULD
   be returned.  The "all of" wildcard MUST NOT be used.

   The NotifiedEntity is an optional parameter that specifies a new
   "notified entity" for the endpoint.

Top      Up      ToC       Page 47 
   LocalConnectionOptions is an optional structure used by the Call
   Agent to direct the handling of the connection by the gateway.  The
   fields contained in a LocalConnectionOptions structure may include
   one or more of the following (each field MUST NOT be supplied more
   than once):

   * Codec compression algorithm:  One or more codecs, listed in order
     of preference.  For interoperability, it is RECOMMENDED to support
     G.711 mu-law encoding ("PCMU").  See Section 2.6 for details on the
     codec selection process.

   * Packetization period:  A single millisecond value or a range may be
     specified.  The packetization period SHOULD NOT contradict the
     specification of the codec compression algorithm.  If a codec is
     specified that has a frame size which is inconsistent with the
     packetization period, and that codec is selected, the gateway is
     authorized to use a packetization period that is consistent with
     the frame size even if it is different from that specified.  In so
     doing, the gateway SHOULD choose a non-zero packetization period as
     close to that specified as possible.  If a packetization period is
     not specified, the endpoint SHOULD use the default packetization
     period(s) for the codec(s) selected.

   * Bandwidth:  The allowable bandwidth, i.e., payload plus any header
     overhead from the transport layer and up, e.g., IP, UDP, and RTP.
     The bandwidth specification SHOULD NOT contradict the specification
     of codec compression algorithm or packetization period.  If a codec
     is specified, then the gateway is authorized to use it, even if it
     results in the usage of a larger bandwidth than specified.  Any
     discrepancy between the bandwidth and codec specification will not
     be reported as an error.

   * Type of Service:  This indicates the class of service to be used
     for this connection.  When the Type of Service is not specified,
     the gateway SHALL use a default value of zero unless provisioned
     otherwise.

   * Usage of echo cancellation:  By default, the telephony gateways
     always perform echo cancellation on the endpoint.  However, it may
     be necessary, for some calls, to turn off these operations.  The
     echo cancellation parameter can have two values, "on" (when the
     echo cancellation is requested) and "off" (when it is turned off).
     The parameter is optional.  If the parameter is omitted when
     creating a connection and there are no other connections on the
     endpoint, the endpoint SHALL apply echo cancellation initially.  If
     the parameter is omitted when creating a connection and there are
     existing connections on the endpoint, echo cancellation is
     unchanged.  The endpoint SHOULD subsequently enable or disable echo

Top      Up      ToC       Page 48 
     cancellation when voiceband data is detected - see e.g., ITU-T
     recommendation V.8, V.25, and G.168.  Following termination of
     voiceband data, the handling of echo cancellation SHALL then revert
     to the current value of the echo cancellation parameter.  It is
     RECOMMENDED that echo cancellation handling is left to the gateway
     rather than having this parameter specified by the Call Agent.

   * Silence Suppression:  The telephony gateways may perform voice
     activity detection, and avoid sending packets during periods of
     silence.  However, it is necessary, for example for modem calls, to
     turn off this detection.  The silence suppression parameter can
     have two values, "on" (when the detection is requested) and "off"
     (when it is not requested).  The default is "off" (unless
     provisioned otherwise).  Upon detecting voiceband data, the
     endpoint SHOULD disable silence suppression.  Following termination
     of voiceband data, the handling of silence suppression SHALL then
     revert to the current value of the silence suppression parameter.

   * Gain Control:  The telephony gateways may perform gain control on
     the endpoint, in order to adapt the level of the signal.  However,
     it is necessary, for example for some modem calls, to turn off this
     function.  The gain control parameter may either be specified as
     "automatic", or as an explicit number of decibels of gain.  The
     gain specified will be added to media sent out over the endpoint
     (as opposed to the connection) and subtracted from media received
     on the endpoint.  The parameter is optional.  When there are no
     other connections on the endpoint, and the parameter is omitted,
     the default is to not perform gain control (unless provisioned
     otherwise), which is equivalent to specifying a gain of 0 decibels.
     If there are other connections on the endpoint, and the parameter
     is omitted, gain control is unchanged.  Upon detecting voiceband
     data, the endpoint SHOULD disable gain control if needed.
     Following termination of voiceband data, the handling of gain
     control SHALL then revert to the current value of the gain control
     parameter.  It should be noted, that handling of gain control is
     normally best left to the gateway and hence use of this parameter
     is NOT RECOMMENDED.

   * RTP security:  The Call agent can request the gateway to enable
     encryption of the audio Packets.  It does so by providing a key
     specification, as specified in RFC 2327.  By default, encryption is
     not performed.

   * Network Type:  The Call Agent may instruct the gateway to prepare
     the connection on a specified type of network.  If absent, the
     value is based on the network type of the gateway being used.

Top      Up      ToC       Page 49 
   * Resource reservation:  The Call Agent may instruct the gateway to
     use network resource reservation for the connection.  See Section
     2.7 for details.

   The Call Agent specifies the relevant fields it cares about in the
   command and leaves the rest to the discretion of the gateway.  For
   those of the above parameters that were not explicitly included, the
   gateway SHOULD use the default values if possible.  For a detailed
   list of local connection options included with this specification
   refer to section 3.2.2.10.  The set of local connection options can
   be extended.

   The Mode indicates the mode of operation for this side of the
   connection.  The basic modes are "send", "receive", "send/receive",
   "conference", "inactive", "loopback", "continuity test", "network
   loop back" and "network continuity test".  The expected handling of
   these modes is specified in the introduction of the "Gateway Control
   Commands", Section 2.3.  Note that signals applied to a connection do
   not follow the connection mode.  Some endpoints may not be capable of
   supporting all modes.  If the command specifies a mode that the
   endpoint does not support, an error SHALL be returned (error 517 -
   unsupported mode, is RECOMMENDED).  Also, if a connection has not yet
   received a RemoteConnectionDescriptor, an error MUST be returned if
   the connection is attempted to be placed in any of the modes "send
   only", "send/receive", "conference", "network loopback", "network
   continuity test", or if a signal (as opposed to detecting an event)
   is to be applied to the connection (error code 527 - missing
   RemoteConnectionDescriptor, is RECOMMENDED).  The set of modes can be
   extended.

   The gateway returns a ConnectionId, that uniquely identifies the
   connection within the endpoint, and a LocalConnectionDescriptor,
   which is a session description that contains information about the
   connection, e.g., IP address and port for the media, as defined in
   SDP.

   The SpecificEndPointId is an optional parameter that identifies the
   responding endpoint.  It is returned when the EndpointId argument
   referred to an "any of" wildcard name and the command succeeded.
   When a SpecificEndPointId is returned, the Call Agent SHALL use it as
   the EndpointId value in successive commands referring to this
   connection.

   The SecondEndpointId can be used instead of the
   RemoteConnectionDescriptor to establish a connection between two
   endpoints located on the same gateway.  The connection is by
   definition a local connection.  The SecondEndpointId can be fully-
   specified by assigning a value to the parameter SecondEndpointId in

Top      Up      ToC       Page 50 
   the function call or it may be under-specified by using the "any of"
   wildcard convention.  If the SecondEndpointId is underspecified, the
   second endpoint identifier will be assigned by the gateway and its
   complete value returned in the SecondEndPointId parameter of the
   response.

   When a SecondEndpointId is specified, the command really creates two
   connections that can be manipulated separately through
   ModifyConnection and DeleteConnection commands.  In addition to the
   ConnectionId and LocalConnectionDescriptor for the first connection,
   the response to the creation provides a SecondConnectionId parameter
   that identifies the second connection.  The second connection is
   established in "send/receive" mode.

   After receiving a "CreateConnection" request that did not include a
   RemoteConnectionDescriptor parameter, a gateway is in an ambiguous
   situation.  Because it has exported a LocalConnectionDescriptor
   parameter, it can potentially receive packets.  Because it has not
   yet received the RemoteConnectionDescriptor parameter of the other
   gateway, it does not know whether the packets that it receives have
   been authorized by the Call Agent.  It must thus navigate between two
   risks, i.e., clipping some important announcements or listening to
   insane data.  The behavior of the gateway is determined by the value
   of the Mode parameter:

   * If the mode was set to ReceiveOnly, the gateway MUST accept the
     media and transmit them through the endpoint.

   * If the mode was set to Inactive, Loopback, or Continuity Test, the
     gateway MUST NOT transmit the media through to the endpoint.

   Note that the mode values SendReceive, Conference, SendOnly, Network
   Loopback and Network Continuity Test do not make sense in this
   situation.  They MUST be treated as errors, and the command MUST be
   rejected (error code 527 - missing RemoteConnectionDescriptor, is
   RECOMMENDED).

   The command may optionally contain an encapsulated Notification
   Request command, which applies to the EndpointId, in which case a
   RequestIdentifier parameter MUST be present, as well as, optionally,
   other parameters of the NotificationRequest with the exception of the
   EndpointId, which is not replicated.  The encapsulated
   NotificationRequest is executed simultaneously with the creation of
   the connection.  For example, when the Call Agent wants to initiate a
   call to a residential gateway, it could:

Top      Up      ToC       Page 51 
   * ask the residential gateway to prepare a connection, in order to be
     sure that the user can start speaking as soon as the phone goes off
     hook,

   * ask the residential gateway to start ringing,

   * ask the residential gateway to notify the Call Agent when the phone
     goes off-hook.

   This can be accomplished in a single CreateConnection command, by
   also transmitting the RequestedEvents parameters for the off-hook
   event, and the SignalRequests parameter for the ringing signal.

   When these parameters are present, the creation and the
   NotificationRequest MUST be synchronized, which means that both MUST
   be accepted, or both MUST be refused.  In our example, the
   CreateConnection may be refused if the gateway does not have
   sufficient resources, or cannot get adequate resources from the local
   network access, and the off-hook NotificationRequest can be refused
   in the glare condition, if the user is already off-hook.  In this
   example, the phone must not ring if the connection cannot be
   established, and the connection must not be established if the user
   is already off-hook.

   The NotifiedEntity parameter, if present, defines the new "notified
   entity" for the endpoint.

   The command may carry an encapsulated EndpointConfiguration command,
   which applies to the EndpointId.  When this command is present, the
   parameters of the EndpointConfiguration command are included with the
   normal parameters of the CreateConnection with the exception of the
   EndpointId, which is not replicated.  The EndpointConfiguration
   command may be encapsulated together with an encapsulated
   NotificationRequest command.  Note that both of these apply to the
   EndpointId only.

   The encapsulated EndpointConfiguration command shares the fate of the
   CreateConnection command.  If the CreateConnection is rejected, the
   EndpointConfiguration is not executed.

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

Top      Up      ToC       Page 52 
2.3.6 ModifyConnection

   This command is used to modify the characteristics of a gateway's
   "view" of a connection.  This "view" of the call includes both the
   local connection descriptor as well as the remote connection
   descriptor.

         ReturnCode,
         [LocalConnectionDescriptor,]
         [PackageList]
         <-- ModifyConnection(CallId,
                              EndpointId,
                              ConnectionId,
                              [NotifiedEntity,]
                              [LocalConnectionOptions,]
                              [Mode,]
                              [RemoteConnectionDescriptor,]
                              [Encapsulated NotificationRequest,]
                              [Encapsulated EndpointConfiguration])

   The parameters used are the same as in the CreateConnection command,
   with the addition of a ConnectionId that identifies the connection
   within the endpoint.  This parameter was returned by the
   CreateConnection command, in addition to the local connection
   descriptor.  It uniquely identifies the connection within the context
   of the endpoint.  The CallId used when the connection was created
   MUST be included as well.

   The EndpointId MUST be a fully qualified endpoint identifier.  The
   local name MUST NOT use the wildcard conventions.

   The ModifyConnection command can be used to affect parameters of a
   connection in the following ways:

   * Provide information about the other end of the connection, through
     the RemoteConnectionDescriptor.  If the parameter is omitted, it
     retains its current value.

   * Activate or deactivate the connection, by changing the value of the
     Mode parameter.  This can occur at any time during the connection,
     with arbitrary parameter values.  If the parameter is omitted, it
     retains its current value.

   * Change the parameters of the connection through the
     LocalConnectionOptions, for example by switching to a different
     coding scheme, changing the packetization period, or modifying the
     handling of echo cancellation.  If one or more
     LocalConnectionOptions parameters are omitted, then the gateway

Top      Up      ToC       Page 53 
     SHOULD refrain from changing that parameter from its current value,
     unless another parameter necessitating such a change is explicitly
     provided.  For example, a codec change might require a change in
     silence suppression.  Note that if a RemoteConnectionDescriptor is
     supplied, then only the LocalConnectionOptions actually supplied
     with the ModifyConnection command will affect the codec negotiation
     (as described in Section 2.6).

   Connections can only be fully activated if the
   RemoteConnectionDescriptor has been provided to the gateway.  The
   receive-only mode, however, can be activated without the provision of
   this descriptor.

   The command will only return a LocalConnectionDescriptor if the local
   connection parameters, such as RTP ports, were modified.  Thus, if,
   for example, only the mode of the connection is changed, a
   LocalConnectionDescriptor will not be returned.  Note however, that
   inclusion of LocalConnectionOptions in the command is not a
   prerequisite for local connection parameter changes to occur.  If a
   connection parameter is omitted, e.g., silence suppression, the old
   value of that parameter will be retained if possible.  If a parameter
   change necessitates a change in one or more unspecified parameters,
   the gateway is free to choose suitable values for the unspecified
   parameters that must change.  This can for instance happen if the
   packetization period was not specified.  If the new codec supported
   the old packetization period, the value of this parameter would not
   change, as a change would not be necessary.  However, if it did not
   support the old packetization period, it would choose a suitable
   value.

   The command may optionally contain an encapsulated Notification
   Request command, in which case a RequestIdentifier parameter MUST be
   present, as well as, optionally, other parameters of the
   NotificationRequest with the exception of the EndpointId, which is
   not replicated.  The encapsulated NotificationRequest is executed
   simultaneously with the modification of the connection.  For example,
   when a connection is accepted, the calling gateway should be
   instructed to place the circuit in send-receive mode and to stop
   providing ringing tones.  This can be accomplished in a single
   ModifyConnection command, by also transmitting the RequestedEvents
   parameters, for the on-hook event, and an empty SignalRequests
   parameter, to stop the provision of ringing tones.

   When these parameters are present, the modification and the
   NotificationRequest MUST be synchronized, which means that both MUST
   be accepted, or both MUST be refused.

Top      Up      ToC       Page 54 
   The NotifiedEntity parameter, if present, defines the new "notified
   entity" for the endpoint.

   The command may carry an encapsulated EndpointConfiguration command,
   that will apply to the same endpoint.  When this command is present,
   the parameters of the EndpointConfiguration command are included with
   the normal parameters of the ModifyConnection with the exception of
   the EndpointId, which is not replicated.  The EndpointConfiguration
   command may be encapsulated together with an encapsulated
   NotificationRequest command.

   The encapsulated EndpointConfiguration command shares the fate of the
   ModifyConnection command.  If the ModifyConnection is rejected, the
   EndpointConfiguration is not executed.

   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.7 DeleteConnection (from the Call Agent)

   This command is used to terminate a connection.  As a side effect, it
   collects statistics on the execution of the connection.

         ReturnCode,
         ConnectionParameters,
         [PackageList]
         <-- DeleteConnection(CallId,
                              EndpointId,
                              ConnectionId,
                              [NotifiedEntity,]
                              [Encapsulated NotificationRequest,]
                              [Encapsulated EndpointConfiguration])

   The endpoint identifier, in this form of the DeleteConnection
   command, SHALL be fully qualified.  Wildcard conventions SHALL NOT be
   used.

   The ConnectionId identifies the connection to be deleted.  The CallId
   used when the connection was created is included as well.

   The NotifiedEntity parameter, if present, defines the new "notified
   entity" for the endpoint.

Top      Up      ToC       Page 55 
   In the case of IP multicast, connections can be deleted individually
   and independently.  However, in the unicast case where a connection
   has two ends, a DeleteConnection command has to be sent to both
   gateways involved in the connection.  After the connection has been
   deleted, media streams previously supported by the connection are no
   longer available.  Any media packets received for the old connection
   are simply discarded and no new media packets for the stream are
   sent.

   After the connection has been deleted, any loopback that has been
   requested for the connection must be cancelled (unless the endpoint
   has another connection requesting loopback).

   In response to the DeleteConnection command, the gateway returns a
   list of connection parameters that describe statistics for the
   connection.

   When the connection was for an Internet media stream, these
   parameters are:

   Number of packets sent:

      The total number of media packets transmitted by the sender since
      starting transmission on this connection.  In the case of RTP, the
      count is not reset if the sender changes its synchronization
      source identifier (SSRC, as defined in RTP), for example as a
      result of a ModifyConnection command.  The value is zero if the
      connection was always set in "receive only" mode and no signals
      were applied to the connection.

   Number of octets sent:

      The total number of payload octets (i.e., not including header or
      padding) transmitted in media packets by the sender since starting
      transmission on this connection.  In the case of RTP, the count is
      not reset if the sender changes its SSRC identifier, for example
      as a result of a ModifyConnection command.  The value is zero if
      the connection was always set in "receive only" mode and no
      signals were applied to the connection.

   Number of packets received:

      The total number of media packets received by the sender since
      starting reception on this connection.  In the case of RTP, the
      count includes packets received from different SSRC, if the sender
      used several values.  The value is zero if the connection was
      always set in "send only" mode.

Top      Up      ToC       Page 56 
   Number of octets received:

      The total number of payload octets (i.e., not including header,
      e.g., RTP, or padding) transmitted in media packets by the sender
      since starting transmission on this connection.  In the case of
      RTP, the count includes packets received from different SSRC, if
      the sender used several values.  The value is zero if the
      connection was always set in "send only" mode.

   Number of packets lost:

      The total number of media packets that have been lost since the
      beginning of reception.  This number is defined to be the number
      of packets expected less the number of packets actually received,
      where the number of packets received includes any which are late
      or duplicates.  For RTP, the count includes packets received from
      different SSRC, if the sender used several values.  Thus packets
      that arrive late are not counted as lost, and the loss may be
      negative if there are duplicates.  The count includes packets
      received from different SSRC, if the sender used several values.
      The number of packets expected is defined to be the extended last
      sequence number received, as defined next, less the initial
      sequence number received.  The count includes packets received
      from different SSRC, if the sender used several values.  The value
      is zero if the connection was always set in "send only" mode.

   Interarrival jitter:

      An estimate of the statistical variance of the media packet
      interarrival time measured in milliseconds and expressed as an
      unsigned integer.  For RTP, the interarrival jitter J is defined
      to be the mean deviation (smoothed absolute value) of the
      difference D in packet spacing at the receiver compared to the
      sender for a pair of packets.  Detailed computation algorithms are
      found in RFC 1889.  The count includes packets received from
      different SSRC, if the sender used several values.  The value is
      zero if the connection was always set in "send only" mode.

   Average transmission delay:

      An estimate of the network latency, expressed in milliseconds. For
      RTP, this is the average value of the difference between the NTP
      timestamp indicated by the senders of the RTCP messages and the
      NTP timestamp of the receivers, measured when the messages are
      received.  The average is obtained by summing all the estimates,

Top      Up      ToC       Page 57 
      then dividing by the number of RTCP messages that have been
      received.  When the gateway's clock is not synchronized by NTP,
      the latency value can be computed as one half of the round trip
      delay, as measured through RTCP.  When the gateway cannot compute
      the one way delay or the round trip delay, the parameter conveys a
      null value.

   For a detailed definition of these variables, refer to RFC 1889.

   When the connection was set up over a LOCAL interconnect, the meaning
   of these parameters is defined as follows:

   Number of packets sent:
      Not significant - MAY be omitted.

   Number of octets sent:
      The total number of payload octets transmitted over the local
      connection.

   Number of packets received:
      Not significant - MAY be omitted.

   Number of octets received:
      The total number of payload octets received over the connection.

   Number of packets lost:
      Not significant - MAY be omitted.  A value of zero is assumed.

   Interarrival jitter:
      Not significant - MAY be omitted.  A value of zero is assumed.

   Average transmission delay:
      Not significant - MAY be omitted.  A value of zero is assumed.

   The set of connection parameters can be extended.  Also, the meaning
   may be further defined by other types of networks which MAY
   furthermore elect to not return all, or even any, of the above
   specified parameters.

   The command may optionally contain an encapsulated Notification
   Request command, in which case a RequestIdentifier parameter MUST be
   present, as well as, optionally, other parameters of the
   NotificationRequest with the exception of the EndpointId, which is
   not replicated.  The encapsulated NotificationRequest is executed
   simultaneously with the deletion of the connection.  For example,
   when a user hang-up is notified, the gateway should be instructed to
   delete the connection and to start looking for an off-hook event.

Top      Up      ToC       Page 58 
   This can be accomplished in a single DeleteConnection command, by
   also transmitting the RequestedEvents parameters, for the off-hook
   event, and an empty SignalRequests parameter.

   When these parameters are present, the DeleteConnection and the
   NotificationRequest must be synchronized, which means that both MUST
   be accepted, or both MUST be refused.

   The command may carry an encapsulated EndpointConfiguration command,
   that will apply to the same endpoint.  When this command is present,
   the parameters of the EndpointConfiguration command are included with
   the normal parameters of the DeleteConnection with the exception of
   the EndpointId, which is not replicated.  The EndpointConfiguration
   command may be encapsulated together with an encapsulated
   NotificationRequest command.

   The encapsulated EndpointConfiguration command shares the fate of the
   DeleteConnection command.  If the DeleteConnection is rejected, the
   EndpointConfiguration is not executed.

   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.8 DeleteConnection (from the gateway)

   In some rare circumstances, a gateway may have to clear a connection,
   for example because it has lost the resource associated with the
   connection, or because it has detected that the endpoint no longer is
   capable or willing to send or receive media.  The gateway may then
   terminate the connection by using a variant of the DeleteConnection
   command:

         ReturnCode,
         [PackageList]
         <-- DeleteConnection(CallId,
                              EndpointId,
                              ConnectionId,
                              ReasonCode,
                              Connection-parameters)

   The EndpointId, in this form of the DeleteConnection command, MUST be
   fully qualified.  Wildcard conventions MUST NOT be used.

Top      Up      ToC       Page 59 
   The ReasonCode is a text string starting with a numeric reason code
   and optionally followed by a descriptive text string.  The reason
   code indicates the cause of the DeleteConnection.  A list of reason
   codes can be found in Section 2.5.

   In addition to the call, endpoint and connection identifiers, the
   gateway will also send the connection parameters that would have been
   returned to the Call Agent in response to a DeleteConnection command.

   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.

   PackageList is a list of supported packages that MAY be included with
   error code 518 (unsupported package).

   Note that use of this command is generally discouraged and should
   only be done as a last resort.  If a connection can be sustained,
   deletion of it should be left to the discretion of the Call Agent
   which is in a far better position to make intelligent decisions in
   this area.

2.3.9 DeleteConnection (multiple connections from the Call Agent)

   A variation of the DeleteConnection function can be used by the Call
   Agent to delete multiple connections at the same time.  Note that
   encapsulating other commands with this variation of the
   DeleteConnection command is not permitted.  The command can be used
   to delete all connections that relate to a Call for an endpoint:

         ReturnCode,
         [PackageList]
         <-- DeleteConnection(CallId,
                              EndpointId)

   The EndpointId, in this form of the DeleteConnection command, MUST
   NOT use the "any of" wildcard.  All connections for the endpoint(s)
   with the CallId specified will be deleted.  Note that the command
   will still succeed if there were no connections with the CallId
   specified, as long as the EndpointId was valid.  However, if the
   EndpointId is invalid, the command will fail.  The command does not
   return any individual statistics or call parameters.

Top      Up      ToC       Page 60 
   It can also be used to delete all connections that terminate in a
   given endpoint:

         ReturnCode,
         [PackageList]
         <-- DeleteConnection(EndpointId)

   The EndpointId, in this form of the DeleteConnection command, MUST
   NOT use the "any of" wildcard.  Again, the command succeeds even if
   there were no connections on the endpoint(s).

   Finally, Call Agents can take advantage of the hierarchical structure
   of endpoint names to delete all the connections that belong to a
   group of endpoints.  In this case, the "local name" component of the
   EndpointId will be specified using the "all of" wildcarding
   convention.  The "any of" convention SHALL NOT be used.  For example,
   if endpoint names are structured as the combination of a physical
   interface name and a circuit number, as in "X35V3+A4/13", the Call
   Agent may replace the circuit number by the "all of" wild card
   character "*", as in "X35V3+A4/*".  This "wildcard" command instructs
   the gateway to delete all the connections that were attached to
   circuits connected to the physical interface "X35V3+A4".

   After all the connections have been deleted, any loopback that has
   been requested for the connections MUST be cancelled by the gateway.

   This command does not return any individual statistics or call
   parameters.

   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.10 AuditEndpoint

   The AuditEndPoint command can be used by the Call Agent to find out
   the status of a given endpoint.

Top      Up      ToC       Page 61 
         ReturnCode,
         EndPointIdList,|{
         [RequestedEvents,]
         [QuarantineHandling,]
         [DigitMap,]
         [SignalRequests,]
         [RequestIdentifier,]
         [NotifiedEntity,]
         [ConnectionIdentifiers,]
         [DetectEvents,]
         [ObservedEvents,]
         [EventStates,]
         [BearerInformation,]
         [RestartMethod,]
         [RestartDelay,]
         [ReasonCode,]
         [MaxMGCPDatagram,]
         [Capabilities]}
         [PackageList]
         <-- AuditEndPoint(EndpointId,
                           [RequestedInfo])

   The EndpointId identifies the endpoint(s) being audited.  The "any
   of" wildcard convention MUST NOT be used.

   The EndpointId identifies the endpoint(s) being audited.  The "all
   of" wildcard convention can be used to start auditing of a group of
   endpoints (regardless of their service-state).  If this convention is
   used, the gateway SHALL return the list of endpoint identifiers that
   match the wildcard in the EndPointIdList parameter, which is simply
   one or more SpecificEndpointIds (each supplied separately).  In the
   case where the "all of" wildcard is used, RequestedInfo SHOULD NOT be
   included (if it is included, it MUST be ignored).  Note that the use
   of the "all of" wildcard can potentially generate a large
   EndPointIdList.  If the resulting EndPointIdList is considered too
   large, the gateway returns an error (error code 533 - response too
   large, is RECOMMENDED).

   When a non-wildcard EndpointId is specified, the (possibly empty)
   RequestedInfo parameter describes the information that is requested
   for the EndpointId specified.  The following endpoint info can be
   audited with this command:

      RequestedEvents, DigitMap, SignalRequests, RequestIdentifier,
      QuarantineHandling, NotifiedEntity, ConnectionIdentifiers,
      DetectEvents, ObservedEvents, EventStates, BearerInformation,
      RestartMethod, RestartDelay, ReasonCode, PackageList,
      MaxMGCPDatagram, and Capabilities.

Top      Up      ToC       Page 62 
   The list may be extended by extension parameters.  The response will
   in turn include information about each of the items for which
   auditing info was requested.  Supported parameters with empty values
   MUST always be returned.  However, if an endpoint is queried about a
   parameter it does not understand, the endpoint MUST NOT generate an
   error; instead the parameter MUST be omitted from the response:

   * RequestedEvents: The current value of RequestedEvents the endpoint
     is using including the action(s) and event parameters associated
     with each event - if no actions are included, the default action is
     assumed. Persistent events are included in the list. If an embedded
     NotificationRequest is active, the RequestedEvents will reflect the
     events requested in the embedded NotificationRequest, not any
     surrounding RequestedEvents (whether embedded or not).

   * DigitMap:  The digit map the endpoint is currently using.  The
     parameter will be empty if the endpoint does not have a digit map.

   * SignalRequests:  A list of the; Time-Out signals that are currently
     active, On/Off signals that are currently "on" for the endpoint
     (with or without parameter), and any pending Brief signals.  Time-
     Out signals that have timed-out, and currently playing Brief
     signals are not included.  Any signal parameters included in the
     original SignalRequests will be included.

   * RequestIdentifier:  The RequestIdentifier for the last
     NotificationRequest received by this endpoint (includes
     NotificationRequests encapsulated in other commands).  If no
     NotificationRequest has been received since reboot/restart, the
     value zero will be returned.

   * QuarantineHandling:  The QuarantineHandling for the last
     NotificationRequest received by this endpoint.  If
     QuarantineHandling was not included, or no notification request has
     been received, the default values will be returned.

   * DetectEvents:  The value of the most recently received DetectEvents
     parameter plus any persistent events implemented by the endpoint.
     If no DetectEvents parameter has been received, the (possibly
     empty) list only includes persistent events.

   * NotifiedEntity:  The current "notified entity" for the endpoint.

   * ConnectionIdentifiers:  The list of ConnectionIdentifiers for all
     connections that currently exist for the specified endpoint.

   * ObservedEvents:  The current list of observed events for the
     endpoint.

Top      Up      ToC       Page 63 
   * EventStates:  For events that have auditable states associated with
     them, the event corresponding to the state the endpoint is in,
     e.g., off-hook if the endpoint is off-hook.  Note that the
     definition of the individual events will state if the event in
     question has an auditable state associated with it.

   * BearerInformation:  The value of the last received
     BearerInformation parameter for this endpoint (this includes the
     case where BearerInformation was provisioned).  The parameter will
     be empty if the endpoint has not received a BearerInformation
     parameter and a value was also not provisioned.

   * RestartMethod:  "restart" if the endpoint is in-service and
     operation is normal, or if the endpoint is in the process of
     becoming in-service (a non-zero RestartDelay will indicate the
     latter).  Otherwise, the value of the restart method parameter in
     the last RestartInProgress command issued (or should have been
     issued) by the endpoint.  Note that a "disconnected" endpoint will
     thus only report "disconnected" as long as it actually is
     disconnected, and "restart" will be reported once it is no longer
     disconnected.  Similarly, "cancel-graceful" will not be reported,
     but "graceful" might (see Section 4.4.5 for further details).

   * RestartDelay:  The value of the restart delay parameter if a
     RestartInProgress command was to be issued by the endpoint at the
     time of this response, or zero if the command would not include
     this parameter.

   * ReasonCode:  The value of the ReasonCode parameter in the last
     RestartInProgress or DeleteConnection command issued by the gateway
     for the endpoint, or the special value 000 if the endpoint's state
     is normal.

   * PackageList:  The packages supported by the endpoint including
     package version numbers.  For backwards compatibility, support for
     the parameter is OPTIONAL although implementations with package
     versions higher than zero SHOULD support it.

   * MaxMGCPDatagram:  The maximum size of an MGCP datagram in bytes
     that can be received by the endpoint (see Section 3.5.4).  The
     value excludes any lower layer overhead.  For backwards
     compatibility, support for this parameter is OPTIONAL.  The default
     maximum MGCP datagram size SHOULD be assumed if a value is not
     returned.

Top      Up      ToC       Page 64 
   * Capabilities:  The capabilities for the endpoint similar to the
     LocalConnectionOptions parameter and including packages and
     connection modes.  Extensions MAY be included as well.  If any
     unknown capabilities are reported, they MUST simply be ignored.  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 MUST return several capability sets, each of which may
     include:

     - Compression Algorithm:  A list of supported codecs.  The rest of
       the parameters in the capability set will apply to all codecs
       specified in this list.

     - Packetization Period:  A single value or a range may be
       specified.

     - Bandwidth:  A single value or a range corresponding to the range
       for packetization periods may be specified (assuming no silence
       suppression).

     - Echo Cancellation:  Whether echo cancellation is supported or not
       for the endpoint.

     - Silence Suppression:  Whether silence suppression is supported or
       not.

     - Gain Control:  Whether gain control is supported or not.

     - Type of Service:  Whether type of service is supported or not.

     - Resource Reservation:  Whether resource reservation is supported
       or not.

     - Security:  Whether media encryption is supported or not.

     - Type of network:  The type(s) of network supported.

     - Packages:  A list of packages supported.  The first package in
       the list will be the default package.

     - Modes:  A list of supported connection modes.

   The Call Agent may then decide to use the AuditConnection command to
   obtain further information about the connections.

   If no info was requested and the EndpointId refers to a valid
   endpoint (in-service or not), the gateway simply returns a positive
   acknowledgement.

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

   Note that PackageList MAY also be included with error code 518
   (unsupported package).



(page 65 continued on part 4)

Next RFC Part