An estimate of the network latency, expressed in milliseconds. This
is the average value of the difference between the NTP timestamp
indicated by the senders of the RTCP messages and the NTP timestamp
of the receivers, measured when this messages are received. The
average is obtained by summing all the estimates, then dividing by
the number of RTCP messages that have been received. This parameter
is omitted if the connection was set in "data" mode.
When the gateway's clock is not synchronized by NTP, the latency
value can be computed as one half of the round trip delay, as
measured through RTCP.
When the gateway cannot compute the one way delay or the round trip
delay, the parameter conveys a null value.
For a detailed definition of these variables, refer to RFC1889.
When the connection was set up over an ATM network, the meaning of
these parameters may change:
Number of packets sent: The total number of ATM cells transmitted
since starting transmission on this connection.
Number of octets sent:
The total number of payload octets transmitted in ATM cells.
Number of packets received:
The total number of ATM cells received since starting reception on
this connection.
Number of octets received:
The total number of payload octets received in ATM cells.
Number of packets lost:
Should be determined as the number of cell losts, or set to zero
if the adaptation layer does not enable the gateway to assess
losses.
Interarrival jitter:
Should be understood as the interarrival jitter between ATM cells.
Average transmission delay:
The gateway may not be able to assess this parameter over an ATM
network. It could simply report a null value.
When the connection was set up over an LOCAL interconnect, the
meaning of these parameters is defined as follows:
Number of packets sent:
Not significant.
Number of octets sent:
The total number of payload octets transmitted over the local
connection.
Number of packets received:
Not significant.
Number of octets received:
The total number of payload octets received over the connection.
Number of packets lost:
Not significant. A value of zero is assumed.
Interarrival jitter:
Not significant. A value of zero is assumed.
Average transmission delay:
Not significant. A value of zero is assumed.
The standard set of connection parameters can be extended by the
creation of extension parameters.
The command may optionally contain an encapsulated Notification
Request command, in which case a RequestIdentifier parameter will be
present, as well as, optionnally, the RequestedEvents DigitMap,
SignalRequests, QuarantineHandling and DetectEvents parameters. The
encapsulated NotificationRequest is executed simultaneously with the
deletion of the connection. For example, when a user hang-up is
notified, the gateway should be instructed to delete the connection
and to start looking for an off hook event.
This can be accomplished in a single DeleteConnection command, by
also transmitting the RequestedEvent parameters, for the off hook
event, and an empty SignalRequest parameter.
When these parameters are present, the DeleteConnection and the
NotificationRequests should be synchronized, which means that both
should be accepted, or both refused.
The command may carry an encapsulated EndpointConfiguration command,
that will apply to the same endpoint. When this command is present,
the parameters of the EndpointConfiguration command are inserted
after the normal parameters of the DeleteConnection with the
exception of the EndpointId, which is not replicated. The
EndpointConfiguration command may be encapsulated together with an
encapsulated NotificationRequest command.
The encapsulated EndpointConfiguration command shares the fate of the
DeleteConnection command. If the DeleteConnection is rejected, the
EndpointConfiguration is not executed.
ReturnCode is a parameter returned by the gateway. It indicates the
outcome of the command and consists of an integer number optionally
followed by commentary.
2.3.6. DeleteConnection (from the VoIP gateway)
In some circumstances, a gateway may have to clear a connection, for
example because it has lost the resource associated with the
connection, or because it has detected that the endpoint no longer is
capable or willing to send or receive voice. The gateway terminates
the connection by using a variant of the DeleteConnection command:
ReturnCode,
<-- DeleteConnection( CallId,
EndpointId,
ConnectionId,
Reason-code,
Connection-parameters)
In addition to the call, endpoint and connection identifiers, the
gateway will also send the call's parameters that would have been
returned to the Call Agent in response to a DeleteConnection command.
The reason code indicates the cause of the disconnection.
ReturnCode is a parameter returned by the call agent. It indicates
the outcome of the command and consists of an integer number
optionally followed by commentary.
2.3.7. DeleteConnection (multiple connections, from the Call Agent)
A variation of the DeleteConnection function can be used by the Call
Agent to delete multiple connections at the same time. The command
can be used to delete all connections that relate to a Call for an
endpoint:
ReturnCode,
<-- DeleteConnection( CallId,
EndpointId)
It can also be used to delete all connections that terminate in a
given endpoint:
ReturnCode,
<-- DeleteConnection( EndpointId)
Finally, Call Agents can take advantage of the hierarchical naming
structure of endoints to delete all the connections that belong to a
group of endpoints. In this case, the "local name" component of the
EndpointID will be specified using the "all value" wildcarding
convention. The "any value" convention shall not be used. For
example, if endpoints names are structured as the combination of a
physical interface name and a circuit number, as in "X35V3+A4/13",
the Call Agent may replace the circuit number by a wild card
character "*", as in "X35V3+A4/*". This "wildcard" command instructs
the gateway to delete all the connections that where attached to
circuits connected to the physical interface "X35V3+A4".
After the connections have been deleted, the endpoint should be
placed in inactive mode. Any loopback that has been requested for the
connections should be cancelled.
This command does not return any individual statistics or call
parameters.
ReturnCode is a parameter returned by the gateway. It indicates the
outcome of the command and consists of an integer number optionally
followed by commentary.
2.3.8. Audit Endpoint
The AuditEndPoint command can be used by the Call Agent to find out
the status of a given endpoint.
ReturnCode,
EndPointIdList|{
[RequestedEvents,]
[DigitMap,]
[SignalRequests,]
[RequestIdentifier,]
[NotifiedEntity,]
[ConnectionIdentifiers,]
[DetectEvents,]
[ObservedEvents,]
[EventStates,]
[BearerInformation,]
[RestartReason,]
[RestartDelay,]
[ReasonCode,]
[Capabilities]}
<--- AuditEndPoint(EndpointId,
[RequestedInfo])
The EndpointId identifies the endpoint that is being audited. The
"all of" wildcard convention can be used to start auditing of a group
of endpoints. If this convention is used, the gateway should return
the list of endpoint identifiers that match the wildcard in the
EndPointIdList parameter. It shall not return any parameter specific
to one of these endpoints.
When a non-wildcard EndpointId is specified, the (possibly empty)
RequestedInfo parameter describes the information that is requested
for the EndpointId specified. The following endpoint info can be
audited with this command:
RequestedEvents, DigitMap, SignalRequests, RequestIdentifier,
NotifiedEntity, ConnectionIdentifiers, DetectEvents, ObservedEvents,
EventStates, RestartReason, RestartDelay, ReasonCode, and
Capabilities.
The response will in turn include information about each of the items
for which auditing info was requested:
* RequestedEvents: The current value of RequestedEvents the endpoint
is using including the action associated with each event.
Persistent events are included in the list.
* DigitMap: the digit map the endpoint is currently using.
* SignalRequests: A list of the; Time-Out signals that are currently
active, On/Off signals that are currently "on" for the endpoint
(with or without parameter), and any pending Brief signals. Time-
Out signals that have timed-out, and currently playing Brief
signals are not included.
* RequestIdentifier, the RequestIdentifier for the last Notification
Request received by this endpoint (includes NotificationRequest
encapsulated in Connection handling primitives). If no
notification request has been received, the value zero will be
returned.
* QuarantineHandling, the QuarantineHandling for the last
NotificationRequest received by this endpoint.
* DetectEvents, the list of events that are currently detected in
quarantine mode.
* NotifiedEntity, the current notified entity for the endpoint.
* ConnectionIdentifiers, the list of ConnectionIdentifiers for all
connections that currently exist for the specified endpoint.
* ObservedEvents: the current list of observed events for the
endpoint.
* EventStates: For events that have auditable states associated with
them, the event corresponding to the state the endpoint is in,
e.g., off-hook if the endpoint is off-hook. The definition of the
individual events will state if the event in question has an
auditable state associated with it.
* BearerInformation: the value of the last received
BearerInformation parameter for this endpoint.
* RestartReason: the value of the restart reason parameter in the
last RestartInProgress command issued by the endpoint, "restart"
indicating a fully functional endpoint.
* RestartDelay: the value of the restart delay parameter if a
RestartInProgress command was issued by the endpoint at the time
of the response, or zero if the command would not include this
parameter.
* ReasonCode:the value of the Reason-Code parameter in the last
RestartInProgress or DeleteConnection command issued by the
gateway for the endpoint, or the special value 000 if the
endpoint's state is nominal.
* The capabilities for the endpoint similar to the
LocalConnectionOptions parameter and including event packages and
connection modes. If there is a need to specify that some
parameters, such as e.g., silence suppression, are only compatible
with some
* codecs, then the gateway will return several capability sets:
Compression Algorithm: a list of supported codecs. The rest of
the parameters will apply to all codecs specified in this list.
Packetization Period: A single value or a range may be
specified.
Bandwidth: A single value or a range corresponding to the range
for packetization periods may be specified (assuming no silence
suppression).
Echo Cancellation: Whether echo cancellation is supported or
not.
Silence Suppression: Whether silence suppression is supported
or not.
Type of Service: Whether type of service is supported or not.
Event Packages: A list of event packages supported. The first
event package in the list will be the default package.
Modes: A list of supported connection modes.
The Call Agent may then decide to use the AuditConnection command to
obtain further information about the connections.
If no info was requested and the EndpointId refers to a valid
endpoint, the gateway simply returns a positive acknowledgement.
If no NotifiedEntity has been specified in the last
NotificationRequest, the notified entity defaults to the source
address of the last NotificationRequest command received for this
connection.
ReturnCode is a parameter returned by the gateway. It indicates the
outcome of the command and consists of an integer number optionally
followed by commentary.
2.3.9. Audit Connection
The AuditConnection command can be used by the Call Agent to retrieve
the parameters attached to a connection:
ReturnCode,
[CallId,]
[NotifiedEntity,]
[LocalConnectionOptions,]
[Mode,]
[RemoteConnectionDescriptor,]
[LocalConnectionDescriptor,]
[ConnectionParameters]
<--- AuditConnection(EndpointId,
ConnectionId,
RequestedInfo)
The EndpointId parameter specifies the endpoint that handles the
connection. The wildcard conventions shall not be used.
The ConnectionId parameter is the identifier of the audited
connection, within the context of the specified endpoint.
The (possibly empty) RequestedInfo describes the information that is
requested for the ConnectionId within the EndpointId specified. The
following connection info can be audited with this command:
CallId, NotifiedEntity, LocalConnectionOptions, Mode,
RemoteConnectionDescriptor, LocalConnectionDescriptor,
ConnectionParameters
The AuditConnectionResponse will in turn include information about
each of the items auditing info was requested for:
* CallId, the CallId for the call the connection belongs to.
* NotifiedEntity, the current notified entity for the Connection.
* LocalConnectionOptions, the LocalConnectionOptions that was
supplied for the connection.
* Mode, the current mode of the connection.
* RemoteConnectionDescriptor, the RemoteConnectionDescriptor that
was supplied to the gateway for the connection.
* LocalConnectionDescriptor, the LocalConnectionDescriptor the gate-
way supplied for the connection.
* ConnectionParameters, the current value of the connection
parameters for the connection.
If no info was requested and the EndpointId is valid, the gateway
simply checks that the connection exists, and if so returns a
positive acknowledgement.
If no NotifiedEntity has been specified for the connection, the
notified entity defaults to the source address of the last connection
handling command received for this connection.
ReturnCode is a parameter returned by the gateway. It indicates the
outcome of the command and consists of an integer number optionally
followed by commentary.
2.3.10. Restart in progress
The RestartInProgress command is used by the gateway to signal that
An endpoint, or a group of endpoint, is taken in or out of service.
ReturnCode,
[NotifiedEntity]
<------- RestartInProgress ( EndPointId,
RestartMethod,
[RestartDelay,]
[Reason-code])
The EndPointId identifies the endpoint that are taken in or out of
service. The "all of" wildcard convention may be used to apply the
command to a group of endpoint, such as for example all endpoints
that are attached to a specified interface, or even all endpoints
that are attached to a given gateway. The "any of" wildcard
convention shall not be used.
The RestartMethod parameter specified the type of restart. Three
values have been defined:
* A "graceful" restart method indicates that the specified endpoints
will Be taken out of service after the specified delay. The
established connections are not yet affected, but the Call Agent
should refrain to establish new connections, and should try to
gracefully tear down the existing connections.
* A "forced" restart method indicates that the specified endpoints
are taken abruptely out of service. The established connections,
if any, are lost.
* A "restart" method indicates that service will be restored on the
endpoints after the specified "restart delay." There are no
connections that are currently established on the endpoints.
* A "disconnected" method indicates that the endpoint has become
disconnected and is now trying to establish connectivity. The
"restart delay" specifies the number of seconds the endpoint has
been disconnected. Established connections are not affected.
* A "cancel-graceful" method indicates that a gateway is canceling a
previously issued "graceful" restart command.
The optional "restart delay" parameter is expressed as a number of
seconds. If the number is absent, the delay value should be
considered null. In the case of the "graceful" method, a null delay
indicates that the call agent should simply wait for the natural
termination of the existing connections, without establishing new
connections. The restart delay is always considered null in the case
of the "forced" method.
A restart delay of null for the "restart" method indicates that
service has already been restored. This typically will occur after
gateway startup/reboot.
The optional reason code parameter the cause of the restart.
Gateways SHOULD send a "graceful" or "forced" RestartInProgress
message as a courtesy to the Call Agent when they are taken out of
service, e.g., by being shutdown, or taken out of service by a
network management system, although the Call Agent cannot rely on
always receiving such messages. Gateways MUST send a "restart"
RestartInProgress message with a null delay to their Call Agent when
they are back in service according to the restart procedure specified
in Section 4.3.4 - Call Agents can rely on receiving this message.
Also, gateways MUST send a "disconnected" RestartInProgress message
to their current "notified entity" according to the "disconnected"
procedure specified in Section 4.3.5. The "restart delay" parameter
MUST NOT be used with the "forced" restart method.
The RestartInProgress message will be sent to the current notified
entity for the EndpointId in question. It is expected that a default
Call Agent, i.e., notified entity, has been provisioned for each
endpoint so, after a reboot, the default Call Agent will be the
notified entity for each endpoint. Gateways should take full
advantage of wild- carding to minimize the number of
RestartInProgress messages generated when multiple endpoints in a
gateway restart and the endpoints are managed by the same Call Agent.
ReturnCode is a parameter returned by the gateway. It indicates the
outcome of the command and consists of an integer number optionally
followed by commentary.
A NotifiedEntity may additionally be returned with the response from
the Call Agent:
* If the response indicated success (return code 200 - transaction
executed), the restart procedure has completed, and the
NotifiedEntity returned is the new "notified entity" for the
endpoint(s).
* If the response from the Call Agent indicated an error, the
restart procedure is not yet complete, and must therefore be
initiated again. If a NotifiedEntity parameter was returned, it
then specifies the new "notified entity" for the endpoint(s),
which must consequently be used when retrying the restart
procedure.
2.4. 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 four ranges of values have been
defined:
* values between 100 and 199 indicate a provisional response,
* values between 200 and 299 indicate a successful completion,
* values between 400 and 499 indicate a transient error,
* values between 500 and 599 indicate a permanent error.
The values that have been already defined are listed in the following
list:
100 The transaction is currently being executed. An actual
completion message will follow on later.
200 The requested transaction was executed normally.
250 The connection was deleted.
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
500 The transaction could not be executed, because the endpoint is
unknown.
01 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
510 The transaction could not be executed, because a protocol error
was detected.
11 The transaction could not be executed, because the command
contained an unrecognized extension.
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).
2.5. 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
gateway of the Restart's reason. The reason code is an integer
number, and the following values have been defined:
000 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)
3. Media Gateway Control Protocol
The MGCP implements the media gateway control interface as a set of
transactions. The transactions are composed of a command and a
mandatory response. There are eight types of command:
* CreateConnection
* ModifyConnection
* DeleteConnection
* NotificationRequest
* Notify
* AuditEndpoint
* AuditConnection
* RestartInProgress
The first four commands are sent by the Call Agent to a gateway. The
Notify command is sent by the gateway to the Call Agent. The gateway
may also send a DeleteConnection as defined in 2.3.6. The Call Agent
may send either of the Audit commands to the gateway. The Gateway
may send a RestartInProgress command to the Call Agent.
3.1. General description
All commands are composed of a Command header, optionally followed by
a session description.
All responses are composed of a Response header, optionally followed
by a session description.
Headers and session descriptions are encoded as a set of text lines,
separated by a carriage return and line feed character (or,
optionnally, a single line-feed character). The headers are separated
from the session description by an empty line.
MGCP uses a transaction identifier to correlate commands and
responses. The transaction identifier is encoded as a component of
the command header and repeated as a component of the response header
(see section 3.2.1, 3.2.1.2 and 3.3).
3.2. Command Header
The command header is composed of:
* A command line, identifying the requested action or verb, the
transaction identifier, the endpoint towards which the action is
requested, and the MGCP protocol version,
* A set of parameter lines, composed of a parameter name followed by
a parameter value.
Unless otherwise noted or dictated by other referenced standards,
each component in the command header is case insensitive. This goes
for verbs as well as parameters and values, and all comparisons MUST
treat upper and lower case as well as combinations of these as being
equal.
3.2.1. Command line
The command line is composed of:
* The name of the requested verb,
* The identification of the transaction,
* The name of the endpoint that should execute the command (in
notifications or restarts, the name of the endpoint that is
issuing the command),
* The protocol version.
These four items are encoded as strings of printable ASCII
characters, separated by white spaces, i.e. the ASCII space (0x20) or
tabulation (0x09) characters. It is recommended to use exactly one
ASCII space separator.
3.2.1.1. Coding of the requested verb
The verbs that can be requested are encoded as four letter upper or
lower case ASCII codes (comparisons should be case insensitive) as
defined in the following table:
______________________________
| Verb | Code|
|______________________|______|
| EndpointConfiguration| EPCF|
| CreateConnection | CRCX|
| ModifyConnection | MDCX|
| DeleteConnection | DLCX|
| NotificationRequest | RQNT|
| Notify | NTFY|
| AuditEndpoint | AUEP|
| AuditConnection | AUCX|
| RestartInProgress | RSIP|
|______________________|______|
The transaction identifier is encoded as a string of up to 9 decimal
digits. In the command lines, it immediately follows the coding of
the verb.
New verbs may be defined in further versions of the protocol. It may
be necessary, for experimentation purposes, to use new verbs before
they are sanctioned in a published version of this protocol.
Experimental verbs should be identified by a four letter code
starting with the letter X, such as for example XPER.
3.2.1.2. Transaction Identifiers
MGCP uses a transaction identifier to correlate commands and
responses. A gateway supports two separate transaction identifier
name spaces:
a transaction identifier name space for sending transactions, and
a transaction identifier name space for receiving transactions.
At a minimum, transaction identifiers for commands sent to a given
gateway MUST be unique for the maximum lifetime of the transactions
within the collection of Call Agents that control that gateway. Thus,
regardless of the sending Call Agent, gateways can always detect
duplicate transactions by simply examining the transaction
identifier. The coordination of these transaction identifiers between
Call Agents is outside the scope of this specification though.
Transaction identifiers for all commands sent from a given gateway
MUST be unique for the maximum lifetime of the transactions
regardless of which Call Agent the command is sent to. Thus, a Call
Agent can always detect a duplicate transaction from a gateway by the
combination of the domain-name of the endpoint and the transaction
identifier.
The transaction identifier is encoded as a string of up to nine
decimal digits. In the command lines, it immediately follows the
coding of the verb.
Transaction identifiers have values between 1 and 999999999. An MGCP
entity MUST NOT reuse a transaction identifier more quickly than
three minutes after completion of the previous command in which the
identifier was used.
3.2.1.3. Coding of the endpoint identifiers and entity names
The endpoint identifiers and entity names are encoded as case
insensitive e-mail addresses, as defined in RFC821. In these
addresses, the domain name identifies the system where the endpoint
is attached, while the left side identifies a specific endpoint on
that system.
Examples of such addresses can be:
______________________________________________________________________
| hrd4/56@gw23.example.net | Circuit number 56 in |
| | interface "hrd4" of the Gateway 23 |
| | of the "Example" network |
| Call-agent@ca.example.net | Call Agent for the |
| | "example" network |
| Busy-signal@ann12.example.net| The "busy signal" virtual |
| | endpoint in the announcement |
| | server number 12. |
|______________________________|______________________________________|
The name of notified entities is expressed with the same syntax, with
the possible addition of a port number as in:
Call-agent@ca.example.net:5234
In case the port number is omitted, the default MGCP port (2427) will
be used.
3.2.1.4. Coding of the protocol version
The protocol version is coded as the key word MGCP followed by a
white space and the version number, and optionally followed by a
profile name.. The version number is composed of a major version,
coded by a decimal number, a dot, and a minor version number, coded
as a decimal number. The version described in this document is
version 1.0.
The profile name, if present, is represented by a white-space
separated strings of visible (printable) characters extending to the
end of the line. Profile names may be defined for user communities
who want to apply restrictions or other profiling to MGCP.
In the initial messages, the version will be coded as:
MGCP 1.0
3.2.2. Parameter lines
Parameter lines are composed of a parameter name, which in most cases
is composed of a single upper case character, followed by a colon, a
white space and the parameter value. The parameter that can be
present in commands are defined in the following table:
_______________________________________________________________________
|Parameter name | Code| Parameter value |
|______________________|______|_______________________________________|
|ResponseAck | K | see description |
|BearerInformation | B | see description |
|CallId | C | Hexadecimal string, at most 32 chars.|
|ConnectionId | I | Hexadecimal string, at most 32 chars.|
|NotifiedEntity | N | An identifier, in RFC821 format, |
| | | composed of an arbitrary string and |
| | | of the domain name of the requesting |
| | | entity, possibly completed by a port |
| | | number, as in: |
| | | Call-agent@ca.example.net:5234 |
|RequestIdentifier | X | Hexadecimal string, at most 32 chars.|
|LocalConnectionOptions| L | See description |
|Connection Mode | M | See description |
|RequestedEvents | R | See description |
|SignalRequests | S | See description |
|DigitMap | D | A text encoding of a digit map |
|ObservedEvents | O | See description |
|ConnectionParameters | P | See description |
|ReasonCode | E | An arbitrary character string |
|SpecificEndpointID | Z | An identifier, in RFC821 format, |
| | | composed of an arbitrary string, |
| | | followed by an "@" followed by the |
| | | domain name of the gateway to which |
| | | this endpoint is attached. |
|Second Endpoint ID | Z2 | Endpoint Id. |
|SecondConnectionId | I2 | Connection Id. |
|RequestedInfo | F | See description |
|QuarantineHandling | Q | See description |
|DetectEvents | T | See Description |
|RestartMethod | RM | See description |
|RestartDelay | RD | A number of seconds, encoded as |
| | | a decimal number |
|EventStates | ES | See description |
|Capabilities | A | See description |
|______________________|______|_______________________________________|
|RemoteConnection | RC | Session Description |
|Descriptor | | |
|LocalConnection | LC | Session Description |
|Descriptor | | |
|______________________|______|_______________________________________|
The parameters are not necessarily present in all commands. The
following table provides the association between parameters and
commands. The letter M stands for mandatory, O for optional and F for
forbidden.
___________________________________________________________________
| Parameter name | EP| CR| MD| DL| RQ| NT| AU| AU| RS|
| | CF| CX| CX| CX| NT| FY| EP| CX| IP|
|_____________________|____|____|____|____|____|____|____|____|____|
| ResponseAck | O | O | O | O | O | O | O | O | O |
| BearerInformation | M | O | O | O | O | F | F | F | F |
| CallId | F | M | M | O | F | F | F | F | F |
| ConnectionId | F | F | M | O | F | F | F | M | F |
| RequestIdentifier | F | O+| O+| O+| M | M | F | F | F |
| LocalConnection | F | O | O | F | F | F | F | F | F |
| Options | | | | | | | | | |
| Connection Mode | F | M | M | F | F | F | F | F | F |
| RequestedEvents | F | O | O | O | O*| F | F | F | F |
| SignalRequests | F | O | O | O | O*| F | F | F | F |
| NotifiedEntity | F | O | O | O | O | O | F | F | F |
| ReasonCode | F | F | F | O | F | F | F | F | O |
| ObservedEvents | F | F | F | F | F | M | F | F | F |
| DigitMap | F | O | O | O | O | F | F | F | F |
| Connection | F | F | F | O | F | F | F | F | F |
| parameters | | | | | | | | | |
| Specific Endpoint ID| F | F | F | F | F | F | F | F | F |
| Second Endpoint ID | F | O | F | F | F | F | F | F | F |
| RequestedInfo | F | F | F | F | F | F | M | M | F |
| QuarantineHandling | F | O | O | O | O | F | F | F | F |
| DetectEvents | F | O | O | O | O | F | F | F | F |
| EventStates | F | F | F | F | F | F | F | F | F |
| RestartMethod | F | F | F | F | F | F | F | F | M |
| RestartDelay | F | F | F | F | F | F | F | F | O |
| SecondConnectionID | F | F | F | F | F | F | F | F | F |
| Capabilities | F | F | F | F | F | F | F | F | F |
|_____________________|____|____|____|____|____|____|____|____|____|
| RemoteConnection | F | O | O | F | F | F | F | F | F |
| Descriptor | | | | | | | | | |
| LocalConnection | F | F | F | F | F | F | F | F | F |
| Descriptor | | | | | | | | | |
|_____________________|____|____|____|____|____|____|____|____|____|
Note (+) that the RequestIdentifier parameter is optional in
connection creation, modification and deletion commands, but that it
becomes mandatory if the command contains an encapsulated
notification request.
Note (*) that the RequestedEvents and SignalRequests parameters are
optional in the NotificationRequest. If these parameters are omitted,
the corresponding lists will be considered empty.
If implementers need to experiment with new parameters, for example
when developing a new application of MGCP, they should identify these
parameters by names that start with the string "X-" or "X+", such as
for example:
X-FlowerOfTheDay: Daisy
Parameter names that start with "X+" are critical parameter
extensions. An MGCP entity that receives a critical parameter
extension that it cannot understand should refuse to execute the
command. It should respond with an error code 511 (Unrecognized
extension).
Parameter names that start with "X-" are non critical parameter
extensions. An MGCP entity that receives a non critical parameter
extension that it cannot understand can safely ignore that parameter.
3.2.2.1. Response Acknowledgement
The response acknowledgement attribute is used to managed the "at-
most-once" facility described in the "transmission over UDP" section.
It contains a comma separated list of "confirmed transaction-id
ranges".
Each "confirmed transaction-id ranges" is composed of either one
decimal number, when the range includes exactly one transaction, or
two decimal numbers separated by a single hyphen, describing the
lower and higher transaction identifiers included in the range.
An example of response acknowledgement is:
K: 6234-6255, 6257, 19030-19044
3.2.2.2. Local connection options
The local connection options describe the operational parameters that
the Call Agent suggests to the gateway. These parameters are:
* The packetization period in milliseconds, encoded as the keyword
"p", followed by a colon and a decimal number. If the Call Agent
specifies a range of values, the range will be specified as two
decimal numbers separated by an hyphen.
* The preferred type of compression algorithm, encoded as the
keyword "a", followed by a colon and a character string. If the
Call Agent specifies a list of values, these values will be
separated by a semicolon.
* The bandwidth in kilobits per second (1000 bits per second),
encoded as the keyword "b", followed by a colon and a decimal
number. If the Call Agent specifies a range of values, the range
will be specified as two decimal numbers separated by an hyphen.
* The echo cancellation parameter, encoded as the keyword "e",
followed by a colon and the value "on" or "off".
* The gain control parameter, encoded as the keyword "gc", followed
by a colon a value which can be either the keyword "auto" or a
decimal number (positive or negative) representing the number of
decibels of gain.
* The silence suppression parameter, encoded as the keyword "s",
followed by a colon and the value "on" or "off".
* The type of service parameter, encoded as the keyword "t",
followed by a colon and the value encoded as two hexadecimal
digits.
* The resource reservation parameter, encoded as the keyword "r",
followed by a colon and the value "g" (guaranteed service), "cl"
(controlled load) or "be" (best effort).
* The encryption key, encoded as the keyword "k" followed by a colon
and a key specification, as defined for the parameter "K" of SDP
(RFC2327).
* The type of network, encoded as the keyword "nt" followed by a
colon and the type of network encoded as the keyword "IN", "ATM"
or "LOCAL".
Each of the parameters is optional. When several parameters are
present, the values are separated by a comma.
Examples of connection descriptors are:
L: p:10, a:PCMU
L: p:10, a:G726-32
L: p:10-20, b:64
L: b:32-64, e:off
These set of attributes may be extended by extension attributes.
Extension attributes are composed of an attribute name, followed by a
semi-colon and by an attribute value. The attribute name should start
by the two characters "x+", for a mandatory extensions, or "x-", for
a non mandatory extension. If a gateway receives a mandatory
extension attribute that it does not recognize, it should reject the
command with an error code 525 (Unknown extension in
LocalConnectionOptions).
3.2.2.3. Capabilities
Capabilities inform the Call Agent about endpoints' capabilities when
audited. The encoding of capabilities is based on the Local
Connection Options encoding for the parameters that are common to
both. In addition, capabilities can also contain a list of supported
packages, and a list of supported modes.
The parameters used are:
*
A list of supported codecs. The following parameters will apply to
all codecs specified in this list. If there is a need to specify
that some parameters, such as e.g. silence suppression, are only
compatible with some codecs, then the gateway will return several
LocalConnectionOptions parameters, one for each set of codecs.
Packetization Period:
A range may be specified.
Bandwidth:
A range corresponding to the range for packetization periods may
be specified (assuming no silence suppression). If absent, the
values will be deduced from the codec type.
Echo Cancellation:
"on" if echo cancellation is supported for this codec, "off"
otherwise. The default is support.
Silence Suppression:
"on" if silence suppression is supported for this codec, "off"
otherwise. The default is support.
Gain Control:
"0" if gain control is not supported. The default is support.
Type of Service:
The value "0" indicates no support for type of service, all other
values indicate support for type of service. The default is
support.
Resource Reservation:
The parameter indicates the reservation services that are
supported, in addition to best effort. The value "g" is encoded
when the gateway supports both the guaranteed and the controlled
load service, "cl" when only the controlled load service is
supported. The default is "best effort."
Encryption Key:
Encoding any value indicates support for encryption. Default is
no support.
Type of network:
The keyword "nt", followed by a colon and a semicolon separated
list of supported network types. This parameter is optional.
Event Packages
The event packages supported by this endpoint encoded as the
keyword "v", followed by a colon and a character string. If a list
of values is specified, these values will be separated by a
semicolon. The first value specified will be the default package
for that endpoint.
Modes
The modes supported by this endpoint encoded as the keyword "m",
followed by a colon and a semicolon-separated list of supported
connection modes for this endpoint.
3.2.2.4. Connection parameters
Connection parameters are encoded as a string of type and value
pairs, where the type is a either letter identifier of the parameter
or an extension type, and the value a decimal integer. Types are
separated from value by an `=' sign. Parameters are encoded from each
other by a comma.
The connection parameter types are specified in the following table:
__________________________________________________________________
| Connection parameter| Code| Connection parameter |
| name | | value |
|_____________________|______|____________________________________|
| Packets sent | PS | The number of packets that |
| | | were sent on the connection. |
| Octets sent | OS | The number of octets that |
| | | were sent on the connection. |
| Packets received | PR | The number of packets that |
| | | were received on the connection. |
| Octets received | OR | The number of octets that |
| | | were received on the connection. |
| Packets lost | PL | The number of packets that |
| | | were not received on the |
| | | connection, as deduced from |
| | | gaps in the sequence number. |
| Jitter | JI | The average inter-packet arrival |
| | | jitter, in milliseconds, |
| | | expressed as an integer number. |
| Latency | LA | Average latency, in milliseconds, |
| | | expressed as an integer number. |
|_____________________|______|____________________________________|
Extension parameters names are composed of the string "X-" followed
by a two letters extension parameter name. Call agents that received
unrecognized extensions shall silently ignore these extensions.
An example of connection parameter encoding is:
P: PS=1245, OS=62345, PR=0, OR=0, PL=0, JI=0, LA=48
3.2.2.5. Reason Codes
Reason codes are three-digit numeric values. The reason code is
optionally followed by a white space and commentary, e.g.:
900 Endpoint malfunctioning
A list of reason-codes can be found in Section 2.5.
3.2.2.6. Connection mode
The connection mode describes the mode of operation of the
connection. The possible values are:
________________________________________________________
| Mode | Meaning |
|____________|__________________________________________|
| M: sendonly| The gateway should only send packets |
| M: recvonly| The gateway should only receive packets |
| M: sendrecv| The gateway should send |
| | and receive packets |
| M: confrnce| The gateway should place |
| | the connection in conference mode |
| M: inactive| The gateway should neither |
| | send nor receive packets |
| M: loopback| The gateway should place |
| | the circuit in loopback mode. |
| M: conttest| The gateway should place |
| | the circuit in test mode. |
| M: netwloop| The gateway should place |
| | the connection in network loopback mode.|
| M: netwtest| The gateway should place |
| | the connection in network |
| | continuity test mode. |
| M: data | The gateway should use the circuit |
| | for network access for data |
| | (e.g., PPP, SLIP, etc.). |
|____________|__________________________________________|
3.2.2.7. Coding of event names
Event names are composed of an optional package name, separated by a
slash (/) from the name of the actual event. The event name can
optionally be followed by an at sign (@) and the identifier of a
connection on which the event should be observed. Event names are
used in the RequestedEvents, SignalRequests and ObservedEvents
parameter.
Each signal has one of the following signal-types associated with:
On/Off (OO), Time-out (TO), Brief (BR). (These signal types are
specified in the package definitions, and are not present in the
messages.) On/Off signals can be parameterized with a "+" to turn
the signal on, or a "-" to turn the signal off. If an on/off signal
is not parameterized, the signal is turned on. Both of the following
will turn the vmwi signal on:
vmwi(+), vmwi
The following are valid examples of event names:
____________________________________________________________
| L/hu | on-hook transition, in the line package |
| F/0 | digit 0 in the MF package |
| fh | Flash-hook, assuming that the line package|
| | is a default package for the end point. |
| G/rt@0A3F58 | Ring back signal on |
| | connection "0A3F58". |
|_____________|_____________________________________________|
In addition, the range and wildcard notation of events can be used,
instead of individual names, in the RequestedEvents and DetectEvents
parameters. The star sign can be used to denote "all connections",
and the dollar sign can be used to denote the "current" connection.
The following are valid examples of such notations:
__________________________________________________________
| M/[0-9] | Digits 0 to 9 in the MF package |
| fh | Flash-hook, assuming that the line package|
| | is a default package for the end point. |
| [0-9*#A-D]| All digits and letters in the DTMF |
| | packages (default for endpoint). |
| T/$ | All events in the trunk packages. |
| R/qa@* | The quality alert event in all |
| | connections |
| R/rt@$ | Ringback on current connection |
|___________|_____________________________________________|
3.2.2.8. RequestedEvents
The RequestedEvent parameter provides the list of events that have
been requested. The event codes are described in the previous
section.
Each event can be qualified by a requested action, or by a list of
actions. The actions, when specified, are encoded as a list of
keywords, enclosed in parenthesis and separated by commas. The codes
for the various actions are:
______________________________________
| Action | Code|
|______________________________|______|
| Notify immediately | N |
| Accumulate | A |
| Treat according to digit map | D |
| Swap | S |
| Ignore | I |
| Keep Signal(s) active | K |
| Embedded Notification Request| E |
|______________________________|______|
When no action is specified, the default action is to notify the
event. This means that, for example, ft and ft(N) are equivalent.
Events that are not listed are ignored.
The digit-map action can only be specified for the digits, letters
and interdigit timers in the MF and DTMF packages, or in other
packages that would define the encoding of digits and timers.
The requested list is encoded on a single line, with event/action
groups separated by commas. Examples of RequestedEvents encoding are:
R: hu(N), hf(S,N)
R: hu(N), [0-9#T](D)
In the case of the "enable" action, the embedded notification request
parameters are encoded as a list of up to three parameter groups,
separated by commas. Each group start by a one letter identifier,