© 2013 Samsung Electronics Co., Ltd. All rights reserved.
This API provides the communication channel with any client devices which will be attached to Smart TV.
It supports N-Screen service by allowing a client application running on a mobile device (such as mobile phone, tablet and laptop) to communicate with a TV application to synchronize state, exchange data and files. N-Screen service is realized by providing N-Service API allowing TV and other devices to exchange messages.
It can be operated with the Samsung Smart TV manufactured since 2013.
There will be a webapis.nservice object that allows accessing the functionality of the communication among client devices and TV host device.
For more information on the N-Service features, see N-Service Guide.
Interface | Method |
---|---|
WebAPIsNServiceManager | |
NServiceOwnDeviceInfoInit | |
NServiceOwnDeviceInfo | |
NServiceHostInfoInit | |
NServiceHostInfo | |
NServiceDeviceListSuccessCallback | void onsuccess(NServiceDeviceArray devices) |
NServiceDeviceManagerCallback | void ondetected(ManagerEvent event) |
NServiceDeviceCallback | void onreceived(NServiceDeviceEventInfo message) |
NServiceHostConnectSuccessCallback | void onsuccess(NServiceHost host) |
NServiceMessageCallback | void onreceive(DOMString message) |
NServiceGroupSuccessCallback | void onjoin(NServiceDeviceGroup group) |
NServiceFileUploadSuccessCallback | void onuploaded(DOMString filePath) |
ManagerEvent | |
NServiceDeviceEventInfo | |
NServiceDeviceMessageInfo | |
NServiceDeviceGroup | NServiceDeviceArray getMembers() void leave(SuccessCallback onsuccess, ErrorCallback? onerror) |
NServiceHost | void disconnect(SuccessCallback onsuccess, ErrorCallback? onerror) NServiceHostInfo getHostInfo() void uploadFile(DOMString filePath, NServiceFileUploadSuccessCallback onsuccess, ErrorCallback? onerror) void deleteFile(DOMString filePath, SuccessCallback? onsuccess, ErrorCallback? onerror) void registerMessageCallback(NServiceMessageCallback messageCallback) void unregisterMessageCallback() |
NServiceDevice | DOMString getName() unsigned short getType() unsigned short sendMessage(DOMString message) void registerDeviceCallback(NServiceDeviceCallback eventCallback) void unregisterDeviceCallback() |
NServiceManager | boolean setOwnDeviceInfo(NServiceOwnDeviceInfo info) NServiceOwnDeviceInfo? getOwnDeviceInfo() void connectNServiceHost(NServiceHostInfo hostInfo, NServiceHostConnectSuccessCallback onsuccess, ErrorCallback? onerror) void joinGroup(DOMString groupName, NServiceGroupSuccessCallback onsuccess, ErrorCallback? onerror) void getNServiceDevices(NServiceDeviceListSuccessCallback onsuccess, ErrorCallback onerror) unsigned short multicastMessage(DOMString groupID, DOMString message) unsigned short broadcastMessage(DOMString message) unsigned short sendMessageToHost(DOMString message) void registerManagerCallback(NServiceDeviceManagerCallback monitorCallback) |
Array of NServiceDevice object.
typedef sequence<NServiceDeviceNServiceDevice> NServiceDeviceArray;
Indicate the status of N-Service host application.
enum NServiceHostStatus { "RUNNING", "INSTALLING", "LAUNCHING", "UNKNOWN" };
Defines what instantiated in the webapis object is.
[NoInterfaceObject] interface WebAPIsNServiceManager { readonly attribute NServiceManagerNServiceManager nservice; };
WebAPIs implements WebAPIsNServiceManagerWebAPIsNServiceManager;
There will be a webapis.nservice object that allows accessing the functionality of the N-Service module.
Provides specifying own device attributes upon own device information creation.
dictionary NServiceOwnDeviceInfoInit { DOMString deviceID; DOMString deviceName; };
This interface is used to input parameters when own device information is created using the NServiceOwnDeviceInfo constructor.
All the attributes are optional and are undefined by default, unless otherwise stated in the parameter description.
DOMString deviceID
The device identification.
DOMString deviceName
The device name.
It has to be less then 64 characters.
Defines the own device information.
[Constructor (NServiceOwnDeviceInfoInitNServiceOwnDeviceInfoInit init)] interface NServiceOwnDeviceInfo { attribute DOMString deviceID; attribute DOMString vendorID; attribute DOMString deviceName; attribute DOMString productID; };
// Create my own device information var myDeviceInfo = new webapis.NServiceOwnDeviceInfo({ deviceID : "12345", deviceName : "Samsung Mobile", });
DOMString deviceID
The device identification.
This property is the unique identifier for own device.
DOMString vendorID
The vendor identification.
This property is the unique identifier for vendor. It has to be any 8 characters exactly. "MyVendor" is the default value.
DOMString deviceName
The device name.
This property is the description of device. It has to be less then 64 characters.
DOMString productID
The product identification.
This property is the unique identifier for the product. It has to be started with "SMART" and it has to be 8 characters exactly. "SMARTDev" is the default value.
Provides specifying N-Service host device attributes upon N-Service host information creation.
dictionary NServiceHostInfoInit { DOMString ipAddress; DOMString appID; };
This interface is used to input parameters when N-Service host device information is created using the NServiceHostInfo constructor.
All the attributes are optional and are undefined by default, unless otherwise stated in the parameter description.
DOMString ipAddress
The IP address of host application.
IP addresses are canonically represented in dot-decimal notation, which consists of four decimal numbers, each ranging from 0 to 255, separated by dots, e.g., 172.16.254.1. Each part represents a group of 8 bits (octet) of the address. In some cases of technical writing, IP addresses may be presented in various hexadecimal, octal, or binary representations.
DOMString appID
The host application identification.
Defines the N-Service host information which will be connected.
[Constructor (NServiceHostInfoInitNServiceHostInfoInit init)] interface NServiceHostInfo { attribute DOMString ipAddress; attribute unsigned short portNumber; attribute DOMString appID; readonly attribute DOMString? version; readonly attribute DOMString? appName; readonly attribute NServiceHostStatusNServiceHostStatus status; };
// Create N-Service host information var hostInfo = new webapis.NServiceHostInfo({ ipAddress : "192.168.129.2", appID : "sample" });
DOMString ipAddress
The IP address of host application.
IP addresses are canonically represented in dot-decimal notation, which consists of four decimal numbers, each ranging from 0 to 255, separated by dots, e.g., 172.16.254.1. Each part represents a group of 8 bits (octet) of the address. In some cases of technical writing, IP addresses may be presented in various hexadecimal, octal, or binary representations.
unsigned short portNumber
The port number of host application.
It is 80 by default.
DOMString appID
The host application identification.
readonly
DOMString? version
The version information.
If this information had not retrieved from host application yet, null will be returns.
readonly
DOMString? appName
The name of host application.
If this information had not retrieved from host application yet, null will be returns.
readonly
NServiceHostStatus status
The status of host application.
If this information had not retrieved from host application yet, "UNKNOWN" will be returns.
Callback for getting the list of N-Service client devices which are attached.
[Callback=FunctionOnly, NoInterfaceObject] interface NServiceDeviceListSuccessCallback { void onsuccess(NServiceDeviceArrayNServiceDeviceArray devices); };
onsuccess
Method invoked when getting N-Service devices request completes successfully.
void onsuccess(NServiceDeviceArray devices);
Callback for receiving the event when notify a N-Service client device connection or disconnection.
[Callback=FunctionOnly, NoInterfaceObject] interface NServiceDeviceManagerCallback { void ondetected(ManagerEventManagerEvent event); };
ondetected
Method invoked when a N-Service client device is joined or leaved.
void ondetected(ManagerEvent event);
Callback for handling messages from a N-Service client device.
[Callback=FunctionOnly, NoInterfaceObject] interface NServiceDeviceCallback { void onreceived(NServiceDeviceEventInfoNServiceDeviceEventInfo message); };
onreceived
Method invoked when a message is coming from a N-Service client device.
void onreceived(NServiceDeviceEventInfo message);
Callback for connecting the N-Service host application.
[Callback=FunctionOnly, NoInterfaceObject] interface NServiceHostConnectSuccessCallback { void onsuccess(NServiceHostNServiceHost host); };
onsuccess
Method invoked when the host application has been successfully connected.
void onsuccess(NServiceHost host);
Callback for listening the message from the N-Service host.
[Callback=FunctionOnly, NoInterfaceObject] interface NServiceMessageCallback { void onreceive(DOMString message); };
onreceive
Method invoked when a message is arrived to client.
void onreceive(DOMString message);
Callback for joining a group.
[Callback=FunctionOnly, NoInterfaceObject] interface NServiceGroupSuccessCallback { void onjoin(NServiceDeviceGroupNServiceDeviceGroup group); };
onjoin
Method invoked when this device has successfully joined to a group.
void onjoin(NServiceDeviceGroup group);
Callback for notifying when a file has successfully uploaded.
[Callback=FunctionOnly, NoInterfaceObject] interface NServiceFileUploadSuccessCallback { void onuploaded(DOMString filePath); };
onuploaded
Method invoked when the file has successfully uploaded to host application.
void onuploaded(DOMString filePath);
Interface which provides the notification when a N-Service client device is attached or detached.
[NoInterfaceObject] interface ManagerEvent { readonly attribute unsigned short eventType; readonly attribute DOMString deviceName; readonly attribute DOMString uniqueID; };
function managerCallback(event) { switch (event.eventType) { webapis.nservice.MGR_EVENT_DEV_CONNECT: alert(event.deviceName + " with " + event.uniqueID + " joins"); break; webapis.nservice.MGR_EVENT_DEV_DISCONNECT: alert(event.deviceName + " with " + event.uniqueID + " leaves"); break; } } webapis.nservice.registerManagerCallback(managerCallback);
readonly
unsigned short eventType
The event type which specifies whether a client device is connected or disconnected.
The value is the one of below types :
readonly
DOMString deviceName
The name of N-Service client device which sent this event.
The name will be same as 'DeviceName' value of the client device which is connected with N-Service REST API.
readonly
DOMString uniqueID
The unique ID of client device which sent this event.
The name will be same as SLDeviceID value of the client device which is connected with N-Service REST API.
Interface which provides change notification from the connected client device.
[NoInterfaceObject] interface NServiceDeviceEventInfo { readonly attribute unsigned short eventType; readonly attribute (NServiceDeviceMessageInfoNServiceDeviceMessageInfo or NServiceDeviceGroupNServiceDeviceGroup) eventData; };
function deviceListSuccessCB(devices) { function deviceCallback(msg) { switch (msg.eventType) { webapis.nservice.DEV_EVENT_MESSAGE_RECEIVED: alert(msg.eventData.message); break; webapis.nservice.DEV_EVENT_JOINED_GROUP: alert("A device is joined to " + msg.eventData.groupName); break; webapis.nservice.DEV_EVENT_LEFT_GROUP: alert("A device is left from " + msg.eventData.groupName); break; } } // If any N-Service client device is already connected, register a message handler to a device found firstly. if (devices.length > 0) { devices[0].registerDeviceCallback(deviceCallback); } } function errorCB(error) { alert(error.name + " : " + error.message); } webapis.nservice.getNServiceDevices(deviceListSuccessCB, errorCB);
readonly
unsigned short eventType
The message data which is delivered.
The value is the one of below types :
readonly
(NServiceDeviceMessageInfo or NServiceDeviceGroup) eventData
The message data which is delivered.
If the eventType attribute contains webapis.nservice.DEV_EVENT_MESSAGE_RECEIVED value, The type of data attribute will be NServiceDeviceMessageInfo. Otherwise, the type of data attribute will be NServiceDeviceGroup.
Interface which provides message body and context.
[NoInterfaceObject] interface NServiceDeviceMessageInfo { readonly attribute DOMString message; readonly attribute DOMString context; };
This interface will be referred only when a NServiceDeviceEventInfo with webapis.nservice.DEV_EVENT_MESSAGE_RECEIVED eventType is arrived.
function deviceListSuccessCB(devices) { function deviceCallback(msg) { switch (msg.eventType) { webapis.nservice.DEV_EVENT_MESSAGE_RECEIVED: alert(msg.eventData.message); alert(msg.eventData.context); break; } } // If any N-Service client device is already connected, register a message handler to a device found firstly. if (devices.length > 0) { devices[0].registerDeviceCallback(deviceCallback); } } function errorCB(error) { alert(error.name + " : " + error.message); } webapis.nservice.getNServiceDevices(deviceListSuccessCB, errorCB);
readonly
DOMString message
The message body.
readonly
DOMString context
The message context.
Interface which provides group information.
[NoInterfaceObject] interface NServiceDeviceGroup { readonly attribute DOMString groupName; NServiceDeviceArrayNServiceDeviceArray getMembers(); void leave(SuccessCallback onsuccess, optional ErrorCallback? onerror); };
In the host side, this interface will be referred only when a NServiceDeviceEventInfo with webapis.nservice.DEV_EVENT_JOINED_GROUP or webapis.nservice.DEV_EVENT_LEFT_GROUP eventType is incomming.
In the client side, this interface will be referred as the return paramter when invoking webapis.nservice.joinGroup() API.
// when the client devices have been retrieved properly in the host side application. function deviceListSuccessCB(devices) { function deviceCallback(msg) { switch (msg.eventType) { webapis.nservice.DEV_EVENT_JOINED_GROUP: webapis.nservice.DEV_EVENT_LEFT_GROUP: alert(msg.groupName + " group has been changed"); break; } } // If any N-Service client device is already connected, register a message handler to a device found firstly. if (devices.length > 0) { devices[0].registerDeviceCallback(deviceCallback); } } function errorCB(error) { alert(error.name + " : " + error.message); } try { // Invoking API on host side. webapis.nservice.getNServiceDevices(deviceListSuccessCB, errorCB); } catch (err) { if (err.name == "NotSupportedError") { // invoking API on client side // assume that the connection to host has successfully completed. webapis.nservice.joinGroup("alpha", function (group) { console.log("Joining to " + group.groupName + " is complete."); var members = group.getMembers(); // communicate with a group member members[0].sendMessage("Hi!, " + members[0].getName()); // leave the group group.leave(function () { console.log("I leaved the group"); }); } } } }
readonly
DOMString groupName
The group name which any device is joined or left.
getMembers
Get the members of group.
NServiceDeviceArray getMembers();
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
with error type SecurityError, if this functionality is not allowed.
leave
Leave this group.
void leave(SuccessCallback onsuccess, optional ErrorCallback? onerror);
The onerror is launched with these error types:
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
with error type SecurityError, if this functionality is not allowed.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
Interface which provides operations to host application
[NoInterfaceObject] interface NServiceHost { void disconnect(SuccessCallback onsuccess, optional ErrorCallback? onerror); NServiceHostInfoNServiceHostInfo getHostInfo(); void uploadFile(DOMString filePath, NServiceFileUploadSuccessCallbackNServiceFileUploadSuccessCallback onsuccess, optional ErrorCallback? onerror); void deleteFile(DOMString filePath, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror); void registerMessageCallback(NServiceMessageCallbackNServiceMessageCallback messageCallback); void unregisterMessageCallback(); };
var myDeviceInfo = new webapis.NServiceOwnDeviceInfo({ deviceID : "12345", deviceName : "Samsung Mobile", }); var hostInfo = new webapis.NServiceHostInfo({ ipAddress : "192.168.129.2", appID : "sample" }); function onMsgReceived(msg) { console.log("message is arrived : " + msg); }; function connectSCB(host) { var hostInfo = host.getHostInfo(); // Register message listener host.registerMessageCallback(onMsgReceived); }; try { webapis.nservice.setOwnDeviceInfo(myDeviceInfo); webapis.nservice.connectNServiceHost(hostInfo, connectSCB); } catch (err) { console.error(err.name); }
disconnect
Request to disconnect with host.
void disconnect(SuccessCallback onsuccess, optional ErrorCallback? onerror);
The onerror is launched with these error types:
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
with error type SecurityError, if this functionality is not allowed.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
getHostInfo
Get current host application.
NServiceHostInfo getHostInfo();
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
with error type SecurityError, if this functionality is not allowed.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
uploadFile
Upload a file to host.
void uploadFile(DOMString filePath, NServiceFileUploadSuccessCallback onsuccess, optional ErrorCallback? onerror);
An image file (jpeg, png, gif), an audio file (mp3) or a plain text file can be uploaded to host. The uploading file size can't be exceeded over 3MB.
The onerror is launched with these error types:
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
with error type SecurityError, if this functionality is not allowed.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
var myDeviceInfo = new webapis.NServiceOwnDeviceInfo({ deviceID : "12345", deviceName : "Samsung Mobile", }); var hostInfo = new webapis.NServiceHostInfo({ ipAddress : "192.168.129.2", appID : "sample" }); function onUploadSCB(filePath) { console.log("A file is uploaded to " + filePath); }; function connectSCB(host) { var fileObj; // assume that this file object has been set properly. hostObj = host; // Register message listener host.uploadFile(fileObj, onUploadSCB, function (error) { console.errror(error.name); }); }; try { webapis.nservice.setOwnDeviceInfo(myDeviceInfo); webapis.nservice.connectNServiceHost(hostInfo, connectSCB); } catch (err) { console.error(err.name); }
deleteFile
Deletes a uploaded file.
void deleteFile(DOMString filePath, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);
This function attempts to asynchronously delete a file which already uploaded to host application.
The ErrorCallback is launched with these error types:
with error type NotSupportedError, if the feature is not supported. This feature is provided from client side only.
with error type SecurityError, if this functionality is not allowed.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
var myDeviceInfo = new webapis.NServiceOwnDeviceInfo({ deviceID : "12345", deviceName : "Samsung Mobile", }); var hostInfo = new webapis.NServiceHostInfo({ ipAddress : "192.168.129.2", appID : "sample" }); var hostObj = null; function onUploadSCB(filePath) { console.log("A file is uploaded to " + filePath); // delete the uploaded file host.deleteFile(fullPath, function () { console.log("file is successfully deleted"); }, function (err) { console.error(error.name); }); }; function connectSCB(host) { var fileObj; // assume that this file object has been set properly. hostObj = host; // Register message listener host.uploadFile(fileObj, onUploadSCB, function (error) { console.errror(error.name); }); }; try { webapis.nservice.setOwnDeviceInfo(myDeviceInfo); webapis.nservice.connectNServiceHost(hostInfo, connectSCB); } catch (err) { console.error(err.name); }
registerMessageCallback
Register a listener to receive host sent messages.
void registerMessageCallback(NServiceMessageCallback messageCallback);
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
with error type SecurityError, if this functionality is not allowed.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
unregisterMessageCallback
Unregister the message listener.
void unregisterMessageCallback();
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
with error type SecurityError, if this functionality is not allowed.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
Interface which provides transaction operations to the N-Service client device.
[NoInterfaceObject] interface NServiceDevice { DOMString getName(); unsigned short getType(); unsigned short sendMessage(DOMString message); void registerDeviceCallback(NServiceDeviceCallbackNServiceDeviceCallback eventCallback) ; void unregisterDeviceCallback(); };
function deviceListSuccessCB(devices) { // If any N-Service client device is already connected if (devices.length > 0) { // Print out the properties of the N-Service device alert("N-Service client unique ID : " + devices[0].getType()); alert("N-Service client device name : " + devices[0].getName()); } } function errorCB(error) { alert(error.name + " : " + error.message); } webapis.nservice.getNServiceDevices(deviceListSuccessCB, errorCB);
getName
Retrieves the name of N-Service client device.
DOMString getName();
In the host side, DeviceName value of the client device which is connected with N-Service REST API will be returned. Otherwise, SLDeviceID value of the client device will be returned in the client side.
with error type SecurityError, if this functionality is not allowed.
getType
Retrieves the type of N-Service client device.
unsigned short getType();
Only webapis.nservice.DEV_SMART_DEVICE will be returned when retrieving it.
with error type SecurityError, if this functionality is not allowed.
sendMessage
Send a message to the N-Service client device
unsigned short sendMessage(DOMString message);
with error type SecurityError, if this functionality is not allowed.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
function deviceListSuccessCB(devices) { // If any N-Service client device is already connected if (devices.length > 0) { // Send a message to first found device var result = devices[0].sendMessage("greeting! we have made communication channel properly."); if (result == webapis.nservice.ERROR_CODE_ERR) { alert("Error!, the message is not sent properly."); } } } function errorCB(error) { alert(error.name + " : " + error.message); } webapis.nservice.getNServiceDevices(deviceListSuccessCB, errorCB);
registerDeviceCallback
Register a callback function to be invoked when a message comes.
void registerDeviceCallback(NServiceDeviceCallback eventCallback);
with error type NotSupportedError, if this feature is not supported. This feature is provided from host side only.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
function deviceListSuccessCB(devices) { function deviceCallback(msg) { // Handle msg argument here. Refers to the sample code of NServiceDeviceEventInfo } // If any N-Service client device is already connected, register a message handler to a device found firstly. if (devices.length > 0) { devices[0].registerDeviceCallback(deviceCallback); } } function errorCB(error) { alert(error.name + " : " + error.message); } webapis.nservice.getNServiceDevices(deviceListSuccessCB, errorCB);
unregisterDeviceCallback
Unregister the listener for receiving a message from the client device.
void unregisterDeviceCallback();
with error type NotSupportedError, if this feature is not supported. This feature is provided from host side only.
function deviceListSuccessCB(devices) { // If any N-Service client device is already connected, register a message handler to a device found firstly. if (devices.length > 0) { // assume that a device callback of device has been attached. devices[0].unregisterDeviceCallback(); } } function errorCB(error) { alert(error.name + " : " + error.message); } webapis.nservice.getNServiceDevices(deviceListSuccessCB, errorCB);
Interface which provides the N-Service operations.
[NoInterfaceObject] interface NServiceManager { const unsigned short ERROR_CODE_NO_ERR = 0; const unsigned short ERROR_CODE_ERR = 9999; const unsigned short DEV_EVENT_MESSAGE_RECEIVED = 150; const unsigned short DEV_EVENT_JOINED_GROUP = 151; const unsigned short DEV_EVENT_LEFT_GROUP = 152; const unsigned short MGR_EVENT_DEV_CONNECT = 11; const unsigned short MGR_EVENT_DEV_DISCONNECT = 12; const unsigned short MGR_EVENT_DEV_STATUS = 13; const unsigned short DEV_SMART_DEVICE = 33; boolean setOwnDeviceInfo(NServiceOwnDeviceInfoNServiceOwnDeviceInfo info); NServiceOwnDeviceInfoNServiceOwnDeviceInfo? getOwnDeviceInfo(); void connectNServiceHost(NServiceHostInfoNServiceHostInfo hostInfo, NServiceHostConnectSuccessCallbackNServiceHostConnectSuccessCallback onsuccess, optional ErrorCallback? onerror); void joinGroup(DOMString groupName, NServiceGroupSuccessCallbackNServiceGroupSuccessCallback onsuccess, optional ErrorCallback? onerror); void getNServiceDevices(NServiceDeviceListSuccessCallbackNServiceDeviceListSuccessCallback onsuccess, optional ErrorCallback onerror); unsigned short multicastMessage(DOMString groupID, DOMString message); unsigned short broadcastMessage(DOMString message); unsigned short sendMessageToHost(DOMString message); void registerManagerCallback(NServiceDeviceManagerCallbackNServiceDeviceManagerCallback monitorCallback); };
Supported operations are as below:
unsigned short ERROR_CODE_NO_ERR
The identifier when no error occurred on sending message.
unsigned short ERROR_CODE_ERR
The identifier when an error occurred on sending message.
unsigned short DEV_EVENT_MESSAGE_RECEIVED
The identifier for a message received from a N-Service client device.
unsigned short DEV_EVENT_JOINED_GROUP
The identifier for the event when a N-Service client device joined a group.
unsigned short DEV_EVENT_LEFT_GROUP
The identifier for the event when a N-Service client device leaved a group.
unsigned short MGR_EVENT_DEV_CONNECT
The identifier for the event when a N-Service device joins.
unsigned short MGR_EVENT_DEV_DISCONNECT
The identifier for the event when a N-Service device leaves.
unsigned short MGR_EVENT_DEV_STATUS
The identifier for the event when a N-Service device status retrieves.
unsigned short DEV_SMART_DEVICE
The identifier for the device type which are currently connected.
setOwnDeviceInfo
Set own device information
boolean setOwnDeviceInfo(NServiceOwnDeviceInfo info);
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
with error type SecurityError, if this functionality is not allowed.
with error type InvalidValuesError, if the own device information to be set has an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var myDeviceInfo = new webapis.NServiceOwnDeviceInfo({ deviceID : "12345", deviceName : "Samsung Mobile" }); try { webapis.nservice.setOwnDeviceInfo(myDeviceInfo); } catch (err) { console.error(err.name); }
getOwnDeviceInfo
Get the own device information
NServiceOwnDeviceInfo? getOwnDeviceInfo();
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
try { var myInfo = webapis.nservice.getOwnDeviceInfo(); if (myInfo == null) { console.log("own device information is not set yet."); } } catch (err) { console.error(err.name); }
connectNServiceHost
Connect to N-Service host application. N-Screen supports a client application to connect to only one host(TV) at a time.
void connectNServiceHost(NServiceHostInfo hostInfo, NServiceHostConnectSuccessCallback onsuccess, optional ErrorCallback? onerror);
The onerror is launched with these error types:
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
with error type InvalidStateError, if client side tries to connect to other host before disconnecting previous connection.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
joinGroup
Join a specific group.
void joinGroup(DOMString groupName, NServiceGroupSuccessCallback onsuccess, optional ErrorCallback? onerror);
If there is no such a group available, the group will be automatically created and joined.
The onerror is launched with these error types:
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
getNServiceDevices
Request to get N-Service client devices which are currently connected.
void getNServiceDevices(NServiceDeviceListSuccessCallback onsuccess, optional ErrorCallback onerror);
The error callback is launched with these error types:
with error type NotSupportedError, if this feature is not supported. This feature is provided from host side only.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
function deviceListSuccessCB(devices) { alert (devices.length + " devices are connected"); } function errorCB(error) { alert(error.name + " : " + error.message); } try { webapis.nservice.getNServiceDevices(deviceListSuccessCB, errorCB); } catch (err) { if (err.name == "NotSupportedError") { console.errror("getNServiceDevices() is not supported in this device. "); } }
multicastMessage
Multicasts a message to N-Service client devices which joined the same group.
unsigned short multicastMessage(DOMString groupID, DOMString message);
with error type SecurityError, if this functionality is not allowed.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
// In the client side, assume that the connection with host has been completed. var result = webapis.nservice.multicastMessage("group1", "Welcome to members of group 1!"); if (result == webapis.nservice.ERROR_CODE_ERR) { alert("multi-casting a message failed to group1."); }
broadcastMessage
Broadcast a message to all client devices.
unsigned short broadcastMessage(DOMString message);
with error type NotSupportedError, if this feature is not supported. This feature is provided from host side only.
with error type SecurityError, if this functionality is not allowed.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
var result = webapis.nservice.broadcastMessage("Welcome everyone!"); if (result == webapis.nservice.ERROR_CODE_ERR) { alert("Broadcasting a message failed."); }
sendMessageToHost
Send a message to host device.
unsigned short sendMessageToHost(DOMString message);
with error type NotSupportedError, if this feature is not supported. This feature is provided from client side only.
with error type SecurityError, if this functionality is not allowed.
with error type InvalidStateError, if the connection between the client and the host is not established, or is invalid.
// Assume that the connection with host has been completed. var result = webapis.nservice.sendMessageHost("Welcome everyone!"); if (result == webapis.nservice.ERROR_CODE_ERR) { alert("Sending a message to TV is failed."); }
registerManagerCallback
Register the listener callback which will be invoked when a N-Service client device joined or leaved.
void registerManagerCallback(NServiceDeviceManagerCallback monitorCallback);
with error type NotSupportedError, if this feature is not supported. This feature is provided from host side only.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
function managerCallback(event) { switch (event.eventType) { webapis.nservice.MGR_EVENT_DEV_CONNECT: alert(event.name + " with " + event.uniqueID + " joins"); break; webapis.nservice.MGR_EVENT_DEV_DISCONNECT: alert(event.name + " with " + event.uniqueID + " leaves"); break; } } webapis.nservice.registerManagerCallback(managerCallback);
module NService { typedef sequence<NServiceDeviceNServiceDevice> NServiceDeviceArray; enum NServiceHostStatus { "RUNNING", "INSTALLING", "LAUNCHING", "UNKNOWN" }; [NoInterfaceObject] interface WebAPIsNServiceManager { readonly attribute NServiceManagerNServiceManager nservice; }; WebAPIs implements WebAPIsNServiceManagerWebAPIsNServiceManager; dictionary NServiceOwnDeviceInfoInit { DOMString deviceID; DOMString deviceName; }; [Constructor (NServiceOwnDeviceInfoInitNServiceOwnDeviceInfoInit init)] interface NServiceOwnDeviceInfo { attribute DOMString deviceID; attribute DOMString vendorID; attribute DOMString deviceName; attribute DOMString productID; }; dictionary NServiceHostInfoInit { DOMString ipAddress; DOMString appID; }; [Constructor (NServiceHostInfoInitNServiceHostInfoInit init)] interface NServiceHostInfo { attribute DOMString ipAddress; attribute unsigned short portNumber; attribute DOMString appID; readonly attribute DOMString? version; readonly attribute DOMString? appName; readonly attribute NServiceHostStatusNServiceHostStatus status; }; [Callback=FunctionOnly, NoInterfaceObject] interface NServiceDeviceListSuccessCallback { void onsuccess(NServiceDeviceArrayNServiceDeviceArray devices); }; [Callback=FunctionOnly, NoInterfaceObject] interface NServiceDeviceManagerCallback { void ondetected(ManagerEventManagerEvent event); }; [Callback=FunctionOnly, NoInterfaceObject] interface NServiceDeviceCallback { void onreceived(NServiceDeviceEventInfoNServiceDeviceEventInfo message); }; [Callback=FunctionOnly, NoInterfaceObject] interface NServiceHostConnectSuccessCallback { void onsuccess(NServiceHostNServiceHost host); }; [Callback=FunctionOnly, NoInterfaceObject] interface NServiceMessageCallback { void onreceive(DOMString message); }; [Callback=FunctionOnly, NoInterfaceObject] interface NServiceGroupSuccessCallback { void onjoin(NServiceDeviceGroupNServiceDeviceGroup group); }; [Callback=FunctionOnly, NoInterfaceObject] interface NServiceFileUploadSuccessCallback { void onuploaded(DOMString filePath); }; [NoInterfaceObject] interface ManagerEvent { readonly attribute unsigned short eventType; readonly attribute DOMString deviceName; readonly attribute DOMString uniqueID; }; [NoInterfaceObject] interface NServiceDeviceEventInfo { readonly attribute unsigned short eventType; readonly attribute (NServiceDeviceMessageInfoNServiceDeviceMessageInfo or NServiceDeviceGroupNServiceDeviceGroup) eventData; }; [NoInterfaceObject] interface NServiceDeviceMessageInfo { readonly attribute DOMString message; readonly attribute DOMString context; }; [NoInterfaceObject] interface NServiceDeviceGroup { readonly attribute DOMString groupName; NServiceDeviceArrayNServiceDeviceArray getMembers(); void leave(SuccessCallback onsuccess, optional ErrorCallback? onerror); }; [NoInterfaceObject] interface NServiceHost { void disconnect(SuccessCallback onsuccess, optional ErrorCallback? onerror); NServiceHostInfoNServiceHostInfo getHostInfo(); void uploadFile(DOMString filePath, NServiceFileUploadSuccessCallbackNServiceFileUploadSuccessCallback onsuccess, optional ErrorCallback? onerror); void deleteFile(DOMString filePath, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror); void registerMessageCallback(NServiceMessageCallbackNServiceMessageCallback messageCallback); void unregisterMessageCallback(); }; [NoInterfaceObject] interface NServiceDevice { DOMString getName(); unsigned short getType(); unsigned short sendMessage(DOMString message); void registerDeviceCallback(NServiceDeviceCallbackNServiceDeviceCallback eventCallback) ; void unregisterDeviceCallback(); }; [NoInterfaceObject] interface NServiceManager { const unsigned short ERROR_CODE_NO_ERR = 0; const unsigned short ERROR_CODE_ERR = 9999; const unsigned short DEV_EVENT_MESSAGE_RECEIVED = 150; const unsigned short DEV_EVENT_JOINED_GROUP = 151; const unsigned short DEV_EVENT_LEFT_GROUP = 152; const unsigned short MGR_EVENT_DEV_CONNECT = 11; const unsigned short MGR_EVENT_DEV_DISCONNECT = 12; const unsigned short MGR_EVENT_DEV_STATUS = 13; const unsigned short DEV_SMART_DEVICE = 33; boolean setOwnDeviceInfo(NServiceOwnDeviceInfoNServiceOwnDeviceInfo info); NServiceOwnDeviceInfoNServiceOwnDeviceInfo? getOwnDeviceInfo(); void connectNServiceHost(NServiceHostInfoNServiceHostInfo hostInfo, NServiceHostConnectSuccessCallbackNServiceHostConnectSuccessCallback onsuccess, optional ErrorCallback? onerror); void joinGroup(DOMString groupName, NServiceGroupSuccessCallbackNServiceGroupSuccessCallback onsuccess, optional ErrorCallback? onerror); void getNServiceDevices(NServiceDeviceListSuccessCallbackNServiceDeviceListSuccessCallback onsuccess, optional ErrorCallback onerror); unsigned short multicastMessage(DOMString groupID, DOMString message); unsigned short broadcastMessage(DOMString message); unsigned short sendMessageToHost(DOMString message); void registerManagerCallback(NServiceDeviceManagerCallbackNServiceDeviceManagerCallback monitorCallback); }; };