Extensions to application/oipfCommunicationServices for voice telephony services
Support in HbbTV
Available since: Not implemented in HbbTV
If an OITF has indicated support for full-duplex Voice Telephony Services functionality by a server by stating <telephony_services>true</telephony_services>, or
<telephony_services video=”false”>true</telephony_services>, or
<telephony_services video=”true”>true</telephony_services>
as defined in section 9.3.9 in its capability description, the OITF SHALL support IMS through the use of the following non-visual embedded object:
<object type=”application/oipfCommunicationServices”/>
The full-duplex Voice Telephony Services API provides support for managing the setup and life-cycle of a telephony call session. It also provides the methods to manage the capture devices and the list of preferred codecs to be used.
The full-duplex Voice Telephony Services API MAY be supported in the combined OITF and IG deployment cases as well as the separated OITF and IG case. It MAY be supported in other deployment cases. The use of the HNI-IGI interface is OPTIONAL between the OITF and IG when these are co-deployed.
Properties
function onCallEvent( Integer eventType, Integer cid, Integer status, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The function that is called when an event related to the identified call is notified. The specified function is called with four arguments: · Integer eventType – the type of event. Valid values are:
(*) Values not supported for voice only telephony services · Integer cid – call session identifier for the application (Call ID). Call IDs are unique, locally generated positive integer values used to identify a call session. · Integer status – status information on the event. The content depends on the event · String info – text field with additional information. The content depends on the event. The values of the cid, status and info parameters are defined according to the type of event. Any parameters which are unused for an event SHALL have the value undefined. EVENT_INCOMING_CALL · cid: call session identifier for the application (Call ID). · status: call type Identifier. Valid Call Type values are:
(*) Values not supported for voice only telephony services · info: originating URI. The sender address of the call. EVENT_CALL_PROGRESS · cid: call session identifier for the application (Call ID). · status: The type of notification coming from the call in progress. This release provides support for a single value; extensions may be defined in future versions.
EVENT_CALL_RESULT · cid: call session identifier for the application (Call ID). · status: the result of an outgoing call. Valid values are:
· info: if status is equal to 0 (ACCEPT), then the info parameter contains the string representing the value of call type Identifier resulting from the negotiation between the peers. Valid Call Type values are shown in the table below:
(*) Values not supported for voice only telephony services EVENT_HANGUP · cid: call session identifier for the application (Call ID). EVENT_SESSION_START · cid: call session identifier for the application (Call ID). EVENT_SESSION_END · cid: call session identifier for the application (Call ID). EVENT_INCOMING_UPDATE · cid: call session identifier for the application (Call ID). · status: call type Identifier. Valid Call Type values are:
EVENT_UPDATE_RESULT · cid: call session identifier for the application (Call ID). · status: the result of an outgoing call. Valid values are:
EVENT_SESSION_UPDATE · cid: call session identifier for the application (Call ID). EVENT_ERROR · cid: call session identifier for the application (Call ID). · status: the error code of the referenced call. Valid values are:
· info: supplementary textual information for the error identified by the status parameter. |
readonly StringCollection callParameters |
The list of call parameters supported. |
Methods
Integer call( String toURI, Integer callType ) | |||||||||
Description | Opens a telephony session with a remote user. Returns a unique, locally generated, positive integer identifier for the call session (call session ID). Returns null if an error occurred. The current specification provides support for a single active call session only. | ||||||||
Arguments | toURI | The address of the remote user. | |||||||
callType | Valid Call Type values are shown in the table below.
(*) Parameters and values not supported for voice only telephony services |
Boolean answer( Integer cid, Integer response ) | |||||||||||
Description | Answers an incoming call. Returns true if the method is successfully executed; false if an error occurred. | ||||||||||
Arguments | cid | Call session identifier for the application (Call ID). | |||||||||
response | Valid response values are shown in the table below.
(*) Parameters and values not supported for voice only telephony services |
Boolean hangUp( Integer cid ) | ||
Description | Closes a telephony session. Returns true if the method is successfully executed; false if an error occurred. | |
Arguments | cid | Call session identifier for the application (Call ID). |
DeviceInfoCollection getDeviceList( Integer deviceType ) | ||||||||
Description | Returns the list of devices installed on the terminal (or connected) for a specific device type. The device in the first position of the returned list is the default device to be used by the terminal. The position of each device is consistent between method invocations as long as no new devices are connected to the OITF or removed. If an error occurs, the method returns null. | |||||||
Arguments | deviceType | Valid types of device are shown in the table below.
(*) Parameters and values not supported for voice only telephony services |
Boolean setCaptureDevice( Integer deviceType, Integer deviceID ) | ||||||||
Description | Sets the capture device (for a specific device type) that will be used during the call. This method does not affect currently ongoing call sessions. Returns true if the method is successfully executed; false if an error occurred. If the application does not set capture devices (i.e. it does not invoke setCaptureDevice() ) then the devices that will be used for the next call session will be the ones in the first position in the DeviceInfoCollection objects returned by the getDeviceList() method for each device type. | |||||||
Arguments | deviceType | Valid types of device are shown in the table below.
(*) Parameters and values not supported for voice only telephony services | ||||||
deviceID | The specific DeviceInfo object id property (in a DeviceInfoCollection) identifying the capture device that will be used for the call |
CodecInfoCollection getCodecList( Integer streamType ) | ||||||||
Description | Returns the list of codec available on the terminal for a specific stream type. If an error occurs or no codecs are available for the specified stream type, the method returns null. | |||||||
Arguments | streamType | Valid stream type values are shown in the table below.
(*) Parameters and values not supported for voice only telephony services |
Boolean setPreferredCodecList( Integer streamType, | ||||||||
Description | Sets a list of preferred codec to be used in the call setup for a specific stream type. Returns true if the method is successfully executed; false if an error occurred. Invocation of this method does not affect currently ongoing call sessions. | |||||||
Arguments | streamType | Valid stream type values are shown in the table below.
(*) Parameters and values not supported for voice only telephony services | ||||||
preferredCodecList | List of codecs to be used during the call setup negotiation (ordered by preference) |
String getCallParameter( Integer cid, String parameter ) | |||||||||||||
Description | Returns a parameter value for the call session identified by the cid parameter. This method can be invoked before a call session creation or during an ongoing call session. If the cid parameter is null then the retrieved settings will be those that will be applied to the next call sessions that will be created (default for outgoing or incoming call). Returns the value of the parameter or null if an error occurred or the parameter is not supported. | ||||||||||||
Arguments | cid | Call session identifier for the application (Call ID). | |||||||||||
parameter | Mandatory values are shown in the table below. Parameter names are not case sensitive.
(*) Parameters and values not supported for voice only telephony services |
String setCallParameter( Integer cid, String parameter, String value ) | |||||||||||||
Description | Sets parameter value for the call session identified by the cid parameter. This method can be invoked before a call session creation or during an ongoing call session. If cid parameter is defined, then the settings will be applied to the call session identified by this Call ID. If cid parameter is null then the settings will be applied at the next call sessions that will be created (default for outgoing or incoming call). Returns true if the method is successfully executed; false if an error occurred. | ||||||||||||
Arguments | cid | Call session identifier for the application (Call ID). | |||||||||||
parameter | Mandatory values are shown in the table below. Parameter names are not case sensitive.
(*) Parameters and values not supported for voice only telephony services | ||||||||||||
value | The value for the parameter |
Events
For the intrinsic events listed in the table below, a corresponding DOM event SHALL be generated in the following manner:
Intrinsic event | Corresponding DOM event | DOM Event properties |
onCallEvent | CallEvent | Bubbles: No Cancellable: No Context Info: eventType, cid, status, info |
Note: this DOM event is directly dispatched to the event target, and will not bubble nor capture. Applications SHOULD NOT rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM event handlers SHALL call the addEventListener() method on the application/oipfCommunicationServices object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.