Samsung Electronics logo

Samsung Web API: MessagePort

© 2014 Samsung Electronics Co., Ltd. All rights reserved.

Introduction

This API provides the functionality for communicating with other applications.

Table of Contents

Summary of Interfaces and Methods

Interface Method
MessagePortManagerObject
MessagePortManager LocalMessagePort requestLocalMessagePort(DOMString localMessagePortName)
LocalMessagePort requestTrustedLocalMessagePort(DOMString localMessagePortName)
RemoteMessagePort requestRemoteMessagePort(ApplicationId appId, DOMString remoteMessagePortName)
RemoteMessagePort requestTrustedRemoteMessagePort(ApplicationId appId, DOMString remoteMessagePortName)
LocalMessagePort long addMessagePortListener(MessagePortCallback listener)
void removeMessagePortListener(long watchId)
RemoteMessagePort void sendMessage(MessagePortDataItem[] data, LocalMessagePort? localMessagePort)
MessagePortDataItem
MessagePortCallback void onreceived(MessagePortDataItem[] data, RemoteMessagePort? remoteMessagePort)

1. Interfaces

1.1. MessagePortManagerObject

The MessagePortManagerObject interface defines what is instantiated by the WebAPIs object. 

  [NoInterfaceObject] interface MessagePortManagerObject {
    readonly attribute MessagePortManager messageport;
  };
  WebAPIs implements MessagePortManagerObject;

There is a webapis.messageport object that allows access to the functionality of the Message Port API.

1.2. MessagePortManager

The MessagePortManager interface provides methods to request message port to communicate. 

  [NoInterfaceObject] interface MessagePortManager {

    LocalMessagePort requestLocalMessagePort(DOMString localMessagePortName) raises(WebAPIException);

    LocalMessagePort requestTrustedLocalMessagePort(DOMString localMessagePortName) raises(WebAPIException);

    RemoteMessagePort requestRemoteMessagePort(ApplicationId appId, DOMString remoteMessagePortName) raises(WebAPIException);

    RemoteMessagePort requestTrustedRemoteMessagePort(ApplicationId appId, DOMString remoteMessagePortName) raises(WebAPIException);
  };

METHODS

requestLocalMessagePort

Requests a LocalMessage Port instance to start receiving message from another application.

Signature
LocalMessagePort requestLocalMessagePort(DOMString localMessagePortName);
Parameters
  • localMessagePortName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The name of the local message port to retrieve.
      The LocalMessagePort instances are identical for the same message port name.
Return value
LocalMessagePort The LocalMessagePort instance.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type InvalidValuesError, if the input parameter contains an invalid value.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

Code example
 // Requests the LocalMessagePort instance with the specified message port name
 var localMsgPort = webapis.messageport.requestLocalMessagePort('MessagePortA');

requestTrustedLocalMessagePort

Requests a trusted LocalMessagePort instance to receive message from another application.

Signature
LocalMessagePort requestTrustedLocalMessagePort(DOMString localMessagePortName);

Trusted local message port can communicate with applications that are signed with same certificate.

Parameters
  • localMessagePortName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The name of local message port.
      The LocalMessagePort instances are identical for the same message port name.
Return value
LocalMessagePort The trusted LocalMessagePort instance.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type InvalidValuesError, if the input parameter contains an invalid value.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

Code example
 // Requests the LocalMessagePort instance with the specified message port name
 var localMsgPort = webapis.messageport.requestTrustedLocalMessagePort('MessagePortB');

requestRemoteMessagePort

Requests a RemoteMessagePort instance to send message to another application.

Signature
RemoteMessagePort requestRemoteMessagePort(ApplicationId appId, DOMString remoteMessagePortName);

If the message port name and application ID is the same, the platform returns the same RemoteMessagePort instance.

Parameters
  • appId
    • Optional: No.
    • Nullable: No.
    • Type: ApplicationId.
    • Description: The ID of the application to send messages.
  • remoteMessagePortName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The name of remote message port.
