The application/oipfCommunicationServices embedded object

Support in HbbTV

Available since: Not implemented in HbbTV

Constants

NameValueUse
STATE_REGISTERED0Specifies that the user has been successfully registered (not subscribed to registration event). This also represents the state when the registration event subscription has been terminated for some reason by network.
STATE_REGISTERED_SUBSCRIPTION_PENDING1Indicates that user is registered successfully but the subscription-state for the registration event indicates a status of “pending”.
STATE_REGISTERED_SUBSCRIPTION_ACTIVE2Specifies that the user has been successfully registered and subscribed to registration event (i.e. subscription-state for registration event indicates a status of “active”).
STATE_DEREGISTERED3Specifies that the user has been successfully deregistered. This can be result of network initiated/locally initiated deregistration request.
STATE_FAILURE4Represents a failure condition.

Properties

function onNotification( String responseHeaders, String msgText, Document msgXML )
This function is called on the application which called subscribeNotification when an unsolicited notification arrives. The application will be notified of all notifications corresponding to any of the subscribed-to feature tags regardless of which application subscribed to it. The specified function is called with 3 arguments. · String responseHeaders – The concatenated list of all HTTP headers, as a single string, with each header line separated by a U+000D (CR) U+000A (LF) pair excluding the status line. In absence of HNI-IGI interface, the responseHeaders will be a concatenated list all SIP headers, as a single string, with each header line separated by a U+000D (CR) U+000A (LF) pair excluding the status line. · String msgText – the response entity body as a string, as defined in the XMLHttpRequest specification as referenced in [OIPF_DAE2_WEB]. · Document msgXML – the response entity body as a Document, as defined in the XMLHttpRequest specification as referenced in [OIPF_DAE2_WEB].

function onNotificationResult( Integer resultMsg )

This function is called with return result from the subscribeNotification method.

This function is not invoked in the case when there is no re-registration as part of subscribeNotification.

The specified function is called with a single argument – resultMsg.

· Integer resultMsg – result message from performing subscribeNotification method.

Result message

Description

Semantics

0

Successful

The action performed by the underlying functionality was successful.

1

Unknown error

The action performed by the underlying functionality failed because an unspecified error occurred.

2

Wrong user credentials

The user credentials was not accepted by the server.

3

The user doesn’t exist.

The user id doesn’t exist in the local user table.

function onRegistrationContextUpdate( String user, Integer state,
Integer errorCode )

This function is called with return result from the methods registerUser and deRegisterUser. In addition, the function is also called whenever there is an update to the registration status of specified user.

The specified function is called with 3 arguments – user, state and errorCode.

· String user – The IMPU of the user.

· Integer state – The current state of the registration as indicated using the constant values defined in section 7.8.1.1.

· Integer errorCode – In case of STATE_FAILED state, provides more information on reason for failure.

errorCode

Description

Semantics

1

Unknown error

The action performed by the underlying functionality failed because an unspecified error occurred.

2

Wrong user credentials

The user credentials were not accepted by the server. The DAE may request from the user a new PIN which can then be used to perform a new registerUser with the provided PIN.

3

The user doesn’t exist.

The user id doesn’t exist in the local user table.

readonly UserData currentUser
The current user property represents the public user identity which is being used or shall be used for HNI-IGI communication. If not set then the default user shall be used or indicated. It shall be set to the default user if a user has not been explicitly set using the setUser() method.

Methods

UserDataCollection getRegisteredUsers()

Description

Return all the users that are currently registered with the IG.

Void registerUser( String userId, String pin )

Description

This method performs user registration to the network.

Results from this method is sent to the callback method onRegistrationContextUpdate.

Arguments

userId

The user identifier represents the public user identity or IMPU.

pin

The pin is optional and carries the password to be used towards the IG in case of HTTP Digest over HNI-IGI interface or SIP Digest if there is no HNI-IGI. If pin is not specified then the default user password shall be used.

The pin used for digest authentication is limited to the HNI-IGI interface with the IG and SHALL NOT impact the HTTP Digest requests from within the DAE application. Support for this parameter is not applicable for non-native HNI-IGI.

void deRegisterUser( String userId )

Description

The indicated user is de-registered. Any sessions that may be open are closed. De-registration of default user has no effect nor de-registration of any users registered from a native application in the OITF.

Results from this method is sent to the callback method onRegistrationContextUpdate.

Arguments

userId

The user identifier represents the public user identity or IMPU.

UserDataCollection getAllUsers()

Description

Return all the users that are currently provisioned in the IG. The first entry in the collection is the default user. The users are retrieved according to [OIPF_PROT2] section 5.4.6.4

Boolean setUser( String userId )

Description

When invoked, any ongoing sessions for the current user shall be closed.

If setUser is unsuccessful due to user not being registered, it is necessary to first register the user and wait for a successful response to the onRegistrationContextUpdate callback function.

If the user gets deregistered (either by the local application or by the network), any ongoing sessions for the user shall be closed .The default user shall be automatically assumed for all services until overridden again by the setUser method.

Argument

userId

The user identifier represents the public user identity or IMPU.

void subscribeNotification( FeatureTagCollection featureTagCollection,
Boolean performUserRegistration )

Description

This method subscribes for new IMS out-of-session dialogues for the indicated application for the currently active user. The notification shall be notified using onNotification callback method.

If the application that made the subscription closes then there is an automatic un-subscription to new notifications. Otherwise it is possible to perform unsubscribeNotification.

Any new dialogues shall be notified over the callback method onNotification.

Arguments

featureTagCollection

The featureTagCollection object of the DAE application. If the value of this argument is NULL then all dialogs SHALL be reported.

performUserRegistration

If this is true a new user registration is required. SHOULD be set to false if it is know that other applications will be registered shortly

This parameter is ignored in the case when the filtering of notifications is done locally. In this case, the initial registration for active user will include all feature tags.

void unsubscribeNotification()

Description

The DAE application calling this method will be de-registered for notifications. Associated feature tag(s) for the DAE application are removed from the featureTagCollection object for the user. A re-registration will be performed for the corresponding user if notifications are not locally filtered.

Results from this method is sent to the callback method onNotificationResult.

Events

For the intrinsic events listed in the table below, a corresponding DOM event SHALL be generated, in the following manner:

Intrinsic eventCorresponding DOM eventDOM Event properties
onNotificationResultNotificationResultBubbles: No Cancellable: No Context Info: resultMsg
onNotificationNotificationBubbles: No Cancellable: No Context Info: callId, contact, from, to
onRegistrationContextUpdateRegistrationContextUpdateBubbles: No Cancellable: No Context Info: user, state, errorCode

Note: these DOM events are 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.