RFC 3435
Media Gateway Control Protocol (MGCP) Version 1.0
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.
* 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
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
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).
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,
* 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
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
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
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.
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
"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.
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.
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).
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.
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
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.
* 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
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:
* 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).
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
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.
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.
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.
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,
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.
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.
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.
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.
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.
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.
* 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.
* 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.
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)
