(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 RFC2327. 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 RFC1889. 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 RFC1889.
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).
2.3.11 AuditConnection
The AuditConnection command can be used by the Call Agent to retrieve
the parameters attached to a connection.
ReturnCode,
[CallId,]
[NotifiedEntity,]
[LocalConnectionOptions,]
[Mode,]
[RemoteConnectionDescriptor,]
[LocalConnectionDescriptor,]
[ConnectionParameters,]
[PackageList]
<-- AuditConnection(EndpointId,
ConnectionId,
RequestedInfo)
The EndpointId parameter specifies the endpoint that handles the
connection. The wildcard conventions SHALL NOT be used.
The ConnectionId parameter is the identifier of the audited
connection, within the context of the specified endpoint.
The (possibly empty) RequestedInfo describes the information that is
requested for the ConnectionId within the EndpointId specified. The
following connection info can be audited with this command:
CallId, NotifiedEntity, LocalConnectionOptions, Mode,
RemoteConnectionDescriptor, LocalConnectionDescriptor,
ConnectionParameters
The AuditConnection response will in turn include information about
each of the items auditing info was requested for:
* CallId, the CallId for the call the connection belongs to.
* NotifiedEntity, the current "notified entity" for the Connection.
Note this is the same as the "notified entity" for the endpoint
(included here for backwards compatibility).
* LocalConnectionOptions, the most recent LocalConnectionOptions
parameters that was actually supplied for the connection (omitting
LocalConnectionOptions from a command thus does not change this
value). Note that default parameters omitted from the most recent
LocalConnectionOptions will not be included.
LocalConnectionOptions that retain their value across
ModifyConnection commands and which have been included in a
previous command for the connection are also included, regardless
of whether they were supplied in the most recent
LocalConnectionOptions or not.
* Mode, the current mode of the connection.
* RemoteConnectionDescriptor, the RemoteConnectionDescriptor that was
supplied to the gateway for the connection.
* LocalConnectionDescriptor, the LocalConnectionDescriptor the
gateway supplied for the connection.
* ConnectionParameters, the current values of the connection
parameters for the connection.
If no info was requested and the EndpointId is valid, the gateway
simply checks that the connection exists, and if so returns a
positive acknowledgement. Note, that by definition, the endpoint
must be in-service for this to happen, as out-of-service endpoints do
not have any connections.
ReturnCode is a parameter returned by the gateway. It indicates the
outcome of the command and consists of an integer number optionally
followed by commentary.
PackageList is a list of supported packages that MAY be included with
error code 518 (unsupported package).
2.3.12 RestartInProgress
The RestartInProgress command is used by the gateway to signal that
an endpoint, or a group of endpoints, is put in-service or out-of-
service.
ReturnCode,
[NotifiedEntity,]
[PackageList]
<-- RestartInProgress(EndPointId,
RestartMethod,
[RestartDelay,]
[ReasonCode])
The EndPointId identifies the endpoint(s) that are put in-service or
out-of-service. The "all of" wildcard convention may be used to
apply the command to a group of endpoints managed by the same Call
Agent, such as for example all endpoints that are attached to a
specified interface, or even all endpoints that are attached to a
given gateway. The "any of" wildcard convention SHALL NOT be used.
The RestartMethod parameter specifies the type of restart. The
following values have been defined:
* A "graceful" restart method indicates that the specified endpoints
will be taken out-of-service after the specified delay. The
established connections are not yet affected, but the Call Agent
SHOULD refrain from establishing new connections, and SHOULD try to
gracefully tear down the existing connections.
* A "forced" restart method indicates that the specified endpoints
are taken abruptly out-of-service. The established connections, if
any, are lost.
* A "restart" method indicates that service will be restored on the
endpoints after the specified "restart delay", i.e., the endpoints
will be in-service. The endpoints are in their clean default state
and there are no connections that are currently established on the
endpoints.
* A "disconnected" method indicates that the endpoint has become
disconnected and is now trying to establish connectivity (see
Section 4.4.7). The "restart delay" specifies the number of
seconds the endpoint has been disconnected. Established
connections are not affected.
* A "cancel-graceful" method indicates that a gateway is canceling a
previously issued "graceful" restart command. The endpoints are
still in-service.
The list of restart methods may be extended.
The optional "restart delay" parameter is expressed as a number of
seconds. If the number is absent, the delay value MUST be considered
null (i.e., zero). In the case of the "graceful" method, a null
delay indicates that the Call Agent SHOULD simply wait for the
natural termination of the existing connections, without establishing
new connections. The restart delay is always considered null in the
case of the "forced" and "cancel-graceful" methods, and hence the
"restart delay" parameter MUST NOT be used with these restart
methods. When the gateway sends a "restart" or "graceful"
RestartInProgress message with a non-zero restart delay, the gateway
SHOULD send an updated RestartInProgress message after the "restart
delay" has passed.
A restart delay of null for the "restart" method indicates that
service has already been restored. This typically will occur after
gateway startup/reboot. To mitigate the effects of a gateway IP
address change as a result of a re-boot, the Call Agent MAY wish to
either flush its DNS cache for the gateway's domain name or resolve
the gateway's domain name by querying the DNS regardless of the TTL
of a current DNS resource record for the restarted gateway.
The optional reason code parameter indicates the cause of the
restart.
Gateways SHOULD send a "graceful" or "forced" RestartInProgress
message (for the relevant endpoints) as a courtesy to the Call Agent
when they are taken out-of-service, e.g., by being shutdown, or taken
out-of-service by a network management system, however the Call Agent
cannot rely on always receiving such a message. Gateways MUST send a