* LocalConnectionOptions, the most recent LocalConnectionOptions parameters that was actually supplied for the connection (omitting LocalConnectionOptions from a command thus does not change this value). Note that default parameters omitted from the most recent LocalConnectionOptions will not be included. LocalConnectionOptions that retain their value across ModifyConnection commands and which have been included in a previous command for the connection are also included, regardless of whether they were supplied in the most recent LocalConnectionOptions or not. * Mode, the current mode of the connection. * RemoteConnectionDescriptor, the RemoteConnectionDescriptor that was supplied to the gateway for the connection. * LocalConnectionDescriptor, the LocalConnectionDescriptor the gateway supplied for the connection. * ConnectionParameters, the current values 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. Note, that by definition, the endpoint must be in-service for this to happen, as out-of-service endpoints do not have any connections. 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. PackageList is a list of supported packages that MAY be included with error code 518 (unsupported package).
The EndPointId identifies the endpoint(s) that are put in-service or out-of-service. The "all of" wildcard convention may be used to apply the command to a group of endpoints managed by the same Call Agent, 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 specifies the type of restart. The following 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 from establishing new connections, and SHOULD try to gracefully tear down the existing connections. * A "forced" restart method indicates that the specified endpoints are taken abruptly 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", i.e., the endpoints will be in-service. The endpoints are in their clean default state and 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 (see Section 4.4.7). 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 endpoints are still in-service. The list of restart methods may be extended. The optional "restart delay" parameter is expressed as a number of seconds. If the number is absent, the delay value MUST be considered null (i.e., zero). 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" and "cancel-graceful" methods, and hence the "restart delay" parameter MUST NOT be used with these restart methods. When the gateway sends a "restart" or "graceful"
RestartInProgress message with a non-zero restart delay, the gateway SHOULD send an updated RestartInProgress message after the "restart delay" has passed. A restart delay of null for the "restart" method indicates that service has already been restored. This typically will occur after gateway startup/reboot. To mitigate the effects of a gateway IP address change as a result of a re-boot, the Call Agent MAY wish to either flush its DNS cache for the gateway's domain name or resolve the gateway's domain name by querying the DNS regardless of the TTL of a current DNS resource record for the restarted gateway. The optional reason code parameter indicates the cause of the restart. Gateways SHOULD send a "graceful" or "forced" RestartInProgress message (for the relevant endpoints) 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, however the Call Agent cannot rely on always receiving such a message. Gateways MUST send a "restart" RestartInProgress message (for the relevant endpoints) with a null delay to their Call Agent when they are back in-service according to the restart procedure specified in Section 4.4.6 - Call Agents can rely on receiving this message. Also, gateways MUST send a "disconnected" RestartInProgress message (for the relevant endpoints) to their current "notified entity" according to the "disconnected" procedure specified in Section 4.4.7. 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 so that after a reboot/restart, the default Call Agent will always be the "notified entity" for the 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 Call Agent. 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 to the RestartInProgress from the Call Agent - this SHOULD normally only be done in response to "restart" or "disconnected" (see also Section 4.4.6 and 4.4.7):
* If the response indicated success (return code 200 - transaction executed), the restart in question completed successfully, 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 in question did not complete successfully. If a NotifiedEntity parameter was included in the response returned, it specifies a new "notified entity" for the endpoint(s), which MUST be used when retrying the restart in question (as a new transaction). This SHOULD only be done with error code 521 (endpoint redirected). Note that the above behavior for returning a NotifiedEntity in the response is only defined for RestartInProgress responses and SHOULD NOT be done for responses to other commands. Any other behavior is undefined. PackageList is a list of supported packages that MAY be included with error code 518 (unsupported package).
* If a Call Agent receives a transient error, there is the expectation of the possibility that a future similar request will be honored by the endpoint. In some cases, this may require some state change in the environment of the endpoint (e.g., hook state as in the case of error codes 401 or 402; resource availability as in the case of error code 403, or bandwidth availability as in the case of error code 404). * Permanent errors (error codes 500 to 599) indicate one or more permanent conditions either due to protocol error or incompatibility between the endpoint and the Call Agent, or because of some error condition over which the Call Agent has no control. Examples are protocol errors, requests for endpoint capabilities that do not exist, errors on interfaces associated with the endpoint, missing or incorrect information in the request or any number of other conditions which will simply not disappear with time. The values that have been already defined are the following: 000 Response Acknowledgement. 100 The transaction is currently being executed. An actual completion message will follow later. 101 The transaction has been queued for execution. An actual completion message will follow later. 200 The requested transaction was executed normally. This return code can be used for a successful response to any command. 250 The connection was deleted. This return code can only be used for a successful response to a DeleteConnection command. 400 The transaction could not be executed, due to some unspecified 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. 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. This includes the case where the endpoint is out-of- service. 502 The transaction could not be executed, because the endpoint does not have sufficient resources (permanent condition). 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, or the call-id supplied is incorrect (e.g., connection-id not associated with this call-id). 517 Unsupported or invalid mode. 518 Unsupported or unknown package. It is RECOMMENDED to include a PackageList parameter with the list of supported packages in the response, especially if the response is generated by the Call Agent. 519 Endpoint does not have a digit map. 520 The transaction could not be executed, because the endpoint is "restarting". In most cases this would be a transient error, in which case, error code 405 SHOULD be used instead. The error code is only included here for backwards compatibility. 521 Endpoint redirected to another Call Agent. The associated redirection behavior is only well-defined when this response is issued for a RestartInProgress command.
522 No such event or signal. The request referred to an event or signal that is not defined in the relevant package (which could be the default package). 523 Unknown action or illegal combination of actions. 524 Internal inconsistency in LocalConnectionOptions. 525 Unknown extension in LocalConnectionOptions. This code SHOULD be used for unsupported mandatory vendor extensions ("x+"). 526 Insufficient bandwidth. In cases where this is a transient error, error code 404 SHOULD be used instead. 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). 532 Unsupported value(s) in LocalConnectionOptions. 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.
The set of return codes may be extended in a future version of the protocol. Implementations that receive an unknown or unsupported return code SHOULD treat the return code as follows: * Unknown 0xx code treated as 000. * Unknown 1xx code treated as 100. * Unknown 2xx code treated as 200. * Unknown 3xx code treated as 521. * Unknown 4xx code treated as 400. * Unknown 5xx-9xx code treated as 510.
In determining which codec(s) to provide in the LocalConnectionDescriptor, there are three lists of codecs that a gateway needs to consider: * A list of codecs allowed by the LocalConnectionOptions in the current command (either explicitly by encoding method or implicitly by bandwidth and/or packetization period). * A list of codecs in the RemoteConnectionDescriptor in the current command. * An internal list of codecs that the gateway can support for the connection. A gateway MAY support one or more codecs for a given connection. Codec selection (including all relevant media parameters) can then be described by the following steps: 1. An approved list of codecs is formed by taking the intersection of the internal list of codecs and codecs allowed by the LocalConnectionOptions. If LocalConnectionOptions were not provided in the current command, the approved list of codecs thus contains the internal list of codecs. 2. If the approved list of codecs is empty, a codec negotiation failure has occurred and an error response is generated (error code 534 - codec negotiation failure, is RECOMMENDED). 3. Otherwise, a negotiated list of codecs is formed by taking the intersection of the approved list of codecs and codecs allowed by the RemoteConnectionDescriptor. If a RemoteConnectionDescriptor was not provided in the current command, the negotiated list of codecs thus contains the approved list of codecs. 4. If the negotiated list of codecs is empty, a codec negotiation failure has occurred and an error response is generated (error code 534 - codec negotiation failure, is RECOMMENDED). 5. Otherwise, codec negotiation has succeeded, and the negotiated list of codecs is returned in the LocalConnectionDescriptor. Note that both LocalConnectionOptions and the RemoteConnectionDescriptor can contain a list of codecs ordered by preference. When both are supplied in the current command, the gateway MUST adhere to the preferences provided in the LocalConnectionOptions.
* RestartInProgress The first five 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 Section 2.3.8. The Call Agent may send either of the Audit commands to the gateway, and the gateway may send a RestartInProgress command to the Call Agent. sections 184.108.40.206 and 3.3). Note that an ABNF grammar for MGCP is provided in Appendix A. Commands and responses SHALL be encoded in accordance with the grammar, which, per RFC 2234, is case-insensitive except for the SDP part. Similarly, implementations SHALL be capable of decoding commands and responses that follow the grammar. Additionally, it is RECOMMENDED that implementations tolerate additional linear white space. Some productions allow for use of quoted strings, which can be necessary to avoid syntax problems. Where the quoted string form is used, the contents will be UTF-8 encoded , and the actual value provided is the unquoted string (UTF-8 encoded). Where both a quoted and unquoted string form is allowed, either form can be used provided it does not otherwise violate the grammar. In the following, we provide additional detail on the format of MGCP commands and responses.
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 999,999,999 (both included). Transaction identifiers SHOULD NOT use any leading zeroes, although equality is based on numerical value, i.e., leading zeroes are ignored. 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. RFC 821, although with some syntactic restrictions on the local part of the name. Furthermore, both the local endpoint name part and the domain name part can each be up to 255 characters. In these addresses, the domain name identifies the system where the endpoint is attached, while the left side identifies a specific endpoint or entity on that system. Examples of such addresses are: ------------------------------------------------------------------ | email@example.com | Circuit number 56 in | | | interface "hrd4" of the Gateway | | | 23 of the "Example" network | | Callfirstname.lastname@example.org | Call Agent for the | | | "example" network | | Busyemail@example.com| The "busy signal" virtual | | | endpoint in the announcement | | | server number 12. | ------------------------------------------------------------------ The name of a notified entity is expressed with the same syntax, with the possible addition of a port number as in: Callfirstname.lastname@example.org:5234
In case the port number is omitted from the notified entity, the default MGCP Call Agent port (2727) MUST be used.
------------------------------------------------------------------ |Parameter name | Code | Parameter value | |----------------------|------|------------------------------------| |BearerInformation | B | See description (220.127.116.11). | |CallId | C | See description (18.104.22.168). | |Capabilities | A | See description (22.214.171.124). | |ConnectionId | I | See description (126.96.36.199). | |ConnectionMode | M | See description (188.8.131.52). | |ConnectionParameters | P | See description (184.108.40.206). | |DetectEvents | T | See description (220.127.116.11). | |DigitMap | D | A text encoding of a digit map. | |EventStates | ES | See description (18.104.22.168). | |LocalConnectionOptions| L | See description (22.214.171.124). | |MaxMGCPDatagram | MD | See description (126.96.36.199). | |NotifiedEntity | N | An identifier, in RFC 821 format, | | | | composed of an arbitrary string | | | | and of the domain name of the | | | | requesting entity, possibly com- | | | | pleted by a port number, as in: | | | | Callemail@example.com:5234 | | | | See also Section 188.8.131.52. | |ObservedEvents | O | See description (184.108.40.206). | |PackageList | PL | See description (220.127.116.11). | |QuarantineHandling | Q | See description (18.104.22.168). | |ReasonCode | E | A string with a 3 digit integer | | | | optionally followed by a set of | | | | arbitrary characters (22.214.171.124). | |RequestedEvents | R | See description (126.96.36.199). | |RequestedInfo | F | See description (188.8.131.52). | |RequestIdentifier | X | See description (184.108.40.206). | |ResponseAck | K | See description (220.127.116.11). | |RestartDelay | RD | A number of seconds, encoded as | | | | a decimal number. | |RestartMethod | RM | See description (18.104.22.168). | |SecondConnectionId | I2 | Connection Id. | |SecondEndpointId | Z2 | Endpoint Id. | |SignalRequests | S | See description (22.214.171.124). | |SpecificEndPointId | Z | An identifier, in RFC 821 format, | | | | composed of an arbitrary string, | | | | followed by an "@" followed by | | | | the domain name of the gateway to | | | | which this endpoint is attached. | | | | See also Section 126.96.36.199. | |----------------------|------|------------------------------------|
|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. Unless otherwise specified, a parameter MUST NOT be present more than once.
------------------------------------------------------------------ | Parameter name | EP | CR | MD | DL | RQ | NT | AU | AU | RS | | | CF | CX | CX | CX | NT | FY | EP | CX | IP | |---------------------|----|----|----|----|----|----|----|----|----| | BearerInformation | O*| O | O | O | O | F | F | F | F | | CallId | F | M | M | O | F | F | F | F | F | | Capabilities | F | F | F | F | F | F | F | F | F | | ConnectionId | F | F | M | O | F | F | F | M | F | | ConnectionMode | F | M | O | F | F | F | F | F | F | | Connection- | F | F | F | O*| F | F | F | F | F | | Parameters | | | | | | | | | | | DetectEvents | F | O | O | O | O | F | F | F | F | | DigitMap | F | O | O | O | O | F | F | F | F | | EventStates | F | F | F | F | F | F | F | F | F | | LocalConnection- | F | O | O | F | F | F | F | F | F | | Options | | | | | | | | | | | MaxMGCPDatagram | F | F | F | F | F | F | F | F | F | | NotifiedEntity | F | O | O | O | O | O | F | F | F | | ObservedEvents | F | F | F | F | F | M | F | F | F | | PackageList | F | F | F | F | F | F | F | F | F | | QuarantineHandling | F | O | O | O | O | F | F | F | F | | ReasonCode | F | F | F | O | F | F | F | F | O | | RequestedEvents | F | O | O | O | O*| F | F | F | F | | RequestIdentifier | F | O*| O*| O*| M | M | F | F | F | | RequestedInfo | F | F | F | F | F | F | O | M | F | | ResponseAck | O | O | O | O | O | O | O | O | O | | RestartDelay | F | F | F | F | F | F | F | F | O | | RestartMethod | F | F | F | F | F | F | F | F | M | | SecondConnectionId | F | F | F | F | F | F | F | F | F | | SecondEndpointId | F | O | F | F | F | F | F | F | F | | SignalRequests | F | O | O | O | O*| F | F | F | F | | SpecificEndpointId | 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 | | | | | | | | | | ------------------------------------------------------------------ Notes (*): * The BearerInformation parameter is only conditionally optional as explained in Section 2.3.2. * The RequestIdentifier parameter is optional in connection creation, modification and deletion commands, however it becomes REQUIRED if the command contains an encapsulated notification request.
* The RequestedEvents and SignalRequests parameters are optional in the NotificationRequest. If these parameters are omitted the corresponding lists will be considered empty. * The ConnectionParameters parameter is only valid in a DeleteConnection request sent by the gateway. The set of parameters can be extended in two different ways: * Package Extension Parameters (preferred) * Vendor Extension Parameters Package Extension Parameters are defined in packages which provides the following benefits: * a registration mechanism (IANA) for the package name. * a separate name space for the parameters. * a convenient grouping of the extensions. * a simple way to determine support for them through auditing. The package extension mechanism is the preferred extension method. Vendor extension parameters can be used if implementers need to experiment with new parameters, for example when developing a new application of MGCP. Vendor extension parameters MUST be identified by names that start with the string "X-" or "X+", such as for example: X-Flower: Daisy Parameter names that start with "X+" are critical parameter extensions. An MGCP entity that receives a critical parameter extension that it cannot understand MUST refuse to execute the command. It SHOULD respond with 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 MUST simply ignore that parameter.
Note that vendor extension parameters use an unmanaged name space, which implies a potential for name clashing. Vendors are consequently encouraged to include some vendor specific string, e.g., vendor name, in their vendor extensions.
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, "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, all other values indicate support for gain control. 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 Service: 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 which is implied by omitting the parameter. Type of network: The keyword "nt", followed by a colon and a semicolon separated list of supported network types. This parameter is optional. Packages: The packages supported by the 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 the 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.
Lack of support for a capability can also be indicated by excluding the parameter from the capability set. An example capability is: A: a:PCMU;G728, p:10-100, e:on, s:off, t:1, v:L, m:sendonly;recvonly;sendrecv;inactive The carriage return above is included for formatting reasons only and is not permissible in a real implementation. If multiple capabilities are to be returned, each will be returned as a separate capability line. Since Local Connection Options can be extended, the list of capability parameters can also be extended. Individual extensions may define how they are reported as capabilities. If no such definition is provided, the following defaults apply: * Package Extension attributes: The individual attributes are not reported. Instead, the name of the package is simply reported in the list of supported packages. * Vendor Extension attributes: The name of the attribute is reported without any value. * Other Extension attributes: The name of the attribute is reported without any value. Section 2.1.7). The wildcard character star ("*") can be use to refer to all packages. The event name can optionally be followed by an at sign (@) and the identifier of a connection (possibly using a wildcard) on which the event should be observed. Event names are used in the RequestedEvents, SignalRequests, ObservedEvents, DetectEvents, and EventStates parameters. Events and signals may be qualified by parameters defined for the event/signal. Such parameters may be enclosed in double-quotes (in fact, some parameters MUST be enclosed in double-quotes due to syntactic restrictions) in which case they are UTF-8 encoded . The parameter name "!" (exclamation point) is reserved for future use for both events and signals.
Each signal has one of the following signal-types associated with it: On/Off (OO), Time-out (TO), or 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 (from the line package "L") on: L/vmwi(+) L/vmwi In addition to "!", "+" and "-", the signal parameter "to" is reserved as well. It can be used with Time-Out signals to override the default time-out value for the current request. A decimal value in milliseconds will be supplied. The individual signal and/or package definition SHOULD indicate if this parameter is supported for one or more TO signals in the package. If not indicated, TO signals in package version zero are assumed to not support it, whereas TO signals in package versions one or higher are assumed to support it. By default, a supplied time-out value MAY be rounded to the nearest non-zero value divisible by 1000, i.e., whole second. The individual signal and/or package definition may define other rounding rules. All new package and TO signal definitions are strongly encouraged to support the "to" signal parameter. The following example illustrates how the "to" parameter can be used to apply a signal for 6 seconds: L/rg(to=6000) L/rg(to(6000)) The following are examples of event names: ----------------------------------------------------------- | L/hu | on-hook transition, in the line package | | F/0 | digit 0 in the MF package | | hf | Hook-flash, assuming that the line package| | | is the default package for the endpoint. | | 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 event code "all" is reserved and refers to all events or signals in a package. The star sign ("*") can be used to denote "all connections", and the dollar sign ("$") can be used to denote the "current" connection (see Section 2.1.7 for details).
The following are examples of such notations: --------------------------------------------------------- | M/[0-9] | Digits 0 to 9 in the MF package. | | hf | Hook-flash, assuming that the line package| | | is a default package for the endpoint. | | [0-9*#A-D]| All digits and letters in the DTMF | | | packages (default for endpoint). | | T/all | All events in the trunk package. | | R/qa@* | The quality alert event on all | | | connections. | | G/rt@$ | Ringback on current connection. | ---------------------------------------------------------
Note that irrespective of the connection mode, signals applied to the connection will still result in packets being sent (see Section 2.3.1). The set of connection modes can be extended through packages.
Package Extension Connection Parameters are defined in packages which provides the following benefits: * A registration mechanism (IANA) for the package name. * A separate name space for the parameters. * A convenient grouping of the extensions. * A simple way to determine support for them through auditing. The package extension mechanism is the preferred extension method. Vendor extension parameters names are composed of the string "X-" followed by a two or more letters extension parameter name. Call agents that receive unrecognized package or vendor connection parameter extensions SHALL silently ignore these parameters. An example of connection parameter encoding is: P: PS=1245, OS=62345, PR=0, OR=0, PL=0, JI=0, LA=48 Section 188.8.131.52), such as for example: T: L/hu,L/hd,L/hf,D/[0-9#*] It should be noted, that no actions can be associated with the events, however event parameters may be provided. Section 184.108.40.206), such as for example: ES: L/hu It should be noted, that no actions can be associated with the events, however event parameters may be provided.
* The allowed codec(s), 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. For RTP, audio codecs SHALL be specified by using encoding names defined in the RTP AV Profile  or its replacement, or by encoding names registered with the IANA. Non-audio media registered as a MIME type MUST use the "<MIME type>/<MIME subtype>" form, as in "image/t38". * 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 a hyphen (as specified for the "ptime" parameter for SDP). * 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 a hyphen. * The type of service parameter, encoded as the keyword "t", followed by a colon and the value encoded as two hexadecimal digits. When the connection is transmitted over an IP network, the parameters encode the 8-bit type of service value parameter of the IP header (a.k.a. DiffServ field). The left-most "bit" in the parameter corresponds to the least significant bit in the IP header. * 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 and 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 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" in SDP (RFC 2327).
* The type of network, encoded as the keyword "nt" followed by a colon and the type of network encoded as the keyword "IN" (internet), "ATM", "LOCAL" (for a local connection), or possibly another type of network registered with the IANA as per SDP (RFC 2327). * 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 encoding of the first three attributes, when they are present, will be compatible with the SDP and RTP profiles. Note that each of the attributes is optional. When several attributes are present, they are separated by a comma. Examples of local connection options are: L: p:10, a:PCMU L: p:10, a:G726-32 L: p:10-20, b:64 L: b:32-64, e:off The set of Local Connection Options attributes can be extended in three different ways: * Package Extension attributes (preferred) * Vendor Extension attributes * Other Extension attributes Package Extension Local Connection Options attributes are defined in packages which provides the following benefits: * A registration mechanism (IANA) for the package name. * A separate name space for the attributes. * A convenient grouping of the extensions. * A simple way to determine support for them through auditing. The package extension mechanism is the preferred extension method.
Vendor extension attributes are composed of an attribute name, and possibly followed by a colon and an attribute value. The attribute name MUST start with the two characters "x+", for a mandatory extension, or "x-", for a non-mandatory extension. If a gateway receives a mandatory extension attribute that it does not recognize, it MUST reject the command (error code 525 - unknown extension in LocalConnectionOptions, is RECOMMENDED). Note that vendor extension attributes use an unmanaged name space, which implies a potential for name clashing. Vendors are consequently encouraged to include some vendor specific string, e.g., vendor name, in their vendor extensions. Finally, for backwards compatibility with some existing implementations, MGCP allows for other extension attributes as well (see grammar in Appendix A). Note however, that these attribute extensions do not provide the package extension attribute benefits. Use of this mechanism for new extensions is discouraged.
Section 2.5. The set of reason codes can be extended through packages.
Section 220.127.116.11. 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 (unless they are persistent). The digit-map action SHOULD only be specified for the digits, letters and interdigit timers in packages that define the encoding of digits, letters, and timers (including extension digit map letters). The requested events list is encoded on a single line, with event/action groups separated by commas. Examples of RequestedEvents encodings are: R: L/hu(N), L/hf(S,N) R: L/hu(N), D/[0-9#T](D) In the case of the "Embedded Notification Request" action, the embedded notification request parameters are encoded as a list of up to three parameter groups separated by commas. Each group starts by a one letter identifier, followed by a list of parameters enclosed between parentheses. The first optional parameter group, identified by the letter "R", is the value of the embedded RequestedEvents parameter. The second optional group, identified by the letter "S", is the embedded value of the SignalRequests parameter. The third
optional group, identified by the letter "D", is the embedded value of the DigitMap. (Note that some existing implementations and profiles may encode these three components in a different order. Implementers are encouraged to accept such encodings, but they SHOULD NOT generate them.) If the RequestedEvents parameter is not present, the parameter will be set to a null value. If the SignalRequests parameter is not present, the parameter will be set to a null value. If the DigitMap is absent, the current value MUST be used. The following are valid examples of embedded requests: R: L/hd(E(R(D/[0-9#T](D),L/hu(N)),S(L/dl),D([0-9].[#T]))) R: L/hd(E(R(D/[0-9#T](D),L/hu(N)),S(L/dl))) Some events can be qualified by additional event parameters. Such event parameters will be separated by commas and enclosed within parentheses. Event parameters may be enclosed in double-quotes (in fact, some event parameters MUST be enclosed in double-quotes due to syntactic restrictions), in which case the quoted string itself is UTF-8 encoded. Please refer to Section 18.104.22.168 for additional detail on event parameters. The following example shows the foobar event with an event parameter "epar": R: X/foobar(N)(epar=2) Notice that the Action was included even though it is the default Notify action - this is required by the grammar. Section 3.2.2. For example, if one wants to audit the value of the NotifiedEntity, RequestIdentifier, RequestedEvents, SignalRequests, DigitMap, QuarantineHandling and DetectEvents parameters, the value of the RequestedInfo parameter will be: F: N,X,R,S,D,Q,T Note that extension parameters in general can be audited as well. The individual extension will define the auditing operation.
The capabilities request, in the AuditEndPoint command, is encoded by the parameter code "A", as in: F: A Section 3.5. It contains a comma separated list of "confirmed transaction-id ranges". Each "confirmed transaction-id range" 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 a response acknowledgement is: K: 6234-6255, 6257, 19030-19044 Section 22.214.171.124. Some signals, such as for example announcement or ADSI display, can be qualified by additional parameters, e.g.:
* the name and parameters of the announcement, * the string that should be displayed. Such parameters will be separated by commas and enclosed within parenthesis, as in: S: L/adsi("123456 Francois Gerard") S: A/ann(http://ann.example.net/no-such-number.au, 1234567) When a quoted-string is provided, the string itself is UTF-8 encoded . When several signals are requested, their codes are separated by a comma, as in: S: L/adsi("123456 Your friend"), L/rg Please refer to Section 126.96.36.199 for additional detail on signal parameters.