MessagePort API

The MessagePort API provides the functionality for communicating with other applications.

For more information on the MessagePort features, see MessagePort Guide.

Since: 2.1

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
void removeMessagePortListener (long watchId)
RemoteMessagePort
void sendMessage (MessagePortDataItem[] data, optional LocalMessagePort? localMessagePort)
MessagePortStringDataItem
MessagePortByteStreamDataItem
MessagePortCallback
void onreceived (MessagePortDataItem[] data, RemoteMessagePort? remoteMessagePort)

1. Type Definitions

1.1. ByteStream

The byte stream. 
  typedef octet[] ByteStream;

Since: 3.0

1.2. StringDataItemValue

The string data item value, which can either be a DOMString or a DOMString array. 
  typedef (DOMString or DOMString[]) StringDataItemValue;

Since: 3.0

1.3. ByteStreamDataItemValue

The byte stream data item value, which can either be a ByteStream or a ByteStream array. 
  typedef (ByteStream or ByteStream[]) ByteStreamDataItemValue;

Since: 3.0

1.4. MessagePortDataItem

The data item value identifier, which can either be a MessagePortStringDataItem or a MessagePortByteStreamDataItem. 
  typedef (MessagePortStringDataItem or MessagePortByteStreamDataItem) MessagePortDataItem;

Since: 3.0

2. Interfaces

2.1. MessagePortManagerObject

The MessagePortManagerObject interface defines what is instantiated by the Tizen object from the Tizen Platform. 
  [NoInterfaceObject] interface MessagePortManagerObject {
    readonly attribute MessagePortManager messageport;
  };
  Tizen implements MessagePortManagerObject;

Since: 2.1

The tizen.messageport object allows access to the functionality of the Message Port API.

2.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);
  };

Since: 2.1

Methods

requestLocalMessagePort
Requests a LocalMessage Port instance to start receiving message from another application. 
LocalMessagePort requestLocalMessagePort(DOMString localMessagePortName);

Since: 2.1

Parameters:

  • localMessagePortName: Name of the local message port to retrieve
    The LocalMessagePort instances are identical for the same message port name.

Return value:

LocalMessagePort LocalMessagePort instance

Exceptions:

  • WebAPIException

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

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

    • with error type UnknownError, if any other error occurs.

Code example:

 // Requests the LocalMessagePort instance with the specified message port name
 var localMsgPort = tizen.messageport.requestLocalMessagePort('MessagePortA');
requestTrustedLocalMessagePort
Requests a trusted LocalMessagePort instance to receive message from another application. 
LocalMessagePort requestTrustedLocalMessagePort(DOMString localMessagePortName);

Since: 2.1

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

Parameters:

  • localMessagePortName: Name of local message port
    The LocalMessagePort instances are identical for the same message port name.

Return value:

LocalMessagePort Trusted LocalMessagePort instance

Exceptions:

  • WebAPIException

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

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

    • with error type UnknownError, if any other error occurs.

Code example:

 // Requests the LocalMessagePort instance with the specified message port name
 var localMsgPort = tizen.messageport.requestTrustedLocalMessagePort('MessagePortB');
requestRemoteMessagePort
Requests a RemoteMessagePort instance to send message to another application. 
RemoteMessagePort requestRemoteMessagePort(ApplicationId appId, DOMString remoteMessagePortName);

Since: 2.1

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

Parameters:

  • appId: ID of the application to send messages
  • remoteMessagePortName: Name of remote message port

Return value:

RemoteMessagePort RemoteMessagePort instance

Exceptions:

  • WebAPIException

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

    • with error type UnknownError, if any other error occurs.

Code example:

 // Requests the RemoteMessagePort instance with the specified message port name
 var remoteMsgPort = tizen.messageport.requestRemoteMessagePort('6xaeuflskd.App1', 'MessagePortA');
requestTrustedRemoteMessagePort
Requests a trusted RemoteMessagePort instance to receive message from another application. 
RemoteMessagePort requestTrustedRemoteMessagePort(ApplicationId appId, DOMString remoteMessagePortName);

Since: 2.1

If the message port name and application ID are 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: ID of the application to send messages
  • remoteMessagePortName: Name of remote message port

Return value:

RemoteMessagePort Trusted RemoteMessagePort instance

Exceptions:

  • WebAPIException

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

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

    • with error type UnknownError, if any other error occurs

Code example:

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

2.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);
  };

Since: 2.1

Attributes

  • readonly DOMString messagePortName
    The name of the message port name.

    Since: 2.1

  • readonly boolean isTrusted
    The flag indicating whether the message port is trusted.

    Since: 2.1

Methods

