RFC 3435
Media Gateway Control Protocol (MGCP) Version 1.0
6.8 LocalConnectionOptions
LocalConnectionOptions extensions SHALL include: * The name and encoding of the LocalConnectionOptions extension. * The possible values and encoding of those values that can be assigned to the LocalConnectionOptions extension. * A description of the operation of the LocalConnectionOptions extension. As part of this description the following MUST be specified: - The default value (if any) if the extension is omitted in a CreateConnection command. - The default value if omitted in a ModifyConnection command. This may be to simply retain the previous value (if any) or to apply the default value. If nothing is specified, the current value is retained if possible. - If Auditing of capabilities will result in the extension being returned, then a description to that effect as well as with what possible values and their encoding (note that the package itself will always be returned). If nothing is specified, the extension SHALL NOT be returned when auditing capabilities. Also note, that the extension MUST be included in the result for an AuditConnection command auditing the LocalConnectionOptions.6.9 Reason Codes
Extension reason codes SHALL include: * The number for the reason code. The number MUST be in the range 800 to 899. * A description of the extension reason code including the circumstances that leads to the generation of the reason code. Those circumstances SHOULD be limited to events caused by another extension defined in the package to ensure the recipient will be able to interpret the extension reason code correctly. Note that the extension reason code may have to be provided in the result for an AuditEndpoint command auditing the reason code.
6.10 RestartMethods
Extension Restart Methods SHALL include: * The name and encoding for the restart method. * A description of the restart method including the circumstances that leads to the generation of the restart method. Those circumstances SHOULD be limited to events caused by another extension defined in the package to ensure the recipient will be able to interpret the extension restart method correctly. * An indication of whether the RestartDelay parameter is to be used with the extension. If nothing is specified, it is assumed that it is not to be used. In that case, RestartDelay MUST be ignored if present. * If the restart method defines a service state, the description MUST explicitly state and describe this. In that case, the extension restart method can then be provided in the result for an AuditEndpoint command auditing the restart method.6.11 Return Codes
Extension Return Codes SHALL include: * The number for the extension return code. The number MUST be in the range 800 to 899. * A description of the extension return code including the circumstances that leads to the generation of the extension return code. Those circumstances SHOULD be limited to events caused by another extension defined in the package to ensure the recipient will be able to interpret the extension return code correctly.7. Versions and Compatibility
7.1 Changes from RFC 2705
RFC 2705 was issued in October 1999, as the last update of draft version 0.5. This updated document benefits from further implementation experience. The main changes from RFC 2705 are: * Contains several clarifications, editorial changes and resolution of known inconsistencies. * Firmed up specification language in accordance with RFC 2119 and added RFC 2119 conventions section.
* Clarified behavior of mixed wild-carding in endpoint names.
* Deleted naming requirement about having first term identify the
physical gateway when the gateway consists of multiple physical
gateways. Also added recommendations on wild-carding naming usage
from the right only, as well as mixed wildcard usage.
* Clarified that synonymous forms and values for endpoint names are
not freely interchangeable.
* Allowed IPv6 addresses in endpoint names.
* Clarified Digit Map matching rules.
* Added missing semantics for symbols used in digit maps.
* Added Timer T description in Digit Maps.
* Added recommendation to support digit map sizes of at least 2048
bytes per endpoint.
* Clarified use of wildcards in several commands.
* Event and Signal Parameters formally defined for events and
signals.
* Persistent events now allowed in base MGCP protocol.
* Added additional detail on connection wildcards.
* Clarified behavior of loopback, and continuity test connection
modes for mixing and multiple connections in those modes.
* Modified BearerInformation to be conditional optional in the
EndpointConfiguration command.
* Clarified "swap audio" action operation for one specific scenario
and noted that operation for other scenarios is undefined.
* Added recommendation that all implementations support PCMU encoding
for interoperability.
* Changed Bandwidth LocalConnectionOptions value from excluding to
including overhead from the IP layer and up for consistency with
SDP.
* Clarified that mode of second connection in a CreateConnection
command will be set to "send/receive".
* Type of service default changed to zero.
* Additional detail on echo cancellation, silence suppression, and
gain control. Also added recommendation for Call Agents not to
specify handling of echo cancellation and gain control.
* Added requirement for a connection to have a
RemoteConnectionDescriptor in order to use the "network loopback"
and "network continuity test" modes.
* Removed procedures and specification for NAS's (will be provided as
package instead).
* Removed procedures and specification for ATM (will be provided as
package instead).
* Added missing optional NotifiedEntity parameter to the
DeleteConnection (from the Call Agent) MGCI command.
* Added optional new MaxMGCPDatagram RequestedInfo code for
AuditEndpoint to enable auditing of maximum size of MGCP datagrams
supported.
* Added optional new PackageList RequestedInfo code for AuditEndpoint
to enable auditing of packages with a package version number.
PackageList parameter also allowed with return code 518
(unsupported package).
* Added missing attributes in Capabilities.
* Clarified that at the expiration of a non-zero restart delay, an
updated RestartInProgress should be sent. Also clarified that a
new NotifiedEntity can only be returned in response to a
RestartInProgress command.
* Added Response Acknowledgement response (return code 000) and
included in three-way handshake.
* ResponseAck parameter changed to be allowed in all commands.
* Added return codes 101, 405, 406, 407, 409, 410, 503, 504, 505,
506, 507, 508, 509, 533, 534, 535, 536, 537, 538, 539, 540, 541,
and defined return codes in range 800-899 to be package specific
return codes. Additional text provided for some return codes and
additional detail on how to handle unknown return codes added.
* Added reason code 903, 904, 905 and defined reason codes 800-899 to
be package specific reason codes.
* Added section clarifying codec negotiation procedure.
* Clarified that resource reservation parameters in a
ModifyConnection command defaults to the current value used.
* Clarified that connection mode is optional in ModifyConnection
commands.
* Corrected LocalConnectionDescriptor to be optional in response to
CreateConnection commands (in case of failure).
* Clarified that quoted-strings are UTF-8 encoded and
interchangeability of quoted strings and unquoted strings.
* Clarified that Transaction Identifiers are compared as numerical
values.
* Clarified bit-ordering for Type Of Service LocalConnectionOptions.
* Clarified the use of RequestIdentifier zero.
* Added example sections for commands, responses, and some call
flows.
* Corrected usage of and requirements for SDP to be strictly RFC 2327
compliant.
* Added requirement that all MGCP implementations must support MGCP
datagrams up to at least 4000 bytes. Also added new section on
Maximum Datagram Size, Fragmentation and reassembly.
* Generalized piggybacking retransmission scheme to only state
underlying requirements to be satisfied.
* Clarified the section on computing retransmission timers.
* Clarified operation of long-running transactions, including
provisional responses, retransmissions and failures.
* Enhanced description of provisional responses and interaction with
three-way handshake.
* Enhanced description of fail-over and the role of "notified
entity". An empty "notified entity" has been allowed, although
strongly discouraged.
* Clarified retransmission procedure and removed "wrong key"
considerations from it. Also fixed inconsistencies between Max1
and Max2 retransmission boundaries and the associated flow diagram.
* Updated domain name resolution for retransmission procedure to
incur less overhead when multiple endpoints are retransmitting.
* Removed requirement for in-order delivery of NotificationRequests
response and Notify commands. Notify commands are still delivered
in-order.
* Clarified that activating an embedded Notification Request does not
clear the list of ObservedEvents.
* Defined interactions between disconnected state and notification
state.
* Added section on transactional semantics.
* Defined gateway behavior when multiple interacting transactions are
received.
* Additional details provided on service states. Clarified
relationship between endpoint service states, restart methods, and
associated processing of commands.
* Clarified operation for transitioning from "restart procedure" to
"disconnected state".
* Allowed auditing commands and responses to bypass the "restart" and
"disconnected" procedures.
* Clarified operation of "disconnected procedure" and in particular
the operation of piggy-backed "disconnected" RestartInProgress
messages.
* Added option to aggregate "disconnected" RestartInProgress messages
under certain conditions to reduce message volume.
* Defined additional behavior for endpoints wishing to send commands
while in the "disconnected" state.
* Added new section on Load Control in General which includes two new
error codes (101 and 409) to handle overload.
* Deleted the "Proposed MoveConnection command".
* Removed packages from protocol specification (will be provided in
separate documents instead).
* Package concept formally extended to be primary extension mechanism
now allowing extensions for the following to be defined in packages
as well:
- BearerInformation
- LocalConnectionOptions
- ExtensionParameters
- Connection Modes
- Actions
- Digit Map Letters
- Connection Parameters
- Restart Methods
- Reason Codes
- Return Codes
* Requirements and suggested format for package definitions added.
* Defined "operation complete" and "operation failure" events to be
automatically present in packages with Time-Out signals.
* Deleted list of differences that were prior to RFC 2705.
* Added Base Package to deal with quarantine buffer overflow,
ObservedEvents overflow, embedded NotificationRequest failure, and
to enable events to be requested persistently. A new "Message"
command is included as well.
* IANA registration procedures for packages and other extensions
added.
* Updated grammar to fix known errors and support new extensions in a
backwards compatible manner. Added new (optional) PackageList and
MaxMGCPDatagram for auditing. Changed explicit white space rules
in some productions to make grammar more consistent.
* Connection Mode interaction table added.
* Added additional detail on virtual endpoint naming conventions.
Also added suggested gateway endpoint convention and a "Range
Wildcard" option to the Endpoint Naming Conventions.
8. Security Considerations
Security issues are discussed in section 5.
9. Acknowledgements
Special thanks are due to the authors of the original MGCP 1.0
specification: Mauricio Arango, Andrew Dugan, Isaac Elliott,
Christian Huitema, and Scott Picket.
We also want to thank the many reviewers who provided advice on the
design of SGCP and then MGCP, notably Sankar Ardhanari, Francois
Berard, David Auerbach, Bob Biskner, David Bukovinsky, Charles Eckel,
Mario Edini, Ed Guy, Barry Hoffner, Jerry Kamitses, Oren Kudevitzki,
Rajesh Kumar, Troy Morley, Dave Oran, Jeff Orwick, John Pickens, Lou
Rubin, Chip Sharp, Paul Sijben, Kurt Steinbrenner, Joe Stone, and
Stuart Wray.
The version 0.1 of MGCP was heavily inspired by the "Internet
Protocol Device Control" (IPDC) designed by the Technical Advisory
Committee set up by Level 3 Communications. Whole sets of text were
retrieved from the IP Connection Control protocol, IP Media Control
protocol, and IP Device Management. The authors wish to acknowledge
the contribution to these protocols made by Ilya Akramovich, Bob
Bell, Dan Brendes, Peter Chung, John Clark, Russ Dehlinger, Andrew
Dugan, Isaac Elliott, Cary FitzGerald, Jan Gronski, Tom Hess, Geoff
Jordan, Tony Lam, Shawn Lewis, Dave Mazik, Alan Mikhak, Pete
O'Connell, Scott Pickett, Shyamal Prasad, Eric Presworsky, Paul
Richards, Dale Skran, Louise Spergel, David Sprague, Raj Srinivasan,
Tom Taylor and Michael Thomas.
10. References
[1] Bradner, S., "The Internet Standards Process -- Revision 3", BCP
9, RFC 2026, October 1996.
[2] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[3] Schulzrinne, H., Casner, S., Frederick, R. and V. Jacobson,
"RTP: A Transport Protocol for Real-Time Applications", RFC
1889, January 1996.
[4] Schulzrinne, H., "RTP Profile for Audio and Video Conferences with Minimal Control", RFC 1890, January 1996. [5] Handley, M. and V. Jacobson, "SDP: Session Description Protocol", RFC 2327, April 1998. [6] Handley, M., Perkins, C. and E. Whelan, "Session Announcement Protocol", RFC 2974, October 2000. [7] Rosenberg, J., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., Schulzrinne, H. and E. Schooler, "Session Initiation Protocol (SIP)", RFC 3261, June 2002. [8] Schulzrinne, H., Rao, A. and R. Lanphier, "Real Time Streaming Protocol (RTSP)", RFC 2326, April 1998. [9] ITU-T, Recommendation Q.761, "FUNCTIONAL DESCRIPTION OF THE ISDN USER PART OF SIGNALING SYSTEM No. 7", (Malaga-Torremolinos, 1984; modified at Helsinki, 1993). [10] ITU-T, Recommendation Q.762, "GENERAL FUNCTION OF MESSAGES AND SIGNALS OF THE ISDN USER PART OF SIGNALING SYSTEM No. 7", (MalagaTorremolinos, 1984; modified at Helsinki, 1993). [11] ITU-T, Recommendation H.323 (02/98), "PACKET-BASED MULTIMEDIA COMMUNICATIONS SYSTEMS". [12] ITU-T, Recommendation H.225, "Call Signaling Protocols and Media Stream Packetization for Packet Based Multimedia Communications Systems". [13] ITU-T, Recommendation H.245 (02/98), "CONTROL PROTOCOL FOR MULTIMEDIA COMMUNICATION". [14] Kent, S. and R. Atkinson, "Security Architecture for the Internet Protocol", RFC 2401, November 1998. [15] Kent, S. and R. Atkinson, "IP Authentication Header", RFC 2402, November 1998. [16] Kent, S. and R. Atkinson, "IP Encapsulating Security Payload (ESP)", RFC 2406, November 1998. [17] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [18] Stevens, W. Richard, "TCP/IP Illustrated, Volume 1, The Protocols", Addison-Wesley, 1994.
[19] Allman, M., Paxson, V. "On Estimating End-to-End Network Path Properties", Proc. SIGCOMM'99, 1999. [20] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 2279, January 1998. [21] Braden, R., "Requirements for Internet Hosts -- Communication Layers", STD 3, RFC 1122, October 1989. [22] Bellcore, "LSSGR: Switching System Generic Requirements for Call Control Using the Integrated Services Digital Network User Part (ISDNUP)", GR-317-CORE, Issue 2, December 1997. [23] Narten, T., and Alvestrand H., "Guidelines for Writing an IANA Considerations Section in RFCs", RFC 2434, October 1998.
Appendix A: Formal Syntax Description of the Protocol
In this section, we provide a formal description of the protocol syntax, following the "Augmented BNF for Syntax Specifications" defined in RFC 2234. The syntax makes use of the core rules defined in RFC 2234, Section 6.1, which are not included here. Furthermore, the syntax follows the case-sensitivity rules of RFC 2234, i.e., MGCP is case-insensitive (but SDP is not). It should be noted, that ABNF does not provide for implicit specification of linear white space and MGCP messages MUST thus follow the explicit linear white space rules provided in the grammar below. However, in line with general robustness principles, implementers are strongly encouraged to tolerate additional linear white space in messages received. 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 = ALPHA 3(ALPHA / DIGIT) ; experimental starts with X transaction-id = 1*9(DIGIT) endpointName = LocalEndpointName "@" DomainName LocalEndpointName = LocalNamePart 0*("/" LocalNamePart) LocalNamePart = AnyName / AllName / NameString AnyName = "$" AllName = "*" NameString = 1*(range-of-allowed-characters) ; VCHAR except "$", "*", "/", "@" range-of-allowed-characters = %x21-23 / %x25-29 / %x2B-2E / %x30-3F / %x41-7E DomainName = 1*255(ALPHA / DIGIT / "." / "-") ; as defined / "#" number ; in RFC 821 / "[" IPv4address / IPv6address "]" ; see RFC 2373 ; Rewritten to ABNF from RFC 821 number = 1*DIGIT ;From RFC 2373 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 (RFC 2327) ;NOTE: encryption key may contain an algorithm as specified in RFC 1890 encryptiondata = ( "clear" ":" encryptionKey ) / ( "base64" ":" encodedEncryptionKey ) / ( "uri" ":" URItoObtainKey ) / ( "prompt" ) ; defined in SDP, not usable in MGCP! encryptionKey = 1*(SuitableLCOCharacter) / quotedString ; See RFC 2045 encodedEncryptionKey = 1*(ALPHA / DIGIT / "+" / "/" / "=") URItoObtainKey = 1*(SuitableLCOCharacter) / quotedString typeOfNetwork = "IN" / "ATM" / "LOCAL" / OtherTypeOfNetwork ; Registered with IANA - see RFC 2327 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 RFC 2327 for proper SDP grammar instead.
SDPinformation = SDPLine CRLF *(SDPLine CRLF) ; see RFC 2327
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).
(next page on part 8)