Return value
RemoteMessagePort The RemoteMessagePort instance.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type NotFoundError, if the port of the target application is not found.

    with error type InvalidValuesError, if an input parameter contains an invalid value.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

Code example
 // Requests the RemoteMessagePort instance with the specified message port name
 var remoteMsgPort = webapis.messageport.requestRemoteMessagePort('6xaeuflskd.App1', 'MessagePortA');

requestTrustedRemoteMessagePort

Requests a trusted RemoteMessagePort instance to receive message from another application.

Signature
RemoteMessagePort requestTrustedRemoteMessagePort(ApplicationId appId, DOMString remoteMessagePortName);

If the message port name and application ID is the same, the platform returns the same RemoteMessagePort instance. Trusted remote message port can communicate with applications that are signed with same certificate.

Parameters
  • appId
    • Optional: No.
    • Nullable: No.
    • Type: ApplicationId.
    • Description: The ID of the application to send messages.
  • remoteMessagePortName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The name of remote message port.
Return value
RemoteMessagePort The trusted RemoteMessagePort instance.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs

    with error type InvalidAccessError, if the target application is not signed with the same certification.

    with error type NotFoundError, if the port of the target application is not found.

    with error type InvalidValuesError, if an input parameter contains an invalid value.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

Code example
 // Requests the RemoteMessagePort instance with the specified message port name.
 var remoteMsgPort = webapis.messageport.requestTrustedRemoteMessagePort('6xauflskd.App1', 'MessagePortB');

1.3. LocalMessagePort

The LocalMessagePort interface provides methods to receive data. 

  [NoInterfaceObject] interface LocalMessagePort {

    readonly attribute DOMString messagePortName;

    readonly attribute boolean isTrusted;

    long addMessagePortListener(MessagePortCallback listener) raises(WebAPIException);

    void removeMessagePortListener(long watchId) raises(WebAPIException);
  };

ATTRIBUTES

readonly DOMString messagePortName

An attribute that stores the name of the message port name.

This attribute is read-only.

readonly boolean isTrusted

An attribute that determines whether the message port is trusted or not.

This attribute is read-only.

METHODS

addMessagePortListener

Adds a message port listener to receive messages from other applications.

Signature
long addMessagePortListener(MessagePortCallback listener);
Parameters
  • listener
    • Optional: No.
    • Nullable: No.
    • Type: MessagePortCallback.
    • Description: The method to invoke when a message is received.
Return value
long ID of the listener that is later used to remove the listener.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type InvalidValuesError, if the input parameter contains an invalid value.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

Code example
 function onreceived(data, remoteMsgPort) {
   console.log('Received data to \'' + remoteMsgPort.messagePortName + '\'');
 }

 var localMsgPort = webapis.messageport.requestLocalMessagePort('MessagePortA');
 var watchId = localMsgPort.addMessagePortListener(onreceived);

removeMessagePortListener

Removes the message port listener.

Signature
void removeMessagePortListener(long watchId);
Parameters
  • watchId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: ID to identify the listener.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type NotFoundError, if the watch ID has not been found.

    with error type InvalidValuesError, if the input parameter contains an invalid value.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

Code example
 var localMsgPort = webapis.messageport.requestLocalMessagePort('MessagePortA');
 var watchId = localMsgPort.addMessagePortListener(onreceived);
 // Communication routines of your app...
 localMsgPort.removeMessagePortListener(watchId);

1.4. RemoteMessagePort

The RemoteMessagePort interface provides methods to send messages. 

  [NoInterfaceObject] interface RemoteMessagePort {

    readonly attribute DOMString messagePortName;

    readonly attribute ApplicationId appId;

    readonly attribute boolean isTrusted;

    void sendMessage(MessagePortDataItem[] data, optional LocalMessagePort? localMessagePort) raises(WebAPIException);
  };

ATTRIBUTES

readonly DOMString messagePortName

An attribute to store the message port name.

This attribute is read-only.

readonly ApplicationId appId

An attribute that store the application ID to connect with.

This attribute is read-only.

readonly boolean isTrusted

An attribute that determines whether the message port is trusted or not.

