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:

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,
String info )

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:

Value	Description
0	EVENT_INCOMING_CALL: an incoming call is received for the active user
1	EVENT_CALL_PROGRESS: called when the outgoing call is in progress (the request has been received by the remote peer and the local signalling engine is waiting for an answer).
2	EVENT_CALL_RESULT: notifies the result of an outgoing call.
3	EVENT_HANGUP: called when the remote peer hang-up the call.
4	EVENT_SESSION_START: the call session is established and running (media streams can be transmitted and rendered).
5	EVENT_SESSION_END: the call session ended and the related resources are released.
6	EVENT_INCOMING_UPDATE: an incoming update request is received for the active user. (*)
7	EVENT_UPDATE_RESULT: notifies the result of an outgoing update request. (*)
8	EVENT_SESSION_UPDATE: the update of the identified call session is active (e.g.: additional media streams can be transmitted and rendered). (*)
9	EVENT_ERROR: notifies an error event raised during the identified call session.

(*) 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:

Value	Description
0	AUDIO_ONLY: full-duplex voice only call
1	VIDEO_ONLY: full-duplex video only call (*)
2	AUDIO_VIDEO: full-duplex video call (voice + video) (*)

(*) 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.

Value	Description
0	RINGING

EVENT_CALL_RESULT

· cid: call session identifier for the application (Call ID).

· status: the result of an outgoing call. Valid values are:

Value	Description
0	ACCEPT: the call request has been accepted by the remote peer
1	REFUSE: the call request has been refused by the remote peer
2	TIMEOUT: the call request has been refused due to no response by the remote peer
3	BUSY: the remote peer is currently busy
4	ABORT: a general error occurred

· 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:

Value	Description
0	AUDIO_ONLY: full-duplex voice only call
1	VIDEO_ONLY: full-duplex video only call (*)
2	AUDIO_VIDEO: full-duplex video call (voice + video) (*)

(*) 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:

Value	Description
0	AUDIO_ONLY: full-duplex voice only call
1	VIDEO_ONLY: full-duplex video only call
2	AUDIO_VIDEO: full-duplex video call (voice + video)

EVENT_UPDATE_RESULT

· cid: call session identifier for the application (Call ID).

· status: the result of an outgoing call. Valid values are:

Value	Description
0	ACCEPT: the call request has been accepted by the remote peer
1	REFUSE: the call request has been refused by the remote peer
2	TIMEOUT: the call request has been refused due to no response by the remote peer
3	ABORT: a general error occurred

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:

Value	Description
0	ERROR_MEDIA: A media subsystem error
1	ERROR_SIGNALING: A signaling subsystem error

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

Value	Description
0	AUDIO_ONLY: activate a full-duplex voice only call
1	VIDEO_ONLY: activate a video only call (*)
2	AUDIO_VIDEO: activate a full-duplex video call (*)

(*) 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.

Value	Description
0	ANSWER_ACCEPT: Accepts the incoming call
1	ANSWER_REFUSE: Refuses the incoming call
2	ANSWER_TIMEOUT: Refuses the incoming call due to no answer from user
3	ANSWER_BUSY: Refuses the incoming call sending a busy

(*) 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.

Value	Description
0	Audio Capture devices
1	Video Capture devices (*)

(*) 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.

Value	Description
0	Audio Capture devices
1	Video Capture devices (*)

(*) 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.

Value	Description
0	Audio
1	Video (*)

(*) Parameters and values not supported for voice only telephony services

Boolean setPreferredCodecList( Integer streamType,
CodecInfoCollection preferredCodecList )

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.

Value	Description
0	Audio
1	Video (*)

(*) 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.

Parameter name	Description
AUDIO_PAUSE	Audio transmission pause. The parameter can be TRUE or FALSE.
VIDEO_PAUSE	Video transmission pause. The parameter can be TRUE or FALSE. (*)
VIDEO_FPS	Captured video frame per second (*)
VIDEO_SIZE	Captured video size (*) · 176×144 · 352×288 · 640×480
MEDIA_BW	Audio and video (if available) transmission gross bandwidth (Kbps)

(*) 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.

Parameter name	Description
AUDIO_PAUSE	Audio transmission pause. The parameter can be TRUE or FALSE.
VIDEO_PAUSE	Video transmission pause. The parameter can be TRUE or FALSE. (*)
VIDEO_FPS	Captured video frame per second (*)
VIDEO_SIZE	Captured video size (*) · 176×144 · 352×288 · 640×480
MEDIA_BW	Audio and video (if available) transmission gross bandwidth (Kbps)

(*) 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.

Cookie	Duration	Description
cookielawinfo-checkbox-analytics	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Analytics".
cookielawinfo-checkbox-functional	11 months	The cookie is set by GDPR cookie consent to record the user consent for the cookies in the category "Functional".
cookielawinfo-checkbox-necessary	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookies is used to store the user consent for the cookies in the category "Necessary".
cookielawinfo-checkbox-others	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Other.
cookielawinfo-checkbox-performance	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Performance".
viewed_cookie_policy	11 months	The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.

Application Management APIs