addMessagePortListener
Adds a message port listener to receive messages from other applications. 
long addMessagePortListener(MessagePortCallback listener);

Since: 2.1

Parameters:

  • listener: Callback function that is called 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 TypeMismatchError, if the input parameter is not compatible with the expected type.

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

    • with error type UnknownError, if any other error occurs.

Code example:

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

 var localMsgPort = tizen.messageport.requestLocalMessagePort('MessagePortA');
 var watchId = localMsgPort.addMessagePortListener(onreceived);
removeMessagePortListener
Removes the message port listener. 
void removeMessagePortListener(long watchId);

Since: 2.1

Parameters:

  • watchId: ID to identify the listener

Exceptions:

  • WebAPIException

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

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

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

    • with error type UnknownError, if any other error occurs.

Code example:

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

2.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);
  };

Since: 2.1

Attributes

  • readonly DOMString messagePortName
    The message port name.

    Since: 2.1

  • readonly ApplicationId appId
    The application ID to connect with.

    Since: 2.1

  • readonly boolean isTrusted
    The flag indicating whether the message port is trusted.

    Since: 2.1

Methods

sendMessage
Sends messages to the specified application. 
void sendMessage(MessagePortDataItem[] data, optional LocalMessagePort? localMessagePort);

Since: 2.1

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: Array of data to send
  • localMessagePort [optional] [nullable]: 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 TypeMismatchError, if the input parameter is not compatible with the expected type.

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

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

    • with error type UnknownError, if any other error occurs.

Code example:

 // Sends string message
 var localMsgPort = tizen.messageport.requestLocalMessagePort('MessagePortA');
 var remoteMsgPort = tizen.messageport.requestRemoteMessagePort('6xaeuflskd.App1', 'MessagePortB');
 localMsgPort.addMessagePortListener(function(items, remoteport) {
   // ...
   if(remoteport !== null) {
     remoteport.sendMessage([{key:'RESULT', value:'OK'}]);
   }
 });
 // stream - FileStream object
 var bytePockets = [], byteCount = 0, i = 0;
 while(byteCount  stream.bytesAvailable - 256) {
   bytePockets[i] = stream.readBytes(256);
   byteCount+=256;
   i++;
 }
 bytePockets[i] = stream.readBytes(stream.bytesAvailable - byteCount);

 var messagePortPockets = [{key: "key1", value: "val1"},
                        {key: "key2", value: ["val2", "val3", "val4"]},
                        {key: "key3", value: bytePockets[0]},
                        {key: "key4", value: bytePockets}];
 remoteMsgPort.sendMessage(messagePortPockets, localMsgPort);

2.5. MessagePortStringDataItem

The dictionary that specifies the string data item that is transferred. 
  dictionary MessagePortStringDataItem {
    DOMString key;
    StringDataItemValue value;
  };

Since: 3.0

2.6. MessagePortByteStreamDataItem

The dictionary that specifies the byte stream data item that is transferred. 
  dictionary MessagePortByteStreamDataItem {
    DOMString key;
    ByteStreamDataItemValue value;
  };

Since: 3.0

2.7. MessagePortCallback

The MessagePortCallback interface defines notification callbacks for receiving data from other applications. 
  [Callback=FunctionOnly, NoInterfaceObject] interface MessagePortCallback {
    void onreceived(MessagePortDataItem[] data, RemoteMessagePort? remoteMessagePort);
  };

Since: 2.1

Methods

onreceived
Called when data is received from other applications via the specified message port name. 
void onreceived(MessagePortDataItem[] data, RemoteMessagePort? remoteMessagePort);

Since: 2.1

Parameters:

  • data: Array of data received from another application
  • remoteMessagePort [nullable]: RemoteMessagePort port that can be used to reply for the received message

Code example:

 // MessagePortCallback instance
 function onreceived(data, remoteMsgPort) {
   console.log('Received data to \'' + remoteMsgPort.messagePortName + '\'');
 }

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

3. Full WebIDL

module MessagePort {

  typedef octet[] ByteStream;
  typedef (DOMString or DOMString[]) StringDataItemValue;
  typedef (ByteStream or ByteStream[]) ByteStreamDataItemValue;
  typedef (MessagePortStringDataItem or MessagePortByteStreamDataItem) MessagePortDataItem;

  [NoInterfaceObject] interface MessagePortManagerObject {
    readonly attribute MessagePortManager messageport;
  };
  Tizen 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 MessagePortStringDataItem {
    DOMString key;
    StringDataItemValue value;
  };
  dictionary MessagePortByteStreamDataItem {
    DOMString key;
    ByteStreamDataItemValue value;
  };

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