MGCP ( Media Gateway Control Protocol )

• Model and Naming Conventions
  The MGCP assumes a connection model where the basic constructs are endpoints and connections. Connections are grouped in calls. One or more connections can belong to one call. Connections and calls are set up at the initiative of one or more Call Agents.



• Usage of SDP
  The Call Agent uses the MGCP to provide the endpoint with the description of connection parameters such as IP addresses, UDP port and RTP profiles. These descriptions will follow the conventions delineated in the Session Description Protocol which is now an IETF proposed standard.



• Commands:
  

  Code	Verb	Description
  AUCX	AuditConnection	The AuditEndPoint command can be used by the Call Agent to find out the status of a given endpoint.
  AUEP	AuditEndpoint	The AuditConnection command can be used by the Call Agent to retrieve the parameters attached to a connection.
  CRCX	CreateConnection	This command is used to create a connection between two endpoints.
  DLCX	DeleteConnection	This command is used to terminate a connection.
  EPCF	EndpointConfiguration	The EndpointConfiguration command can be used to specify the encoding of the signals that will be received by the endpoint.
  MDCX	ModifyConnection	This command is used to modify the characteristics of a gateway"s "view" of a connection.
  RQNT	NotificationRequest	The NotificationRequest command is used to request the gateway to send notifications upon the occurrence of specified events in an endpoint.
  NTFY	Notify	Notifications with the observed events are sent by the gateway via the Notify command when a triggering event occurs.
  RSIP	RestartInProgress	The RestartInProgress command is used by the gateway to signal that an endpoint, or a group of endpoints, is put in-service or out-of- service.

  
  
  
• Return Codes and Error Codes
  All MGCP commands are acknowledged. The acknowledgment carries a return code, which indicates the status of the command. The return code is an integer number, for which the following ranges of values have been defined:


• (0xx) Response acknowledgements:



Code	Description
0	The transaction is currently being executed. An actual completion message will follow on later.




• (1xx) Provisional response:



Code	Description
100	The transaction is currently being executed. An actual completion message will follow on later.
101	The transaction has been queued for execution. An actual completion message will follow later.




• (2xx) Successful completion:



Code	Description
200	The requested transaction was executed normally.
250	The connection was deleted.




• (4xx) Transient error:



Code	Description
400	The transaction could not be executed, due to a transient error.
401	The phone is already off hook.
402	The phone is already on hook.
403	The transaction could not be executed, because the endpoint does not have sufficient resources at this time.
404	Insufficient bandwidth at this time.
405	The transaction could not be executed, because the endpoint is "restarting".
406	Transaction time-out. The transaction did not complete in a reasonable period of time and has been aborted.
407	Transaction aborted. The transaction was aborted by some external action, e.g., a ModifyConnection command aborted by a DeleteConnection command.
409	The transaction could not be executed because of internal overload.
410	No endpoint available. A valid "any of" wildcard was used, however there was no endpoint available to satisfy the request.




• (5xx) Permanent error:



Code	Description
500	The transaction could not be executed, because the endpoint is unknown.
501	The transaction could not be executed, because the endpoint is not ready.
502	The transaction could not be executed, because the endpoint does not have sufficient resources.
503	"All of" wildcard too complicated.
504	Unknown or unsupported command.
505	Unsupported RemoteConnectionDescriptor. This SHOULD be used when one or more mandatory parameters or values in the RemoteConnectionDescriptor is not supported.
506	Unable to satisfy both LocalConnectionOptions and RemoteConnectionDescriptor. This SHOULD be used when the LocalConnectionOptions and RemoteConnectionDescriptor contain one or more mandatory parameters or values that conflict with each other and/or cannot be supported at the same time (except for codec negotiation failure, see error code 534).
507	Unsupported functionality. Some unspecified functionality required to carry out the command is not supported. Note that several other error codes have been defined for specific areas of unsupported functionality (e.g. 508, 511, etc.), and this error code SHOULD only be used if there is no other more specific error code for the unsupported functionality.
508	Unknown or unsupported quarantine handling.
509	Error in RemoteConnectionDescriptor. This SHOULD be used when there is a syntax or semantic error in the RemoteConnectionDescriptor.
510	The transaction could not be executed, because some unspecified protocol error was detected. Automatic recovery from such an error will be very difficult, and hence this code SHOULD only be used as a last resort.
511	The transaction could not be executed, because the command contained an unrecognized extension. This code SHOULD be used for unsupported critical parameter extensions ("X+").
512	The transaction could not be executed, because the gateway is not equipped to detect one of the requested events.
513	The transaction could not be executed, because the gateway is not equipped to generate one of the requested signals.
514	The transaction could not be executed, because the gateway cannot send the specified announcement.
515	The transaction refers to an incorrect connection-id (may have been already deleted).
516	The transaction refers to an unknown call-id.
517	Unsupported or invalid mode.
518	Unsupported or unknown package.
519	Endpoint does not have a digit map.
520	The transaction could not be executed, because the endpoint is "restarting".
521	Endpoint redirected to another Call Agent.
522	No such event or signal.
523	Unknown action or illegal combination of actions.
524	Internal inconsistency in LocalConnectionOptions.
525	Unknown extension in LocalConnectionOptions.
526	Insufficient bandwidth.
527	Missing RemoteConnectionDescriptor.
528	Incompatible protocol version.
529	Internal hardware failure.
530	CAS signaling protocol error.
531	Failure of a grouping of trunks (e.g. facility failure).
533	Response too large.
534	Codec negotiation failure.
535	Packetization period not supported.
536	Unknown or unsupported RestartMethod.
537	Unknown or unsupported digit map extension.
538	Event/signal parameter error (e.g., missing, erroneous, unsupported, unknown, etc.).
539	Invalid or unsupported command parameter. This code SHOULD only be used when the parameter is neither a package or vendor extension parameter.
540	Per endpoint connection limit exceeded.
541	Invalid or unsupported LocalConnectionOptions. This code SHOULD only be used when the LocalConnectionOptions is neither a package nor a vendor extension LocalConnectionOptions.




