This event is only included here to maintain compatibility with
the previous version of this package. This event indicates that
the packetization period changed to some decimal number in
milliseconds enclosed in parenthesis, as in SR(20).
Used Codec Changed (uc):
This event is only included here to maintain compatibility with
the previous version of this package. This event is requested
without a parameter, but when reported, the hexadecimal payload
type is enclosed in parenthesis, as in UC(8), to indicate the
codec was changed to PCM A-law. Codec Numbers are specified in
RFC 3551 [26], or in a new definition of the audio profiles for
RTP that replaces this RFC.
2.11. Resource Reservation Package
Package Name: RES
Version: 0
2.11.1. Description
The "RES" package provides local connection option support for
resource reservations as well as an event to indicate reservation
loss.
A number of LocalConnectionOption parameters are used in doing
resource reservations: "reservation request", "reservation
direction", "reservation confirmation" and "resource sharing".
Reservation Request LocalConnectionOption: The gateways can be
instructed to perform a reservation on a given connection using RSVP.
When a reservation is needed, the Call Agent will specify the
reservation profile that should be used, which is either "controlled
load" or "guaranteed service". The absence of reservation can be
indicated by asking for the "best effort" service, which is the
default value for this parameter.
Whether or not RSVP will be done is dependent on whether the
reservation request LocalConnectionOption parameter has been included
in a connection request for this connection (with either "controlled
load" or "guaranteed service" indicated). If a modify connection
(MDCX) request requires a change in the reservation and the
"reservation request" parameter is not included in the
LocalConnectionOptions, but was included in the
LocalConnectionOptions for a previous connection request for that
connection, then the "reservation request" value defaults to its
previously saved value for that connection. If a modify connection
(MDCX) request explicitly contains a "reservation request",
indicating a request for "best effort" for a connection that has an
existing reservation, the existing reservation will be torn down.
Reservation Direction LocalConnectionOption:
When reservation has been requested on a connection, the gateway
will examine the reservation direction LocalConnectionOption
parameter to determine the direction that the reservations require
and do the following:
* Start emitting RSVP "PATH" messages if the reservation
direction LocalConnectionOptions parameter specified "send-
only" or "send-receive".
* Start emitting RSVP "RESV" messages as soon as it receives
"PATH" messages if the reservation direction parameter
specified "receive-only" or "send-receive".
If an RSVP reservation is requested, but the reservation direction
LocalConnectionOption parameter is missing, the reservation
direction defaults to the previously saved value of the
reservation direction parameter for that connection. If there was
no previous reservation direction parameter for that connection,
the value is deduced from the connection mode. That is:
* Start emitting RSVP "PATH" messages if the connection is in
"send-only", "send-receive", "conference", "network loop
back" or "network continuity test" mode (if a remote
connection descriptor has been received).
* Start emitting RSVP "RESV" messages as soon as it receives
"PATH" messages if the connection is in "receive-only",
"send-receive", "conference", "network loop back" or
"network continuity test" mode.
Reservation Confirmation LocalConnectionOption:
Another LocalConnectionOption parameter for RSVP reservations is
the reservation confirmation parameter, which determines what the
resource reservation pre-condition (see [1]) is for acknowledging
a successful connection request:
* If the reservation confirmation parameter is set to "none",
the gateway will "Ack" the connection request without
waiting for reservation completion. This is the default
behavior.
* If the "reservation confirmation" parameter is set to
"send-only", the gateway will "Ack" when the PATH message
has been sent and the corresponding RESV is received to
indicate successful reservation in the send direction.
* If the "reservation confirmation" parameter is set to
"receive-only", the gateway will "Ack" when reservation
confirm for a reservation has been received.
* If the reservation confirmation parameter is set to "send-
receive", the gateway will "Ack" only after the PATH message
has been sent and the corresponding RESV has been received
for send direction, and reservation confirm has been
received for the receive direction.
Note that:
Values "receive-only" and "send-receive" are triggers for the
gateway to request reservation confirm (RESVCONF) when it sends
out the RESV.
Pre-conditions SHOULD only be added for the direction(s) for which
resource reservations have been requested. If a direction is
added as a pre-condition, and that direction was not requested in
the resource reservation, the direction MUST simply be ignored as
a pre-condition.
In this approach, resource reservation success is the pre-
condition to final acknowledgement of the connection request. If
the reservation fails, the connection request also fails (error
code 404 - insufficient bandwidth) - as will any other part of the
transaction, e.g., a notification request included as part of the
connection request. A typical example of this would be a request
to ring the phone and look for off-hook, included with the
connection request. If the reservation fails, the phone will not
ring. Similarly, if the phone is already off-hook, the command
fails and there will be no resource reservation.
A provisional response SHOULD be provided if confirmation is
expected to occur outside the normal retry timers and in fact a
provisional response MUST be provided if the reservation
confirmation parameter has value "send-receive" (without a
provisional response, SDP information cannot be returned until the
final "Ack" which will not occur until the reservation is
complete. This can result in a deadlock since the SDP information
typically needs to be passed to the other end in order for it to
initiate the RSVP PATH message in the other direction). The SDP
information and connectionID MUST be included in both the
provisional response and the final response. Note that in order
to ensure rapid detection of a lost final response, final
responses issued after provisional responses for a transaction
SHALL be acknowledged, i.e., they SHALL include an empty
"ResponseAck" parameter in the final response (see [1]).
If the transaction time is outside the expected bounds (time
T-HIST - see the section on provisional responses in [1]), error
code 406 (transaction timeout) SHOULD be returned.
Also note that if the reservation confirmation parameter is
omitted, the value of the reservation confirmation parameter
defaults to its previously saved value. If there is no previously
saved value for the reservation confirmation parameter, or the
reservation confirmation parameter has the value "none", then
successful resource reservation is not a pre-condition to
providing an acknowledgement to the connection request (i.e., the
gateway can "Ack" right away without waiting for the reservation
to complete and a provisional response will not be necessary).
Resource Sharing LocalConnectionOption:
It may be possible to share network resources across multiple
connections. An example is a call-waiting scenario, where only
one connection will ever be active at a time. In a 3-way calling
scenario with a similar set of connections, sharing is not
possible. Only the Call Agent knows what may be possible,
depending on the feature that is being invoked.
In order to allow the Call Agent to indicate that sharing is
possible, a resource sharing LocalConnectionOption parameter is
introduced. This parameter can have one of the following values:
* A value "$" can be specified where $ refers to "this
connection". This value is used when doing a create
connection and indicates the intent to share resources with
this connection.
* A connection ID can be specified which indicates that this
is a request to share resources with the connection having
this connection ID (allowing multiple connections to share
resources with the connection indicated).
* The value can be empty, which indicates a request to no
longer share the resources of this connection with other
connections.
In the case of a CRCX, the default value for the resource sharing
local connection option is empty, and for an MDCX, the default
value is its current value.
The RSVP filters will be deduced from the characteristics of the
connection. The RSVP resource profiles will be deduced from the
connection’s bandwidth and packetization period.
Note that if RSVP is used with PacketCable Dynamic Quality of Service
[35], then the parameters in NCS [36] would be used instead of the
reservation direction, confirmation and reservation sharing
parameters described here.
2.11.2. Parameter Encoding
The Local Connection Options for the "RES" package consist of the
following:
* The resource reservation parameter, encoded as the keyword "r",
followed by a colon and the value "g" (guaranteed service),
"cl" (controlled load) or "be" (best effort).
* The reservation direction parameter, encoded as the keyword
"r-dir" followed by a colon and the value "sendonly",
"recvonly" or "sendrecv".
* The reservation confirmation parameter, encoded as the keyword
"r-cnf" followed by a colon and the value "none", "sendonly",
"recvonly" or "sendrecv".
* The resource sharing parameter, encoded as the keyword "r-sh"
followed by a colon and either:
* The wild-card character "$" indicating this connection,
indicating future plans to share resources with this
connection, or
* A connection ID, indicating a request to share resources
with the connection having the specified connection ID
(and all other connections sharing resources with that
connection), or
* An empty value (i.e., "r-sh:" with no value indicated),
indicating a request to no longer share the resources of
this connection with other connections
Note that normally local connection options that are associated with
a package have the package prefix included as per the package
extension rules in [1]. The local connection options in the "RES"
package are exceptions. The package prefix is not included in the
case of the "RES" package because it was created before the extension
rules in [1] were defined.
2.11.3. Events
The following events are included as part of the resource reservation
package:
------------------------------------------------------
| Symbol | Definition | R | S Duration |
|------------------------------------------------------|
| re | Resource Error | C | |
| rl | Resource Lost | C | |
------------------------------------------------------
Resource Error (re):
This is an indication that an error in the resource reservation
occurred during the life of the connection. This event is not
requested with a parameter, but is reported with a parameter (see
possible values below). This event may or may not indicate the
permanent loss of the reservation (i.e., any error associated with
the reservation whether permanent or temporary will be reported).
If requested on an endpoint (without specifying the connection
ID), the request refers to all present and future connections on
that endpoint. When reported, the connectionID is always supplied
along with a reason for the error indicated as a parameter. One
of the following possible reasons for loss MUST be included as the
parameter when the event is reported:
- "resverr" is used to indicate that a ResvErr message was
received.
- "patherr" is used to indicate that a PathErr message was
received.
- "other"
In addition to a parameter indicating one of the reasons above,
additional information on the type of error MAY be included as a
second parameter in the form of a quoted string.
Example report might include:
O: res/rl@0A3F58(resverr)
or
O: res/rl@0A3F58(resverr, "some additional commentary")
Note that this event will not be reported if an error occurs while
a resource reservation is initially being set up (i.e., the event
was only reported as a result of an error that occurred after the
reservation was set up).
Resource Lost (rl):
Loss of reservation during the life of a connection can be
reported by using the "rl" event. This event is not requested
with a parameter, but is reported with a parameter (see below for
possible values). If requested on an endpoint (without specifying
the connection ID), the request refers to all present and future
connections on that endpoint.
When reported, the connectionID is always supplied along with a
reason for the loss indicated as a parameter. One of the
following possible reasons for loss MUST be supplied as the
parameter when the event is reported:
- "resvtear" indicating that the reservation loss was
indicated by ResvTear message.
- "pathtear" indicating that the reservation loss was
indicated by PathTear message.
- "other"
In addition to a parameter indicating one of the reasons above,
additional information on the type of error MAY be included as a
second parameter in the form of a quoted string.
Example report might include:
O: res/rl@0A3F58(ResvTear)
or
O: res/rl@0A3F58(ResvTear, "some other commentary")
Note that this event will not be reported if an error occurs while
a resource reservation is initially being set up (i.e., the event
is only reported if the reservation was lost after it was
initially set up).
2.12. Announcement Server Package
Package Name: A
Version: 1
---------------------------------------------------------------
| Symbol | Definition | R | S Duration |
|---------------------------------------------------------------|
| ann(url) | Play an Announcement | | TO, C variable |
| oc | Operation Complete | x | |
| of | Operation Failure | x | |
---------------------------------------------------------------
Changes from the previous version: change to conform to standard
reporting of operation failure and operation complete events.
The announcement signal is qualified by a URL name:
S: ann(http://scripts.example.net/all-lines-busy.au)
The URL name MAY be followed by a list of initial parameters,
separated by commas. However, standard parameters are not included
as part of this package definition (Note: use of additional
parameters is optional and would result in a proprietary interface).
The gateway SHOULD support one or more standard URL schemes such as:
* file, http, ftp (RFC 1738 [28]), which indicate where the audio
file is located (where to load the file from before playing the
audio file on the gateway).
* RTSP URL (section 3.2 of RFC 2326 [29]), which in this case
allows the media gateway to directly initiate playing of the
announcement via an RTSP server.
The pre-condition for a successful response (return code of "200") is
correct syntax and capability (support is available for this
request). Standard MGCP return codes apply in the case of failure.
Further indications of failure are provided in the operation failure
event as a comment after the name of the failed event in the form of
a quoted string.
If the announcement cannot be played out for a reason determined
after a successful response to the request has been provided, an
operation failure event will be returned. The failure MAY be
explained by some commentary (in the form of a quoted string), as in:
O: a/of(a/ann,"file not found")
The "operation complete" event will be detected when the announcement
is played out.
O: a/oc(a/ann)
2.13. Script Package
Package Name: Script
Version: 1
-----------------------------------------------------------------
| Symbol | Definition | R | S | Duration |
|-----------------------------------------------------------------|
| ir(..) | Intermediate Results/Req.| x | BR | |
| java(url,...) | Load & Run java script | | TO | variable |
| oc | operation complete | x | | |
| of | operation failure | x | | |
| perl(url,...) | Load & Run perl script | | TO | variable |
| tcl(url,...) | Load & Run TCL script | | TO | variable |
| vxml(url,...) | Load & Run VXML doc. | | TO | variable |
| xml(url,...) | Load & Run XML script | | TO | variable |
-----------------------------------------------------------------
Changes from the previous version of the package: "vxml" was added as
a language type for loading and running VXML documents; change to
conform with standard reporting of operation failure and operation
complete events; addition of "ir" event.
The current definition defines keywords for the most common
languages. More languages may be defined in later versions of this
package.
The "signal" specifying the scripting language is parameterized with
a URL indicating the location of the script. The URL parameter MAY
be optionally followed by a comma-separated list of arguments as
initial parameters to use in running the script. URL schemes may
include file ftp, or http schemes with syntax according to RFC 2396
[30]. As an example:
S: script/vxml(ftp://ftp.example.net/credit-card.vxml,arg1,arg2,
...,argn)
The argument list "arg1,arg2,...,argn" is passed to the
script/document as a list of initial parameters.
The pre-condition for a successful response (return code of "200") is
correct syntax and capability (support is available for this
request). Standard MGCP return codes apply in the case of failure.
Some further (non-application/script specific) failure indications
MAY be provided in the operation failure event as a comment in the
form of a quoted string following the name of the failed event.
Example
O: script/of(script/vxml,"file not found")
The script produces an output, which consists of one or several text
strings, separated by commas. This provides the return-status of the
script as well as return parameters (if there are any)
O: script/oc(script/vxml,return-status=<status>,
name1=value1,name2=value2,...)
where <status> can have one of the values "success" or "failure".
This is then followed by output parameters as a comma-separated list
of name-value pairs.
Intermediate Result/Request (ir(<params>)):
This provides a way for:
* The script to inform the Call Agent of intermediate results
(e.g., a case where it is important because of timing
concerns to inform the Call Agent prior to operation
complete).
* The script to request some information from the Call Agent.
* The Call Agent to inform the script of some event or
information that may be important for the operation of the
script (in this case "ir" is used as a signal).
Parameters (i.e., <params>) SHOULD be a comma-separated list of
name-value pairs e.g., ir(name1=value1,name2=value2,..). The Call
Agent MAY include event parameters when it requests this event, in
which case, the MGCP syntax requirements require that the action
be specified (e.g., "R: ir(N)(nam1=value1,name2=value2,..)").
If the Call Agent requests "ir" as a signal, at least one
parameter MUST be provided.
When requesting the "ir" signal, the Call Agent MUST also repeat
the original script signal. This is in order to be consistent
with the semantics of TO signals in MGCP (i.e., if the original
"script" signal is not included, then the signal/script will be
stopped). The only problem with this is that there is a possible
race condition in which a request to send an "ir" signal could
occur just as the script stopped. In order to avoid this
confusion, the following is RECOMMENDED: when the script signal is
included with an "ir" signal, include a parameter (of the script