MessagePort API

The Message Port API provides the functionality for communicating with other applications.

For more information on the Message Port features, see Message Port Guide.

Since: 2.1

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
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.

Attributes

  • readonly MessagePortManager messageport
    Object representing a exif manager.

    Since: 2.1

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 LocalMessagePort 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 message. */
var localMsgPort = tizen.messageport.requestLocalMessagePort("MessagePortA");
/* Assuming the message port of application with id: "6xaeuflskd.App1" is registered. */
var remoteMsgPort = tizen.messageport.requestRemoteMessagePort("6xaeuflskd.App1", "MessagePortB");
localMsgPort.addMessagePortListener(function(items, remoteport)
{
  /* Do something. */
  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;
  dictionary MessagePortStringDataItem {
    DOMString key;
    StringDataItemValue value;
  };
  dictionary MessagePortByteStreamDataItem {
    DOMString key;
    ByteStreamDataItemValue value;
  };
  Tizen implements MessagePortManagerObject;
  [NoInterfaceObject] interface MessagePortManagerObject {
    readonly attribute MessagePortManager messageport;
  };
  [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);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface MessagePortCallback {
    void onreceived(MessagePortDataItem[] data, RemoteMessagePort? remoteMessagePort);
  };
};
Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
For details, see the Content License.