• (8xx) Package specific response codes:



Code	Description
800	Invalid NextEndpointName.
801	Invalid StartEndpointName.
802	Invalid or unsupported BulkRequestInfo Parameter.
803	Invalid or unsupported StateType.
804	Bulk Audit Type not supported.
805	Incorrectly specified endpoint range.
806	Requested StartEndpoint unknown or unavailable.




• Reason codes
  Reason codes are used by the gateway when deleting a connection to inform the Call Agent about the reason for deleting the connection. They may also be used in a RestartInProgress command to inform the Call Agent of the reason for the RestartInProgress.
  
  The reason code is an integer number, and the following values have been defined:



Code	Description
0	Endpoint state is nominal. (This code is used only in response to audit requests.).
900	Endpoint malfunctioning.
901	Endpoint taken out of service.
902	Loss of lower layer connectivity (e.g., downstream sync).
903	QoS resource reservation was lost.
904	Manual intervention.
905	Facility failure (e.g., DS-0 failure).

• Protocol Structure
  The MGCP is a text based protocol. The transactions are composed of a command and a mandatory response. There are eight types of commands:



MGC --> MG	CreateConnection: Creates a connection between two endpoints; uses SDP to define the receive capabilities of the paricipating endpoints.
MGC --> MG	ModifyConnection: Modifies the properties of a connection; has nearly the same parameters as the CreateConnection command.
MGC <--> MG	DeleteConnection: Terminates a connection and collects statistics on the execution of the connection.
MGC --> MG	NotificationRequest: Requests the media gateway to send notifications on the occurrence of specified events in an endpoint.
MGC <-- MG	Notify: Informs the media gateway controller when observed events occur.
MGC --> MG	AuditEndpoint: Determines the status of an endpoint.
MGC --> MG	AuditConnection: Retrieves the parameters related to a connection.
MGC <-- MG	RestartInProgress: Signals that an endpoint or group of endpoints is take in or out of service.




• 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 zero or more parameter lines, composed of a parameter name followed by a parameter value.

Unless otherwise noted or dictated by other referenced standards (e.g., SDP), each component in the command header is case insensitive. This goes for verbs as well as parameters and values, and hence all comparisons MUST treat upper and lower case as well as combinations of these as being equal.


• 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 a 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, and the transaction identifier. Response codes defined in packages (8xx) are followed by white space, a slash ("/") and the package name. All response codes may furthermore be followed by optional commentary preceded by a white space.



• Transmission over UDP
  MGCP messages are transmitted over UDP. Commands are sent to one of the IP addresses defined in the DNS for the specified endpoint. The responses are sent back to the source address (i.e., IP address and UDP port number) of the commands - the response may or may not arrive from the same address as the command was sent to.



• States, Failover and Race Conditions
  In order to implement proper call signaling, the Call Agent must keep track of the state of the endpoint, and the gateway must make sure that events are properly notified to the Call Agent. Special conditions exist when the gateway or the Call Agent are restarted: the gateway must be redirected to a new Call Agent during "failover" procedures, the Call Agent must take special action when the gateway is taken offline, or restarted.

Example 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

Example 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

Example 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.

Example 4: 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 codes 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.

■ Parent layer
■ Child layer

TCP/UDP

MGCP