Extensions to application/oipfCommunicationServices for presence and messaging services

Support in HbbTV

Available since: Not implemented in HbbTV

If a client has indicated support for the control of its presence and messaging functionality by a server by stating <presenceMessaging>true</presenceMessaging> as defined in section 9.3.9 in its capability description, the client SHALL support Communication Services through the use of the following non-visual embedded object:

<object type=”application/oipfCommunicationServices”/>

The presence and messaging API provides for instant messaging, presence and contact list services. The messages can either be in a chat session using MSRP (see [OIPF_PROT2]) or page mode messages sent without a session. The support of presence and messaging SHALL follow the OMA specification [PRES], [IM].

The Communication Services API SHALL be supported in combined OITF and IG deployment cases. 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 onIncomingMessage( String fromURI, String msg, Integer cid )
The function that is called when an incoming chat message is received for the active user. The specified function is called with 3 arguments: · String fromURI – The sender address of the message. · String msg – The text message sent by the remote peer. · Integer cid – Chat session identifier, either the same as one received from the openSession() method or new if session is started by remote peer. Empty identifier if message is sent without a session.
function onContactStatusChange( String remoteURI, Integer state )
This function is called when status has changed for a contact in the contact list or a user used with the method subscribeToStatus(). The specified function is called with two arguments: · String remoteURI – The user address for which the status has changed. · Integer state – Set to 1 if the user is present, and 0 if not. Other values may be defined in the future.
function onNewWatcher( String remoteURI )
This function is called when a remote URI is requesting watcher authorization of the local user’s presentity. The specified function is called with one argument: · String remoteURI – The remote user address which requested watcher authorization.

Methods

Integer openChatSession( String toURI )

Description

Opens a chat session with a remote user.

Returns an integer identifier for the chat session to be used when a message is sent in the chat session or to match when incoming message is received.

Arguments

toURI

The address of the remote chat user.

void sendMessageInSession( Integer cid, String msg )

Description

Sends a new text message in a chat session. The chat can either be started by the user by calling the method openChatSession() or can be a session received in the onIncomingMessage callback function.

Arguments

cid

The chat session identifier.

msg

Text message to send.

void closeChatSession( Integer cid )

Description

Closes a chat session.

Arguments

cid

The chat session identifier.

void sendMessage( String toURI, String msg )

Description

Sends a new text message to a remote peer without starting a session.

Arguments

toURI

The address of the remote chat user.

msg

Text message to send.

void setStatus( Integer state )

Description

Sets the presence state of the local user.

Arguments

state

Set to 1 if the user is present, and 0 if not. Other values may be defined in the future.

void subscribeToStatus( String remoteURI )

Description

Subscribe to status for a remote user.

Arguments

remoteURI

The address of the remote user.

ContactCollection getContacts()

Description

Get the users contact list.

void allowContact( String remoteURI )

Description

Allows the watcher authorization to subscribe to the local user’s presentity.

Arguments

remoteURI

The address of the remote user.

void blockContact( String remoteURI )

Description

Blocks the watcher authorization to subscribe to the local user’s presentity.

Arguments

remoteURI

The address of the remote user.

Boolean createContactList( String contactListUri, ContactCollection contacts )

Description

Creates a contact list.

Arguments

contactListUri

The public user identity or IMPU of the contact list.

contacts

The collection of contact objects representing the members of the list.

ContactCollection getContacts( String contactListUri )

Description

Get the users in the specified contact list.

Arguments

contactListUri

The public user identity or IMPU of the contact list.

Boolean addToContactList( String contactListUri, Contact member )

Description

Updates the specified contact list by adding a new member to that list.

Arguments

contactListUri

The public user identity or IMPU of the contact list to be updated.

member

The new contact to be added to the list.

Boolean removeFromContactList( String contactListUri, Contact member )

Description

Updates the specified contact list by removing specified member from that list.

Arguments

contactListUri

The public user identity or IMPU of the contact list to be updated.

member

The new contact to be removed from the list

Boolean deleteContactList( String contactListUri )

Description

Deletes the specified contact list.

Arguments

contactListUri

The public user identity or IMPU of the contact list to be deleted

void allowAllContacts( String domain )

Description

Allows all watchers belonging to specified domain authorization to subscribe to local user’s presentity. If null, then all contacts will be allowed.

Arguments

domain

Watchers belonging to this domain are authorized to subscribe. If null, then all watchers are authorized to subscribe irrespective of domain.

void blockAllContacts( String domain )

Description

Blocks all watchers belonging to specified domain from subscribing to local user’s presentity. If null, then all contacts will be blocked.

Arguments

domain

Watchers belonging to this domain are denied authorization to subscribe. If null, then all watchers are blocked from subscribing irrespective of domain.

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
onIncomingMessageIncomingMessageBubbles: No Cancellable: No Context Info: fromURI, msg, cid
onContactStatusChangeContactStatusChangeBubbles: No Cancellable: No Context Info: remoteURI, present
onNewWatcherNewWatcherBubbles: No Cancellable: No Context Info: remoteURI

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.