This attribute is read-only.

METHODS

sendMessage

Sends messages to the specified application.

Signature
void sendMessage(MessagePortDataItem[] data, optional LocalMessagePort? localMessagePort);

The sent messages will be ignored without any notice, unless the target application added one or more listeners to the target local message port.

Parameters
  • data
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Data array of data to send.
  • localMessagePort
    • Optional: Yes.
    • Nullable: Yes.
    • Type: LocalMessagePort.
    • Description: LocalMessagePort object that gives local message port of the current application. It can be used to receive reply messages from the other end of the message port. The order of items in this array is not guaranteed to be preserved during data transfer, and values of key within this array must not be duplicated or empty.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type QuotaExceededError, if the size of message has exceeded the maximum limit.

    with error type InvalidValuesError, if an input parameter contains an invalid value.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

Code example
 // Sends message
 var localMsgPort = webapis.messageport.requestLocalMessagePort('MessagePortA');
 var remoteMsgPort = webapis.messageport.requestRemoteMessagePort('6xaeuflskd.App1', 'MessagePortB');
 localMsgPort.addMessagePortListener(function(items, remoteport) {
   // ...
   if(remoteport !== null) {
     remoteport.sendMessage([{key:'RESULT', value:'OK'}]);
   }
 });
 remoteMsgPort.sendMessage(
   [
     { key:'CMD', value:'openWindow' },
     { key:'OPTION', value:'bx' }
   ]
   , localMsgPort);

1.5. MessagePortDataItem

A dictionary for specifying the data item that is transferred. 

  dictionary MessagePortDataItem {
    DOMString key;
    DOMString value;
  };

1.6. MessagePortCallback

This interface defines notification callbacks for receiving data from other applications. 

  [Callback=FunctionOnly, NoInterfaceObject] interface MessagePortCallback {
    void onreceived(MessagePortDataItem[] data, RemoteMessagePort? remoteMessagePort);
  };

METHODS

onreceived

Called when data is received from other applications via the specified message port name.

Signature
void onreceived(MessagePortDataItem[] data, RemoteMessagePort? remoteMessagePort);
Parameters
  • data
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: An array of data received from another application.
  • remoteMessagePort
    • Optional: No.
    • Nullable: Yes.
    • Type: RemoteMessagePort.
    • Description: The RemoteMessagePort port that can be used to reply for the received message.

2. Full WebIDL 

module MessagePort {

  [NoInterfaceObject] interface MessagePortManagerObject {
    readonly attribute MessagePortManager messageport;
  };
  WebAPIs implements MessagePortManagerObject;

  [NoInterfaceObject] interface MessagePortManager {

    LocalMessagePort requestLocalMessagePort(DOMString localMessagePortName) raises(WebAPIException);

    LocalMessagePort requestTrustedLocalMessagePort(DOMString localMessagePortName) raises(WebAPIException);

    RemoteMessagePort requestRemoteMessagePort(ApplicationId appId, DOMString remoteMessagePortName) raises(WebAPIException);

    RemoteMessagePort requestTrustedRemoteMessagePort(ApplicationId appId, DOMString remoteMessagePortName) raises(WebAPIException);
  };

  [NoInterfaceObject] interface LocalMessagePort {

    readonly attribute DOMString messagePortName;

    readonly attribute boolean isTrusted;

    long addMessagePortListener(MessagePortCallback listener) raises(WebAPIException);

    void removeMessagePortListener(long watchId) raises(WebAPIException);
  };

  [NoInterfaceObject] interface RemoteMessagePort {

    readonly attribute DOMString messagePortName;

    readonly attribute ApplicationId appId;

    readonly attribute boolean isTrusted;

    void sendMessage(MessagePortDataItem[] data, optional LocalMessagePort? localMessagePort) raises(WebAPIException);
  };

  dictionary MessagePortDataItem {
    DOMString key;
    DOMString value;
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface MessagePortCallback {
    void onreceived(MessagePortDataItem[] data, RemoteMessagePort? remoteMessagePort);
  };
};