/ "[" IPv4address / IPv6address "]" ; see RFC2373
; Rewritten to ABNF from RFC821
number = 1*DIGIT
;From RFC2373
IPv6address = hexpart [ ":" IPv4address ]
IPv4address = 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT
; this production, while occurring in RFC2373, is not referenced
; IPv6prefix = hexpart "/" 1*2DIGIT
hexpart = hexseq / hexseq "::" [ hexseq ] / "::" [ hexseq ]
hexseq = hex4 *( ":" hex4)
hex4 = 1*4HEXDIG
MGCPversion = "MGCP" 1*(WSP) 1*(DIGIT) "." 1*(DIGIT)
[1*(WSP) ProfileName]
ProfileName = VCHAR *( WSP / VCHAR)
MGCPParameter = ParameterValue EOL
; Check infoCode if more parameter values defined
; Most optional values can only be omitted when auditing
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])
/ ("PL" ":" 0*(WSP) [PackageList]) ; Auditing only
/ ("MD" ":" 0*(WSP) MaxMGCPDatagram) ; Auditing only
/ (extensionParameter ":" 0*(WSP) [parameterString])
; A final response may include an empty ResponseAck
ResponseAck = confirmedTransactionIdRange
*( "," 0*(WSP) confirmedTransactionIdRange )
confirmedTransactionIdRange = transaction-id ["-" transaction-id]
BearerInformation = BearerAttribute 0*("," 0*(WSP) BearerAttribute)
BearerAttribute = ("e" ":" BearerEncoding)
/ (BearerExtensionName [":" BearerExtensionValue])
BearerExtensionName = PackageLCOExtensionName
BearerExtensionValue = LocalOptionExtensionValue
BearerEncoding = "A" / "mu"
CallId = 1*32(HEXDIG)
; The audit request response may include a list of identifiers
ConnectionId = 1*32(HEXDIG) 0*("," 0*(WSP) 1*32(HEXDIG))
SecondConnectionID = ConnectionId
NotifiedEntity = [LocalName "@"] DomainName [":" portNumber]
LocalName = LocalEndpointName ; No internal structure
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" ":" encryptiondata)
/ ("nt" ":" ( typeOfNetwork /
supportedTypeOfNetwork))
/ (LocalOptionExtensionName
[":" LocalOptionExtensionValue])
Capabilities = CapabilityValue 0*(WSP)
0*("," 0*(WSP) CapabilityValue 0*(WSP))
CapabilityValue = LocalOptionValue
/ ("v" ":" supportedPackages)
/ ("m" ":" supportedModes)
PackageList = pkgNameAndVers 0*("," pkgNameAndVers)
pkgNameAndVers = packageName ":" packageVersion
packageVersion = 1*(DIGIT)
packetizationPeriod = 1*4(DIGIT) ["-" 1*4(DIGIT)]
compressionAlgorithm = algorithmName 0*(";" algorithmName)
algorithmName = 1*(SuitableLCOCharacter)
bandwidth = 1*4(DIGIT) ["-" 1*4(DIGIT)]
echoCancellation = "on" / "off"
gainControl = "auto" / ["-"] 1*4(DIGIT)
silenceSuppression = "on" / "off"
typeOfService = 1*2(HEXDIG) ; 1 hex only for capabilities
resourceReservation = "g" / "cl" / "be"
;encryption parameters are coded as in SDP (RFC2327)
;NOTE: encryption key may contain an algorithm as specified in RFC1890
encryptiondata = ( "clear" ":" encryptionKey )
/ ( "base64" ":" encodedEncryptionKey )
/ ( "uri" ":" URItoObtainKey )
/ ( "prompt" ) ; defined in SDP, not usable in MGCP!
encryptionKey = 1*(SuitableLCOCharacter) / quotedString
; See RFC2045
encodedEncryptionKey = 1*(ALPHA / DIGIT / "+" / "/" / "=")
URItoObtainKey = 1*(SuitableLCOCharacter) / quotedString
typeOfNetwork = "IN" / "ATM" / "LOCAL" / OtherTypeOfNetwork
; Registered with IANA - see RFC2327
OtherTypeOfNetwork = 1*(SuitableLCOCharacter)
supportedTypeOfNetwork = typeOfNetwork *(";" typeOfNetwork)
supportedModes = ConnectionMode 0*(";" ConnectionMode)
supportedPackages = packageName 0*(";" packageName)
packageName = 1*(ALPHA / DIGIT / HYPHEN) ; Hyphen neither first or last
LocalOptionExtensionName = VendorLCOExtensionName
/ PackageLCOExtensionName
/ OtherLCOExtensionName
VendorLCOExtensionName = "x" ("+"/"-") 1*32(SuitableExtLCOCharacter)
PackageLCOExtensionName = packageName "/"
1*32(SuitablePkgExtLCOCharacter)
; must not start with "x-" or "x+"
OtherLCOExtensionName = 1*32(SuitableExtLCOCharacter)
LocalOptionExtensionValue = (1*(SuitableExtLCOValChar)
/ quotedString)
*(";" (1*(SuitableExtLCOValChar)
/ quotedString))
;Note: No "data" mode.
ConnectionMode = "sendonly" / "recvonly" / "sendrecv"
/ "confrnce" / "inactive" / "loopback"
/ "conttest" / "netwloop" / "netwtest"
/ ExtensionConnectionMode
ExtensionConnectionMode = PkgExtConnectionMode
PkgExtConnectionMode = packageName "/" 1*(ALPHA / DIGIT)
RequestedEvents = requestedEvent 0*("," 0*(WSP) requestedEvent)
requestedEvent = (eventName ["(" requestedActions ")"])
/ (eventName "(" requestedActions ")"
"(" eventParameters ")" )
eventName = [(packageName / "*") "/"]
(eventId / "all" / eventRange
/ "*" / "#") ; for DTMF
["@" (ConnectionId / "$" / "*")]
eventId = 1*(ALPHA / DIGIT / HYPHEN) ; Hyphen neither first nor last
eventRange = "[" 1*(DigitMapLetter / (DIGIT "-" DIGIT) /
(DTMFLetter "-" DTMFLetter)) "]"
DTMFLetter = "A" / "B" / "C" / "D"
requestedActions = requestedAction 0*("," 0*(WSP) requestedAction)
requestedAction = "N" / "A" / "D" / "S" / "I" / "K"
/ "E" "(" EmbeddedRequest ")"
/ ExtensionAction
ExtensionAction = PackageExtAction
PackageExtAction = packageName "/" Action ["(" ActionParameters ")"]
Action = 1*ALPHA
ActionParameters = eventParameters ; May contain actions
;NOTE: Should tolerate different order when receiving, e.g., for NCS.
EmbeddedRequest = ( "R" "(" EmbeddedRequestList ")"
["," 0*(WSP) "S" "(" EmbeddedSignalRequest ")"]
["," 0*(WSP) "D" "(" EmbeddedDigitMap ")"] )
/ ( "S" "(" EmbeddedSignalRequest ")"
["," 0*(WSP) "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 = eventParameterValue
/ eventParameterName "=" eventParameter
/ eventParameterName "(" eventParameters ")"
eventParameterString = 1*(SuitableEventParamCharacter)
eventParameterName = eventParameterString
eventParameterValue = eventParameterString / quotedString
DigitMap = DigitString / "(" DigitStringList ")"
DigitStringList = DigitString 0*( "|" DigitString )
DigitString = 1*(DigitStringElement)
DigitStringElement = DigitPosition ["."]
DigitPosition = DigitMapLetter / DigitMapRange
; NOTE "X" is now included
DigitMapLetter = DIGIT / "#" / "*" / "A" / "B" / "C" / "D" / "T"
/ "X" / ExtensionDigitMapLetter
ExtensionDigitMapLetter = "E" / "F" / "G" / "H" / "I" / "J" / "K"
/ "L" / "M" / "N" / "O" / "P" / "Q" / "R"
/ "S" / "U" / "V" / "W" / "Y" / "Z"
; NOTE "[x]" is now allowed
DigitMapRange = "[" 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 = VendorCPExtensionName
/ PackageCPExtensionName
VendorCPExtensionName = "X" "-" 2*ALPHA
PackageCPExtensionName = packageName "/" CPName
CPName = 1*(ALPHA / DIGIT / HYPHEN)
ConnectionParameterExtensionValue = 1*9(DIGIT)
MaxMGCPDatagram = 1*9(DIGIT)
ReasonCode = 3DIGIT
[1*(WSP) "/" packageName] ; Only for 8xx
[WSP 1*(%x20-7E)]
SpecificEndpointID = endpointName
SecondEndpointID = endpointName
RequestedInfo = infoCode 0*("," 0*(WSP) infoCode)
infoCode = "B" / "C" / "I" / "N" / "X" / "L" / "M" / "R" / "S"
/ "D" / "O" / "P" / "E" / "Z" / "Q" / "T" / "RC" / "LC"
/ "A" / "ES" / "RM" / "RD" / "PL" / "MD" / extensionParameter
QuarantineHandling = loopControl / processControl
/ (loopControl "," 0*(WSP) processControl )
loopControl = "step" / "loop"
processControl = "process" / "discard"
DetectEvents = SignalRequests
RestartMethod = "graceful" / "forced" / "restart" / "disconnected"
/ "cancel-graceful" / extensionRestartMethod
extensionRestartMethod = PackageExtensionRM
PackageExtensionRM = packageName "/" 1*32(ALPHA / DIGIT / HYPHEN)
RestartDelay = 1*6(DIGIT)
extensionParameter = VendorExtensionParameter
/ PackageExtensionParameter
/ OtherExtensionParameter
VendorExtensionParameter = "X" ("-"/"+") 1*6(ALPHA / DIGIT)
PackageExtensionParameter = packageName "/"
1*32(ALPHA / DIGIT / HYPHEN)
; must not start with "x-" or x+"
OtherExtensionParameter = 1*32(ALPHA / DIGIT / HYPHEN)
;If first character is a double-quote, then it is a quoted-string
parameterString = (%x21 / %x23-7F) *(%x20-7F) ; first and last must not
; be white space
/ quotedString
MGCPResponse = MGCPResponseLine 0*(MGCPParameter)
*2(EOL *SDPinformation)
MGCPResponseLine = responseCode 1*(WSP) transaction-id
[1*(WSP) "/" packageName] ; Only for 8xx
[WSP responseString] EOL
responseCode = 3DIGIT
responseString = *(%x20-7E)
SuitablePkgExtLCOCharacter = SuitableLCOCharacter
SuitableExtLCOCharacter = DIGIT / ALPHA / "+" / "-" / "_" / "&"
/ "!" / "'" / "|" / "=" / "#" / "?"
/ "." / "$" / "*" / "@" / "[" / "]"
/ "^" / "`" / "{" / "}" / "~"
SuitableLCOCharacter = SuitableExtLCOCharacter / "/"
SuitableExtLCOValChar = SuitableLCOCharacter / ":"
; VCHAR except """, "(", ")", ",", and "="
SuitableEventParamCharacter = %x21 / %x23-27 / %x2A-2B
/ %x2D-3C / %x3E-7E
; NOTE: UTF8 encoded
quotedString = DQUOTE 0*(quoteEscape / quoteChar) DQUOTE
quoteEscape = DQUOTE DQUOTE
quoteChar = (%x00-21 / %x23-FF)
EOL = CRLF / LF
HYPHEN = "-"
; See RFC2327 for proper SDP grammar instead.
SDPinformation = SDPLine CRLF *(SDPLine CRLF) ; see RFC2327
SDPLine = 1*(%x01-09 / %x0B / %x0C / %x0E-FF) ; for proper def.
Appendix B: Base Package
Package name: B
Version: 0
The MGCP specification defines a base package which contains a set of
events and extension parameters that are of general use to the
protocol. Although not required, it is highly RECOMMENDED to support
this package as it provides important functionality for the base
protocol.
B.1 Events
The table below lists the events:
------------------------------------------------------------------
| Symbol | Definition | R | S Duration |
|---------|----------------------------|-----|---------------------|
| enf(##) | embedded RQNT failure | x | |
| oef | observed events full | x | |
| qbo | quarantine buffer overflow | x | |
------------------------------------------------------------------
The events are defined as follows:
Embedded NotificationRequest failure (enf):
The Embedded NotificationRequest Failure (enf) event is generated
when an embedded Notification Request failure occurs. When the
event is requested, it should be as part of the Embedded
NotificationRequest itself. When the event is reported, it may be
parameterized with an error code (see Section 2.4) detailing the
error that occurred. When requested, it cannot be parameterized.
Observed events full (oef):
The event is generated when the endpoint is unable to accumulate
any more events in the list of ObservedEvents. If this event
occurs, and it is not used to trigger a Notify, subsequent events
that should have been added to the list will be lost.
Quarantine buffer overflow (qbo):
The event is generated when the quarantine buffer overflows and one
or more events have been lost.
B.2 Extension Parameters
B.2.1 PersistentEvents
PersistentEvents: A list of events that the gateway is requested to
detect and report persistently. The parameter is optional but can be
provided in any command where the DetectEvents parameter can be
provided. The initial default value of the parameter is empty. When
the parameter is omitted from a command, it retains its current
value. When the parameter is provided, it completely replaces the
current value. Providing an event in this list, is similar (but
preferable) to defining that particular event as being persistent.
The current list of PersistentEvents will implicitly apply to the
current as well as subsequent NotificationRequests, however no glare
detection etc. will be performed (similarly to DetectEvents). If an
event provided in this list is included in a RequestedEvents list,
the action and event parameters used in the RequestedEvents will
replace the action and event parameters associated with the event in
the PersistentEvents list for the life of the RequestedEvents list,
after which the PersistentEvents action and event parameters are
restored. Events with event states requested through this parameter
will be included in the list of EventStates if audited.
PersistentEvents can also be used to detect events on connections.
Use of the "all connections" wildcard is straightforward, whereas
using PersistentEvents with one or more specific connections must be
considered carefully. Once the connection in question is deleted, a
subsequent NotificationRequest without a new PersistentEvents value
will fail (error code 515 - incorrect connection-id, is RECOMMENDED),
as it implicitly refers to the deleted connection.
The parameter generates the relevant error codes from the base
protocol, e.g., error code 512 if an unknown event is specified.
The PersistentEvents parameter can be audited, in which case it will
return its current value. Auditing of RequestedEvents is not
affected by this extension, i.e., events specified in this list are
not automatically reported when auditing RequestedEvents.
The parameter name for PersistentEvents is "PR" and it is defined by
the production:
PersistentEvents = "PR" ":" 0*WSP [RequestedEvents]
The following example illustrates the use of the parameter:
B/PR: L/hd(N), L/hf(N), L/hu(N), B/enf, B/oef, B/qbo
which instructs the endpoint to persistently detect and report off-
hook, hook-flash, and on-hook. It also instructs the endpoint to
persistently detect and report Embedded Notification Request failure,
Observed events full, and Quarantine buffer overflow.
B.2.2 NotificationState
NotificationState is a RequestedInfo parameter that can be audited
with the AuditEndpoint command. It can be used to determine if the
endpoint is in the notification state or not.
The parameter is forbidden in any command. In responses, it is a
valid response parameter for AuditEndpoint only.
It is defined by the following grammar:
NotificationState = "NS" ":" 0*WSP NotificationStateValue
NotificationStateValue = "ns" / "ls" / "o"
It is requested as part of auditing by including the parameter code
in RequestedInfo, as in:
F: B/NS
The response parameter will contain the value "ns" if the endpoint is
in the "notification state", the value "ls" if the endpoint is in the
"lockstep state" (i.e., waiting for an RQNT after a response to a
NTFY has been received when operating in "step" mode), or the value
"o" otherwise, as for example:
B/NS: ns
B.3 Verbs
MGCP packages are not intended to define new commands, however an
exception is made in this case in order to add an important general
capability currently missing, namely the ability for the gateway to
send a generic message to the Call Agent.
The definition of the new command is:
ReturnCode
<-- Message(EndpointId
[, ...])
EndpointId is the name for the endpoint(s) in the gateway which is
issuing the Message command. The identifier MUST be a fully
qualified endpoint identifier, including the domain name of the
gateway. The local part of the endpoint name MUST NOT use the "any
of" wildcard.
The only parameter specified in the definition of the Message command
is the EndpointId, however, it is envisioned that extensions will
define additional parameters to be used with the Message command.
Such extensions MUST NOT alter or otherwise interfere with the normal
operation of the basic MGCP protocol. They may however define
additional capabilities above and beyond that provided by the basic
MGCP protocol. For example, an extension to enable the gateway to
audit the packages supported by the Call Agent could be defined,
whereas using the Message command as an alternative way of reporting
observed events would be illegal, as that would alter the normal MGCP
protocol behavior.
In order to not interfere with normal MGCP operation, lack of a
response to the Message command MUST NOT lead the endpoint to become
disconnected. The endpoint(s) MUST be prepared to handle this
transparently and continue normal processing unaffected.
If the endpoint(s) receive a response indicating that the Call Agent
does not support the Message command, the endpoint(s) MUST NOT send a
Message command again until the current "notified entity" has
changed. Similarly, if the endpoint(s) receive a response indicating
that the Call Agent does not support one or more parameters in the
Message command, the endpoint(s) MUST NOT send a Message command with
those parameters again until the current "notified entity" has
changed.
The Message command is encoded as MESG, as shown in the following
example:
MESG 1200 aaln/1@rgw.whatever.net MGCP 1.0
Appendix C: IANA Considerations
C.1 New MGCP Package Sub-Registry
The IANA has established a new sub-registry for MGCP packages under
http://www.iana.org/assignments/mgcp-packages.
Packages can be registered with the IANA according to the following
procedure:
The package MUST have a unique string name which MUST NOT start with
the two characters "x-" or "x+".
The package title, name, and version (zero assumed by default) MUST
be registered with IANA as well as a reference to the document that
describes the package. The document MUST have a stable URL and MUST
be contained on a public web server.
Packages may define one or more Extension Digit Map Letters, however
these are taken from a limited and flat name space. To prevent name
clashing, IANA SHALL NOT register a package that defines an Extension
Digit Map Letter already defined in another package registered by
IANA. To ease this task, such packages SHALL contain the line
"Extension Digit Map Letters: " followed by a list of the Extension
Digit Map Letters defined in the package at the beginning of the
package definition.
A contact name, e-mail and postal address for the package MUST be
provided. The contact information SHALL be updated by the defining
organization as necessary.
Finally, prior to registering a package, the IANA MUST have a
designated expert [23] review the package. The expert reviewer will
send e-mail to the IANA on the overall review determination.
C.2 New MGCP Package
This document defines a new MGCP Base Package in Appendix B, which
has been registered by IANA.
C.3 New MGCP LocalConnectionOptions Sub-Registry
The IANA has established a new sub-registry for MGCP
LocalConnectionOptions under http://www.iana.org/assignments/mgcp-
localconnectionoptions.
Packages are the preferred extension mechanism, however for backwards
compatibility, local connection options beyond those provided in this
specification can be registered with IANA. Each such local
connection option MUST have a unique string name which MUST NOT start
with "x-" or "x+". The local connection option field name and
encoding name MUST be registered with IANA as well as a reference to
the document that describes the local connection option. The
document MUST have a stable URL and MUST be contained on a public web
server.
A contact name, e-mail and postal address for the local connection
option MUST be provided. The contact information SHALL be updated by
the defining organization as necessary.
Finally, prior to registering a LocalConnectionOption, the IANA MUST
have a designated expert [23] review the LocalConnectionOption. The
expert reviewer will send e-mail to the IANA on the overall review
determination.
Appendix D: Mode Interactions
An MGCP endpoint can establish one or more media streams. These
streams are either incoming (from a remote endpoint) or outgoing
(generated at the handset microphone). The "connection mode"
parameter establishes the direction and generation of these streams.
When there is only one connection to an endpoint, the mapping of
these streams is straightforward; the handset plays the incoming
stream over the handset speaker and generates the outgoing stream
from the handset microphone signal, depending on the mode parameter.
However, when several connections are established to an endpoint,
there can be many incoming and outgoing streams. Depending on the
connection mode used, these streams may interact differently with
each other and the streams going to/from the handset.
The table below describes how different connections SHALL be mixed
when one or more connections are concurrently "active". An active
connection is here defined as a connection that is in one of the
following modes:
* "send/receive"
* "send only"
* "receive only"
* "conference"
Connections in "network loopback", "network continuity test", or
"inactive" modes are not affected by connections in the "active"
modes. The Table uses the following conventions:
* Ai is the incoming media stream from Connection A
* Bi is the incoming media stream from Connection B
* Hi is the incoming media stream from the Handset Microphone
* Ao is the outgoing media stream to Connection A
* Bo is the outgoing media stream to Connection B
* Ho is the outgoing media stream to the Handset earpiece
* NA indicates no stream whatsoever (assuming there are no signals
applied on the connection)
"netw" in the following table indicates either "netwloop" or
"netwtest" mode.
-------------------------------------------------------------
| | Connection A Mode |
| |-----------------------------------------------------
| |sendonly|recvonly|sendrecv|confrnce|inactive| netw |
|-------|-----------------------------------------------------|
| |Send | Ao=Hi | Ao=NA | Ao=Hi | Ao=Hi | Ao=NA | Ao=Ai |
|C|only | Bo=Hi | Bo=Hi | Bo=Hi | Bo=Hi | Bo=Hi | Bo=Hi |
|o| | Ho=NA | Ho=Ai | Ho=Ai | Ho=Ai | Ho=NA | Ho=NA |
|n|-----------------------------------------------------------
|n|recv | |Ao=NA |Ao=Hi |Ao=Hi | Ao=NA | Ao=Ai |
|e|only | |Bo=NA |Bo=NA |Bo=NA | Bo=NA | Bo=NA |
|c| | |Ho=Ai+Bi|Ho=Ai+Bi|Ho=Ai+Bi| Ho=Bi | Ho=Bi |
|t|-----------------------------------------------------------|
|i|send | | |Ao=Hi |Ao=Hi | Ao=NA | Ao=Ai |
|o|recv | | |Bo=Hi |Bo=Hi | Bo=Hi | Bo=Hi |
|n| | | |Ho=Ai+Bi|Ho=Ai+Bi| Ho=Bi | Ho=Bi |
| |-----------------------------------------------------------|
|B|conf | | | |Ao=Hi+Bi| Ao=NA | Ao=Ai |
| |rnce | | | |Bo=Hi+Ai| Bo=Hi | Bo=Hi |
|M| | | | |Ho=Ai+Bi| Ho=Bi | Ho=Bi |
|o|-----------------------------------------------------------|
|d|Inac | | | | | Ao=NA | Ao=Ai |
|e|tive | | | | | Bo=NA | Bo=NA |
| | | | | | | Ho=NA | Ho=NA |
| |-----------------------------------------------------------|
| |netw | | | | | | Ao=Ai |
| | | | | | | | Bo=Bi |
| | | | | | | | Ho=NA |
-------------------------------------------------------------
If there are three or more "active" connections they will still
interact as defined in the table above with the outgoing media
streams mixed for each interaction (union of all streams). If
internal resources are used up and the streams cannot be mixed, the
gateway MUST return an error (error code 403 or 502, not enough
resources, are RECOMMENDED).
Appendix E: Endpoint Naming Conventions
The following sections provide some RECOMMENDED endpoint naming
conventions.
E.1 Analog Access Line Endpoints
The string "aaln", should be used as the first term in a local
endpoint name for analog access line endpoints. Terms following
"aaln" should follow the physical hierarchy of the gateway so that if
the gateway has a number of RJ11 ports, the local endpoint name could
look like the following:
aaln/#
where "#" is the number of the analog line (RJ11 port) on the
gateway.
On the other hand, the gateway may have a number of physical plug-in
units, each of which contain some number of RJ11 ports, in which
case, the local endpoint name might look like the following:
aaln/<unit #>/#
where <unit #> is the number of the plug in unit in the gateway and
"#" is the number of the analog line (RJ11 port) on that unit.
Leading zeroes MUST NOT be used in any of the numbers ("#") above.
E.2 Digital Trunks
The string "ds" should be used for the first term of digital
endpoints with a naming convention that follows the physical and
digital hierarchy such as:
ds/<unit-type1>-<unit #>/<unit-type2>-<unit #>/.../<channel #>
where: <unit-type> identifies the particular hierarchy level. Some
example values of <unit-type> are: "s", "su", "oc3", "ds3", "e3",
"ds2", "e2", "ds1", "e1" where "s" indicates a slot number and "su"
indicates a sub-unit within a slot. Leading zeroes MUST NOT be used
in any of the numbers ("#") above.
The <unit #> is a decimal number which is used to reference a
particular instance of a <unit-type> at that level of the hierarchy.
The number of levels and naming of those levels is based on the
physical hierarchy within the media gateway.
E.3 Virtual Endpoints
Another type of endpoint is one that is not associated with a
physical interface (such as an analog or digital endpoint). This
type of endpoint is called a virtual endpoint and is often used to
represent some DSP resources that gives the endpoint some capability.
Examples are announcement, IVR or conference bridge devices. These
devices may have multiple instances of DSP functions so that a
possible naming convention is:
<virtual-endpoint-type>/<endpoint-#>
where <virtual-endpoint-type> may be some string representing the
type of endpoint (such as "ann" for announcement server or "cnf" for
conference server) and <endpoint-#> would identify a particular
virtual endpoint within the device. Leading zeroes MUST NOT be used
in the number ("#") above. If the physical hierarchy of the server
includes plug-in DSP cards, another level of hierarchy in the local
endpoint name may be used to describe the plug in unit.
A virtual endpoint may be created as the result of using the "any of"
wildcard. Similarly, a virtual endpoint may cease to exist once the
last connection on the virtual endpoint is deleted. The definition
of the virtual endpoint MUST detail both of these aspects.
When a <virtual-endpoint-type> creates and deletes virtual endpoints
automatically, there will be cases where no virtual endpoints exist
at the time a RestartInProgress command is to be issued. In such
cases, the gateway SHOULD simply use the "all of" wildcard in lieu of
any specific <endpoint-#> as in, e.g.:
ann/*@mygateway.whatever.net
If the RestartInProgress command refers to all endpoints in the
gateway (virtual or not), the <virtual-endpoint-id> can be omitted as
in, e.g.:
*@mygateway.whatever.net
Commands received by the gateway will still have to refer to an
actual endpoint (possibly created by that command by use of the "any
of" wildcard) in order for the command to be processed though.
E.4 Media Gateway
MGCP only defines operation on endpoints in a media gateway. It may
be beneficial to define an endpoint that represents the gateway
itself as opposed to the endpoints managed by the gateway.
Implementations that wish to do so should use the local endpoint name
"mg" (for media gateway) as in:
mg@mygateway.whatever.net
Note that defining such an endpoint does not change any of the
protocol semantics, i.e., the "mg" endpoint and other endpoints
(e.g., digital trunks) in the gateway are still independent endpoints
and MUST be treated as such. For example, RestartInProgress commands
MUST still be issued for all endpoints in the gateway as usual.
E.5 Range Wildcards
As described in Section 2.1.2, the MGCP endpoint naming scheme
defines the "all of" and "any of" wildcards for the individual terms
in a local endpoint name. While the "all of" wildcard is very useful
for reducing the number of messages, it can by definition only be
used when we wish to refer to all instances of a given term in the
local endpoint name. Furthermore, in the case where a command is to
be sent by the gateway to the Call Agent, the "all of" wildcard can
only be used if all of the endpoints named by it have the same
"notified entity". Implementations that prefer a finer-grained
wildcarding scheme can use the range wildcarding scheme described
here.
A range wildcard is defined as follows:
RangeWildcard = "[" NumericalRange *( "," NumericalRange ) "]"
NumericalRange = 1*(DIGIT) [ "-" 1*(DIGIT) ]
Note that white space is not permitted. Also, since range wildcards
use the character "[" to indicate the start of a range, the "["
character MUST NOT be used in endpoint names that use range
wildcards. The length of a range wildcard SHOULD be bounded to a
reasonably small value, e.g., 128 characters.
Range wildcards can be used anywhere an "all of" wildcard can be
used. The semantics are identical for the endpoints named. However,
it MUST be noted, that use of the range wildcarding scheme requires
support on both the gateway and the Call Agent. Therefore, a gateway
MUST NOT assume that it's Call Agent supports range wildcarding and
vice versa. In practice, this typically means that both the gateway
and Call Agent will need to be provisioned consistently in order to
use range wildcards. Also, if a gateway or Call Agent using range
wildcards receives an error response that could indicate a possible
endpoint naming problem, they MUST be able to automatically revert to
not using range wildcards.
The following examples illustrates the use of range wildcards:
ds/ds1-1/[1-12]
ds/ds1-1/[1,3,20-24]
ds/ds1-[1-2]/*
ds/ds3-1/[1-96]
The following example illustrates how to use it in a command:
RSIP 1204 ds/ds3-1/[1-96]@tgw-18.whatever.net MGCP 1.0
RM: restart
RD: 0
Appendix F: Example Command Encodings
This appendix provides examples of commands and responses shown with
the actual encoding used. Examples are provided for each command.
All commentary shown in the commands and responses is optional.
F.1 NotificationRequest
The first example illustrates a NotificationRequest that will ring a
phone and look for an off-hook event:
RQNT 1201 aaln/1@rgw-2567.whatever.net MGCP 1.0
N: ca@ca1.whatever.net:5678
X: 0123456789AC
R: l/hd(N)
S: l/rg
The response indicates that the transaction was successful:
200 1201 OK
The second example illustrates a NotificationRequest that will look
for and accumulate an off-hook event, and then provide dial-tone and
accumulate digits according to the digit map provided. The "notified
entity" is set to "ca@ca1.whatever.net:5678", and since the
SignalRequests parameter is empty (it could have been omitted as
well), all currently active TO signals will be stopped. All events
in the quarantine buffer will be processed, and the list of events to
detect in the "notification" state will include fax tones in addition
to the "requested events" and persistent events:
RQNT 1202 aaln/1@rgw-2567.whatever.net MGCP 1.0
N: ca@ca1.whatever.net:5678
X: 0123456789AC
R: L/hd(A, E(S(L/dl),R(L/oc, L/hu, D/[0-9#*T](D))))
D: (0T|00T|#xxxxxxx|*xx|91xxxxxxxxxx|9011x.T)
S:
Q: process
T: G/ft
The response indicates that the transaction was successful:
200 1202 OK
F.2 Notify
The example below illustrates a Notify message that notifies an off-
hook event followed by a 12-digit number beginning with "91". A
transaction identifier correlating the Notify with the
NotificationRequest it results from is included. The command is sent
to the current "notified entity", which typically will be the actual
value supplied in the NotifiedEntity parameter, i.e.,
"ca@ca1.whatever.net:5678" - a failover situation could have changed
this:
NTFY 2002 aaln/1@rgw-2567.whatever.net MGCP 1.0
N: ca@ca1.whatever.net:5678
X: 0123456789AC
O: L/hd,D/9,D/1,D/2,D/0,D/1,D/8,D/2,D/9,D/4,D/2,D/6,D/6
The Notify response indicates that the transaction was successful:
200 2002 OK
F.3 CreateConnection
The first example illustrates a CreateConnection command to create a
connection on the endpoint specified. The connection will be part of
the specified CallId. The LocalConnectionOptions specify that G.711
mu-law will be the codec used and the packetization period will be 10
ms. The connection mode will be "receive only":
CRCX 1204 aaln/1@rgw-2567.whatever.net MGCP 1.0
C: A3C47F21456789F0
L: p:10, a:PCMU
M: recvonly
The response indicates that the transaction was successful, and a
connection identifier for the newly created connection is therefore
included. A session description for the new connection is included
as well - note that it is preceded by an empty line.
200 1204 OK
I: FDE234C8
v=0
o=- 25678 753849 IN IP4 128.96.41.1
s=-
c=IN IP4 128.96.41.1
t=0 0
m=audio 3456 RTP/AVP 0
The second example illustrates a CreateConnection command containing
a notification request and a RemoteConnectionDescriptor:
CRCX 1205 aaln/1@rgw-2569.whatever.net MGCP 1.0
C: A3C47F21456789F0
L: p:10, a:PCMU
M: sendrecv
X: 0123456789AD
R: L/hd
S: L/rg
v=0
o=- 25678 753849 IN IP4 128.96.41.1
s=-
c=IN IP4 128.96.41.1
t=0 0
m=audio 3456 RTP/AVP 0
The response indicates that the transaction failed, because the phone
was already off-hook. Consequently, neither a connection-id nor a
session description is returned:
401 1205 Phone off-hook
Our third example illustrates the use of the provisional response and
the three-way handshake. We create another connection and
acknowledge the previous response received by using the response
acknowledgement parameter:
CRCX 1206 aaln/1@rgw-2569.whatever.net MGCP 1.0
K: 1205
C: A3C47F21456789F0
L: p:10, a:PCMU
M: inactive
v=0
o=- 25678 753849 IN IP4 128.96.41.1
s=-
c=IN IP4 128.96.41.1
t=0 0
m=audio 3456 RTP/AVP 0
A provisional response is returned initially:
100 1206 Pending
I: DFE233D1
v=0
o=- 4723891 7428910 IN IP4 128.96.63.25
s=-
c=IN IP4 128.96.63.25
t=0 0
m=audio 3456 RTP/AVP 0
A little later, the final response is received:
200 1206 OK
K:
I: DFE233D1
v=0
o=- 4723891 7428910 IN IP4 128.96.63.25
s=-
c=IN IP4 128.96.63.25
t=0 0
m=audio 3456 RTP/AVP 0
The Call Agent acknowledges the final response as requested:
000 1206
and the transaction is complete.
F.4 ModifyConnection
The first example shows a ModifyConnection command that simply sets
the connection mode of a connection to "send/receive" - the "notified
entity" is set as well:
MDCX 1209 aaln/1@rgw-2567.whatever.net MGCP 1.0
C: A3C47F21456789F0
I: FDE234C8
N: ca@ca1.whatever.net
M: sendrecv
The response indicates that the transaction was successful:
200 1209 OK
In the second example, we pass a session description and include a
notification request with the ModifyConnection command. The endpoint
will start playing ring-back tones to the user:
MDCX 1210 aaln/1@rgw-2567.whatever.net MGCP 1.0
C: A3C47F21456789F0
I: FDE234C8
M: recvonly
X: 0123456789AE
R: L/hu
S: G/rt
v=0
o=- 4723891 7428910 IN IP4 128.96.63.25
s=-
c=IN IP4 128.96.63.25
t=0 0
m=audio 3456 RTP/AVP 0
The response indicates that the transaction was successful:
200 1206 OK
F.5 DeleteConnection (from the Call Agent)
In this example, the Call Agent simply instructs the gateway to
delete the connection "FDE234C8" on the endpoint specified:
DLCX 1210 aaln/1@rgw-2567.whatever.net MGCP 1.0
C: A3C47F21456789F0
I: FDE234C8
The response indicates success, and that the connection was deleted.
Connection parameters for the connection are therefore included as
well:
250 1210 OK
P: PS=1245, OS=62345, PR=780, OR=45123, PL=10, JI=27, LA=48
F.6 DeleteConnection (from the gateway)
In this example, the gateway sends a DeleteConnection command to the
Call Agent to instruct it that a connection on the specified endpoint
has been deleted. The ReasonCode specifies the reason for the
deletion, and Connection Parameters for the connection are provided
as well:
DLCX 1210 aaln/1@rgw-2567.whatever.net MGCP 1.0
C: A3C47F21456789F0
I: FDE234C8
E: 900 - Hardware error
P: PS=1245, OS=62345, PR=780, OR=45123, PL=10, JI=27, LA=48
The Call Agent sends a success response to the gateway:
200 1210 OK
F.7 DeleteConnection (multiple connections from the Call Agent)
In the first example, the Call Agent instructs the gateway to delete
all connections related to call "A3C47F21456789F0" on the specified
endpoint:
DLCX 1210 aaln/1@rgw-2567.whatever.net MGCP 1.0
C: A3C47F21456789F0
The response indicates success and that the connection(s) were
deleted:
250 1210 OK
In the second example, the Call Agent instructs the gateway to delete
all connections related to all of the endpoints specified:
DLCX 1210 aaln/*@rgw-2567.whatever.net MGCP 1.0
The response indicates success:
250 1210 OK
F.8 AuditEndpoint
In the first example, the Call Agent wants to learn what endpoints
are present on the gateway specified, hence the use of the "all of"
wild-card for the local portion of the endpoint-name:
AUEP 1200 *@rgw-2567.whatever.net MGCP 1.0
The gateway indicates success and includes a list of endpoint names:
200 1200 OK
Z: aaln/1@rgw-2567.whatever.net
Z: aaln/2@rgw-2567.whatever.net
In the second example, the capabilities of one of the endpoints is
requested:
AUEP 1201 aaln/1@rgw-2567.whatever.net MGCP 1.0
F: A
The response indicates success and the capabilities as well. Two
codecs are supported, however with different capabilities.
Consequently two separate capability sets are returned:
200 1201 OK
A: a:PCMU, p:10-100, e:on, s:off, v:L;S, m:sendonly;
recvonly;sendrecv;inactive;netwloop;netwtest
A: a:G729, p:30-90, e:on, s:on, v:L;S, m:sendonly;
recvonly;sendrecv;inactive;confrnce;netwloop
Note that the carriage return in the Capabilities lines are shown for
formatting reasons only - they are not permissible in a real
implementation.
In the third example, the Call Agent audits several types of
information for the endpoint:
AUEP 2002 aaln/1@rgw-2567.whatever.net MGCP 1.0
F: R,D,S,X,N,I,T,O,ES
The response indicates success:
200 2002 OK
R: L/hu,L/oc(N),D/[0-9](N)
D:
S: L/vmwi(+)
X: 0123456789B1
N: [128.96.41.12]
I: 32F345E2
T: G/ft
O: L/hd,D/9,D/1,D/2
ES: L/hd
The list of requested events contains three events. Where no package
name is specified, the default package is assumed. The same goes for
actions, so the default action - Notify - must therefore be assumed
for the "L/hu" event. The omission of a value for the "digit map"
means the endpoint currently does not have a digit map. There are
currently no active time-out signals, however the OO signal "vmwi" is
currently on and is consequently included - in this case it was
parameterized, however the parameter could have been excluded. The
current "notified entity" refers to an IP-address and only a single
connection exists for the endpoint. The current value of
DetectEvents is "G/ft", and the list of ObservedEvents contains the
four events specified. Finally, the event-states audited reveals
that the phone was off-hook at the time the transaction was
processed.
F.9 AuditConnection
The first example shows an AuditConnection command where we audit the
CallId, NotifiedEntity, LocalConnectionOptions, Connection Mode,
LocalConnectionDescriptor, and the Connection Parameters:
AUCX 2003 aaln/1@rgw-2567.whatever.net MGCP 1.0
I: 32F345E2
F: C,N,L,M,LC,P
The response indicates success and includes information for the
RequestedInfo:
200 2003 OK
C: A3C47F21456789F0
N: ca@ca1.whatever.net
L: p:10, a:PCMU
M: sendrecv
P: PS=395, OS=22850, PR=615, OR=30937, PL=7, JI=26, LA=47
v=0
o=- 4723891 7428910 IN IP4 128.96.63.25
s=-
c=IN IP4 128.96.63.25
t=0 0
m=audio 1296 RTP/AVP 0
In the second example, we request to audit RemoteConnectionDescriptor
and LocalConnectionDescriptor:
AUCX 1203 aaln/2@rgw-2567.whatever.net MGCP 1.0
I: FDE234C8
F: RC,LC
The response indicates success, and includes information for the
RequestedInfo. In this case, no RemoteConnectionDescriptor exists,
hence only the protocol version field is included for the
RemoteConnectionDescriptor:
200 1203 OK
v=0
o=- 4723891 7428910 IN IP4 128.96.63.25
s=-
c=IN IP4 128.96.63.25
t=0 0
m=audio 1296 RTP/AVP 0
v=0
F.10 RestartInProgress
The first example illustrates a RestartInProgress message sent by an
gateway to inform the Call Agent that the specified endpoint will be
taken out-of-service in 300 seconds:
RSIP 1200 aaln/1@rgw-2567.whatever.net MGCP 1.0
RM: graceful
RD: 300
The Call Agent's response indicates that the transaction was
successful:
200 1200 OK
In the second example, the RestartInProgress message sent by the
gateway informs the Call Agent, that all of the gateway's endpoints
are being placed in-service in 0 seconds, i.e., they are currently in
service. The restart delay could have been omitted as well:
RSIP 1204 *@rgw-2567.whatever.net MGCP 1.0
RM: restart
RD: 0
The Call Agent's response indicates success, and furthermore provides
the endpoints in question with a new "notified entity":
200 1204 OK
N: CA-1@whatever.net
Alternatively, the command could have failed with a new "notified
entity" as in:
521 1204 OK
N: CA-1@whatever.net
In that case, the command would then have to be retried in order to
satisfy the "restart procedure", this time going to Call Agent "CA-
1@whatever.net".
Appendix G: Example Call Flows
The message flow tables in this section use the following
abbreviations:
* rgw = Residential Gateway
* ca = Call Agent
* n+ = step 'n' is repeated one or more times
Note that any use of upper and lower case within the text of the
messages is to aid readability and is not in any way a requirement.
The only requirement involving case is to be case insensitive at all
times.
G.1 Restart
G.1.1 Residential Gateway Restart
The following table shows a message sequence that might occur when a
call agent (ca) is contacted by two independent residential gateways
(rgw1 and rgw2) which have restarted.
Table F.1: Residential Gateway Restart
---------------------------------------------------------------------
|step#| usr1 | rgw1 | ca | rgw2 | usr2 |
|=====|============|============|============|============|===========|
| 1 | | rsip -> | | | |
| | | | <- ack | | |
|-----|------------|------------|------------|------------|-----------|
| 2 | | | <- auep | | |
| | | ack -> | | | |
|-----|------------|------------|------------|------------|-----------|