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 | long addMessagePortListener (MessagePortCallback listener) 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);
};
};