the end of a digit map entry, instructs the gateway to only consider
that entry a match if the current dial string does not partially
match another entry. For example, given the digit map
([3-7]11|123xxxxxxx|[1-7]xxxxxxP|8xxxP)
and a current dial string of "1234567", we would not consider this a
match (as the rules in [1] would otherwise imply); however a current
dial string of "411" would be considered a match as usual. A current
dial string of "8234" would be considered a match since there is no
other partial match.
Note that the digit map letter "P" is not an event, but simply a
syntactic and semantic digit map extension. Thus, the "P" is not
included in the list of requested or observed events.
Support for this package is strongly RECOMMENDED.
2.8. Signal List Package
Package Name: SL
Version: 0
---------------------------------------------------------
| Symbol | Definition | R | S Duration |
|---------------------------------------------------------|
| oc | Operation Complete | x | |
| of | Operation Failure | x | |
| s(list) | Signal List | | TO variable |
---------------------------------------------------------
Operation Complete (oc):
This is the standard definition of operation complete from [1].
Operation Failure (of):
This is the standard definition of operation failure from [1].
Signal List(s(<list>)):
The <list> contains a comma-separated list of signals to be played
out. Each of the signals in <list> MUST be either of type BR or
type TO. Semantically, the signal list is still treated as a
single parameterized signal of type Time-Out though. The signals
in the list are played to completion one after the other in the
left to right order specified. The package for each signal in the
list must be specified. For example, to play out the DTMF digits
123456:
S: sl/s(d/1,d/2,d/3,d/4,d/5,d/6)
This will result in the DTMF digits 1, 2, 3, 4, 5 and 6 being
played out in order.
It is illegal to include an OO signal as one of the signals in the
list or to request recursive definitions (signal lists within
signal lists). If this or any other unsupported signal is
included, error code 538 (event/signal parameter error) MUST be
returned by the gateway.
Note that as the gateway plays the ordered list of signals, if it
encounters a TO signal with an infinite timeout, it will continue
to play that signal until the Signal List signal is stopped (i.e.,
other signals later in the list will never be played).
If the operation complete ("oc") event is requested, it will be
detected once, when the last signal in the list has been played
out (regardless of whether there are any TO signals in the list).
The operation complete event will only report the signal list name
itself, i.e., without the parameters supplied as in:
O: sl/oc(sl/s)
Should any of the signals in the signal list result in an error,
an operation failure event for the Signal List signal MUST be
generated. Only the signal list name will be included, thus it is
not possible to determine which of the signals in the signal list
actually failed.
Note that if an event occurs while the "SL/S" signal is playing,
the "SL/S" signal is stopped in the following manner:
* If the signal in the list that was playing at the time the
event occurred is of type BR, then the BR signal will be
played to completion and no other signals in the list will
be played.
* If the signal in the list that was playing at the time the
event occurred is of type TO, then the TO signal will stop
immediately and no other signals in the list will be played.
2.9. Media Format Parameter Package
Package Name: FM
Version: 0
This package provides support for the media format parameter Local
Connection Option (LCO). The media format parameter LCO is similar
to the "fmtp" attribute in SDP [15] and is applicable to all of the
same media formats that the corresponding SDP fmtp attribute could be
used with (i.e., media format parameters for any media format MIME
type). The media format parameter is encoded as the keyword "fmtp"
or "o-fmtp", followed by a colon and a quoted string beginning with
the media format name (MIME subtype only) followed by a space,
followed by the media format parameters associated with that media
format. For simplicity, we will use the terms "codec" and "media
format" interchangeably in the following. Multiple formats may be
indicated by either repeating the "fmtp" local connection option
multiple times, such as:
L:a:codec1;codec2, fmtp:"codec1 formatX", fmtp:"codec2 formatY"
or alternatively by having a single "fmtp" keyword followed by a
colon, and a semi-colon separated list of quoted strings for each
media format parameter, as in:
L:a:codec1;codec2, fmtp:"codec1 formatX";"codec2 formatY"
The two formats may be mixed.
If it is possible for the same codec to be requested with and without
the special "fmtp" format, the following could result:
L:a:codec1;codec1, fmtp:"codec1 formatX"
However, it would not be clear if the fmtp parameter was to be
applied to the first or the second occurrence of the codec. The
problem with that is, that codec ordering is important (i.e., codecs
are listed in preferred order), and the above syntax does not provide
a way to indicate if "formatX" is preferred (i.e., associated with
the first "codec1") or not (i.e., associated with the second
"codec1"). In order to resolve this dilemma, when the same codec is
requested with multiple formats, the codec name in the "fmtp" format
string is followed by a colon and an <order>, where <order> is a
number from one to N for N occurrences of the same codec in the codec
list i.e.:
L:a:codec1;codec1, fmtp:"codec1:2 formatX"
indicates that "formatX" is associated with the second instance of
"codec1" in the "a:codec1;codec1" list. If an invalid instance
number is supplied (e.g., instance 3 where there are only two
instances), then error code 524 - inconsistency in local connection
options will be returned.
Pre-pending "fmtp" with the string "o-" (i.e., "o-fmtp") indicates
that the format is optional. In that case, the gateway may decide
not to use the fmtp parameter specified, or only use it in part.
If the "fmtp" in an LCO is not optional (i.e., does not have "o-" in
front of it), and the LCO value is either not recognized or not
supported, then the associated codec is considered "not supported".
When auditing capabilities, the "fmtp" local connection option MUST
be returned with a semi-colon separated list of supported formats
and/or multiple independent "fmtp" parameters as in:
A: a:telephone-event, fmtp:"telephone-event 0-15,32-35",...
A: a:PCMU;G729, fmtp:"PCMU foo";"PCMU bar", fmtp:"G729 foobar",...
One example uses the media format parameter LCO in conjunction with
the media format "telephone-event", as defined in RFC 2833 [33]. If
the media format "telephone-event" is used without the "fmtp" media
format parameter, the DTMF digits (telephone events 0-15 from RFC
2833 [33]) are assumed - such practice is however discouraged. On
the other hand, the media format parameter LCO MAY be used to specify
the exact set of events that are being requested via RFC 2833 [33].
Example:
L: a:PCMU;telephone-event,fmtp:"telephone-event 16"
indicates that if telephone events are supported at all, then this
request is specifically for event 16.
In another case, the Call Agent may indicate that some format
parameters are "required", while others are optional. In the example
below, telephone events 0-15 are a "must", while telephone events 16,
70 and 71 are optional.
L: a:PCMU;telephone-event, o-fmtp:"telephone-event 16,70,71",
fmtp:"telephone-event 0-15"
If the gateway cannot support telephone events 0-15, it MUST NOT
include the "telephone-event" media format in the SDP in its
response. On the other hand, if it can support those telephone
events, it SHOULD indicate support for those events, as well as any
of the events 16, 70 and 71 that it supports.
If a request is made to audit the capabilities of an endpoint, and
the endpoint supports the "telephone event" media format with events
"0-16", then the audit would include the following:
A: a:telephone-event, fmtp: "telephone-event 0-16"
Another example is the use of redundancy with RFC 2198 [32]. Again,
the format of the fmtp string is similar to that used in the SDP
except that the literal string ("red" in this case) is used rather
than the payload type:
L: a:G729;pcmu;red,fmtp:"red pcmu/g729"
The corresponding media description in the SDP as part of the
connection request acknowledgment might look like:
m=audio 12345 RTP/AVP 98 18 0
a=rtpmap:98 red/8000/1
a=fmtp:98 0/18
If we combine both telephone events and redundancy, an example local
connection option might look as follows (carriage return added for
formatting reasons here):
L: a:G729;pcmu;red;telephone-event,fmtp:"red pcmu/g729",
fmtp: "telephone-event 16"
Note that we again specify the literal string for the encoding method
rather than its payload type. This is a general principle that
should be used with this LocalConnectionOption.
The corresponding SDP might appear as follows:
m=audio 12345 RTP/AVP 97 98 18 0
a=rtpmap:97 red/8000/1
a=fmtp:97 0/18
a=rtpmap:98 telephone event
a=fmtp:98 16
Note that the fmtp LCO may be used in any situation where the
corresponding SDP attribute may be used. An example of a local
connection option that involves a media type other than audio and a
"foobar" fmtp parameter:
L: a:image/tiff, fmtp:"tiff foobar"
Note that normally local connection options that are associated with
a package should have the package prefix included as per the package
extension rules in [1]. The "fmtp" and "o-fmtp" LCO in the "FM"
package are an exception. The package prefix is not included in the
case of the "fmtp" and "o-fmtp" local connection options because they
were created before the extension rules in [1] were defined.
These two LocalConnectionOptions have been registered with IANA.
2.10. RTP Package
Package Name: R
Version: 1
-------------------------------------------------------------
| Symbol | Definition | R | S Duration |
|-------------------------------------------------------------|
| co1 | Continuity Tone (single | C | TO,C 3 sec. |
| | or return tone) | | |
| co2 | Continuity Test (go tone, | C | TO,C 3 sec. |
| | in dual tone procedures) | | |
| iu(..) | ICMP Unreachable | C | |
| | Received | | |
| ji(..) | Jitter Buffer Size Changed | C | |
| ma | Media Start | C | |
| oc | Operation Complete | x | |
| of | Operation Failure | x | |
| pl(..) | Packet Loss Exceeded | C | |
| qa | Quality Alert | C | |
| rto(..) | RTP/RTCP Timeout | C | |
| sr | Sampling Rate Changed | C | |
| uc | Used Codec Changed | C | |
-------------------------------------------------------------
Changes in event types: "co1" and "co2" signals changed from OO to
TO.
New events added to this package from the previously unversioned
package: "iu", "rto", "ma".
Note that default time-out values may be over-ridden by the Call
Agent for any Time-Out signal defined in this package by a "to"
signal parameter. Refer to section 2 of this document, as well as
[1] for details.
The events in this package all refer to media streams (connections),
i.e., they cannot be detected on an endpoint. Furthermore, with the
exception of the "iu" event, which is defined for any type of media,
all other events in this package are defined for RTP media streams
only (i.e., if they are used on connections that do not use RTP, the
behavior is not defined).
Signals requested (e.g., "co1" and "co2") must indicate the
connection ID (e.g., "S: r/co1@connectionID"). An event may be
requested for all existing connections using the "*" wildcard for the
connectionID as described in [1].
Example:
R: r/uc@* (request to detect uc on all connections) or
R: r/uc@connectionID (request to detect uc only on a specific
connection)
An event detected on a connection will include the connectionID,
e.g.:
O: r/uc@connectionID(15)
Continuity tones (co1 and co2):
These are the same as the events defined in the Trunk package,
except in this case, they are only played over a network
connection and the connectionID MUST be supplied (e.g., "s:
r/co1@connectionID"). They can be used in conjunction with the
Network LoopBack (netwloop) or Network Continuity Test (netwtest)
modes to test the continuity of an RTP circuit. However, in the
case of testing IP continuity, a one-tone test is sufficient i.e.,
generating and detecting "co1" at one end, with connection mode in
network loopback mode at the other end. Note that the test can
also be done using telephone events rather than tones, i.e., event
167 in RFC 2833 [33] corresponds to "co1". In this case,
connection requests are made with local connection options such
as:
L: a:PCMU;telephone-event,fmtp:"telephone-event 167"
in order to request support for telephone event 167. If both ends
support the event, then the network loopback proceeds as usual,
except that telephone events corresponding to the co1 tone are
sent, as opposed to the co1 tone itself.
ICMP Unreachable Received (iu):
This event indicates that some number of ICMP unreachable packets
[19] was received for this connection since an RQNT was received
requesting this event. This notification indicates that packets
that were sent by the gateway on this connection either did not
arrive at their destination or were not accepted (e.g., the port
was closed). When this event is requested, a single parameter
with a decimal number from 1 to 255 may be included to indicate
the number of ICMP un-reachable packets that must occur before the
event is notified. If no parameter is supplied, with the request
then a default value of 3 is assumed. This is a one-shot event in
that once the event occurs, a further request is required in order
to re-initiate counting.
The observed event is parameterized with two parameters:
* The first parameter is the number of ICMP unreachable
packets received (i.e., the same value that was included in
the request - or the value 3, if the requested event was not
parameterized)
* The second parameter is the error code indicated in the ICMP
unreachable packet, e.g.:
0 = net unreachable;
1 = host unreachable;
2 = protocol unreachable;
3 = port unreachable;
4 = fragmentation needed and DF set;
5 = source route failed.
etc.
An example of a request might be as follows:
RQNT 2001 ds/ds1-3/6@gw-o.whatever.net MGCP 1.0
X: 0123456789B0
R: r/iu@364823(N)(5)
In this case, a notify will occur if 5 ICMP port unreachable
packets are received as a result of RTP and/or RTCP packets being
sent from this gateway on the connection with connection ID
364823.
The resulting NTFY with observed events might be as follows:
NTFY 3002 ds/ds1-3/6@gw-o.whatever.net MGCP 1.0
X: 0123456789B0
O: r/iu@364823(5,3)
The first parameter indicates 5 ICMP unreachable packets were
received since the RQNT with this request was sent. The second
parameter ("3") specifies the reason, which in this case, is "port
unreachable".
Jitter Buffer Size Changed (ji):
This event is only included here to maintain compatibility with
the previous version of this package. This event is used to
indicate that the gateway has made an adjustment to the depth of
the jitter buffer. The syntax for requesting notification is
"ji", which tells the media gateway that the controller wants
notification of any jitter buffer size changes. The syntax for
notification from the media gateway to the controller is
"JI(####)", where the #### is a decimal number from 1 to 65536,
indicating the new size of the jitter buffer in milliseconds.
Media Start (ma):
The media start event occurs on a connection when the first valid
RTP media packet is received on the connection. This event can be
used to synchronize a local signal, e.g., ringback, with the
arrival of media from the other party.
The event is detected on a connection. If no connection is
specified, the event applies to all connections for the endpoint,
regardless of when the connections are created (i.e., if a
connection is not specified, the event will occur when the first
valid RTP packet arrives on any one of the connections on that
endpoint).
Operation complete (oc):
This is the standard definition of operation complete [1].
Operation failure (of):
This is the standard definition of operation failure [1].
Packet Loss Exceeded (pl):
Packet loss rate exceeds the threshold of the specified decimal
number (with a range of 1 to 100,000) of packets per 100,000
packets, where the packet loss number is indicated in parenthesis.
For example, PL(10) is a drop rate of 10 in 100,000 packets. This
event is requested with a parameter indicating at what packet loss
rate the Call Agent wishes to be reported. If the packet loss
exceeds that value, the event is reported with that same
parameter. The event is only reported once when the packet loss
threshold is exceeded. Once reported, a following request will
re-initiate packet loss measurements and report when the threshold
is exceeded again.
Quality alert (qa):
The packet loss rate or the combination of delay and jitter
exceeding a quality threshold. The quality thresholds for delay,
jitter and packet loss rate are provisioned values.
RTP/RTCP Timeout (rto(<timeout>,st=<start-time>)):
This event indicates that neither RTP nor RTCP packets have been
received on this connection for a period of time equal to the
<timeout> value (in seconds). The timeout value can be supplied
as a decimal number from 1 to 65535 in the parameter when the
request is made. The <timeout> parameter will be supplied in
ObservedEvents when the event is reported - it then simply repeats
the value used. If an RTP or RTCP packet is received before the
timer expires, then the timer is reset and re-started. The event
will only be generated if the timer expires without an RTP or RTCP
packet arriving on the specified connection during the specified
period of time. Note that if the event is requested without the
<timeout> parameter, then a default timeout of 60 seconds is
assumed. The <timeout> value will still be reported in
ObservedEvents, even if no timeout value was indicated in the
request (the default value will be indicated in that case). This
is a one-shot event in that once the event occurs, a further
request is required in order to re-initialize the timer.
Another optional <start-time> parameter may also be included.
This is used to indicate when the timer starts. It can have one
of the following values:
* "im" for immediate i.e., the timer starts as soon as the
request is received. This is the default.
* "ra" to indicate that the timer should start only after an
RTCP packet has been received from the other end (i.e., the
timer will be initiated when the first RTCP packet is
received after the request is made). Note that in the case
where the other end does not support RTCP, the timer will
never be initiated.
Note that either the <timeout> or <start-time> may be included in
the request, but only the <timeout> value is included in the
report.
An example of a request might be as follows:
RQNT 2001 ds/ds1-3/6@gw-o.whatever.net MGCP 1.0
X: 0123456789B0
R: r/rto@364823(N)(120,st=im)
In this case, a notify will occur if there is a period of time
when no RTP or RTCP packets have been received on connection
364823 for 120 seconds.
The resulting NTFY with observed events would be as follows:
NTFY 3002 ds/ds1-3/6@gw-o.whatever.net MGCP 1.0
X: 0123456789B0
O: r/rto@364823(120)
Sampling Rate Changed (sr):