RFC 2705
Media Gateway Control Protocol (MGCP) Version 1.0
3. Media Gateway Control Protocol
The MGCP implements the media gateway control interface as a set of transactions. The transactions are composed of a command and a mandatory response. There are eight types of command: * CreateConnection * ModifyConnection * DeleteConnection * NotificationRequest * Notify * AuditEndpoint * AuditConnection * RestartInProgress The first four commands are sent by the Call Agent to a gateway. The Notify command is sent by the gateway to the Call Agent. The gateway may also send a DeleteConnection as defined in 2.3.6. The Call Agent may send either of the Audit commands to the gateway. The Gateway may send a RestartInProgress command to the Call Agent.
3.1. General description
All commands are composed of a Command header, optionally followed by a session description. All responses are composed of a Response header, optionally followed by a session description. Headers and session descriptions are encoded as a set of text lines, separated by a carriage return and line feed character (or, optionnally, a single line-feed character). The headers are separated from the session description by an empty line. MGCP uses a transaction identifier to correlate commands and responses. The transaction identifier is encoded as a component of the command header and repeated as a component of the response header (see section 3.2.1, 3.2.1.2 and 3.3).3.2. Command Header
The command header is composed of: * A command line, identifying the requested action or verb, the transaction identifier, the endpoint towards which the action is requested, and the MGCP protocol version, * A set of parameter lines, composed of a parameter name followed by a parameter value. Unless otherwise noted or dictated by other referenced standards, each component in the command header is case insensitive. This goes for verbs as well as parameters and values, and all comparisons MUST treat upper and lower case as well as combinations of these as being equal.3.2.1. Command line
The command line is composed of: * The name of the requested verb, * The identification of the transaction, * The name of the endpoint that should execute the command (in notifications or restarts, the name of the endpoint that is issuing the command), * The protocol version.
These four items are encoded as strings of printable ASCII characters, separated by white spaces, i.e. the ASCII space (0x20) or tabulation (0x09) characters. It is recommended to use exactly one ASCII space separator.3.2.1.1. Coding of the requested verb
The verbs that can be requested are encoded as four letter upper or lower case ASCII codes (comparisons should be case insensitive) as defined in the following table: ______________________________ | Verb | Code| |______________________|______| | EndpointConfiguration| EPCF| | CreateConnection | CRCX| | ModifyConnection | MDCX| | DeleteConnection | DLCX| | NotificationRequest | RQNT| | Notify | NTFY| | AuditEndpoint | AUEP| | AuditConnection | AUCX| | RestartInProgress | RSIP| |______________________|______| The transaction identifier is encoded as a string of up to 9 decimal digits. In the command lines, it immediately follows the coding of the verb. New verbs may be defined in further versions of the protocol. It may be necessary, for experimentation purposes, to use new verbs before they are sanctioned in a published version of this protocol. Experimental verbs should be identified by a four letter code starting with the letter X, such as for example XPER.3.2.1.2. Transaction Identifiers
MGCP uses a transaction identifier to correlate commands and responses. A gateway supports two separate transaction identifier name spaces: a transaction identifier name space for sending transactions, and a transaction identifier name space for receiving transactions. At a minimum, transaction identifiers for commands sent to a given gateway MUST be unique for the maximum lifetime of the transactions within the collection of Call Agents that control that gateway. Thus,
regardless of the sending Call Agent, gateways can always detect duplicate transactions by simply examining the transaction identifier. The coordination of these transaction identifiers between Call Agents is outside the scope of this specification though. Transaction identifiers for all commands sent from a given gateway MUST be unique for the maximum lifetime of the transactions regardless of which Call Agent the command is sent to. Thus, a Call Agent can always detect a duplicate transaction from a gateway by the combination of the domain-name of the endpoint and the transaction identifier. The transaction identifier is encoded as a string of up to nine decimal digits. In the command lines, it immediately follows the coding of the verb. Transaction identifiers have values between 1 and 999999999. An MGCP entity MUST NOT reuse a transaction identifier more quickly than three minutes after completion of the previous command in which the identifier was used.3.2.1.3. Coding of the endpoint identifiers and entity names
The endpoint identifiers and entity names are encoded as case insensitive e-mail addresses, as defined in RFC 821. In these addresses, the domain name identifies the system where the endpoint is attached, while the left side identifies a specific endpoint on that system. Examples of such addresses can be: ______________________________________________________________________ | hrd4/56@gw23.example.net | Circuit number 56 in | | | interface "hrd4" of the Gateway 23 | | | of the "Example" network | | Call-agent@ca.example.net | Call Agent for the | | | "example" network | | Busy-signal@ann12.example.net| The "busy signal" virtual | | | endpoint in the announcement | | | server number 12. | |______________________________|______________________________________| The name of notified entities is expressed with the same syntax, with the possible addition of a port number as in: Call-agent@ca.example.net:5234
In case the port number is omitted, the default MGCP port (2427) will be used.3.2.1.4. Coding of the protocol version
The protocol version is coded as the key word MGCP followed by a white space and the version number, and optionally followed by a profile name.. The version number is composed of a major version, coded by a decimal number, a dot, and a minor version number, coded as a decimal number. The version described in this document is version 1.0. The profile name, if present, is represented by a white-space separated strings of visible (printable) characters extending to the end of the line. Profile names may be defined for user communities who want to apply restrictions or other profiling to MGCP. In the initial messages, the version will be coded as: MGCP 1.03.2.2. Parameter lines
Parameter lines are composed of a parameter name, which in most cases is composed of a single upper case character, followed by a colon, a white space and the parameter value. The parameter that can be present in commands are defined in the following table:
_______________________________________________________________________ |Parameter name | Code| Parameter value | |______________________|______|_______________________________________| |ResponseAck | K | see description | |BearerInformation | B | see description | |CallId | C | Hexadecimal string, at most 32 chars.| |ConnectionId | I | Hexadecimal string, at most 32 chars.| |NotifiedEntity | N | An identifier, in RFC 821 format, | | | | composed of an arbitrary string and | | | | of the domain name of the requesting | | | | entity, possibly completed by a port | | | | number, as in: | | | | Call-agent@ca.example.net:5234 | |RequestIdentifier | X | Hexadecimal string, at most 32 chars.| |LocalConnectionOptions| L | See description | |Connection Mode | M | See description | |RequestedEvents | R | See description | |SignalRequests | S | See description | |DigitMap | D | A text encoding of a digit map | |ObservedEvents | O | See description | |ConnectionParameters | P | See description | |ReasonCode | E | An arbitrary character string | |SpecificEndpointID | Z | An identifier, in RFC 821 format, | | | | composed of an arbitrary string, | | | | followed by an "@" followed by the | | | | domain name of the gateway to which | | | | this endpoint is attached. | |Second Endpoint ID | Z2 | Endpoint Id. | |SecondConnectionId | I2 | Connection Id. | |RequestedInfo | F | See description | |QuarantineHandling | Q | See description | |DetectEvents | T | See Description | |RestartMethod | RM | See description | |RestartDelay | RD | A number of seconds, encoded as | | | | a decimal number | |EventStates | ES | See description | |Capabilities | A | See description | |______________________|______|_______________________________________| |RemoteConnection | RC | Session Description | |Descriptor | | | |LocalConnection | LC | Session Description | |Descriptor | | | |______________________|______|_______________________________________|
The parameters are not necessarily present in all commands. The following table provides the association between parameters and commands. The letter M stands for mandatory, O for optional and F for forbidden. ___________________________________________________________________ | Parameter name | EP| CR| MD| DL| RQ| NT| AU| AU| RS| | | CF| CX| CX| CX| NT| FY| EP| CX| IP| |_____________________|____|____|____|____|____|____|____|____|____| | ResponseAck | O | O | O | O | O | O | O | O | O | | BearerInformation | M | O | O | O | O | F | F | F | F | | CallId | F | M | M | O | F | F | F | F | F | | ConnectionId | F | F | M | O | F | F | F | M | F | | RequestIdentifier | F | O+| O+| O+| M | M | F | F | F | | LocalConnection | F | O | O | F | F | F | F | F | F | | Options | | | | | | | | | | | Connection Mode | F | M | M | F | F | F | F | F | F | | RequestedEvents | F | O | O | O | O*| F | F | F | F | | SignalRequests | F | O | O | O | O*| F | F | F | F | | NotifiedEntity | F | O | O | O | O | O | F | F | F | | ReasonCode | F | F | F | O | F | F | F | F | O | | ObservedEvents | F | F | F | F | F | M | F | F | F | | DigitMap | F | O | O | O | O | F | F | F | F | | Connection | F | F | F | O | F | F | F | F | F | | parameters | | | | | | | | | | | Specific Endpoint ID| F | F | F | F | F | F | F | F | F | | Second Endpoint ID | F | O | F | F | F | F | F | F | F | | RequestedInfo | F | F | F | F | F | F | M | M | F | | QuarantineHandling | F | O | O | O | O | F | F | F | F | | DetectEvents | F | O | O | O | O | F | F | F | F | | EventStates | F | F | F | F | F | F | F | F | F | | RestartMethod | F | F | F | F | F | F | F | F | M | | RestartDelay | F | F | F | F | F | F | F | F | O | | SecondConnectionID | F | F | F | F | F | F | F | F | F | | Capabilities | F | F | F | F | F | F | F | F | F | |_____________________|____|____|____|____|____|____|____|____|____| | RemoteConnection | F | O | O | F | F | F | F | F | F | | Descriptor | | | | | | | | | | | LocalConnection | F | F | F | F | F | F | F | F | F | | Descriptor | | | | | | | | | | |_____________________|____|____|____|____|____|____|____|____|____| Note (+) that the RequestIdentifier parameter is optional in connection creation, modification and deletion commands, but that it becomes mandatory if the command contains an encapsulated notification request.
Note (*) that the RequestedEvents and SignalRequests parameters are
optional in the NotificationRequest. If these parameters are omitted,
the corresponding lists will be considered empty.
If implementers need to experiment with new parameters, for example
when developing a new application of MGCP, they should identify these
parameters by names that start with the string "X-" or "X+", such as
for example:
X-FlowerOfTheDay: Daisy
Parameter names that start with "X+" are critical parameter
extensions. An MGCP entity that receives a critical parameter
extension that it cannot understand should refuse to execute the
command. It should respond with an error code 511 (Unrecognized
extension).
Parameter names that start with "X-" are non critical parameter
extensions. An MGCP entity that receives a non critical parameter
extension that it cannot understand can safely ignore that parameter.
3.2.2.1. Response Acknowledgement
The response acknowledgement attribute is used to managed the "at-
most-once" facility described in the "transmission over UDP" section.
It contains a comma separated list of "confirmed transaction-id
ranges".
Each "confirmed transaction-id ranges" is composed of either one
decimal number, when the range includes exactly one transaction, or
two decimal numbers separated by a single hyphen, describing the
lower and higher transaction identifiers included in the range.
An example of response acknowledgement is:
K: 6234-6255, 6257, 19030-19044
3.2.2.2. Local connection options
The local connection options describe the operational parameters that
the Call Agent suggests to the gateway. These parameters are:
* The packetization period in milliseconds, encoded as the keyword
"p", followed by a colon and a decimal number. If the Call Agent
specifies a range of values, the range will be specified as two
decimal numbers separated by an hyphen.
* The preferred type of compression algorithm, encoded as the
keyword "a", followed by a colon and a character string. If the
Call Agent specifies a list of values, these values will be
separated by a semicolon.
* The bandwidth in kilobits per second (1000 bits per second),
encoded as the keyword "b", followed by a colon and a decimal
number. If the Call Agent specifies a range of values, the range
will be specified as two decimal numbers separated by an hyphen.
* The echo cancellation parameter, encoded as the keyword "e",
followed by a colon and the value "on" or "off".
* The gain control parameter, encoded as the keyword "gc", followed
by a colon a value which can be either the keyword "auto" or a
decimal number (positive or negative) representing the number of
decibels of gain.
* The silence suppression parameter, encoded as the keyword "s",
followed by a colon and the value "on" or "off".
* The type of service parameter, encoded as the keyword "t",
followed by a colon and the value encoded as two hexadecimal
digits.
* 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 encryption key, encoded as the keyword "k" followed by a colon
and a key specification, as defined for the parameter "K" of SDP
(RFC 2327).
* The type of network, encoded as the keyword "nt" followed by a
colon and the type of network encoded as the keyword "IN", "ATM"
or "LOCAL".
Each of the parameters is optional. When several parameters are
present, the values are separated by a comma.
Examples of connection descriptors are:
L: p:10, a:PCMU
L: p:10, a:G726-32
L: p:10-20, b:64
L: b:32-64, e:off
These set of attributes may be extended by extension attributes.
Extension attributes are composed of an attribute name, followed by a semi-colon and by an attribute value. The attribute name should start by the two characters "x+", for a mandatory extensions, or "x-", for a non mandatory extension. If a gateway receives a mandatory extension attribute that it does not recognize, it should reject the command with an error code 525 (Unknown extension in LocalConnectionOptions).3.2.2.3. Capabilities
Capabilities inform the Call Agent about endpoints' capabilities when audited. The encoding of capabilities is based on the Local Connection Options encoding for the parameters that are common to both. In addition, capabilities can also contain a list of supported packages, and a list of supported modes. The parameters used are: * A list of supported codecs. The following parameters will apply to all codecs specified in this list. If there is a need to specify that some parameters, such as e.g. silence suppression, are only compatible with some codecs, then the gateway will return several LocalConnectionOptions parameters, one for each set of codecs. Packetization Period: A range may be specified. Bandwidth: A range corresponding to the range for packetization periods may be specified (assuming no silence suppression). If absent, the values will be deduced from the codec type. Echo Cancellation: "on" if echo cancellation is supported for this codec, "off" otherwise. The default is support. Silence Suppression: "on" if silence suppression is supported for this codec, "off" otherwise. The default is support. Gain Control: "0" if gain control is not supported. The default is support. Type of Service: The value "0" indicates no support for type of service, all other values indicate support for type of service. The default is support.
Resource Reservation:
The parameter indicates the reservation services that are
supported, in addition to best effort. The value "g" is encoded
when the gateway supports both the guaranteed and the controlled
load service, "cl" when only the controlled load service is
supported. The default is "best effort."
Encryption Key:
Encoding any value indicates support for encryption. Default is
no support.
Type of network:
The keyword "nt", followed by a colon and a semicolon separated
list of supported network types. This parameter is optional.
Event Packages
The event packages supported by this endpoint encoded as the
keyword "v", followed by a colon and a character string. If a list
of values is specified, these values will be separated by a
semicolon. The first value specified will be the default package
for that endpoint.
Modes
The modes supported by this endpoint encoded as the keyword "m",
followed by a colon and a semicolon-separated list of supported
connection modes for this endpoint.
3.2.2.4. Connection parameters
Connection parameters are encoded as a string of type and value
pairs, where the type is a either letter identifier of the parameter
or an extension type, and the value a decimal integer. Types are
separated from value by an `=' sign. Parameters are encoded from each
other by a comma.
The connection parameter types are specified in the following table:
__________________________________________________________________
| Connection parameter| Code| Connection parameter |
| name | | value |
|_____________________|______|____________________________________|
| Packets sent | PS | The number of packets that |
| | | were sent on the connection. |
| Octets sent | OS | The number of octets that |
| | | were sent on the connection. |
| Packets received | PR | The number of packets that |
| | | were received on the connection. |
| Octets received | OR | The number of octets that |
| | | were received on the connection. |
| Packets lost | PL | The number of packets that |
| | | were not received on the |
| | | connection, as deduced from |
| | | gaps in the sequence number. |
| Jitter | JI | The average inter-packet arrival |
| | | jitter, in milliseconds, |
| | | expressed as an integer number. |
| Latency | LA | Average latency, in milliseconds, |
| | | expressed as an integer number. |
|_____________________|______|____________________________________|
Extension parameters names are composed of the string "X-" followed
by a two letters extension parameter name. Call agents that received
unrecognized extensions shall silently ignore these extensions.
An example of connection parameter encoding is:
P: PS=1245, OS=62345, PR=0, OR=0, PL=0, JI=0, LA=48
3.2.2.5. Reason Codes
Reason codes are three-digit numeric values. The reason code is
optionally followed by a white space and commentary, e.g.:
900 Endpoint malfunctioning
A list of reason-codes can be found in Section 2.5.
3.2.2.6. Connection mode
The connection mode describes the mode of operation of the connection. The possible values are: ________________________________________________________ | Mode | Meaning | |____________|__________________________________________| | M: sendonly| The gateway should only send packets | | M: recvonly| The gateway should only receive packets | | M: sendrecv| The gateway should send | | | and receive packets | | M: confrnce| The gateway should place | | | the connection in conference mode | | M: inactive| The gateway should neither | | | send nor receive packets | | M: loopback| The gateway should place | | | the circuit in loopback mode. | | M: conttest| The gateway should place | | | the circuit in test mode. | | M: netwloop| The gateway should place | | | the connection in network loopback mode.| | M: netwtest| The gateway should place | | | the connection in network | | | continuity test mode. | | M: data | The gateway should use the circuit | | | for network access for data | | | (e.g., PPP, SLIP, etc.). | |____________|__________________________________________|3.2.2.7. Coding of event names
Event names are composed of an optional package name, separated by a slash (/) from the name of the actual event. The event name can optionally be followed by an at sign (@) and the identifier of a connection on which the event should be observed. Event names are used in the RequestedEvents, SignalRequests and ObservedEvents parameter. Each signal has one of the following signal-types associated with: On/Off (OO), Time-out (TO), Brief (BR). (These signal types are specified in the package definitions, and are not present in the messages.) On/Off signals can be parameterized with a "+" to turn the signal on, or a "-" to turn the signal off. If an on/off signal is not parameterized, the signal is turned on. Both of the following will turn the vmwi signal on: vmwi(+), vmwi
The following are valid examples of event names:
____________________________________________________________
| L/hu | on-hook transition, in the line package |
| F/0 | digit 0 in the MF package |
| fh | Flash-hook, assuming that the line package|
| | is a default package for the end point. |
| G/rt@0A3F58 | Ring back signal on |
| | connection "0A3F58". |
|_____________|_____________________________________________|
In addition, the range and wildcard notation of events can be used,
instead of individual names, in the RequestedEvents and DetectEvents
parameters. The star sign can be used to denote "all connections",
and the dollar sign can be used to denote the "current" connection.
The following are valid examples of such notations:
__________________________________________________________
| M/[0-9] | Digits 0 to 9 in the MF package |
| fh | Flash-hook, assuming that the line package|
| | is a default package for the end point. |
| [0-9*#A-D]| All digits and letters in the DTMF |
| | packages (default for endpoint). |
| T/$ | All events in the trunk packages. |
| R/qa@* | The quality alert event in all |
| | connections |
| R/rt@$ | Ringback on current connection |
|___________|_____________________________________________|
3.2.2.8. RequestedEvents
The RequestedEvent parameter provides the list of events that have
been requested. The event codes are described in the previous
section.
Each event can be qualified by a requested action, or by a list of
actions. The actions, when specified, are encoded as a list of
keywords, enclosed in parenthesis and separated by commas. The codes
for the various actions are:
______________________________________
| Action | Code|
|______________________________|______|
| Notify immediately | N |
| Accumulate | A |
| Treat according to digit map | D |
| Swap | S |
| Ignore | I |
| Keep Signal(s) active | K |
| Embedded Notification Request| E |
|______________________________|______|
When no action is specified, the default action is to notify the
event. This means that, for example, ft and ft(N) are equivalent.
Events that are not listed are ignored.
The digit-map action can only be specified for the digits, letters
and interdigit timers in the MF and DTMF packages, or in other
packages that would define the encoding of digits and timers.
The requested list is encoded on a single line, with event/action
groups separated by commas. Examples of RequestedEvents encoding are:
R: hu(N), hf(S,N)
R: hu(N), [0-9#T](D)
In the case of the "enable" action, the embedded notification request
parameters are encoded as a list of up to three parameter groups,
separated by commas. Each group start by a one letter identifier,
followed by a list of parameters enclosed between parenthesis. The
first optional parameter group, identified by the letter "R", is the
enabled value of the RequestedEvents parameter. The second optional
group, identified by the letter "S", is the enabled value of the
SignalRequests parameter. The third optional group, identified by
the letter "D", is the enabled value of the DigitMap. (Note that some
existing implementation may encode these three components in a
different order.)
If the RequestedEvents is not present, the parameter will be set to a
null value. If the SignalRequest is not present, the parameter will
be set to a null value. If the DigitMap is absent, the current value
should be used. The following are valid examples of embedded
requests:
R: hd(E(R([0-9#T](D),hu(N)),S(dl),D([0-9].[#T])))
R: hd(E(R([0-9#T](D),hu(N)),S(dl)))
3.2.2.9. SignalRequests
The SignalRequests parameter provides the name of the signals that have been requested. Each signal is identified by a name, as indicated in the previous section. Several signals, such as for example announcement or ADSI display, can be qualified by additional parameters: * the name and parameters of the announcement, * the string that should be displayed. These parameters will be encoded as a set of UTF8 character strings, spearated by comams and enclosed within parenthesis, as in: S: adsi("123456 Francois Gerard") S: ann(no-such-number, 1234567) When several signals are requested, their codes are separated by a comma, as in: S: asdi(123456 Your friend), rg3.2.2.10. ObservedEvent
The observed event parameters provides the list of events that have been observed. The event codes are the same as those used in the NotificationRequest. Events that have been accumulated according to the digit map may be grouped in a single string; they should be reported as lists of isolated events if other events where detected during the digit accumulation. Examples of observed actions are: O: L/hu O: 8295555T O: 8,2,9,5,5,L/hf,5,5,T O: L/hf, L/hf, L/hu3.2.2.11. RequestedInfo
The RequestedInfo parameter contains a comma separated list of parameter codes, as defined in the "Parameter lines" section. For example, if one wants to audit the value of the NotifiedEntity, RequestIdentifier, RequestedEvents, SignalRequests, DigitMap, QuarantineHandling and DetectEvents parameters, The value of the RequestedInfo parameter will be: F:N,X,R,S,D,Q,T
The capabilities request, in the AuditEndPoint command, is encoded by
the keyword "A", as in:
F:A
3.2.2.12. QuarantineHandling
The quarantine handling parameter contains a list of comma separated
keywords:
* The keyword "process" or "discard" to indicate the treatment of
quarantined events. If neither process or discard is present,
process is assumed.
* The keyword "step" or "loop" to indicate whether exactly at most
one notification is expected, or whether multiple notifications
are allowed. If neither step or loop is present, step is assumed.
The following values are valid examples:
Q:loop
Q:process
Q:discard,loop
3.2.2.13. DetectEvents
The DetectEvent parameter is encoded as a comma separated list of
events, such as for example:
T: hu,hd,hf,[0-9#*]
It should be noted, that no actions can be associated with the
events.
3.2.2.14. EventStates
The EventStates parameter is encoded as a comma separated list of
events, such as for example:
ES: hu
It should be noted, that no actions can be associated with the
events.
3.2.2.15. RestartMethod
The RestartMethod parameter is encoded as one of the keywords "graceful", "forced", "restart", "disconnected" or "cancel-graceful" as for example: RM:restart3.2.2.16. Bearer Information
The values of the bearer informations are encoded as a comma separated list of attributes, represented by an attribute name, separated by a colon from an attribute value. The only attribute that is defined is the "encoding" (code "e"), whose defined values are "A" (A-law) and "mu" (mu-law). An example of bearer information encoding is: B: e:mu3.3. Format of response headers
The response header is composed of a response line, optionally followed by headers that encode the response parameters. An example of response header could be: 200 1203 OK The response line starts with the response code, which is a three digit numeric value. The code is followed by a white space, the transaction identifier, and an optional commentary preceded by a white space. The following table describe the parameters whose presence is mandatory or optional in a response header, as a function of the command that triggered the response. The letter M stands for mandatory, O for optional and F for forbidden.
___________________________________________________________________
| Parameter name | EP| CR| MD| DL| RQ| NT| AU| AU| RS|
| | CF| CX| CX| CX| NT| FY| EP| CX| IP|
|_____________________|____|____|____|____|____|____|____|____|____|
| ResponseAck | F | F | F | F | F | F | F | F | F |
| BearerInformation | F | F | F | F | F | F | O | F | F |
| CallId | F | F | F | F | F | F | F | O | F |
| ConnectionId | F | O*| F | F | F | F | F | F | F |
| RequestIdentifier | F | F | F | F | F | F | O | F | F |
| LocalConnection | F | F | F | F | F | F | O | O | F |
| Options | | | | | | | | | |
| Connection Mode | F | F | F | F | F | F | F | O | F |
| RequestedEvents | F | F | F | F | F | F | O | F | F |
| SignalRequests | F | F | F | F | F | F | O | F | F |
| NotifiedEntity | F | F | F | F | F | F | F | F | O |
| ReasonCode | F | F | F | F | F | F | O | F | F |
| ObservedEvents | F | F | F | F | F | F | O | F | F |
| DigitMap | F | F | F | F | F | F | O | F | F |
| Connection | F | F | F | O | F | F | F | O | F |
| Parameters | | | | | | | | | |
| Specific Endpoint ID| F | O | F | F | F | F | F | F | F |
| RequestedInfo | F | F | F | F | F | F | F | F | F |
| QuarantineHandling | F | F | F | F | F | F | O | F | F |
| DetectEvents | F | F | F | F | F | F | O | F | F |
| EventStates | F | F | F | F | F | F | O | F | F |
| RestartMethod | F | F | F | F | F | F | O | F | F |
| RestartDelay | F | F | F | F | F | F | O | F | F |
| Capabilities | F | F | F | F | F | F | O | F | F |
| SecondConnectionId | F | O | F | F | F | F | F | F | F |
| SecondEndpointID | F | O | F | F | F | F | F | F | F |
|_____________________|____|____|____|____|____|____|____|____|____|
| LocalConnection | F | M | O | F | F | F | F | O*| F |
| Descriptor | | | | | | | | | |
| RemoteConnection | F | F | F | F | F | F | F | O*| F |
| Descriptor | | | | | | | | | |
|_____________________|____|____|____|____|____|____|____|____|____|
In the case of a CreateConnection message, the response line is
followed by a Connection-Id parameter. It may also be followed a
Specific-Endpoint-Id parameter, if the creation request was sent to a
wildcarded Endpoint-Id. The connection-Id parameter is marked as
optional in the Table. In fact, it is mandatory with all positive
responses, when a connection was created, and forbidden when the
response is negative, when no connection as created.
In the case of a DeleteConnection message, the response line is
followed by a Connection Parameters parameter, as defined in section
3.2.2.2.
A LocalConnectionDescriptor should be transmitted with a positive response (code 200) to a CreateConnection. It may be transmitted in response to a ModifyConnection command, if the modification resulted in a modification of the session parameters. The LocalConnectionDescriptor is encoded as a "session description," as defined in section 3.4. It is separated from the response header by an empty line. When several session descriptors are encoded in the same response, they are encoded one after each other, separated by an empty line. This is the case for example when the response to an audit connection request carries both a local session description and a remote session description, as in: 200 1203 OK C: A3C47F21456789F0 N: [128.96.41.12] L: p:10, a:PCMU;G726-32 M: sendrecv P: PS=1245, OS=62345, PR=780, OR=45123, PL=10, JI=27,LA=48 v=0 c=IN IP4 128.96.41.1 m=audio 1296 RTP/AVP 0 v=0 c=IN IP4 128.96.63.25 m=audio 1296 RTP/AVP 0 96 a=rtpmap:96 G726-32/8000 In this example, according to the SDP syntax, each description starts with a "version" line, (v=...). The local description is always transmitted before the remote description. If a connection descriptor is requested, but it does not exist for the connection audited, that connection descriptor will appear with the SDP protocol version field only.
3.4. Formal syntax description of the protocol
In this section, we provided a formal description of the protocol syntax, following the "Augmented BNF for Syntax Specifications" defined in RFC 2234. MGCPMessage = MGCPCommand / MGCPResponse MGCPCommand = MGCPCommandLine 0*(MGCPParameter) [EOL *SDPinformation] MGCPCommandLine = MGCPVerb 1*(WSP) <transaction-id> 1*(WSP) <endpointName> 1*(WSP) MGCPversion EOL MGCPVerb = "EPCF" / "CRCX" / "MDCX" / "DLCX" / "RQNT" / "NTFY" / "AUEP" / "AUCX" / "RSIP" / extensionVerb extensionVerb = "X" 3(ALPHA / DIGIT) transaction-id = 1*9(DIGIT) endpointName = localEndpointName "@" DomainName LocalEndpointName = LocalNamePart 0*("/" LocalNamePart) LocalNamePart = AnyName / AllName / NameString AnyName = "$" AllNames = "*" NameString = 1*(range-of-allowed-characters) DomainName = 1*256(ALPHA / DIGIT / "." / "-") ; as defined in RFC 821 MGCPversion = "MGCP" 1*(WSP) 1*(DIGIT) "." 1*(DIGIT) [1*(WSP) ProfileName] ProfileName = 1*(range-of-allowed-characters) MGCPParameter = ParameterValue EOL ParameterValue = ("K" ":" 0*WSP <ResponseAck>) / ("B" ":" 0*WSP <BearerInformation>) / ("C" ":" 0*WSP <CallId>) / ("I" ":" 0*WSP <ConnectionId>) / ("N" ":" 0*WSP <NotifiedEntity>) / ("X" ":" 0*WSP <RequestIdentifier>) / ("L" ":" 0*WSP <LocalConnectionOptions>) / ("M" ":" 0*WSP <ConnectionMode>) / ("R" ":" 0*WSP <RequestedEvents>) / ("S" ":" 0*WSP <SignalRequests>) / ("D" ":" 0*WSP <DigitMap>) / ("O" ":" 0*WSP <ObservedEvents>) / ("P" ":" 0*WSP <ConnectionParameters>) / ("E" ":" 0*WSP <ReasonCode>) /
("Z" ":" 0*WSP <SpecificEndpointID>) /
("Z2" ":" 0*WSP <SecondEndpointID>) /
("I2" ":" 0*WSP <SecondConnectionID>) /
("F" ":" 0*WSP <RequestedInfo>) /
("Q" ":" 0*WSP <QuarantineHandling>) /
("T" ":" 0*WSP <DetectEvents>) /
("RM" ":" 0*WSP <RestartMethod>) /
("RD" ":" 0*WSP <RestartDelay>) /
("A" ":" 0*WSP <Capabilities>) /
("ES" ":" 0*WSP <EventStates>) /
(extensionParameter ":" 0*WSP <parameterString>)
ResponseAck = confirmedTransactionIdRange
*[ "," confirmedTransactionIdRange ]
confirmedTransactionIdRange = 1*9DIGIT [ "-" 1*9DIGIT ]
BearerInformation = BearerAttribute 0*("," 0*WSP BearerAttribute)
BearerAttribute = ("e" ":" <BearerEncoding>)
BearerEncoding = "A" / "mu"
CallId = 1*32(HEXDIG)
// The audit request response may include a list of identifiers
ConnectionId = 1*32(HEXDIG) 0*("," 1*32(HEXDIG))
SecondConnectionID = ConnectionId
NotifiedEntity = [LocalName "@"] DomainName [":" portNumber]
LocalName = 1*32(suitableCharacter)
portNumber = 1*5(DIGIT)
RequestIdentifier = 1*32(HEXDIG)
LocalConnectionOptions = [ LocalOptionValue 0*(WSP)
0*("," 0*(WSP) LocalOptionValue 0*(WSP)) ]
LocalOptionValue = ("p" ":" <packetizationPeriod> )
/ ("a" ":" <compressionAlgorithm> )
/ ("b" ":" <bandwidth> )
/ ("e" ":" <echoCancellation> )
/ ("gc" ":" <gainControl> )
/ ("s" ":" <silenceSuppression> )
/ ("t" ":" <typeOfService> )
/ ("r" ":" <resourceReservation> )
/ ("k" ":" <encryptionmethod>[":"<encryptionKey>])
/ ("nt" ":" <typeOfNetwork> )
/ (localOptionExtensionName ":"
/ localOptionExtensionValue)
Capabilities = [ CapabilityValue 0*(WSP)
0*("," 0*(WSP) CapabilityValue 0*(WSP)) ]
CapabilityValue = LocalOptionValue
/ ("v" ":" <supportedPackages>)
/ ("m" ":" <supportedModes> )
packetizationPeriod = 1*4(DIGIT)["-" 1*4(DIGIT)]
compressionAlgorithm = algorithmName 0*(";" algorithmName)
algorithmName = 1*32(SuitableCharacter)
bandwidth = 1*4(DIGIT)["-" 1*4(DIGIT)]
echoCancellation = "on" / "off"
gainControl = "auto" / ["-"]1*4(DIGIT)
silenceSuppression = "on" / "off"
typeOfService = 2HEXDIG
resourceReservation = "g" / "cl" / "be"
;encryption parameters are coded as in SDP (RFC 2327)
encryptiondata = ( "clear" ":" <encryptionKey> )
/ ( "base64" ":" <encodedEncryptionKey> )
/ ( "uri" ":" <URItoObtainKey> )
/ ( "prompt" ) ; defined in SDP, not usable in MGCP!
encryptionKey = 1*(SuitableCharacter / SP)
encodedEncryptionKey = 1*(ALPHA / DIGIT / "+" / "/" / "=")
URItoObtainKey = 1*(SuitableCharacter) / quotedString
typeOfNetwork = "IN" / "ATM" / "LOCAL"
supportedModes= ConnectionMode 0*(";" ConnectionMode)
supportedPackages = packageName 0*(";" packageName)
localOptionExtensionName = "x" ("+"/"-") 1*32(SuitableCharacter)
localOptionExtensionValue = 1*32(SuitableCharacter) / quotedString
ConnectionMode = "sendonly" / "recvonly" / "sendrecv" /
"confrnce" / "inactive" / "loopback" /
"conttest" / "netwloop" / "netwtest" / "data"
RequestedEvents = [requestedEvent 0*("," 0*(WSP) requestedEvent)]
requestedEvent = eventName [ "(" requestedActions ")" ]
eventName = [ (packageName / "*") "/" ] (eventId / "all" / eventRange)
[ "@" (ConnectionId / "$" / "*") ]
packageName = 1*(ALPHA / DIGIT / HYPHEN)
eventId = 1*(SuitableCharacter)
eventRange = "[" 1*(DIGIT / DTMFLetter / "*" / "#" /
(DIGIT "-" DIGIT)/(DTMFLetter "-"
DTMFLetter)) "]"
requestedActions = requestedAction 0*("," 0*(WSP) requestedAction)
requestedAction = "N" / "A" / "D" / "S" / "I" / "K" /
"E" "(" EmbeddedRequest ")"
EmbeddedRequest = ( "R" "(" EmbeddedRequestList ")"
["," "S" "(" EmbeddedSignalRequest ")" ]
["," "D" "(" EmbeddedDigitMap ")" ] )
/ ( "S" "(" EmbeddedSignalRequest ")"
["," "D" "(" EmbeddedDigitMap ")" ] )
/ ( "D" "(" EmbeddedDigitMap ")" )
EmbeddedRequestList = RequestedEvents
EmbeddedSignalRequest = SignalRequests
EmbeddedDigitMap = DigitMap
SignalRequests = [ SignalRequest 0*("," 0*(WSP) SignalRequest ) ]
SignalRequest = eventName [ "(" eventParameters ")" ]
eventParameters = eventParameter 0*("," 0*(WSP) eventParameter)
eventParameter = eventParameterString / quotedString
eventParameterString = 1*(SuitableCharacter)
DigitMap = DigitString / "(" DigitStringList ")"
DigitStringList = DigitString 0*( "|" DigitString )
DigitString = 1*(DigitStringElement)
DigitStringElement = DigitPosition ["."]
DigitPosition = DigitMapLetter / DigitMapRange
DigitMapLetter = DIGIT / "#" / "*" / "A" / "B" / "C" / "D" / "T"
DigitMapRange = "x" / "[" 1*DigitLetter "]"
DigitLetter ::= *((DIGIT "-" DIGIT ) / DigitMapLetter)
ObservedEvents = SignalRequests
EventStates = SignalRequests
ConnectionParameters = [ConnectionParameter
0*( "," 0*(WSP) ConnectionParameter )
ConnectionParameter = ( "PS" "=" packetsSent )
/ ( "OS" "=" octetsSent )
/ ( "PR" "=" packetsReceived )
/ ( "OR" "=" octetsReceived )
/ ( "PL" "=" packetsLost )
/ ( "JI" "=" jitter )
/ ( "LA" "=" averageLatency )
/ ( ConnectionParameterExtensionName "="
ConnectionParameterExtensionValue )
packetsSent = 1*9(DIGIT)
octetsSent = 1*9(DIGIT)
packetsReceived = 1*9(DIGIT)
octetsReceived = 1*9(DIGIT)
packetsLost = 1*9(DIGIT)
jitter = 1*9(DIGIT)
averageLatency = 1*9(DIGIT)
ConnectionParameterExtensionName = "X" "-" 2*ALPHA
ConnectionParameterExtensionValue = 1*9(DIGIT)
ReasonCode = 3DIGIT [SPACE 1*(%x20-7E)]
SpecificEndpointID = endpointName
SecondEndpointID = endpointName
RequestedInfo = [infoCode 0*("," infoCode)]
infoCode = "B" / "C" / "I" / "N" / "X" / "L" / "M" /
"R" / "S" / "D" / "O" / "P" / "E" / "Z" /
"Q" / "T" / "RC" / "LC" / "A" / "ES" / "RM" / "RD"
QuarantineHandling = loopControl / processControl /
(loopControl "," processControl )
loopControl = "step" / "loop"
processControl = "process" / "discard"
DetectEvents = [eventName 0*("," eventName)]
RestartMethod = "graceful" / "forced" / "restart" / "disconnected"
RestartDelay = 1*6(DIGIT)
extensionParameter = "X" ("-"/"+") 1*6(ALPHA / DIGIT)
parameterString = 1*(%x20-7F)
MGCPResponse = MGCPResponseLine 0*(MGCPParameter)
[EOL *SDPinformation]
MGCPResponseLine = (<responseCode> 1*(WSP) <transaction-id>
[1*(WSP) <responseString>] EOL)
responseCode = 3DIGIT
responseString = *(%x20-7E)
SuitableCharacter= DIGIT / ALPHA / "+" / "-" / "_" / "&" /
"!" / "'" / "|" / "=" / "#" / "?" / "/" /
"." / "$" / "*" / ";" / "@" / "[" / "]" /
"^" / "`" / "{" / "}" / "~"
quotedString = DQUOTE visibleString
0*(quoteEscape visibleString) DQUOTE
quoteEscape = DQUOTE DQUOTE
visibleString = (%x00-21 / %x23-FF)
EOL = CRLF / LF
SDPinformation = ;See RFC 2327
3.5. Encoding of the session description
The session description is encoded in conformance with the session
description protocol, SDP. MGCP implementations are expected to be
fully capable of parsing any conformant SDP message, and should send
session descriptions that strictly conform to the SDP standard. The
usage of SDP actually depends on the type of session that is being,
as specified in the "mode" parameter:
* if the mode is set to "data", the session description describes
the configuration of a data access service.
* if the mode is set to any other value, the session description is
for an audio service.
For an audio service, the gateway will consider the information
provided in SDP for the "audio" media. For a data service, the
gateway will consider the information provided for the "network-
access" media.
3.5.1. Usage of SDP for an audio service
In a telephony gateway, we only have to describe sessions that use
exactly one media, audio. The parameters of SDP that are relevant for
the telephony application are:
At the session description level:
* The IP address of the remote gateway (in commands) or of the
local gateway (in responses), or multicast address of the audio
conference, encoded as an SDP "connection data" parameter. This
parameter specifies the IP address that will be used to
exchange RTP packets.
For the audio media:
* Media description field (m) specifying the audio media, the
transport port used for receiving RTP packets by the remote
gateway (commands) or by the local gateway (responses), the
RTP/AVP transport, and the list of formats that the gateway
will accept. This list should normally always include the code
0 (reserved for PCMU).
* Optionally, RTPMAP attributes that define the encoding of
dynamic audio formats,
* Optionally, a packetization period (packet time) attribute
(Ptime) defining the duration of the packet,
* Optionally, an attribute defining the type of connection
(sendonly, recvonly, sendrecv, inactive). Note that this
attribute does not have a direct relation with the "Mode"
parameter of MGCP. In fact, the SDP type of connection will
most of the time be set to "sendrecv", regardless of the value
used by MGCP. Other values will only be used rarely, for
example in the case of information or announcement servers that
need to establish one way connections.
* The IP address of the remote gateway (in commands) or of the
local gateway (in responses), if it is not present at the
session level.
An example of SDP specification for an audio connection could be:
v=0
c=IN IP4 128.96.41.1
m=audio 3456 RTP/AVP 0 96
a=rtpmap:96 G726-32/8000
There is a request, in some environments, to use the MGCP to
negotiate connections that will use other transmission channels than
RTP over UDP and IP. This will be detailed in an extension to this
document.
3.5.2. Usage of SDP in a network access service
The parameters of SDP that are relevant for a data network access
application are:
For the data media:
* Media description field (m) specifying the network access
media, identified by the code "m=nas/xxxx", where "xxxx"
describes the access control method that should be used for
parametrizing the network access, as specified below. The field
may also specify the port that should be used for contacting
the server, as specified in the SDP syntax.
* Connection address parameter (c=) specifying the address, or
the domain name, of the server that implement the access
control method. This parameter may also be specified at the
session level.
* Optionally, a bearer type attribute (a=bearer:) describing the
type of data connection to be used, including the modem type.
* Optionally, a framing type attribue (a=framing:) describing the
type of framing that will be used on the channel.
* Optionally, attributes describing the called number
(a=dialed:), the number to which the call was delivered
(a=called:) and the calling number (a=dialing:).
* Optionally, attributes describing the range of addresses that
could be used by the dialup client on its LAN (a=subnet:).
* Optionally, an encryption key, encoded as specified in the SDP
protocol(k=).
The connection address shall be encoded as specified in the SDP
standard. It will be used in conjunction with the port specified in
the media line to access a server, whose type will one of:
__________________________________________________________
| Method name| Method description |
|____________|____________________________________________|
| radius | Authentication according |
| | to the Radius protocol. |
| tacacs | Authentication according |
| | to the TACACS+ protocol. |
| diameter | Authentication according |
| | to the Diameter protocol. |
| l2tp | Level 2 tunneling protocol. |
| | The address and port are those of the LNS.|
| login | Local login. (There is normally |
| | no server for that method.) |
| none | No authentication required. |
| | (The call was probably vetted |
| | by the Call Agent.) |
|____________|____________________________________________|
If needed, the gateway may use the key specified in the announcement
to access the service. That key, in particular, may be used for the
establishment of an L2TP tunnel.
The bearer attribute is composed of a bearer name and an optional
extension. The bearer type specifies the type of modulation (modem
name) or, in the case of digital connections, the type of ISDN
service (8 bits, 7 bits). When an extension is present, it is
separated from the bearer name by a single slash (/). The valid
values of the bearer attribute are defined in the following table:
____________________________________________________________________
| Type of bearer description | Example of values |
|_________________________________|_________________________________|
| ITU modem standard | V.32, V.34, V.90. |
| ITU modem standard qualified | v.90/3com, |
| by a manufacturer name | v.90/rockwell, |
| | v.90/xxx |
| Well known modem types | X2, K56flex |
| ISDN transparent access, 64 kbps| ISDN64 |
| ISDN64 + V.110 | ISDN64/V.110 |
| ISDN64 + V.120 | ISDN64/V.120 |
| ISDN transparent access, 56 kbps| ISDN56 |
| Informal identification | (Requires coordination between |
| | the Call Agent and the gateway)|
|_________________________________|_________________________________|
The valid values of the framing attribute are defined in the
following table:
_________________________________________________
| Type of framing description| Example of values|
|____________________________|___________________|
| PPP, asynchronous framing | ppp-asynch |
| PPP, HDLC framing | ppp-hdlc |
| SLIP, asynchronous | slip |
| Asynchronous, no framing | asynch |
|____________________________|___________________|
The network access authentication parameter provides instructions on
the access control that should be exercized for the data call. This
optional attribute is encoded as:
"a=subnet:" <network type> <address type>
<connection address> "/" <prefix length>
Where the parameters "network type", "address type", and "connection
address" are formatted as defined for the connection address
parameter (c=) in SDP, and where the "prefix length" is a decimal
representation of the number of bits in the prefix.
Examples of SDP announcement for the network access service could be:
v=0
m=nas/radius
c=IN IP4 radius.example.net
a=bearer:v.34
a=framing:ppp-asynch
a=dialed:18001234567
a=called:12345678901
a=dialing:12340567890
v=0
m=nas/none
c=IN IP4 128.96.41.1
a=subnet:IN IP4 123.45.67.64/26
a=bearer:isdn64
a=framing:ppp-sync
a=dialed:18001234567
a=dialing:2345678901
v=0
c=IN IP4 access.example.net
m=nas/l2tp
k=clear:some-shared-secret
a=bearer:v.32
a=framing:ppp-asynch
a=dialed:18001234567
a=dialing:2345678901
3.5.3. Usage of SDP for ATM connections
The specification of the SDP payload for ATM connections will be
described in a companion document, "Usage of MGCP to control Voice
over ATM gateways." The following text is indicative.
The SDP payload will specify:
* That the connection is to be established over an ATM interface,
using the "c=" parameter of SDP to specify an address in the ATM
family, the ATM addressing variant (NSAP, UNI, E.164) and the ATM
address.
* The "m=audio" parameter will specify the audio encoding and, if
needed, the VPI and VCI.
* Additional attributes parameters (a=) will be used to specify the
ATM coding variants, such as the type of adaptation layer and the
error correction or loss compenmsation algorithms.
An example of SDP payload for an ATM connection could be:
v=0 c=ATM NSAP
47.0091.8100.0000.0060.3e64.fd01.0060.3e64.fd01.fe m=audio
5/1002 ATM/AVP PCMU a=connection_type:AAL2
3.5.4. Usage of SDP for local connections
When MGCP is used to set up internal connections within a single
gateway, the SDP format is used to encode the parameters of that
connection. The following parameters will be used:
* The connection parameter (C=) will specify that the connection is
local, using the keyword "LOCAL" as network type space, the
keyword "EPN" (endpoint name) as address type, and the name of
the endpoint as the connection-address.
* The "m=audio" parameter will specify a port number, which will
always be set to 0, the type of protocol, always set to the
keyword LOCAL, and the type of encoding, using the same
conventions used for RTP (RTP payload numbers.) The type of
encoding should normally be set to 0 (PCMU).
An example of local SDP payload could be:
v=0
c=LOCAL EPN X35V3+A4/13
m=audio 0 LOCAL 0
(page 91 continued on part 4)
