CreateConnection

This command is used to create a connection between two endpoints.

ReturnCode, [ConnectionId,]

[SpecificEndPointId,]

[LocalConnectionDescriptor,]

[SecondEndPointId,]

[SecondConnectionId,]

[PackageList]

<-- CreateConnection(CallId, EndpointId,

[NotifiedEntity,]

[LocalConnectionOptions,]

Mode,

[{RemoteConnectionDescriptor | SecondEndpointId}, ]

[Encapsulated NotificationRequest,]

[Encapsulated EndpointConfiguration]) A connection is defined by its endpoints. The input parameters in CreateConnection provide the data necessary to build a gateway’s "view" of a connection.

CallId is a parameter that identifies the call (or session) to which this connection belongs. This parameter SHOULD, at a minimum, be unique within the collection of Call Agents that control the same gateways. Connections that belong to the same call SHOULD share the same call-id. The call-id has little semantic meaning in the

protocol; however it can be used to identify calls for reporting and accounting purposes. It does not affect the handling of connections by the gateway.

EndpointId is the identifier for the connection endpoint in the gateway where CreateConnection executes. The EndpointId can be fully-specified by assigning a value to the parameter EndpointId in the function call or it may be under-specified by using the "any of"

wildcard convention. If the endpoint is underspecified, the endpoint identifier SHALL be assigned by the gateway and its complete value returned in the SpecificEndPointId parameter of the response. When the "any of" wildcard is used, the endpoint assigned MUST be service and MUST NOT already have any connections on it. If no such endpoint is available, error code 410 (no endpoint available) SHOULD be returned. The "all of" wildcard MUST NOT be used.

The NotifiedEntity is an optional parameter that specifies a new "notified entity" for the endpoint.

LocalConnectionOptions is an optional structure used by the Call Agent to direct the handling of the connection by the gateway. The fields contained in a LocalConnectionOptions structure may include one or more of the following (each field MUST NOT be supplied more than once):

* Codec compression algorithm: One or more codecs, listed in order of preference. For interoperability, it is RECOMMENDED to support G.711 mu-law encoding ("PCMU"). See Section 2.6 for details on the codec selection process.

* Packetization period: A single millisecond value or a range may be specified. The packetization period SHOULD NOT contradict the specification of the codec compression algorithm. If a codec is specified that has a frame size which is inconsistent with the packetization period, and that codec is selected, the gateway is authorized to use a packetization period that is consistent with the frame size even if it is different from that specified. In so doing, the gateway SHOULD choose a non-zero packetization period as close to that specified as possible. If a packetization period is not specified, the endpoint SHOULD use the default packetization period(s) for the codec(s) selected.

* Bandwidth: The allowable bandwidth, i.e., payload plus any header overhead from the transport layer and up, e.g., IP, UDP, and RTP.

The bandwidth specification SHOULD NOT contradict the specification of codec compression algorithm or packetization period. If a codec is specified, then the gateway is authorized to use it, even if it results in the usage of a larger bandwidth than specified. Any discrepancy between the bandwidth and codec specification will not be reported as an error.

* Type of Service: This indicates the class of service to be used for this connection. When the Type of Service is not specified, the gateway SHALL use a default value of zero unless provisioned otherwise.

* Usage of echo cancellation: By default, the telephony gateways always perform echo cancellation on the endpoint. However, it may be necessary, for some calls, to turn off these operations. The echo cancellation parameter can have two values, "on" (when the echo cancellation is requested) and "off" (when it is turned off).

The parameter is optional. If the parameter is omitted when creating a connection and there are no other connections on the endpoint, the endpoint SHALL apply echo cancellation initially. If the parameter is omitted when creating a connection and there are existing connections on the endpoint, echo cancellation is

unchanged. The endpoint SHOULD subsequently enable or disable echo

cancellation when voiceband data is detected - see e.g., ITU-T recommendation V.8, V.25, and G.168. Following termination of voiceband data, the handling of echo cancellation SHALL then revert to the current value of the echo cancellation parameter. It is RECOMMENDED that echo cancellation handling is left to the gateway rather than having this parameter specified by the Call Agent.

* Silence Suppression: The telephony gateways may perform voice activity detection, and avoid sending packets during periods of silence. However, it is necessary, for example for modem calls, to turn off this detection. The silence suppression parameter can have two values, "on" (when the detection is requested) and "off"

(when it is not requested). The default is "off" (unless provisioned otherwise). Upon detecting voiceband data, the

endpoint SHOULD disable silence suppression. Following termination of voiceband data, the handling of silence suppression SHALL then revert to the current value of the silence suppression parameter.

* Gain Control: The telephony gateways may perform gain control on the endpoint, in order to adapt the level of the signal. However, it is necessary, for example for some modem calls, to turn off this function. The gain control parameter may either be specified as "automatic", or as an explicit number of decibels of gain. The gain specified will be added to media sent out over the endpoint (as opposed to the connection) and subtracted from media received on the endpoint. The parameter is optional. When there are no other connections on the endpoint, and the parameter is omitted, the default is to not perform gain control (unless provisioned otherwise), which is equivalent to specifying a gain of 0 decibels.

If there are other connections on the endpoint, and the parameter is omitted, gain control is unchanged. Upon detecting voiceband data, the endpoint SHOULD disable gain control if needed.

Following termination of voiceband data, the handling of gain control SHALL then revert to the current value of the gain control parameter. It should be noted, that handling of gain control is normally best left to the gateway and hence use of this parameter is NOT RECOMMENDED.

* RTP security: The Call agent can request the gateway to enable encryption of the audio Packets. It does so by providing a key specification, as specified in RFC 2327. By default, encryption is not performed.

