diff options
| author | Thomas Voss <mail@thomasvoss.com> | 2024-11-27 20:54:24 +0100 |
|---|---|---|
| committer | Thomas Voss <mail@thomasvoss.com> | 2024-11-27 20:54:24 +0100 |
| commit | 4bfd864f10b68b71482b35c818559068ef8d5797 (patch) | |
| tree | e3989f47a7994642eb325063d46e8f08ffa681dc /doc/rfc/rfc3660.txt | |
| parent | ea76e11061bda059ae9f9ad130a9895cc85607db (diff) | |
doc: Add RFC documents
Diffstat (limited to 'doc/rfc/rfc3660.txt')
| -rw-r--r-- | doc/rfc/rfc3660.txt | 3587 |
1 files changed, 3587 insertions, 0 deletions
diff --git a/doc/rfc/rfc3660.txt b/doc/rfc/rfc3660.txt new file mode 100644 index 0000000..1f8ceb4 --- /dev/null +++ b/doc/rfc/rfc3660.txt @@ -0,0 +1,3587 @@ + + + + + + +Network Working Group B. Foster +Request for Comments: 3660 F. Andreasen +Updates: 2705 Cisco Systems +Category: Informational December 2003 + + + Basic Media Gateway Control Protocol (MGCP) Packages + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2003). All Rights Reserved. + +IESG Note + + This document is being published for the information of the + community. It describes a non-IETF protocol that is currently being + deployed in a number of products. Implementers should be aware of + RFC 3525 [37], which was developed in the IETF Megaco Working Group + and the ITU-T SG16, and is considered by the IETF and ITU-T to be the + standards-based (including reviewed security considerations) way to + meet the needs that MGCP was designed to address. The IETF Megaco + Working Group and the ITU-T Study Group 16 are developing extensions + to RFC 3525 [37] that for functions of the type in addressed in this + document. + +Abstract + + This document provides a basic set of Media Gateway Control Protocol + (MGCP) packages. The generic, line, trunk, handset, RTP, DTMF (Dual + Tone Multifrequency), announcement server and script packages are + updates of packages from RFC 2705 with additional explanation and in + some cases new versions of these packages. In addition to these, + five new packages are defined here. These are the signal list, + resource reservation, media format, supplementary services and digit + map extension packages. + + + + + + + + + + +Foster & Andreasen Informational [Page 1] + +RFC 3660 Basic MGCP Packages December 2003 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 1.1. List of Packages . . . . . . . . . . . . . . . . . . . . 3 + 1.2. Changes to Existing RFC 2705 Packages. . . . . . . . . . 3 + 1.2.1. Change in Signal Types . . . . . . . . . . . . . 3 + 1.2.2. Operation Complete and Operation Failure . . . . 3 + 1.2.3. Package Versions . . . . . . . . . . . . . . . . 4 + 1.2.4. Event Definitions, Aliases and Interoperability + Issues . . . . . . . . . . . . . . . . . . . . . 4 + 1.2.5. New Events . . . . . . . . . . . . . . . . . . . 5 + 1.3. New Packages and Excluded Packages . . . . . . . . . . . 5 + 2. Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 2.1. Generic Media Package. . . . . . . . . . . . . . . . . . 7 + 2.2. DTMF Package . . . . . . . . . . . . . . . . . . . . . . 11 + 2.3. Trunk Package. . . . . . . . . . . . . . . . . . . . . . 16 + 2.4. Line Package . . . . . . . . . . . . . . . . . . . . . . 24 + 2.5. Handset Emulation Package. . . . . . . . . . . . . . . . 33 + 2.6. Supplementary Services Tone Package. . . . . . . . . . . 36 + 2.7. Digit Map Extension. . . . . . . . . . . . . . . . . . . 37 + 2.8. Signal List Package. . . . . . . . . . . . . . . . . . . 38 + 2.9. Media Format Parameter Package . . . . . . . . . . . . . 39 + 2.10. RTP Package. . . . . . . . . . . . . . . . . . . . . . . 43 + 2.11. Resource Reservation Package . . . . . . . . . . . . . . 48 + 2.11.1. Description. . . . . . . . . . . . . . . . . . . 48 + 2.11.2. Parameter Encoding . . . . . . . . . . . . . . . 52 + 2.11.3. Events . . . . . . . . . . . . . . . . . . . . . 53 + 2.12. Announcement Server Package. . . . . . . . . . . . . . . 55 + 2.13. Script Package . . . . . . . . . . . . . . . . . . . . . 56 + 3. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 59 + 4. Security Considerations. . . . . . . . . . . . . . . . . . . . 59 + 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 59 + 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 60 + 6.1. Normative References . . . . . . . . . . . . . . . . . . 60 + 6.2. Informative References . . . . . . . . . . . . . . . . . 62 + 7. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 63 + 8. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 64 + +1. Introduction + + This document provides a basic set of Media Gateway Control Protocol + (MGCP) packages. The generic, line, trunk, handset, RTP, DTMF, + announcement server and script packages are updates of packages from + RFC 2705 [38] with additional explanation and in some cases new + versions of these packages. In addition to these, five new packages + are defined here. These are the signal list, resource reservation, + media format, supplementary services and digit map extension + packages. + + + +Foster & Andreasen Informational [Page 2] + +RFC 3660 Basic MGCP Packages December 2003 + + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in BCP 14, RFC 2119 [31]. + +1.1. List of Packages + + The basic set of packages specified in this document is for use with + MGCP 1.0 as defined in [1]. Included are the following packages: + + ------------------------------------------- + | Package | Name | + |-------------------------------------------| + | Generic Media Package | G | + | DTMF package | D | + | Trunk Package | T | + | Line Package | L | + | Handset Package | H | + | Supplementary Services Package | SST | + | Digit Map Extension | DM1 | + | Signal List Package | SL | + | Media Format Package | FM | + | RTP Package | R | + | Resource Reservation Package | RES | + | Announcement Server Package | A | + | Script Package | Script | + ------------------------------------------- + +1.2. Changes to Existing RFC 2705 Packages + +1.2.1. Change in signal types + + MGCP 1.0, as defined in RFC 2705 [38] (and now updated in [1]), + provided some additional clarification on the meaning of On-Off (OO) + signals compared to earlier versions of MGCP. This lead to some + inconsistency in some of the signal definitions in the accompanying + packages in RFC 2705 [38]. This has been corrected in the packages + that are included here by changing some of the signals from type On- + Off to type Time-Out (TO). + +1.2.2. Operation Complete and Operation Failure + + Another change made to improve consistency and interoperability was + to add the "operation complete" and "operation failure" events in + packages where there are TO signals defined, but where the "operation + complete" and "operation failure" events were not previously included + as part of the package. By definition, all packages that contain + + + + + +Foster & Andreasen Informational [Page 3] + +RFC 3660 Basic MGCP Packages December 2003 + + + Time-Out type signals now contain the "operation failure" ("of") and + "operation complete" ("oc") events as defined in [1], irrespective of + whether they are provided as part of the package description or not. + + If a package without Time-Out signals contains definitions for the + "oc" and "of" events, the event definitions provided in the package + may over-ride those indicated here. Such practice is however + discouraged and is purely allowed to avoid potential backwards + compatibility problems. + + It is considered good practice to explicitly mention that the "oc" + and "of" events are supported in accordance with their default + definitions. If no definition is included in the package, the + default syntax and semantics are assumed. + + Please refer to [1] for additional details on these events. + +1.2.3. Package Versions + + The generic, line, trunk, handset, RTP, DTMF, announcement server and + script packages included in this document are new versions of + packages that were previously contained in RFC 2705 [38]. The + updated base MGCP 1.0 specification [1] provides an optional + capability of auditing package versions. Any gateway that implements + versioned packages SHOULD also implement this option. + +1.2.4. Event Definitions, Aliases and Interoperability Issues + + Some event definitions or clarifications of previous event + definitions have also been added in order to improve + interoperability. + + In some cases, events have aliases either in the same or in other + packages and a recommendation has been made for the use of alternates + by Call Agents for future implementations. For maximum + interoperability, gateways MUST still implement these events (in fact + they MUST always implement all of the events, signals, etc. in a + package). + + Some events that were previously defined require specific + provisioning in both the gateway and the Call Agent in order to allow + for interoperability. In those cases, a warning to that affect has + been included. + + + + + + + + +Foster & Andreasen Informational [Page 4] + +RFC 3660 Basic MGCP Packages December 2003 + + +1.2.5. New Events + + In some cases, new events have been added to existing packages. Any + changes to existing packages of course have resulted in the package + version number being updated from unversioned (version 0) to version + 1. + +1.3. New Packages and Excluded Packages + + Two packages from RFC 2705 [38] have not been included. These are + the "MF" and the "NAS" packages. These packages are still valid as + are all unversioned (version 0) packages defined in RFC 2705 [38]. + The reason these packages were not included are: + + * The original MF package had no defined way to outpulse MF + digits so that MF CAS is now provided by other packages (i.e., + the "MS", "MO" and "MD" packages) in a separate document. + + * The "N" package, as defined in RFC 2705 [38], was incomplete. + A new MGCP "NAS" package has been developed and provided in a + separate document. + + New packages have also been included beyond what was included in RFC + 2705 [38]. These are the signal list, resource reservation, media + format, supplementary services and digit map extension packages. The + Resource Reservation ("RES") and Media Format ("FM") packages in + particular are different from other packages in this document in that + they contain new LocalConnectionOptions. This is allowed by the new + extension rules in [1]. Future packages of this type MUST use a + packages prefix in front of local connection options ("<package- + name>/<Local Connection Option>") so as to avoid name-space problems. + However because of the timing of the arrival of these packages + relative to updating MGCP 1.0, this was not done for the "RES" and + "FM" packages. The resulting new local connection options have been + registered with IANA. For future cases where a package prefix is + included, only the package name needs to be registered. + +2. Packages + + For those packages that involve MGCP events, the terms "signal" and + "event" are used to differentiate a request from a Call Agent to a + Media Gateway to apply an event ("signal"), from the request for the + detection of an "event" that occurs on the Media Gateway and is + "Notified" to the Call Agent. + + + + + + + +Foster & Andreasen Informational [Page 5] + +RFC 3660 Basic MGCP Packages December 2003 + + + For packages that involve events and signals, the tables contain five + columns: + + Symbol: the (package) unique symbol used to identify the event. + + Definition: a short description of the event. + + R: an x appears in this column if the event can be requested by + the Call Agent. Alternatively, one or more of the following + symbols may appear. An "S" is included if the event-state may be + audited. A "C" indicates that the event can be detected on a + connection, and a "P" indicates the event is persistent. + + S: if nothing appears in this column for an event, then the event + cannot be signaled by the Call Agent. Otherwise, the following + symbols identify the type of event: + + * OO On/Off signal + + * TO Time-Out signal. + + * BR Brief signal. + + In addition, a "C" will be included if the signal can be generated + on a connection. + + Duration: specifies the default duration of TO signals. If a + duration is left unspecified, then the default timeout will be + assumed to be infinite, unless explicitly noted in the description + of the signal. A duration may also be declared as being variable + in a case where signals involve complex sequencing (e.g., scripts + or digit out-pulsing) where the amount of time may vary with + either processing time or the signaling environment. + + Default time-out values may be over-ridden by the Call Agent for any + Time-Out event defined in this document (with the exception of those + that have a default value of "variable") by a "to" signal parameter + which specifies the timeout value in milliseconds (see [1]). The + following example indicates a timeout value of 20 seconds: + + S: sst/cw(to=20000) + + As indicated in [1]: by default, a supplied time-out value MAY be + rounded to the nearest non-zero value divisible by 1000, i.e., whole + second. However, individual signal definitions within a package may + define other rounding rules. + + + + + +Foster & Andreasen Informational [Page 6] + +RFC 3660 Basic MGCP Packages December 2003 + + + Note that Time-Out signals that involve other parameters still allow + the use of the "to" signal parameter e.g.: + + S: T/sit(1,to=3000) + + The order of the "to" parameter relative to the other parameters is + not important. + + Note: as per [1], On-Off (OO) signals are parameterized with "+" + (meaning turn on) or "-" (meaning turn off). If the parameter is + missing, the default is to turn on the signal. Unlike Time-Out + signals, On-Off signals do not stop when an event occurs. + + Other than the "to" parameter for Time-out (TO) signals and the "+" + and "-" for On-Off (OO) signals, signals and events in the packages + in this document do not have parameters unless explicitly indicated + in the description of the event for that package. + + In some of the signal definitions below, specific tone definitions + are provided even though actual frequencies may vary from country to + country. + +2.1. Generic Media Package + + Package Name: G + Version: 1 + + The generic media package groups the events and signals that can be + observed on several types of endpoints, such as trunk gateway + endpoints, access gateway endpoints or residential gateway endpoints. + + --------------------------------------------------------------- + | Symbol | Definition | R | S Duration | + |---------------------------------------------------------------| + | cf | Confirm Tone | | BR | + | cg | Congestion Tone | | TO infinite | + | ft | Fax Tone | x | | + | it | Intercept Tone | | TO infinite | + | ld | Long Duration Connection | C | | + | mt | Modem Tone | x | | + | oc | Operation Complete | x | | + | of | Operation Failure | x | | + | pat(###) | Pattern Detected | x | OO | + | pt | Preemption Tone | | TO infinite | + | rbk(...) | Ringback | | TO,C 180 seconds| + | rt | Ringback Tone | | TO,C 180 seconds| + --------------------------------------------------------------- + + + + +Foster & Andreasen Informational [Page 7] + +RFC 3660 Basic MGCP Packages December 2003 + + + New events added to this package from the previously unversioned + package: "oc" + + Changes: "it" and "pt" signals changed from OO to TO. + + 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 and signals are defined as follows: + + Confirmation Tone (cf): + This is also referred to as "positive indication tone" in ITU-T + E.182. In North America, Confirmation Tone uses the same + frequencies and levels as dial tone (350 and 440 Hertz) but with a + cadence of 0.1 second on, 0.1 second off, repeated three times. + See GR-506-CORE [7] Section 17.2.4. It is considered an error to + try and play confirmation tone on a phone that is on-hook and an + error MUST consequently be returned when such attempts are made + (error code 402 - phone on-hook). + + Congestion Tone (cg): + Refer to ITU-T E.180 [8] and E.182 [10]. This maps to re-order + tone in North America (refer to GR-506-CORE [7] Section 17.2.7). + + Fax Tone (ft): + The fax tone event is generated whenever a fax call is detected by + the presence of V.21 fax preamble. The fax tone event SHOULD also + be generated when the T.30 CNG tone is detected. See ITU-T + Recommendations T.30 [21] and V.21 [22]. + + Intercept Tone(it): + This is a country specific tone as defined in ITU-T E.180 + Supplement 2 [9]. + + Long Duration Connection (ld): + The "long duration connection" is detected when a connection has + been established for more than a provisioned amount of time. The + default value is 1 hour. + + This event is detected on a connection. When no connection is + specified as part of the request, the event applies to all + connections for the endpoint, regardless of when the connections + are created. The "all connections" wildcard (see [1]) may also be + used for this case, and is in fact preferred for consistency. In + + + + + +Foster & Andreasen Informational [Page 8] + +RFC 3660 Basic MGCP Packages December 2003 + + + either case, the name of the connection on which the event was + detected will be included when the event is observed, e.g.: + + G/ld@0A3F58 + + Modem Tone (mt): + Indicates V.25 Answer tone (ANS) with or without phase reversals + or V.8 Modified Answer Tone (ANSam) tone with or without phase + reversals. Note that this implies the presence of a data call. + Also note that despite the name of the event, devices other than + modems may generate such tones, e.g., a fax machine. + + Operation Complete (oc): + The standard definition of operation complete [1]. + + Operation Failure (of): + The standard definition of operation failure [1]. + + Pattern Detected (pat(###)): + This event requires special provisioning that needs to be agreed + on between the Call Agent and media gateway in order to ensure + interoperability. It is retained in order to maintain backwards + compatibility with version 0 of the "G" package. This event MUST + be parameterized with a decimal numeric value from 0 to 999 + specifying the pattern to detect. When reported, the pattern is + also included as a parameter. + + Preemption Tone (pt): + This is a country specific tone and is defined in ITU-T E.180 + Supplement 2 [9]. + + Ringback (rbk(connectionID)): + This is an alias for "rt@connectionID" and is included here for + backwards compatibility only. It is recommended that Call Agents + use "rt@connectionID" instead of "rbk(connectionID)" for ring-back + over a connection for new implementations. Although the ringback + signal is applied on a connection, the "rbk" signal does not + support the "@connection" syntax. When the signal is requested, + it MUST be parameterized with a connection-ID or a connection-ID + wildcard as specified in [1]. + + Ringback Tone (rt): + Refer to ITU-T E.180 [8] and ITU-T E.182 [10]. Also referred to + as ringing tone - a tone advising the caller that a connection has + been made and that a calling signal is being applied to the called + party or service point. In North America, this tone is a + combination of two AC tones with frequencies of 440 and 480 Hertz + and levels of -19 dBm each, to give a combined level of -16 dBm. + + + +Foster & Andreasen Informational [Page 9] + +RFC 3660 Basic MGCP Packages December 2003 + + + The cadence for Audible Ring Tone is 2 seconds on, followed by 4 + seconds off. See GR-506-CORE [7] - LSSGR: SIGNALING, Section + 17.2.5. + + This signal can be applied directly to an endpoint or + alternatively on a connection using the syntax "rt@connectionID". + When the ringback signal is applied to an endpoint, it is + considered an error to try and play ringback tone if the endpoint + is considered on-hook, and an error MUST consequently be returned + when such attempts are made (error code 402 - phone on-hook). + When the ringback signal is applied to a connection, no such check + is to be made. + + Note that as specified in [1], signals requested on a connection + MUST be played regardless of the connection mode. For example, in + a call-waiting situation, ringback tone may be played on a + connection in "inactive" mode. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Foster & Andreasen Informational [Page 10] + +RFC 3660 Basic MGCP Packages December 2003 + + +2.2. DTMF package + + Package name: D + Version: 1 + + -------------------------------------------------------------- + | Symbol | Definition | R | S Duration | + |--------------------------------------------------------------| + | 0 | DTMF 0 | x | BR | + | 1 | DTMF 1 | x | BR | + | 2 | DTMF 2 | x | BR | + | 3 | DTMF 3 | x | BR | + | 4 | DTMF 4 | x | BR | + | 5 | DTMF 5 | x | BR | + | 6 | DTMF 6 | x | BR | + | 7 | DTMF 7 | x | BR | + | 8 | DTMF 8 | x | BR | + | 9 | DTMF 9 | x | BR | + | # | DTMF # | x | BR | + | * | DTMF * | x | BR | + | A | DTMF A | x | BR | + | B | DTMF B | x | BR | + | C | DTMF C | x | BR | + | D | DTMF D | x | BR | + | DD(..) | DTMF Tone Duration | x | TO 3 seconds | + | DO(..) | DTMF OO Signal | | OO | + | L | Long Duration Indicator | x | | + | oc | Operation Complete | x | | + | of | Operation Failure | x | | + | T | Interdigit Timer | x | TO 16 seconds | + | X | DTMF Tones Wildcard, | x | | + | | match any digit 0-9 | | | + -------------------------------------------------------------- + + Changes from the previous version of the package: events "dd", "do", + "oc" were added. + + Note that DTMF tones including the DTMF tones wildcard can use the + eventRange notation defined in [1] when requesting events, e.g., + "D/[0-9](N)". + + 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. + + + + + + +Foster & Andreasen Informational [Page 11] + +RFC 3660 Basic MGCP Packages December 2003 + + + The events are defined as follows: + + DTMF tones (0-9,#,*,A,B,C,D): + Detection and generation of DTMF tones is described in GR-506-CORE + [7] - LSSGR: SIGNALING, Section 15. Note that it is considered an + error to try and play DTMF tones on a phone that is on-hook and an + error MUST consequently be returned when such attempts are made + (error code 402 - phone on-hook). The event codes can be + specified in a digit map. When requested as a signal, as per + GR-506-CORE [7], section 15, a minimum tone duration of 50 ms will + be followed by a minimum interdigit silence period of 45 ms, i.e., + if requested in a signal list such as "S: sl/s(d/5,d/6,d/7)", then + interdigit timing requirements will be satisfied. + + Note that some types of endpoints, such as announcement endpoints, + MAY allow detection and/or generation of a DTMF tone over a + connection. However, this requires consistent provisioning + between the Call Agent and announcement server (it is not required + in order to be compliant with the DTMF package). + + DTMF Tone Duration (dd(dg=<tone>,to=<time>,su=<TrueOrFalse>)): + This event can be used to indicate if/when the specified <tone> + has a duration greater than the <time> value indicated (and is + reported once the duration is exceeded). The parameters can be + supplied in any order. The value of <tone> can be any of the DTMF + tone symbols (without including the package name) specified in the + DTMF package (including X in the case of events, but not signals). + If this parameter is absent, any DTMF tone that occurs will be + reported. The parameter <time> is in milli-seconds and may be + rounded to the nearest 10 ms by the gateway. The minimum value of + <time> that can be requested when requesting an event is 40 ms. + When requesting a signal, the minimum value of <time> that can be + requested is 50 ms. The maximum value of <time> that can be + requested for either an event or a signal is 60000 ms. If the + "to=<time>" parameter is absent when requested as an event, the + event will report the full duration (up to 60000 ms) of the tone + when the tone is completed. When reported as an ObservedEvent, + both parameters are always supplied. In this case, <tone> is the + actual tone detected and <time> is either: + + * The <time> specified in the request (possibly rounded), or + + * If the request did not contain a "to=<time>" parameter, the + full duration of the tone. + + The parameter "su" MAY be included when this is requested as an + event (but is not reported). This parameter is used to indicate + whether or not the DTMF digits requested should be suppressed + + + +Foster & Andreasen Informational [Page 12] + +RFC 3660 Basic MGCP Packages December 2003 + + + in-band when it is requested. Possible values are "true", + indicating that in-band DTMF should be suppressed and "false" + indicating that DTMF should continue to be passed in-band. The + default value of the parameter, if missing, is "false". The "su" + parameter MUST NOT be included when requesting "D/dd" as a signal. + + When used as a signal, "dd" provides the ability to generate a + DTMF tone as a TO signal. When applied as a signal, an additional + 50 ms of silence will be tacked onto the end before the operation + complete occurs, i.e., "S: dd(dg=5,to=2500)" will play the DTMF + tone for the number "5" for 2.5 seconds, followed by 50 ms of + silence period. The operation complete (if requested) will be + notified after the silence interval occurs. Any value from 50 ms + to 60000 ms can be requested. Gateways generating or detecting + the tone may round off the requested time to the nearest 10 ms. + + The "dd" event can be used in place of the "long duration" event + in order to detect a digit pressed for longer than 2 seconds. For + example, in order to detect if a user presses the long "#" for + longer than 2 seconds, a request could be made with the + RequestedEvents line "R: d/dd(N)(dg=#,to=2000)". The resulting + ObservedEvents line would be "O: d/dd(dg=#,to=2000)". + + Suppose instead, that the RequestedEvents line contains + + R: d/[0-9*#],d/dd + + Suppose the user then pushes the "#" for 2.5 seconds. In this + case, two events will be notified: + + O: d/# + + when the "#" key is first pressed, and + + O: d/dd(dg=#,to=2500) + + when the "#" key is finally released. + + DTMF OO Signal (do(dg=<tone>,<on-or-off>)): + This signal is used to generate a DTMF tone as an on-off signal. + The <tone> parameter is any of the symbols for a specific tone in + the DTMF package (i.e., "0" to "9", "A", "B", "C", "D", "*", or + "#"). The <on-or-off> indicator is "+" for on and "-" for off as + per [1]. The <tone> parameter MUST be supplied, otherwise a + return code of 538 - "Event/signal parameter error" will be + provided in the response. If the <on-or-off> parameter is + missing, the default is to turn the signal on as usual (i.e., "+" + is the default). The order of the parameters is not significant + + + +Foster & Andreasen Informational [Page 13] + +RFC 3660 Basic MGCP Packages December 2003 + + + since "+" and "-" are reserved characters and are easily + distinguished from the <tone> parameter. + + Long Duration Indicator (l): + The "long duration indicator" is observed when a DTMF signal is + produced for a duration larger than two seconds. In this case, + the gateway will detect two successive events: first, when the + signal has been recognized, the DTMF signal, and then, 2 seconds + later, the long duration signal. + + Operation Complete (oc): + This is the standard definition of operation complete [1]. + + Operation Failure (of): + This is the standard definition of operation failure [1]. + + Timer (t): + Timer T can be used as an event or as a time-out (TO) signal. As + a signal, its only behavior is the normal characteristics of a + "TO" signal as defined in [1] (i.e., if no event occurs before the + time-out, an operation complete event will be generated). + + As an event, Timer T is a digit input timer that can be used in + two ways: + + * When timer T is used with the accumulate according to digit + map action, the timer is not started until the first DTMF + tone is entered, and the timer is restarted after each new + DTMF tone is entered until either a digit map match or + mismatch occurs. In this case, timer T functions as an + inter-digit timer as illustrated by: + + R: D/[0-9T](D) + + * When timer T is used without the "accumulate according to + digit map" action, the timer is started immediately and + simply cancelled (but not restarted) as soon as a DTMF tone + is entered. In this case, timer T can be used as an inter- + digit timer when overlap sending is used, as in: + + R: D/[0-9](N), D/T(N) + + When used with the "accumulate according to digit map" action, + timer T takes on one of two values, T-partial or T-critical. When + at least one more symbol is required for the "current dial string" + to match any one of the patterns in the digit map, timer T takes + on the value T-partial, corresponding to partial dial timing. If + a timer is all that is required to produce a match, timer T takes + + + +Foster & Andreasen Informational [Page 14] + +RFC 3660 Basic MGCP Packages December 2003 + + + on the value T-critical corresponding to critical dial timing. + When timer T is used without the "accumulate according to digit + map" action, timer T takes on the value T-critical. The default + value for T-partial is 16 seconds and the default value for + T-critical is 4 seconds. The provisioning process may alter both + of these. If timer T is not used, then inter-digit timing will + not be performed. + + The following examples illustrate this. Consider the digit map: + + (xxxxxxx|x11T) + + and assume that DTMF and the timer T is accumulated according to + digit map. At the first DTMF input, say "4", timer T is started + with a value of T-partial since at least one more symbol is + required. If "1" is then input, it leads to a restart of timer T + with a value of T-partial again. If "1" is now input again, we + have a current dial string of "411" and a timer is now all that is + required to produce a match. Hence timer T is now restarted with + value T-critical. + + Finally, consider the following subtle examples (all assuming DTMF + and timer T being accumulated according to digit map): + + The digit map + + (1[2-3T].) + + will match immediately on the input "1" since zero or more matches + of the range are specified. + + The digit map + + (1[2-3].T) + + and an input of "1" will lead to timer T being set to T-critical. + + A digit map of + + (1[2-3]T.) + + and an input of "1" will lead to timer T being set to T-partial. + Furthermore, upon subsequent input of "2" or "3" a perfect match + will be triggered immediately since timer T is completely + irrelevant. + + + + + + +Foster & Andreasen Informational [Page 15] + +RFC 3660 Basic MGCP Packages December 2003 + + + DTMF Tones Wildcard (X): + The DTMF tones wildcard matches any DTMF digit between 0 and 9. + The actual event code generated will however be the event code for + the digit detected. The DTMF tones wildcard is often used to + detect DTMF input to be matched against a digit map. + +2.3. Trunk Package + + Package Name: T + Version: 1 + + ---------------------------------------------------------------- + | Symbol | Definition | R | S Duration | + |----------------------------------------------------------------| + | as | Answer Supervision | x | BR | + | bl | Blocking | | BR | + | bz | Busy | | TO 30 sec. | + | co1 | Continuity Tone (go tone, | x | TO 3 sec. | + | | or return tone) | | | + | co2 | Continuity Test (go tone, | x | TO 3 sec. | + | | or return tone in dual tone | | | + | | procedures) | | | + | ct(...) | Continuity Transponder | | OO | + | lb | Loopback | | OO | + | nm | New Milliwatt Tone | x | TO 3 sec | + | mm | Newest Milliwatt Tone | x | TO 3 sec | + | oc | Operation Complete | x | | + | of | Operation Failure | x | | + | om | Old Milliwatt Tone | x | TO 3 sec | + | pst | Permanent Signal Tone | | TO infinite | + | qt | Quiet Termination | | TO infinite | + | ro | Reorder Tone | x | TO 30 sec. | + | sit(#) | Special Information Tone | x | TO 2 sec. | + | | | | (see notes) | + | tl | Test Line | x | TO infinite | + | tp(###) | Test Pattern | x | TO 3 sec | + | zz | No Circuit | x | TO 2 sec | + ---------------------------------------------------------------- + + New events added to this package from the previously unversioned + package: "bz", "ct", "mm", "oc", "pst", "qt", "sit", and "tp". + + Changes in event types: "co1", "co2", "nm", "om", "tl", "zz" signals + changed from OO to TO; "as" and "bl" changed from OO to BR. + + + + + + + +Foster & Andreasen Informational [Page 16] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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 definition of the trunk package events are as follows: + + Answer Supervision (as): + This event is used to indicate the occurrence answer supervision. + In most cases, it is a result of a steady off-hook in response to + a call request. This event is included for backwards + compatibility with the previous version of the package. The + preferred alternative is to use the "answer" event in the + appropriate CAS packages [34] (Note: check the details on the use + of "answer" in the particular CAS package; in most cases "answer" + as an event is an indication of a steady off-hook regardless of + whether or not it is an indication of answer supervision). For + details on when answer supervision is appropriate refer to [5]. + + Blocking (bl): + This event is used to indicate an incoming off-hook for the + purposes of blocking a one-way trunk in CAS trunks. This event is + included for backwards compatibility with the previous version of + the package. The preferred alternative is the "block" event in + the appropriate CAS packages [34]. + + Busy Tone (bz): + Refer to ITU-T E.180 [8]. In North America, station Busy is a + combination of two AC tones with frequencies of 480 and 620 Hertz + and levels of -24 dBm each, to give a combined level of -21 dBm. + The cadence for Station Busy Tone is 0.5 seconds on, followed by + 0.5 seconds off, then repeating. See GR-506-CORE [7]- LSSGR: + SIGNALING, Section 17.2.6. + + Continuity Tone (co1): + A tone at 2010 Hz (see section 3.1.1.3 of [2]). When generated as + a signal, the frequency of the tone must be within + or - 8 Hz, + while the frequency of the tone corresponding to the event must be + within + or - 30 Hz. + + Continuity Test (co2): + A tone at 1780 Hz (see section 3.1.1.3 of [2]). When generated as + a signal, the frequency of the tone must be within + or - 20 Hz, + while the frequency of the tone corresponding to the event must be + within + or - 30 Hz. + + In continuity testing the tone corresponding to the signal at the + originating gateway is referred to as the "go" tone, and the tone + + + +Foster & Andreasen Informational [Page 17] + +RFC 3660 Basic MGCP Packages December 2003 + + + corresponding to the event at that same gateway is referred to as + the "return" or "check" tone. + + Note that generation and notification of continuity tones are done + as per continuity test requirements as defined in ITU-T Q.724 [3], + as well as by Bellcore GR-317-CORE [2] specifications, i.e., the + semantics of notification of the return tone is more than that the + tone was received, but is an indication that the test has passed. + Details are provided in the following paragraphs. + + The continuity tones represented by co1 and co2 are used when the + Call Agent wants to initiate a continuity test. There are two + types of tests, single tone and dual tone; In the case of the dual + tone, either tone can be sent and the opposite received depending + on the trunk interconnections (4-wire or 2-wire) as indicated + below: + + Originating Terminating + ============ =========== + + 4w -------------- 1780 Hz -----------> 2w + <------------- 2010 Hz ------------ (transponder) + + 2w -------------- 2010 Hz -----------> 2w/4w + <------------- 1780 Hz ------------ (transponder) + + 4w -------------- 2010 Hz -----------> 4w + <------------- 2010 Hz ------------ (loopback) + + The Call agent is expected to know, through provisioning + information, which test should be applied to a given endpoint. As + an example, for a 4-wire to 2-wire connection, the Call Agent + might send a request like the following to an originating gateway: + + RQNT 1234 ds/ds1-1/17@tgw2.example.net + X: AB123FE0 + S: t/co1 + R: t/co2,t/oc,t/of + + On a terminating side of a trunk, the call agent may request a + continuity test connection (connection mode "conttest") to the + terminating gateway as follows: + + CRCX 3001 ds/ds1-2/4@tgw34.example.net + C: 3748ABC364 + M: conttest + + + + + +Foster & Andreasen Informational [Page 18] + +RFC 3660 Basic MGCP Packages December 2003 + + + Alternatively, rather than using a connection mode, the "T/ct" + signal can be used (see description of this signal further below): + + RQNT 3001 ds/ds1-2/4@tgw34.example.net + X: 1233472 + S: t/ct(in=co1,out=co2,+) + + The originating gateway would send the requested "go" tone, and + would look for the appropriate "return tone". Once the return + tone is received, the originating gateway removes the go tone and + checks to see that the return tone has been removed within the + specified performance limits (i.e., GR-246-CORE, T1.113.4, Annex B + [23]). When it detects that the test is successful, the gateway + will send a notification of the return tone event (Note that + notification of the return tone event therefore must not be sent + prior to detection of the removal of the return tone). + + The "T/co1" and "T/co2" signals are TO signals so that an + operation complete event will occur when the signal times out. If + a timeout value other than the default is desired, the "to" + parameter may be used (e.g., "S: T/co1(to=2000)"). + + If the gateway detects the failure of the continuity test prior to + the timeout, an operation failure event will be generated. + Otherwise, the failure of the continuity test is determined by the + failure to receive the return tone event before the timeout occurs + (operation complete event). As with TO signals in general, + operation complete and operation fail events are parameterized + with the name of the signal. + + In the example above where the go tone is "co1" and the return + tone is "co2": + + * A notification of the "co2" event indicates success (i.e., + "O: t/co2"). + + * A notification of the operation failure event indicates + failure prior to timeout (i.e., "O: t/of(t/co1)"). + + * A notification of the operation complete event indicates + that the return tone was not received properly prior to the + occurrence of the timeout (i.e., "O: t/oc(t/co2)"). + + On a terminating end of a trunk, either a "loopback" connection + (single tone test) or "conttest" connection (dual tone test) is + made (or alternatively the "T/lb" or "T/ct" signals are + requested). It is up to the termination end to make sure that the + return tone is removed as soon as the go tone disappears. The + + + +Foster & Andreasen Informational [Page 19] + +RFC 3660 Basic MGCP Packages December 2003 + + + Call Agent requests the removal of "contest" or "loopback" + connections (or "T/lb" or "T/ct" signals) at a termination end + when the results of the continuity test are obtained. + + When "conttest" is used, the endpoint is provisioned as to which + transponder test is being performed (2010 Hz received and 1780 Hz + sent or vice versa). In the case of the corresponding "T/ct" + signal, the Call Agent can specify which tone is received and sent + as parameters. + + Note that continuity tones in the trunk package are only ever sent + to the telephony endpoint. For network-based continuity, there + are continuity tones available in the RTP ("R") package. Although + a transponder (dual tone) test can be done, a single tone test is + generally sufficient in the case of continuity testing across an + IP network. + + Continuity Transponder(ct(in=<tone-in>,out=<tone-out>, <+ or ->)): + This signal is used to provide transponder functionality + independent of the connection mode, i.e., this is an alternative + way to provide the same functionality as the "conttest" connection + mode. The parameters can be provided in any order. The <tone-in> + and <tone-out> parameters can have values "co1" or "co2", + corresponding to the 2010 Hz and 1780 Hz tones associated with + those symbols. If one of the tones is "co1", then the other must + be "co2" and vice versa (i.e., <tone-in> and <tone-out> must have + different values; if loopback is required, then the "lb" signal in + this package or "loopback" connection mode should be used). + + On detecting <tone-in>, <tone-out> will be generated in return. + The tone corresponding to <tone-out> will continue to be generated + until either: + + * The signal is explicitly turned off (e.g., "S: t/ct(-)") or + + * Removal of the <tone-in> tone is detected. + + Note that while the signal is active (regardless of whether a tone + is active or not), media from the endpoint will not be forwarded + to or from the packet network (i.e., the continuity transponder + signal must be explicitly turned off by the Call Agent in order to + resume passing media between the packet network and the endpoint). + + Loopback (lb): + This signal is used to provide loopback functionality independent + of the connection mode, i.e., this is an alternative way to + provide the same functionality as "loopback" connection mode. + + + + +Foster & Andreasen Informational [Page 20] + +RFC 3660 Basic MGCP Packages December 2003 + + + Note that while the loop-back signal is active (regardless of + whether a tone is active or not), media from the endpoint will not + be forwarded to or from the packet network (i.e., the loopback + signal must be explicitly turned off by the Call Agent in order to + resume passing media between the packet network and the endpoint). + + New Milliwatt Tone (nm): + 1004 Hz tone - refer to [4] and section 8.2.5 of [5]. + + Newest Milliwatt Tone (mm): + 1013.8 Hz - refer to [4]. + + Operation Complete (oc): + This is the standard definition of operation complete [1]. + + Operation Failure (of): + This is the standard definition of operation failure [1]. + + Old Milliwatt Tone (om): + 1000 Hz tone - refer to [4] and section 8.2.5 of [5]. + + Permanent Signal Tone (pst): + In North America, this tone is applied to a busy line + verify/operator interrupt under specific circumstances as + described in [17]. + + Quiet Termination (qt): + Quiet Termination is used in a 102 trunk test. Reference section + 6.20.5 [5] as well as [4]. + + Reorder Tone(ro): + This maps to congestion tone in the ITU-T E.182 specification. In + North America, reorder tone is a combination of two AC tones with + frequencies of 480 and 620 Hertz and levels of -24 dBm each, to + give a combined level of -21 dBm. The cadence for reorder tone is + 0.25 seconds on, followed by 0.25 seconds off, repeating + continuously (until time-out). See GR-506-CORE [7], Section + 17.2.7. + + Special Information Tone(sit(#)): + As described in ITU-T E.180 [8], the special information tone + consists of a tone period in which 3 tones are produced followed + by a silent period of 1 second (total TO period of approximately 2 + seconds). When used as a signal, it MUST be parameterized with a + parameter value from 1 to 7, with the following meaning as defined + in SR-2275, section 6.21.2 of [5]. + + + + + +Foster & Andreasen Informational [Page 21] + +RFC 3660 Basic MGCP Packages December 2003 + + + ------------------------------------------- + | sit(1) | RO' | reorder SIT, intra-LATA | + | sit(2) | RO" | reorder SIT, inter-LATA | + | sit(3) | NC' | no circuit SIT, intra-LATA | + | sit(4) | NC" | no circuit SIT, inter-LATA | + | sit(5) | IC | intercept SIT | + | sit(6) | VC | vacant code SIT | + | sit(7) | IO | ineffective other SIT | + ------------------------------------------- + + When requested as an event, the event MUST be parameterized with a + decimal number from 1 to 7 to indicate which tone the gateway is + required to detect. The resulting notification also includes the + parameter. Other countries may have one or more special + information tones with country specific definitions (refer to + ITU-T E.180 supp. 2 [9]). In this case, special information tone + 1 as defined in [9] is sit(1), special information tone 2 is + sit(2) etc. + + As an example, the Call Agent might make a request such as: + + RQNT 1234 ds/ds1-1/17@tgw2.example.net + X: AB123FE0 + R: t/sit(N)(2) + + If the tone is detected, the resulting notification might appear + as follows: + + NTFY 3002 ds/ds1-3/6@gw-o.whatever.net MGCP 1.0 + X: AB123FE0 + O: t/sit(2) + + Test Line (tl): + 105 Test Line test progress tone (2225 Hz + or - 25 Hz at -10 + dBm0). Refer to section 8.2.5 of [5]. + + Test Pattern (tp(###)): + The tp(###) signal inserts the pattern ### continuously into the + channel until the timeout period expires. The parameter is + provided as a decimal number from 0 to 255. If the parameter is + omitted, the default value is decimal 95. + + In RequestedEvents, the parameter MAY be supplied to indicate what + pattern the Call Agent wishes the gateway to detect. If the + parameter is omitted, the value 95 is assumed. The pattern MUST + be returned in the ObservedEvent (even if the parameter was not + requested). + + + + +Foster & Andreasen Informational [Page 22] + +RFC 3660 Basic MGCP Packages December 2003 + + + A typical use for the test pattern signal is for the test line 108 + (digital loopback) test (refer to section 8.2.5 of [5]). At the + termination side of a trunk, the Call Agent would request a + connection in "loopback" mode, which would do a digital loopback. + On the origination side of the trunk, the Call Agent would request + that the test pattern be injected into the digital channel, and + would check to see that the pattern was returned within the + timeout period. As an example, the Call Agent would make the + following request on the origination side: + + RQNT 1234 ds/ds1-1/17@tgw2.example.net + X: AB123FE0 + S: t/tp + R: t/tp, t/oc, t/of + + In this case the Call Agent will either receive: + + * An ObservedEvent indicating that the test has passed (i.e., + "O:t/op(95)") or + + * An ObservedEvent indicating that the timeout occurred before + the pattern was received (i.e., "O:t/oc(t/tp)"), indicating + that the test failed. Of course an operation failure would + indicate failure as well. + + No Circuit (zz): + This is an alias for Special Information Tone 2, i.e., "sit(2)". + + + + + + + + + + + + + + + + + + + + + + + + +Foster & Andreasen Informational [Page 23] + +RFC 3660 Basic MGCP Packages December 2003 + + +2.4. Line Package + + Package Name: L + Version: 1 + + ---------------------------------------------------------------- + |Symbol | Definition | R | S Duration | + |----------------------------------------------------------------| + |adsi(string) | ADSI Display | | BR | + |aw | Answer Tone | x | OO | + |bz | Busy Tone | | TO 30 sec. | + |ci(ti,nu,na) | Caller-id | | BR | + |dl | Dial Tone | | TO 16 sec. | + |e | Error Tone | x | TO 2 sec. | + |hd | Off-hook Transition | S | | + |hf | Flash-hook | x | | + |ht | On Hold Tone | | OO | + |hu | On-hook Transition | S | | + |lsa | Line Side Answer Sup. | | OO | + |mwi | Message Waiting ind. | | TO 16 sec. | + |nbz | Network busy | x | TO infinite | + |oc | Operation Complete | x | | + |of | Operation Failure | x | | + |osi | Network Disconnect | | TO 900 ms | + |ot | Off-hook Warning Tone | | TO infinite | + |p | Prompt Tone | x | BR | + |rg | Ringing | | TO 180 sec. | + |r0, r1, r2, | Distinctive Ringing | | TO 180 sec. | + |r3, r4, r5, | | | | + |r6 or r7 | | | | + |ro | Reorder Tone | | TO 30 sec. | + |rs | Ringsplash | | BR | + |s(###) | Distinctive Tone Pattern | x | BR | + |sit(#) | Special Information Tone | | TO 2 sec. | + | | | | (see notes) | + |sl | Stutter Dial Tone | | TO 16 sec. | + |v | Alerting Tone | | OO | + |vmwi | Visual Message | | OO | + | | Waiting Indicator | | | + |wt | Call Waiting Tone | | TO 12 sec | + |wt1, wt2, | Alternative Call | | TO 12 sec | + |wt3, wt4 | Waiting Tones | | (see notes) | + |y | Recorder Warning Tone | | TO infinite | + |z | Calling Card Service Tone| | BR | + ---------------------------------------------------------------- + + New events added to this package from the previously unversioned + package: "ht", "osi", and "lsa". + + + +Foster & Andreasen Informational [Page 24] + +RFC 3660 Basic MGCP Packages December 2003 + + + Changes in event types: signals "y", "z", changed from OO to TO and + BR respectively. Ringing tones were extended to allow for a ring + repetition signal parameter. + + 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 description of events and signals in the line package are as + follows: + + ADSI Display (adsi): + This signal is included here to maintain compatibility with the + previous version of this package. The signal is not well-defined + and its use is discouraged. + + Answer Tone (aw): + This event is included here to maintain compatibility with the + previous version of this package. The event is not well-defined + and its use is discouraged. + + Busy Tone (bz): + Refer to ITU-T E.180 [8]. In North America, station Busy is a + combination of two AC tones with frequencies of 480 and 620 Hertz + and levels of -24 dBm each, to give a combined level of -21 dBm. + The cadence for Station Busy Tone is 0.5 seconds on followed by + 0.5 seconds off, repeating. See GR-506-CORE [7], Section 17.2.6. + It is considered an error to try and play busy tone on a phone + that is on-hook and an error MUST consequently be returned when + such attempts are made (error code 402 - phone on-hook). + + Caller-id (ci(time, number, name)): + See GR-1188 [24], GR-30-CORE [14], and GR-31 [25]. For backwards + compatibility, each of the three fields are optional, but each of + the commas will always be included. In accordance with the + general MGCP grammar, it is RECOMMENDED to always include all + three fields - an empty quoted string can then be used in lieu of + omitting a parameter: + + The time parameter is coded as "MM/DD/HH/MM", where MM is a two- + digit decimal value for a Month between 01 and 12, DD is a two- + digit value for a Day between 01 and 31, and Hour and Minute are + two-digit values coded according to military local time, e.g., 00 + is midnight, 01 is 1 a.m., and 13 is 1 p.m. (Note: two digits + MUST always be provided for each of the values of month, day, + hour, minutes e.g., the month of January is indicated by the two + digits "01" rather than just "1"). + + + +Foster & Andreasen Informational [Page 25] + +RFC 3660 Basic MGCP Packages December 2003 + + + The number parameter is coded as an ASCII character string of + decimal digits that identify the calling line number. White + spaces are permitted if the string is quoted, but they will be + ignored. If a quoted-string is provided, the string itself is + UTF-8 encoded (RFC 2279) as usual for signal parameters. + + The name parameter is coded as a string of ASCII characters that + identify the calling line name. White spaces are permitted if the + string is quoted. If a quoted-string is provided, the string + itself is UTF-8 encoded (RFC 2279). + + A "P" in the number or name field is used to indicate a private + number or name, and an "O" is used to indicate an unavailable + number or name. Other letters MAY be used to provide additional + clarification as per provider or vendor specifications. + + The following example illustrates the use of the caller-id signal: + + S: l/ci(09/14/17/26, "555 1212", "John Doe") + + An example indicating that the name and number are private: + + S: l/ci(09/14/17/26,P,P) + + Dial Tone (dl): + Refer to the ITU-T E.180 [8] specification. In North America, + dial tone is a combination of two continuous AC tones with + frequencies of 350 and 440 Hertz and levels of -13dBm each, to + give a combined level of -10 dBm. See GR-506-CORE [7] - LSSGR: + SIGNALING, Section 17.2.1. It is considered an error to try and + play dial-tone on a phone that is on-hook and an error MUST + consequently be returned when such attempts are made (error code + 402 - phone on-hook). + + Error Tone (e): + This tone is maintained for backwards compatibility. The tone is + not well defined and its use is discouraged. + + Off-hook Transition (hd): + See GR-506-CORE [7], Section 12. It is considered an error to try + and request off-hook on a phone that is off-hook and an error MUST + consequently be returned when such attempts are made (error code + 401 - phone off-hook). + + + + + + + + +Foster & Andreasen Informational [Page 26] + +RFC 3660 Basic MGCP Packages December 2003 + + + Flash Hook (hf): + See GR-506-CORE [7], Section 12. It is considered an error to try + and request flash hook on a phone that is on-hook and an error + MUST consequently be returned when such attempts are made (error + code 402 - phone on-hook). + + Tone On Hold (ht): + A tone used to reassure a calling subscriber who has been placed + on "hold". Refer to ITU-T E.182 [10]. + + On-hook Transition (hu): + See GR-506-CORE [7], Section 12. The timing for the on-hook + signal is for flash response enabled, unless provisioned + otherwise. It is considered an error to try and request flash + hook on a phone that is on-hook and an error MUST consequently be + returned when such attempts are made (error code 402 - phone on- + hook). + + Line Side Answer Supervision (lsa): + This provides Reverse Loop Current Feed (RLCF) on the line (refer + to GR-506-CORE [7]) and is a way of indicating that the called + party has answered for some line-side equipment. + + Message Waiting Indicator (mwi): + Message Waiting indicator tone uses the same frequencies and + levels as dial tone (350 and 440 Hertz at -13dBm each), but with a + cadence of 0.1 second on, 0.1 second off, repeated 10 times, + followed by steady application of dial tone. See GR-506-CORE [7], + Section 17.2.3. It is considered an error to try and play + message-waiting indicator on a phone that is on-hook and an error + MUST consequently be returned when such attempts are made (error + code 402 - phone on-hook). + + Network Busy (nbz): + This is included here to maintain compatibility with the previous + version of this package. The "nbz" signal is an alias for re- + order tone signal("ro"). Future Call Agent implementations that + require a network busy signal should use the "ro" signal. It is + also recommended that future Call Agents not request to be + notified of the "nbz" event (a network busy event is generally not + required in a line package; hence, "ro" is only a signal, not an + event). + + Operation Complete (oc): + This is the standard definition of operation complete [1]. + + Operation Failure (of): + This is the standard definition of operation failure [1]. + + + +Foster & Andreasen Informational [Page 27] + +RFC 3660 Basic MGCP Packages December 2003 + + + Network Disconnect (osi): + Network Disconnect indicates that the far-end party has + disconnected. The signal that is sent on the line is provisioned + in the media gateway since it may vary from country to country. + In North America, this signal is an open switch interval which + results in a Loop Current Feed Open Signal (LCFO) being applied to + the line (refer to GR-506-CORE [7], see also See GR-505-CORE [6], + Section 4.5.2.1). The default time-out value for this signal is + 900 ms. + + Off-hook Warning Tone (ot): + Off-hook warning tone, also known as receiver Off-Hook Tone (ROH + Tone). This is the irritating noise a telephone makes when it is + not hung up correctly. In North America, ROH Tone is generated by + combining four tones at frequencies of 1400 Hertz, 2060 Hertz, + 2450 Hertz and 2600 Hertz, at a cadence of 0.1 second on, 0.1 + second off, then repeating. GR-506-CORE [7], Section 17.2.8 + contains details about required power levels. It is considered an + error to try and play off-hook warning tone on a phone that is + on-hook, and an error MUST consequently be returned when such + attempts are made (error code 402 - phone on-hook). + + Prompt Tone (p): + The definition of the prompt tone and its use may be found in + requirement GR-220 [20]. The tone in GR-220 (requirement "R3-170" + or GR-220) is a 300 ms burst of a 400 Hz tone. + + Ringing (rg): + See GR-506-CORE [7], Section 14. The provisioning process may + define the ringing cadence. The ringing signal may be + parameterized with the signal parameter "rep" which specifies the + maximum number of ringing cycles (repetitions) to apply. The + value for "rep" is specified in decimal and can have any value + from 1 to 255. The following will apply the ringing signal for up + to 6 ringing cycles: + + S: l/rg(rep=6) + + If the "rep" parameter is specified, the signal times-out when the + number of repetitions are completed (i.e., an operation complete + event can be requested and will occur at the end of the + timeout/number of rings). + + If the "rep" parameter is supplied, then any timeout ("to") value + that is included will be ignored, i.e.: + + S: l/rg(rep=6,to=12000) + + + + +Foster & Andreasen Informational [Page 28] + +RFC 3660 Basic MGCP Packages December 2003 + + + will be treated the same as the previous example where the + parameter "to=12000" was not included. Of course, if the "to" + parameter is included without the "rep", it will be acted upon + i.e.: + + S: l/rg(to=12000) + + will ring for 12 seconds. + + It is considered an error to try and ring a phone that is off-hook + and an error MUST consequently be returned when such attempts are + made (error code 401 - phone off-hook). + + Distinctive Ringing (r0, r1, r2, r3, r4, r5, r6 or r7): + See GR-506-CORE [7], Section 14. Default values for r1 to r5 are + as defined for distinctive ringing pattern 1 to 5 in GR-506-CORE + [7]. The default values for r0, r6 and r7 are normal ringing + (i.e., the same cadence "rg"). The provisioning process may + define the ringing cadence for each of these signals. The + distinctive ringing signals may be parameterized with the signal + parameter "rep" which specifies the maximum number of ringing + cycles (repetitions) to apply. The value for "rep" is specified + in decimal and can have any value from 1 to 255. + + The following will apply the ringing signal for up to 6 ringing + cycles: + + S: l/r1(rep=6) + + If the "rep" parameter is specified, the signal times-out when the + number of repetitions are completed (i.e., an operation complete + event can be requested and will occur at the end of the + timeout/number of rings) + + If the "rep" parameter is supplied, then any timeout ("to") value + that is included will be ignored, i.e.: + + S: l/r1(rep=6,to=12000) + + will be treated the same as the previous example where the + parameter "to=12000" was not included. Of course, if the "to" + parameter is included without the "rep", it will be acted upon + i.e.: + + S: l/r1(to=12000) + + will ring for 12 seconds. + + + + +Foster & Andreasen Informational [Page 29] + +RFC 3660 Basic MGCP Packages December 2003 + + + It is considered an error to try and ring a phone that is off-hook + and an error MUST consequently be returned when such attempts are + made (error code 401 - phone off-hook). + + Reorder Tone (ro): + This maps to congestion tone in the ITU-T E.182 [10] + specification. In North America, reorder tone is a combination of + two AC tones with frequencies of 480 and 620 Hertz, and levels of + -24 dBm each, to give a combined level of -21 dBm. The cadence + for reorder tone is 0.25 seconds on, followed by 0.25 seconds off, + repeating continuously. + + Ringsplash (rs): + Also known as "Reminder ring", this tone is a burst of ringing + that may be applied to the physical forwarding line (when idle) to + indicate that a call has been forwarded and to remind the user + that a Call Forward sub-feature is active. In the US, it is + defined to be a 0.5(-0,+0.1) second burst of power ringing (see + [11]). + + Distinctive Tone Pattern (s(###)): + This is used to signal or detect a tone pattern defined by the + parameter where the parameter may have a value from 0 to 999. + When specified as an event, the parameter MUST be included. The + parameter will also be included when the event is reported. This + event (the definition of tones associated with each parameter + value) requires special provisioning in the Call Agent and gateway + to insure interoperability. This signal is included here to + maintain compatibility with the previous version of this package. + + Special Information Tone(sit(#)): + As described in ITU-T E.180 [8], the special information tone + consists of a tone period in which 3 tones are produced, followed + by a silent period of 1 second (total TO period of approximately 2 + seconds). It MAY be parameterized with a parameter value from 1 + to 7, with the following meaning as defined in SR-2275, section + 6.21.2 [5]: + + ------------------------------------------- + | sit(1) | RO' | reorder SIT, intra-LATA | + | sit(2) | RO" | reorder SIT, inter-LATA | + | sit(3) | NC' | no circuit SIT, intra-LATA | + | sit(4) | NC" | no circuit SIT, inter-LATA | + | sit(5) | IC | intercept SIT | + | sit(6) | VC | vacant code SIT | + | sit(7) | IO | ineffective other SIT | + ------------------------------------------- + + + + +Foster & Andreasen Informational [Page 30] + +RFC 3660 Basic MGCP Packages December 2003 + + + If the parameter is left out, the NC' SIT tone that corresponds to + the signal "L/sit(3)" is assumed. + + Other countries may have one or more special information tones + with country specific definitions (refer to ITU-T E.180 supp. 2 + [9]). In this case, special information tone 1 as defined in [9] + is sit(1), special information tone 2 is sit(2) etc. + + Stutter Dial Tone (sl): + Stutter Dial Tone (also called Recall Dial Tone in GR-506-CORE [7] + and "special dial tone" in ITU-T E.182 [10]) is used to confirm + some action and request additional input from the user. An + example application is to cancel call-waiting, prior to entering a + destination address. + + The stutter dial tone signal may be parameterized with the signal + parameter "del", which will specify a delay in milliseconds to + apply between the confirmation tone and the dial tone. The + parameter can have any value from 0 to 10000 ms, rounded to the + nearest non-zero value divisible by 100 (i.e., tenth of a second). + The following will apply stutter dial tone with a delay of 1.5 + seconds between the confirmation tone and the dial tone: + + S: l/sl(del=1500) + + It is considered an error to try and play stutter dial tone on a + phone that is on-hook and an error MUST consequently be returned + when such attempts are made (error code 402 - phone on-hook). + + Alerting Tone (v): + A 440 Hz Tone of a 2 second duration, followed by a 1/2 second of + tone every 10 seconds. This event is included for backwards + compatibility with the previous version of the package. + + Visual Message Waiting Indicator (vmwi): + The transmission of the VMWI messages will conform to the + requirements in [13] and the CPE guidelines in [12]. Refer also + to section 6.6 of GR-30-CORE [14]. VMWI messages will only be + sent from the gateway to the attached equipment when the line is + idle. If new messages arrive while the line is busy, the VMWI + indicator message will be delayed until the line goes back to the + idle state. After the gateway restarts, the state of the signal + will be "off", and hence the Call Agent MUST refresh the CPE's + visual indicator if it is supposed to be "on". + + + + + + + +Foster & Andreasen Informational [Page 31] + +RFC 3660 Basic MGCP Packages December 2003 + + + Alternative Call Waiting Tones (wt, wt1, .., wt4): + Refer to ITU-T E.180 [8]. For North American tone definitions, + refer to GR-506-CORE [7], Section 14.2. "wt" and "wt1" are both + aliases for the default Call Waiting tone, which in North America, + is a 440-Hz tone applied for 300 plus or minus 50 ms. The tone is + then repeated once after 10 seconds. + + These signals are timeout signals with a default timeout value of + 12 seconds, which allows the tone to be played twice with a single + request (refer to GR-571-CORE [16]). However, there are cases + (Requirement R3-73 of GR-575-CORE [18]), in which only a single + tone is required. In that case, the Call Agent may make the + request with a shorter timeout period to eliminate the second tone + (e.g., "S: wt(to=2000)" - which stops the signal after 2 seconds + so that the second tone will not occur). + + Signals wt2, wt3 and wt4 are alternates that are used for + distinctive call-waiting tone patterns (refer to GR-506-CORE, + Section 14.2 [7]. It is considered an error to try and apply + call-waiting tone on a phone that is on-hook and an error MUST + consequently be returned when such attempts are made (error code + 402 - phone on-hook). + + Recorder Warning Tone(y): + Refer to ITU-T E.180 [8] - also Bellcore document SR-2275 [5] + section 6.20. When recording equipment is used, this tone is + connected to the line to inform the distant party that the + conversation is being recorded - typical value used is a 1400 Hz + Tone of a 0.5 second duration every 15 seconds. + + Calling Card Service Tone(z): + This tone is used to inform the customer that credit card + information must be keyed in. Typically, it consists of 60 ms of + 941 + 1477 Hz (the DTMF #digit) and 940 ms of 350 + 440 Hz (dial + tone), decaying exponentially with a time constant of 200 ms. + Refer to Bellcore document SR-2275 [5], section 6.20. + + + + + + + + + + + + + + + +Foster & Andreasen Informational [Page 32] + +RFC 3660 Basic MGCP Packages December 2003 + + +2.5. Handset Emulation Package + + Package Name: H + Version: 1 + + ---------------------------------------------------------------- + |Symbol | Definition | R | S Duration | + |----------------------------------------------------------------| + |adsi(string) | ADSI Display | x | BR | + |aw | Answer Tone | x | OO | + |bz | Busy Tone | x | TO 30 sec. | + |ci(ti,nu,na) | Caller-id | x | BR | + |dl | Dial Tone | x | TO 16 sec. | + |e | Error Tone | x | TO 2 sec. | + |hd | Off-hook Transition | S | BR | + |hu | On-hook Transition | S | BR | + |hf | Flash Hook | x | BR | + |ht | Tone On Hold | x | OO | + |lsa | Line Side Answer Sup. | x | OO | + |mwi | Message Waiting Ind. | x | TO 16 sec. | + |nbz | Network Busy | x | TO infinite | + |oc | Operation Complete | x | | + |ot | Off-hook Warning Tone | x | TO infinite | + |of | Operation Failure | x | | + |osi | Network Disconnect | x | TO 900 ms | + |p | Prompt Tone | x | BR | + |rg | Ringing | x | TO 180 sec. | + |r0, r1, r2, | Distinctive Ringing | x | TO 180 sec. | + |r3, r4, r5, | | | | + |r6 or r7 | | | | + |ro | Reorder Tone | x | TO 30 sec. | + |rs | Ringsplash | x | BR | + |s(###) | Distinctive Tone Pattern | x | BR | + |sit(#) | Sit Tone | x | TO 2 sec. | + |sl | Stutter Dial Tone | x | TO 16 sec. | + |v | Alerting Tone | x | OO | + |vmwi | Vis. Message Waiting Ind.| x | OO | + |wt | Call Waiting tone | x | TO 12 sec. | + |wt1, wt2, | Alternative Call | x | TO 12 sec | + |wt3, wt4 | Waiting Tones | | (see notes) | + |y | Recorder Warning Tone | x | TO infinite | + |z | Calling Card Serv. Tone | x | BR | + ---------------------------------------------------------------- + + The handset emulation package is similar to the line package except + that events such as "off-hook" can be signaled as well as detected. + + + + + +Foster & Andreasen Informational [Page 33] + +RFC 3660 Basic MGCP Packages December 2003 + + + Changes from the original package - are the same changes as were made + for the line package, plus "hu" and "hd" signal types were changed + from OO to BR. + + Event definitions are the same as for the line package with the + following exceptions: + + ASDI: + When requested as an event by the Call Agent, the event is not + parameterized. However, the parameter is included when the event + is reported. + + Caller-id: + When requested as an event by the Call Agent, the event MUST not + be parameterized. However, parameters are included when the event + is reported i.e.: + + O: l/ci(09/14/17/26,"555 1212","John Doe") + + Line Side Answer Supervision: + When requested as an event by the Call Agent, it indicates when + the reverse loop current feed (RLCF) was turned on and off. The + event is not parameterized when it is requested. However, a + parameter is included when it is reported i.e.: + + O: l/lsa(+) to indicate RLCF was turned on + O: l/lsa(-) to indicate RLCF was turned off + + Ringing (rg): + When requested as an event, the Call Agent may optionally include + the rep parameter indicating a request to report after some number + of rings e.g.: + + RQNT 1234 aaln/1@rgw2.example.net + X: AB123FE0 + R: h/rg(N)(rep=3) + + The resulting notification after the number of rings is detected + includes the parameter again: + + NTFY 3002 ds/ds1-3/6@gw-o.whatever.net MGCP 1.0 + X: AB123FE0 + O: h/rg(rep=3) + + If the parameter is not included in the request, it is also not + included in the report. In that case, the event is reported as + soon as ringing is detected. + + + + +Foster & Andreasen Informational [Page 34] + +RFC 3660 Basic MGCP Packages December 2003 + + + Distinctive Ringing (r0, r1, r2, r3, r4, r5, r6 or r7): + As with the "rg" event, if the "rep" parameter is included when + one of these is requested as an event, it is also reported. If it + is not requested with the parameter, then the parameter is also + not included in the report. In that case, the event is reported + as soon as ringing with the requested cadence is detected. + + Stutter Dial Tone (sl): + Stutter Dial Tone MUST not be parameterized when requested as an + event. However, the "del" parameter is reported. + + RQNT 1234 aaln/1@rgw2.example.net + X: AB123FE0 + R: h/sl + + The resulting notification indicates the delay between the + confirmation tone and the dial tone: + + NTFY 3002 ds/ds1-3/6@gw-o.whatever.net MGCP 1.0 + X: AB123FE0 + O: h/sl(del=1500) + + As with the signal, the report indicates the delay rounded to the + nearest 100 ms. + + Visual Message Waiting: + When requested as an event by the Call Agent, it indicates when + the visual message waiting indicator was turned on and off. The + event is not parameterized when it is requested. However, a + parameter is included when it is reported i.e.: + + O: l/vmwi(+) to indicate message waiting turned on + O: l/vmwi(-) to indicate message waiting turned off + + Note that: + + * All TO signals in the handset package can include a "to" + parameter when requested as a signal. + + * However, requests to be notified about these events MUST NOT + include the "to" parameter, i.e., the "to" parameter is not + valid in RequestedEvents. + + + + + + + + + +Foster & Andreasen Informational [Page 35] + +RFC 3660 Basic MGCP Packages December 2003 + + +2.6. Supplementary Services Tone Package + + Package Name: SST + Version: 0 + + --------------------------------------------------------------- + |Symbol | Definition | R | S Duration | + |---------------------------------------------------------------| + |cd | Conference Depart | | BR | + |cj | Conference Join | | BR | + |cm | Comfort Tone | | TO infinite | + |cw | Caller Waiting Tone | | TO 30 sec. | + |ht | On Hold Tone | | OO | + |ni | Negative Indication | | TO infinite | + |nu | Number Unobtainable | | TO infinite | + |oc | Operation Complete | x | | + |of | Operation Failure | x | | + |pr | Pay Phone Recognition | | BR | + |pt | Pay Tone | | BR | + ---------------------------------------------------------------- + + 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 are defined as follows: + + Conference Depart(cd): + Tone used to indicate that a participant has left a conference + call. The tone characteristics are left to the specific gateway + implementation. + + Conference Join (cj): + Tone used to indicate that a party has joined a conference call. + The tone characteristics are left to the specific gateway + implementation. + + Comfort Tone (cm): + Comfort Tone is used to indicate that the call is being processed + and that the caller should wait. Refer to ITU-T E.182 [10]. + + Caller Waiting Tone (cw): + Not to be confused with a call-waiting tone, this is a tone + advising a caller that a called station, though busy, has a call + waiting service active. Refer to ITU-T E.182 [10]. + + + + + +Foster & Andreasen Informational [Page 36] + +RFC 3660 Basic MGCP Packages December 2003 + + + Tone on-hold (ht): + A tone used to reassure a calling subscriber who has been placed + on "hold". Refer to ITU-T E.182 [10]. + + Negative Indication (ni): + A tone advising a subscriber that the request for service cannot + be accepted. Refer to ITU-T E.182 [10]. For North America, this + maps to the re-order tone (see GR-506-CORE [7], Section 17.2.7). + + Number Unobtainable Tone (nu): + Refer to ITU-T E.180, supplement 2 [9]. This is also referred to + as "vacant tone" and maps to a "re-order tone" in North America + (see GR-506-CORE [7], Section 17.2.7). + + Operation Complete (oc): + The standard definition of operation complete [1]. + + Operation Failure (of): + The standard definition of operation failure [1]. + + Pay Phone Recognition (pr): + A tone advising an operator that the endpoint is identified as a + payphone. Refer to ITU-T E.182 [10]. + + Pay Tone (pt): + A tone indicating that payment is required. Refer to ITU-T E.182 + [10]. + +2.7. Digit Map Extension + + Package Name: dm1 ("dm" followed by the number "1") + Version: 0 + Extension Digit Map Letters: P + + This package defines an Extension Digit Map Letter that is used to + override the shortest possible match behavior for a given entry in a + digit map (see [1]). The letter "P" (for partial match override), at + 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. + + + +Foster & Andreasen Informational [Page 37] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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. + + + + + + +Foster & Andreasen Informational [Page 38] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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 + + + + + +Foster & Andreasen Informational [Page 39] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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". + + + + + +Foster & Andreasen Informational [Page 40] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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" + + + +Foster & Andreasen Informational [Page 41] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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. + + + + + + + + + + +Foster & Andreasen Informational [Page 42] + +RFC 3660 Basic MGCP Packages December 2003 + + +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]. + + + + +Foster & Andreasen Informational [Page 43] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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. + + + + +Foster & Andreasen Informational [Page 44] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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". + + + + + + +Foster & Andreasen Informational [Page 45] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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. + + + + +Foster & Andreasen Informational [Page 46] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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. + + + + + +Foster & Andreasen Informational [Page 47] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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): + 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 + + + +Foster & Andreasen Informational [Page 48] + +RFC 3660 Basic MGCP Packages December 2003 + + + (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: + + + + + +Foster & Andreasen Informational [Page 49] + +RFC 3660 Basic MGCP Packages December 2003 + + + * 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 + + + +Foster & Andreasen Informational [Page 50] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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). + + + + + +Foster & Andreasen Informational [Page 51] + +RFC 3660 Basic MGCP Packages December 2003 + + + * 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 + + + + + + +Foster & Andreasen Informational [Page 52] + +RFC 3660 Basic MGCP Packages December 2003 + + + * 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. + + + +Foster & Andreasen Informational [Page 53] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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") + + + + + + +Foster & Andreasen Informational [Page 54] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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. + + + + + +Foster & Andreasen Informational [Page 55] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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) + + + +Foster & Andreasen Informational [Page 56] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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. + + + + +Foster & Andreasen Informational [Page 57] + +RFC 3660 Basic MGCP Packages December 2003 + + + 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 + signal) to indicate that this is not a new instance of the script + i.e., if there is no script executing at the present time do not + start executing a new one. + + The "ir" signal is only associated with an executing script. If + none are running when a request for the event/signal is made, or + if a new script request is not included with the request, then the + "ir" signal/event will not be executed (i.e., the "ir" event with + its parameters is passed to an existing script for parsing and + execution and is considered opaque as far as MGCP as concerned. + If no such script exists, response code "800" will be returned, + indicating that the script is not executing). + + The following response code is associated with this package: + + Code Text Explanation + + 800 Script not Request for "ir" signal or event + Executing but no script is executing at the + time the request was received. + + Note that package specific error codes include the package name + following the error code. For example, if error code 800 occurs + in response to a request with a transaction ID of 1001, it would + be sent as: + + 800 1001 /SCRIPT + + + + + + + + + + + + + + + +Foster & Andreasen Informational [Page 58] + +RFC 3660 Basic MGCP Packages December 2003 + + +3. IANA Considerations + + The following packages and their versions have been registered with + IANA as per the instructions in [1]. + + Package Title Name Version + ------------- ---- ------- + Announcement A 1 + DTMF D 1 + Digit Map Extension DM1 0 + Media Format FM 0 + Generic G 1 + Handset H 1 + Line L 1 + RTP R 1 + Resource Reservation RES 0 + Script SCRIPT 1 + Supplementary Tones SST 0 + Signal List SL 0 + Trunk T 1 + + The following extension digit map letter has been registered with + IANA: + + Package Letter + ------- ------ + DM1 P + + The following Local Connections have been registered with IANA: + + Field Name + ------- ----- + Media Format fmtp + Reservation Confirmation r-cnf + Reservation Direction r-dir + Resource Sharing r-sh + +4. Security Considerations + + The MGCP packages contained in this document do not require any + further security considerations beyond those indicated in the base + MGCP specification [1]. + +5. Acknowledgements + + Special thanks are due to the authors of the original MGCP 1.0 + specification: Mauricio Arango, Andrew Dugan, Isaac Elliott, + Christian Huitema, and Scott Picket. + + + +Foster & Andreasen Informational [Page 59] + +RFC 3660 Basic MGCP Packages December 2003 + + + Thanks also to the reviewers of this document, including but not + limited to: Jerry Kamitses, Sonus Networks; Dave Auerbach, Dan Wing, + Cisco Systems; Ed Guy, EMC Software; Martin Wakley, Nortel Networks. + +6. References + +6.1. Normative References + + [1] Andreasen, F. and B. Foster, "Media Gateway Control Protocol + (MGCP) Version 1.0", RFC 3435, January 2003. + + [2] Bellcore, "LSSGR: Switching System Generic Requirements for Call + Control Using the Integrated Services Digital Network User Part + (ISDNUP)", GR-317-CORE, Issue 2, December 1997. + + [3] ITU-T, "Telephone User Part Signaling Procedures", ITU-T Q.724, + November 1988. + + [4] ANSI, "OAM&P - Terminating Test Line Access and Capabilities", + T1.207-2000. + + [5] Bellcore, "Notes on the Network", Special Report SR-2275, Issue + 3, December 1997. + + [6] Bellcore, "Call Processing" GR-505-CORE, Issue 1, December 1997. + + [7] Bellcore, "LSSGR: Signaling for Analog Interfaces", GR-506-CORE, + Issue 1, June 1996. + + [8] ITU-T, "Technical Characteristics of Tones for the Telephone + Service", ITU-T E.180, March 1998. + + [9] ITU-T, "Various Tones Used in National Networks", ITU-T E.180, + Supplement 2, January 1994. + + [10] ITU-T, "Applications of Tones and Recorded Announcements in + Telephone Services", ITU-T E.182, March 1998. + + [11] Bellcore, "Call Forwarding Sub-Features FSD-01-02-1450, GR-586, + Issue 1, June 2000. + + [12] Bellcore, "CPE Compatibility Considerations for the Voiceband + Data Transmission Interface", SR-TSV-002476, December 1992. + + [13] Bellcore, "LSSGR: Visual Message Waiting Indicator Generic + Requirements (FSD 01-02-2000)", GR-1401, Issue 01, June 2000. + + + + + +Foster & Andreasen Informational [Page 60] + +RFC 3660 Basic MGCP Packages December 2003 + + + [14] Bellcore, "LSSGR Voiceband Data Transmission Interface", Section + 6.6, GR-30-CORE, Issue 02, December 1998. + + [15] Handley, M. and V. Jacobson, "SDP: Session Description + Protocol", RFC 2327, April 1998. + + [16] Bellcore, "LSSGR: Call Waiting, FSD 01-02-1201", GR-571, Issue + 01, June 2000. + + [17] Bellcore, "LSSGR: Verification Connections FSD 25-05-0903", GR- + 531-CORE, Issue 1, June 2000. + + [18] Bellcore, " LSSGR: CLASS Feature: Calling Identity Delivery on + Call Waiting, FSD 01-02-1090, GR-575, Issue 01, June 2000. + + [19] Postel, J., "Internet Control Message Protocol", STD 5, RFC 792, + September 1981. + + [20] Bellcore, "Class Feature: Screen Editing (FSD 30-28-0000)", GR- + 220, Issue 2, April 2002. + + [21] ITU-T, "Procedure for document facsimile transmission in the + general switched telephone network", ITU-T T.30, April 1999. + + [22] ITU-T, "300 bits per second duplex modem standardized for use in + the general switched telephone network", ITU-T V.21, November + 1988. + + [23] Telcordia Technologies, "Telcordia Technologies Specification of + Signaling System Number 7", GR-246-CORE, Issue 7, December 2002. + + [24] Telcordia Technologies, "LSSGR: CLASS Feature: Calling Name + Delivery Generic Requirements (FSD 01-02-1070)", GR-1188, Issue + 02, December 2000. + + [25] Telcordia Technologies, "LSSGR: CLASS Feature: Calling Number + Delivery (FSD 01-02-1051)", GR-31, Issue 01, June 2000. + + [26] Schulzrinne, H. and S. Casner, "RTP Profile for Audio and Video + Conferences with Minimal Control", RFC 3551, July 2003. + + [27] Braden, R., Ed., Zhang, L., Berson, S., Herzog, S. and S. Jamin, + "Resource ReSerVation Protocol (RSVP) -- Version 1 Functional + Specification", RFC 2205, September 1997. + + [28] Berners-Lee, T., Masinter, L. and M. McCahill, Eds., "Uniform + Resource Locators (URL)", RFC 1738, December 1994. + + + + +Foster & Andreasen Informational [Page 61] + +RFC 3660 Basic MGCP Packages December 2003 + + + [29] Schulzrinne, H., Rao, A. and R. Lanphier, "Real Time Streaming + Protocol (RTSP)", RFC 2326, April 1998. + + [30] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource + Identifiers (URI): Generic Syntax", RFC 2396, August 1998. + + [31] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + +6.2. Informative References + + [32] Perkins, C., Kouvelas, I., Hodson, O., Hardman, V., Handley, M., + Bolot, J.C., Vega-Garcia, A. and S. Fosse-Parisis, "RTP Payload + for Redundant Audio Data", RFC 2198, September 1997. + + [33] Schulzrinne, H. and S. Petrack, "RTP Payload for DTMF Digits, + Telephony Tones and Telephony Signals", RFC 2833, May 2000. + + [34] Foster, B., "MGCP CAS Packages", RFC 3064, February 2001. + + [35] PacketCableTM, Dynamic Quality if Service Specification, + http://www.packetcable.com/downloads/specs/PKT-SP-DQOS-I07- + 030815.pdf + + [36] PacketCableTM Network-Based Call Signaling Protocol + http://www.packetcable.com/downloads/specs/PKT-SP-EC-MGCP-I08- + 030728.pdf + + [37] Groves, C., Pantaleo, M., Anderson, T. and T. Taylor, Eds., + "Gateway Control Protocol Version 1", RFC 3525, June 2003. + + [38] Arango, M., Dugan, A., Elliott, I., Huitema, C. and S. Pickett, + "Media Gateway Control Protocol (MGCP) Version 1.0", RFC 2705, + October 1999. + + + + + + + + + + + + + + + + + +Foster & Andreasen Informational [Page 62] + +RFC 3660 Basic MGCP Packages December 2003 + + +7. Authors' Addresses + + Bill Foster + Cisco Systems + + Phone: +1 250 758 9418 + EMail: bfoster@cisco.com + + + Flemming Andreasen + Cisco Systems + Edison, NJ 08837 + + EMail: fandreas@cisco.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Foster & Andreasen Informational [Page 63] + +RFC 3660 Basic MGCP Packages December 2003 + + +8. Full Copyright Statement + + Copyright (C) The Internet Society (2003). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assignees. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Foster & Andreasen Informational [Page 64] + |