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 event | Corresponding DOM event | DOM Event properties |
| onIncomingMessage | IncomingMessage | Bubbles: No Cancellable: No Context Info: fromURI, msg, cid |
| onContactStatusChange | ContactStatusChange | Bubbles: No Cancellable: No Context Info: remoteURI, present |
| onNewWatcher | NewWatcher | Bubbles: 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.