* Network Type: The Call Agent may instruct the gateway to prepare the connection on a specified type of network. If absent, the value is based on the network type of the gateway being used.

* Resource reservation: The Call Agent may instruct the gateway to use network resource reservation for the connection. See Section 2.7 for details.

The Call Agent specifies the relevant fields it cares about in the command and leaves the rest to the discretion of the gateway. For those of the above parameters that were not explicitly included, the gateway SHOULD use the default values if possible. For a detailed list of local connection options included with this specification refer to section 3.2.2.10. The set of local connection options can be extended.

The Mode indicates the mode of operation for this side of the

connection. The basic modes are "send", "receive", "send/receive", "conference", "inactive", "loopback", "continuity test", "network loop back" and "network continuity test". The expected handling of these modes is specified in the introduction of the "Gateway Control Commands", Section 2.3. Note that signals applied to a connection do not follow the connection mode. Some endpoints may not be capable of supporting all modes. If the command specifies a mode that the

endpoint does not support, an error SHALL be returned (error 517 unsupported mode, is RECOMMENDED). Also, if a connection has not yet received a RemoteConnectionDescriptor, an error MUST be returned if the connection is attempted to be placed in any of the modes "send only", "send/receive", "conference", "network loopback", "network continuity test", or if a signal (as opposed to detecting an event) is to be applied to the connection (error code 527 - missing

RemoteConnectionDescriptor, is RECOMMENDED). The set of modes can be extended.

The gateway returns a ConnectionId, that uniquely identifies the connection within the endpoint, and a LocalConnectionDescriptor, which is a session description that contains information about the connection, e.g., IP address and port for the media, as defined in SDP.

The SpecificEndPointId is an optional parameter that identifies the responding endpoint. It is returned when the EndpointId argument referred to an "any of" wildcard name and the command succeeded.

When a SpecificEndPointId is returned, the Call Agent SHALL use it as the EndpointId value in successive commands referring to this

connection.

The SecondEndpointId can be used instead of the

RemoteConnectionDescriptor to establish a connection between two endpoints located on the same gateway. The connection is by

definition a local connection. The SecondEndpointId can be specified by assigning a value to the parameter SecondEndpointId in

the function call or it may be under-specified by using the "any of"

wildcard convention. If the SecondEndpointId is underspecified, the second endpoint identifier will be assigned by the gateway and its complete value returned in the SecondEndPointId parameter of the response.

When a SecondEndpointId is specified, the command really creates two connections that can be manipulated separately through

ModifyConnection and DeleteConnection commands. In addition to the ConnectionId and LocalConnectionDescriptor for the first connection, the response to the creation provides a SecondConnectionId parameter that identifies the second connection. The second connection is established in "send/receive" mode.

After receiving a "CreateConnection" request that did not include a RemoteConnectionDescriptor parameter, a gateway is in an ambiguous situation. Because it has exported a LocalConnectionDescriptor parameter, it can potentially receive packets. Because it has not yet received the RemoteConnectionDescriptor parameter of the other gateway, it does not know whether the packets that it receives have been authorized by the Call Agent. It must thus navigate between two risks, i.e., clipping some important announcements or listening to insane data. The behavior of the gateway is determined by the value of the Mode parameter:

* If the mode was set to ReceiveOnly, the gateway MUST accept the media and transmit them through the endpoint.

* If the mode was set to Inactive, Loopback, or Continuity Test, the gateway MUST NOT transmit the media through to the endpoint.

Note that the mode values SendReceive, Conference, SendOnly, Network Loopback and Network Continuity Test do not make sense in this

situation. They MUST be treated as errors, and the command MUST be rejected (error code 527 - missing RemoteConnectionDescriptor, is RECOMMENDED).

The command may optionally contain an encapsulated Notification Request command, which applies to the EndpointId, in which case a RequestIdentifier parameter MUST be present, as well as, optionally, other parameters of the NotificationRequest with the exception of the EndpointId, which is not replicated. The encapsulated

NotificationRequest is executed simultaneously with the creation of the connection. For example, when the Call Agent wants to initiate a call to a residential gateway, it could:

* ask the residential gateway to prepare a connection, in order to be sure that the user can start speaking as soon as the phone goes off hook,

* ask the residential gateway to start ringing,

* ask the residential gateway to notify the Call Agent when the phone goes off-hook.

This can be accomplished in a single CreateConnection command, by also transmitting the RequestedEvents parameters for the off-hook event, and the SignalRequests parameter for the ringing signal.

When these parameters are present, the creation and the

NotificationRequest MUST be synchronized, which means that both MUST be accepted, or both MUST be refused. In our example, the

CreateConnection may be refused if the gateway does not have

sufficient resources, or cannot get adequate resources from the local network access, and the off-hook NotificationRequest can be refused in the glare condition, if the user is already off-hook. In this example, the phone must not ring if the connection cannot be

established, and the connection must not be established if the user is already off-hook.

The NotifiedEntity parameter, if present, defines the new "notified entity" for the endpoint.

The command may carry an encapsulated EndpointConfiguration command, which applies to the EndpointId. When this command is present, the parameters of the EndpointConfiguration command are included with the normal parameters of the CreateConnection with the exception of the EndpointId, which is not replicated. The EndpointConfiguration command may be encapsulated together with an encapsulated

NotificationRequest command. Note that both of these apply to the EndpointId only.

The encapsulated EndpointConfiguration command shares the fate of the CreateConnection command. If the CreateConnection 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.

PackageList is a list of supported packages that MAY be included with error code 518 (unsupported package).