Samsung Electronics logo

Samsung Web API: ChordService


Introduction

This API provides application developers with a simple, high-level set of APIs that can be used to build new exciting distributed applications. The Chord SDK intends to make a development environment easier, by providing simple APIs.

  • UDP broadcast based discovery
  • TCP/IP based protocol stack for Peer-to-Peer communication
  • Allows group creation and management using the concept of the channel.
  • Supports user defined data and file transfer to a particular node or all nodes in the same channel.
  • Provides reliable data path for peers to communicate.

Each Chord node sends a UDP broadcast message about once a second and parses broadcast messages from other nodes. The UDP broadcast messages are handled on the Chord internally. Using UDP broadcast messages, all Wi-Fi nodes located in the same subnet can be discovered. The UDP Broadcast was chosen instead of multicast after extensive testing on public Wi-Fi networks in coffee shops, airports and other public places. The result was that a large number of public networks did not support UDP multicast but broadcast was supported in majority of the places.

The channel is the key concept of the Chord. The channel is a logical grouping of nodes that makes communication possible. Nodes that join to a channel can communicate within the same channel. Nodes that do not join to a channel cannot communicate within the channel. By default, all nodes join to a public channel whose name is "Chord". Nodes can communicate through the public channel. The public channel is a communication channel for the Chord internal. Chord recommends an application not to use the public channel for communication. An application can define and use private channels for communication. A node can join several private channels at the same time.

This document uses following terminology:

  • Peer : Physical existence of a device in a network.
  • Node : A peer joined to a Chord network.
  • Channel : Logical grouping of nodes.

For more information on the Chord Service features, see Chord Service Guide.


Table of Contents


Summary of Interfaces and Methods

Interface Method
WebAPIsChordObject
Chord
ChordServiceConnectorObject
ChordServiceConnector ChordServiceProvider startServiceProvider(NetworkType type, ChordServiceStatusChangeCallback changeCallback, DOMString fileDirectory, unsigned long? keepAliveTime)
void stopServiceProvider()
AvailableNetworkTypeArray getAvailableInterfaceTypes()
ChordServiceStatusChangeCallback void onstatechanged(ChordServiceState serviceState)
ChordServiceProvider ChordChannel? joinChannel(DOMString channelName, ChordChannelStatusChangeCallback changeCallback)
void leaveChannel(DOMString channelName)
ChordChannel? getJoinedChannel(DOMString channelName)
ChordChannelArray getJoinedChannelList()
ChordChannel? getPublicChannel()
DOMString getLocalNodeName()
ChordChannel TransferID sendFile(DOMString dstNodeName, DOMString filePath, DOMString fileType, unsigned long timeout)
void cancelFile(TransferID id)
void acceptFile(TransferID id, unsigned long timeout, unsigned short retry, unsigned long chunkSize)
void rejectFile(TransferID id)
void sendData(DOMString dstNodeName, DOMString[] data, DOMString dataInfo)
void sendDataAll(DOMString[] data, DOMString dataInfo)
DOMString getChannelName()
ChordNodeNameArray getJoinedNodeList()
ChordChannelStatusChangeCallback void onnodejoined(DOMString channelName, DOMString nodeName)
void onnodeleft(DOMString channelName, DOMString nodeName)
void ondatareceived(DOMString srcChannelName, DOMString srcNodeName, DOMString[] data, DOMString dataInfo)
void onfilewillreceive(DOMString srcChannelName, DOMString srcNodeName, TransferID id, TransferFile file)
void onfilechunkreceived(DOMString srcChannelName, DOMString srcNodeName, TransferID id, TransferFile file, unsigned long offset)
void onfilereceived(DOMString srcChannelName, DOMString srcNodeName, TransferID id, TransferFile file, DOMString tmpFilePath)
void onfilechunksent(DOMString dstChannelName, DOMString dstNodeName, TransferID id, TransferFile file, unsigned long offset, unsigned long chunkSize)
void onfilesent(DOMString dstChannelName, DOMString dstNodeName, TransferID id, TransferFile file)
void onfiletransfererror(DOMString dstChannelName, DOMString dstNodeName, TransferID id, TransferFile file, FileTransferState state)
TransferFile

1. Type Definitions

1.1. ChordServiceState

A state of chord service

    enum ChordServiceState {"STARTED", "STOPPED", " RECONNECTED ", " DISCONNECTED", "FORCTOESTOP", "FAILSTOTART"};

Supported chord service's states are:

  • STARTED : The state that chord service is started by user
  • STOPPED : The state that manager service is stopped by user
  • RECONNECTED : The state that chord service is restarted by network reconnection
  • DISCONNECTED : The state that chord service is stopped by network disconnection
  • FORCETOSTOP : The state that chord service is stopped due to unexpected error
  • FATILTOSTART : The stat that chord service fails to start due to any error

1.2. FileTransferState

A state of Chord service

    enum FileTransferState {"FAILTOSEND", "REJECTED", "CANCELED", "FAILTOCREATE", "NORESOURCE", "TIMEOUT" };

Supported Chord service's states are:

  • FAILTOSEND : The state that a node fails to send a file
  • REJECTED : The state that a recipient rejects to get a file
  • CANCELED : The state that a recipient or sender cancel to send or get a file during transfer
  • FAILTOCREATE : The state that a recipient is not able to get a file due to error to create a file
  • NORESOURCE : The state that memory allocation failed at the recipient side
  • TIMEOUT : The state that time out occurs during file transfer

1.3. NetworkType

Identifies the network type which will be connected for the chord service.

    enum NetworkType {"WIFI", "WIFI_AP", "WIFI_DIRECT" };

The connection will be through :

  • WIFI : Wi-Fi network mode.
  • WIFI_AP : Wi-Fi tethering mode.
  • WIFI_DIRECT : Wi-Fi direct mode.

1.4. AvailableNetworkTypeArray

Array of Available Network Interfaces' Type.

    typedef sequence<NetworkTypeNetworkType> AvailableNetworkTypeArray;

1.5. ChordChannelArray

Array of Chord Channels.

    typedef sequence<ChordChannelChordChannel> ChordChannelArray;

1.6. ChordChannelNameArray

Array of Chord Channel Names.

    typedef sequence<DOMString> ChordChannelNameArray;

1.7. ChordNodeNameArray

Array of Chord Node Names.

    typedef sequence<DOMString> ChordNodeNameArray;

1.8. TransferID

A transfer id.

    typedef DOMString TransferID;

2. Interfaces

2.1. WebAPIsChordObject

Defines what is instantiated in the webapis object.

    [NoInterfaceObject] interface WebAPIsChordObject {
          readonly attribute ChordChord chord;
    };
    WebAPIs implements WebAPIsChordObjectWebAPIsChordObject;

There will be a webapis.chord object that allows accessing the functionality of the Chord Service API.

2.2. Chord

The Chord root API.

    [NoInterfaceObject] interface Chord {
    };

Chord interfaces will be always available within WebAPIs object in the ECMAScript hierarchy (window.webapis.chord).

2.3. ChordServiceConnectorObject

Defines what is instantiated in the chord object.

    [NoInterfaceObject] interface ChordServiceConnectorObject {
        readonly attribute ChordServiceConnectorChordServiceConnector serviceconnector;
    };
    ChordChord implements ChordServiceConnectorObjectChordServiceConnectorObject;

There will be a webapis.chord.serviceconnector object that allows accessing the functionality of the Chord Service Connector API.

2.4. ChordServiceConnector

Control the lifecycle of Chord Service

    [NoInterfaceObject] interface ChordServiceConnector {
        

        ChordServiceProviderChordServiceProvider startServiceProvider(NetworkTypeNetworkType type, 
            ChordServiceStatusChangeCallbackChordServiceStatusChangeCallback changeCallback, 
            DOMString fileDirectory, 
            optional unsigned long? keepAliveTime);


        void stopServiceProvider();


        AvailableNetworkTypeArrayAvailableNetworkTypeArray  getAvailableInterfaceTypes();        
    };

An application that intends to use the Chord Service should start by launching service provider. Through this, application can connect to the Chord Service Framework.

METHODS

startServiceProvider

Start service provider.

Signature
ChordServiceProvider startServiceProvider(NetworkType type, ChordServiceStatusChangeCallback changeCallback, DOMString fileDirectory, optional unsigned long? keepAliveTime);

Synchronous function that connects application to Chord Service Framework, and returns ChordServiceProvider object.

Parameters
  • type
    • Optional: No.
    • Nullable: No.
    • Type: NetworkType.
    • Description: An interface type to communicate. It is a mandatory input.
  • changeCallback
    • Optional: No.
    • Nullable: No.
    • Type: ChordServiceStatusChangeCallback.
    • Description: Listen to chord manager event. It is a mandatory input.
  • fileDirectory
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: Directory path to save receiving file temporarily. It is a mandatory input.
  • keepAliveTime
    • Optional: Yes.
    • Nullable: Yes.
    • Type: unsigned long.
    • Description: Timeout with millisecond. The timeoutMsec determines the maximum keep-alive time to wait to leave when there is no data from the nodes. Default time is 15000 millisecond.
Return value
Returns the handle, a ChordServiceProvider instance, to the Chord Service
Exceptions
  • WebAPIException:

    with error type InvalidValuesError,If any input parameter contains invalid values.

    with error type NetworkNotAvailableError, if the given network interface is not available

    with error type NotFoundError, if the given temporal directory does not exist

    with error type AlreadyStartedError, if the Chord service has been already started before

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type UnknownError in any other case.

Code example
 var serviceProvider = null;

 function onstatechanged(state) {
     console.log(state);
 }

 try {       
     var interfaceTypes = webapis.chord.serviceconnector.getAvailableInterfaceTypes();
     serviceProvider = webapis.chord.serviceconnector.startServiceProvider(interfaceTypes[0], onstatechanged, "/Chord");  
 } catch (error) {      
    console.log(error.name);  
 }  
     

stopServiceProvider

Stop service provider.

Signature
void stopServiceProvider();

Synchronous function that stop the Chord service.

Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type UnknownError in any other case.

getAvailableInterfaceTypes

Get a list of available interface types.

Signature
AvailableNetworkTypeArray getAvailableInterfaceTypes();

Synchronous function that returns the name of available interface types.

Return value
Returns a list of the names of available network interfaces. It returns an empty list, there is no available network interface.
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type UnknownError in any other case.

Code example
 try {
    // Get all available network interfaces
     var interfaceTypes = webapis.chord.serviceconnector.getAvailableInterfaceTypes();
     for (var i = 0 ; i < interfaceTypes.length ; i++ ) {
         console.log(interfaceTypes[i] + " is available.");
 } catch (error) {
     console.log(error);
 }
          

2.5. ChordServiceStatusChangeCallback

Callback invoked when the state of service provider changes

    [Callback=FunctionOnly, NoInterfaceObject] interface ChordServiceStatusChangeCallback {
       void onstatechanged(ChordServiceStateChordServiceState serviceState);
    };

2.6. ChordServiceProvider

Chord channel and node

    [NoInterfaceObject] interface ChordServiceProvider {


        ChordChannelChordChannel? joinChannel(DOMString channelName, ChordChannelStatusChangeCallbackChordChannelStatusChangeCallback changeCallback);


        void leaveChannel(DOMString channelName);


        ChordChannelChordChannel? getJoinedChannel(DOMString channelName);


        ChordChannelArrayChordChannelArray getJoinedChannelList();


        ChordChannelChordChannel? getPublicChannel();


        DOMString getLocalNodeName();
    };

Nodes in the Chord network communicate with other Chord nodes, without Server-Client model or Master-Slave model. To achieve the above functionality, each node must maintain a channel list of joined channels and a node list for each channel using this ChordServiceProvider interface

METHODS

joinChannel

Join a desired channel with a given listener.

Signature
ChordChannel? joinChannel(DOMString channelName, ChordChannelStatusChangeCallback changeCallback);

Synchronous function that join a channel. If there is no channel with the given name, the ChordServiceProvider will create a channel with the name.

Note that the name of the public channel is 'Chord'.

After the callback, given as a parameter, is invoked with 'STARTED', a Node is created and to control the Channel is possible. If channel-related functions are called before 'STARTED' event occurs, a null value will be returned.

Each channel is distinguished by the channelName. It is very important that this value has an unique value on the Chord network.

Parameters
  • channelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: Channel name. It is a mandatory input.
  • changeCallback
    • Optional: No.
    • Nullable: No.
    • Type: ChordChannelStatusChangeCallback.
    • Description: A listener that gets notified when there is events joined channel. It is a mandatory input.
Return value
Returns a handle of the channel if it is joined successfully, null otherwise.
Exceptions
  • WebAPIException:

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError any other case.

Code example
 var channel = null;

 var channelChangeCallback = {
     onnodejoined : function (channel, node) {
         console.log(node + " is newly joined in " + channel);
     },
     onnodeleft : function (channel, node) {
         console.log(node + " is disjoined from "  + channel);
     },
     ondatareceived : function (srcChannel, srcNode, data, dataInfo) {
         console.log("A data arrives from " + srcNode + " with the purpose of "+ dataInfo);
     },
     onfilewillreceive : function (srcChannel, srcNode,, id, file) {
     },
     onfilechunkreceived : function (srcChannel, srcNode, id, file, offset) {
     },
     onfilereceived : function (srcChannel, srcNode, id, file, tmpFilePath) {
     },
     onfilechunksent : function (dstChannel, dstNode, id, file, offset, chunkSize) {
     },
     onfilesent : function (dstChannel, dstNode, dstNode, id, file) {
     },
     onfiletransfererror : function (dstChannel, dstNode, id, file, state) {
     }
 };
 
 function onstatechanged(state) {
     if (state == "STARTED") {
          channel = serviceProvider.joinChannel("com.sec.chord.TESTCHANNEL",channelChangeCallback);
     } else if (state == "RECONNECTED") {
     }
 }

 try {
     var interfaceTypes = webapis.chord.serviceconnector.getAvailableInterfaceTypes();
     serviceProvider = webapis.chord.serviceconnector.startServiceProvider(interfaceTypes[0], onstatechanged, "/Chord");
 } catch (error) {
     console.log(error);
 }

   

leaveChannel

Leave a given channel.

Signature
void leaveChannel(DOMString channelName);

Synchronous function that leaves a channel.

Parameters
  • channelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: Channel name
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

Code example
 var channel = null, serviceProvider;
 // on clicking the exit button
 function onexitapp() {
     try {
         serviceProvider.leaveChannel("com.sec.chord.TESTCHANNEL");
         webapis.chord.stopServiceProvider();
     } catch (error) {
         console.log(error);
     }
 }

 function onstatechanged(state) {
     if (state == "STARTED") {
         channel = serviceProvider.joinChannel("com.sec.chord.TESTCHANNEL",channelChangeCallback);
     } else if (state == "RECONNECTED") {
     }
 }

 try {
     var interfaceTypes = webapis.chord.serviceconnector.getAvailableInterfaceTypes();
     serviceProvider = webapis.chord.serviceconnector.startServiceProvider(interfaceTypes[0], onstatechanged, "/Chord");
 } catch (error) {
     console.log(error);
 }

  

getJoinedChannel

Request the channel instance for the specific channel name.

Signature
ChordChannel? getJoinedChannel(DOMString channelName);

Synchronous function that gets a channel instance for the given name. If there is no channel with the given name, the ChordServiceProvider will return null. If this function is invoked in the state of "STOPPED", the ChordServiceProvider will return null.

Parameters
  • channelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: Channel name
Return value
Returns a handle of the channel if exist, null otherwise.
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

Code example
 var serviceProvider; // assume that serviceProvider object has been retrieved properly.

 try {
     var channel = serviceProvider.getJoinedChannel("com.sec.chord.TESTCHANNEL");
     if (channel) {
         var name = channel.getChannelName();
         console.log("The name of channel is " + name);
     } else {
     console.log("There is no channel in network");
     }
 } catch (error) {
     console.log(error);
 }
 

getJoinedChannelList

Request for joined channel interfaces.

Signature
ChordChannelArray getJoinedChannelList();

Synchronous function that gets all the nodes which my local node joined. If this function is invoked in the state of "STOPPED", the ChordServiceProvider will return empty list.

Return value
Returns a list of handle for joined channel. It returns an empty list, there is no joined channel.
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

Code example
 var serviceProvider; // assume that serviceProvider object has been retrieved properly.
 try {
     var channelList = serviceProvider.getJoinedChannelList();
     for (i = 0;ichannelList.length;i++) {
         console.log("CH - "+i + " : " + chanelList[i].getChannelName());
     }
 } catch(error) {
     console.log(error);
 }
 

getPublicChannel

Request the channel interface for the public channel

Signature
ChordChannel? getPublicChannel();

Synchronous function that gets a public channel instance. If this function is invoked in the state of "STOPPED", the ChordServiceProvider will return null.

Return value
Returns the channel which is opened in public.
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

getLocalNodeName

Request the name of the local node

Signature
DOMString getLocalNodeName();

Synchronous function that gets the name of local node

Return value
Returns the name of the local node.
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

2.7. ChordChannel

Defines Chord channel operation

    [NoInterfaceObject] interface ChordChannel {

        TransferIDTransferID sendFile(DOMString dstNodeName, DOMString filePath, DOMString fileType, optional unsigned long timeout);
        

        void cancelFile(TransferIDTransferID id);
        

        void acceptFile(TransferIDTransferID id, 
                                   optional unsigned long timeout, 
                                   optional unsigned short retry, 
                                   optional unsigned long chunkSize);
                

        void rejectFile(TransferIDTransferID id);


        void sendData(DOMString dstNodeName, DOMString[] data, DOMString dataInfo);
        

        void sendDataAll(DOMString[] data, DOMString dataInfo);
                

        DOMString getChannelName();
        

        ChordNodeNameArrayChordNodeNameArray getJoinedNodeList();

    };

METHODS

sendFile

Send file to the nodes on the channel

Signature
TransferID sendFile(DOMString dstNodeName, DOMString filePath, DOMString fileType, optional unsigned long timeout);

Synchronous function that Send file to the nodes. If you want to send file to multiple users on the channel, voke sendFile() for each node

Parameters
  • dstNodeName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The node name that the file is sent to. It is mandatory.
  • filePath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The absolute path of the file to be transferred. It is mandatory.
  • fileType
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: User defined file type. It is mandatory.
  • timeout
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned long.
    • Description: The time(msec) to allow the receiver to accept the receiving data requests. Default time is 5000 millisecond.
Return value
Returns TransferID that is used to call the cancelFile() method.
Exceptions
  • WebAPIException:

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

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

Code example
 var serviceProvider; // assume that serviceProvider object has been retrieved properly.

 try {
     var channel = serviceProvider.getJoinedChannel("com.sec.chord.TESTCHANNEL");
     if (channel) {
         var filePath = "sample_file_path";
         var fileType = "FILE_TYPE_PICTURE"
         var timeout = 10000;
         ChordNodeArrary nodeArray = getJoinedNodeList();
         for (var i = 0; i  nodeArray.length; i++) {
             channel.sendFile(nodeArray[i], filePath, fileType, timeout);
             console.log("Send " + filePath + " to " + nodeArray[i]);
        }
   } else {
       console.log("There is no channel in network");
   }
 } catch (error) {
     console.log(error);
 }
  

cancelFile

Cancel file transfer while it is in progress.

Signature
void cancelFile(TransferID id);

Synchronous function which cancels the file transfer.

Parameters
  • id
    • Optional: No.
    • Nullable: No.
    • Type: TransferID.
    • Description: TransferID.
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

Code example
 var serviceProvider; // assume that serviceProvider object has been retrieved properly.

 try {
     var channel = serviceProvider.getJoinedChannel("com.sec.chord.TESTCHANNEL");
     if (channel) {
         var filePath = "sample_file_path";
         var fileType = "FILE_TYPE_PICTURE"
         var timeout = 10000;
         ChordNodeArrary nodeArray = getJoinedNodeList();
         for (var i = 0; i  nodeArray.length; i++) {
             TransferID  transferID = channel.sendFile(nodeArray[i], filePath, fileType, timeout);
             console.log("Send " + filePath + " to " + nodeArray[i]);
             channel.cancelFile(transferID);
            console.log("cancel sending " + filePath + " to " + nodeArray[i]);
        }
   } else {
       console.log("There is no channel in network");
   }
 } catch (error) {
     console.log(error);
 }
  

acceptFile

Accept to receive file.

Signature
void acceptFile(TransferID id, optional unsigned long timeout, optional unsigned short retry, optional unsigned long chunkSize);

Synchronous function that accept to receive file. It can be called once when an onFileWillReceive() notification is received.

Parameters
  • id
    • Optional: No.
    • Nullable: No.
    • Type: TransferID.
    • Description: TransferID.
  • timeout
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned long.
    • Description: The timeout to request the chunk data. The default value is [TBD]
  • retry
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: The count that allow to retry to request chunk data. The default value is [TBD]
  • chunkSize
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned long.
    • Description: Chunk size. The default value is [TBD]
Exceptions
  • WebAPIException:

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

Code example
 var channel = null; 
 var serviceProvider; // assume that serviceProvider object has been retrieved properly.
 var channelChangeCallback = {
     onfilewillreceive : function(srcNode, id, file) {
         try {
             channel.acceptFile(id, 10000, 1, 300 * 1024);
         } catch (error) {
             console.log(error);
         }
     }
 };

 function onstatechanged(state) {
     if (state == "STARTED") {
         channel = serviceProvider.joinChannel("com.sec.chord.TESTCHANNEL",channelChangeCallback);
     } else if (state == "RECONNECTED") {
     }
 }

  

rejectFile

Reject to receive file.

Signature
void rejectFile(TransferID id);

Synchronous function that reject to receive file. Can be called once an onFileWillReceive() notification is received.

Parameters
  • id
    • Optional: No.
    • Nullable: No.
    • Type: TransferID.
    • Description: TransferID.
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

Code example
 var channel = null; 
 var serviceProvider; // assume that serviceProvider object has been retrieved properly.

 var channelChangeCallback = {
     onfilewillreceive : function(srcNode, id, file) {
         try {
             channel.rejectFile(id);
          } catch (error) {
             console.log(error);
          }
     }
 };

 function onstatechanged(state) {
     if (state == "STARTED") {
         channel = serviceProvider.joinChannel("com.sec.chord.TESTCHANNEL",channelChangeCallback);
     } else if (state == "RECONNECTED") {
     }
 }

 try {
     var interfaceTypes = webapis.chord.serviceconnector.getAvailableInterfaceTypes();
     serviceProvider = webapis.chord.serviceconnector.startServiceProvider(interfaceTypes[0], onstatechanged, "/Chord");
 } catch (error) {
     console.log(error);
 }

  

sendData

Send data message to the node.

Signature
void sendData(DOMString dstNodeName, DOMString[] data, DOMString dataInfo);

Synchronous function that send data message If you want to send message to multiple users on the channel, voke sendData() for each node

Parameters
  • dstNodeName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The joined node name that the message is sent to. It is mandatory.
  • data
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The package of data to send.
  • dataInfo
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: User defined message type. It is mandatory
Exceptions
  • WebAPIException:

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

Code example
 var serviceProvider; // assume that serviceProvider object has been retrieved properly.

 try {
     var channel = serviceProvider.getJoinedChannel("com.sec.chord.TESTCHANNEL");
     if (channel) {
         var firstNode = 0;
         ChordNodeArrary nodeArray = getJoinedNodeList();
         var dataInfo = "DATA_TYPE_CHAT";
         channel.sendData(nodeArray[firstNode], message, dataInfo);
         console.log("Send message to " + nodeArray[firstNode]);
     } else {
         console.log("There is no channel in network");
     }
 } catch (error) {
     console.log(error.name);
 }
  

sendDataAll

Send data message to the all node on the channel.

Signature
void sendDataAll(DOMString[] data, DOMString dataInfo);

Synchronous function that send data message to the nodes in the channel

Parameters
  • data
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The package of data to send.
  • dataInfo
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: User defined message type. It is mandatory
Exceptions
  • WebAPIException:

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

Code example
 var serviceProvider; // assume that serviceProvider object has been retrieved properly.

 try {
     var channel = serviceProvider.getJoinedChannel("com.sec.chord.TESTCHANNEL");
     if (channel) {
         channel.sendDataAll(message, dataInfo);
     } else {
         console.log("There is no channel in network");
     }
 } catch (error) {
     console.log(error.name);
 }
  

getChannelName

Get the channel name.

Signature
DOMString getChannelName();

Synchronous function that get the channel name.

Return value
Returns the channel name.
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

Code example
 var serviceProvider; // assume that serviceProvider object has been retrieved properly.

 try {
     var channel = serviceProvider.getJoinedChannel("com.sec.chord.TESTCHANNEL");
     if (channel) {
         var name = channel.getChannelName();
         console.log("The name of channel is " + name);
     } else {
         console.log("There is no channel in network");
     }
 } catch (error) {
     console.log(error);
 }
 

getJoinedNodeList

Requests for nodes on the channel.

Signature
ChordNodeNameArray getJoinedNodeList();

Synchronous function that requests node list on the channel

Return value
Returns a list of nodes names in the channel. It returns empty list, there is no joined node.
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported

    with error type InvalidStateError, if an attempt is made to use an object that is not, or is no longer, usable.

    with error type UnknownError in any other case.

Code example
 var serviceProvider; // assume that serviceProvider object has been retrieved properly.

 try {
     var channel = serviceProvider.getJoinedChannel("com.sec.chord.TESTCHANNEL");
     if (channel) {
         ChordNodeArrary nodeArray = getJoinedNodeList();
         for (var i = 0; i  nodeArray.length; i++) {
             console.log(i + ". node name is " + nodeArray[i]);
         }
   } else {
      console.log("There is no channel in network");
   }
 } catch (error) {
    console.log(error.name);
 }
  

2.8. ChordChannelStatusChangeCallback

Listener for chord channel events.

    [Callback, NoInterfaceObject] interface ChordChannelStatusChangeCallback {
    

        void onnodejoined(DOMString channelName, DOMString nodeName);        
        

        void onnodeleft(DOMString channelName, DOMString nodeName);    


        void ondatareceived(DOMString srcChannelName, DOMString srcNodeName, DOMString[] data, DOMString dataInfo);
        

        void onfilewillreceive(DOMString srcChannelName, DOMString srcNodeName, TransferIDTransferID id, TransferFileTransferFile file);
        

        void onfilechunkreceived(DOMString srcChannelName, DOMString srcNodeName, TransferIDTransferID id, TransferFileTransferFile file, unsigned long offset); 
        

        void onfilereceived(DOMString srcChannelName, DOMString srcNodeName, TransferIDTransferID id, TransferFileTransferFile file, DOMString tmpFilePath);
        

        void onfilechunksent(DOMString dstChannelName, DOMString dstNodeName, TransferIDTransferID id, TransferFileTransferFile file, unsigned long offset, unsigned long chunkSize);
        

        void onfilesent(DOMString dstChannelName, DOMString dstNodeName, TransferIDTransferID id, TransferFileTransferFile file);


        void onfiletransfererror(DOMString dstChannelName, DOMString dstNodeName, TransferIDTransferID id, TransferFileTransferFile file, FileTransferStateFileTransferState state);
        
    };

This interface defines a listener for chord channel events. A listener implementation can be registered using the joinChannel() API called when joining a channel.

Code example
 var channel = null; 
 var serviceProvider;
 var channelChangeCallback = {
     onnodejoined : function (channel, node) {
         console.log(node + " is newly joined in " + channel);
     },
     onnodeleft : function (channel, node) {
         console.log(node + " is disjoined from "  + channel);
     },
     ondatareceived : function (srcChannel, srcNode, data, dataInfo) {
         console.log("message [" + data + "] was received from " + srcNode);
     },
     onfilewillreceive : function (srcChannel, srcNode, id, file) {
           console.log("file [" + file.fileName + "] will be received from " + srcNode.nodeName );
           // if you want to receive : invoke acceptFile()
           if (file.fileInfo == "FILE_TYPE_PICTURE") {
               channel.acceptFile(id, 10000, 1, 300 * 1024);
           }
           // or if you don't want to receive : invoke rejectFile()
           else if (file.fileInfo == "FILE_TYPE_VIDEO") {
                channel.rejectFile(id);
           }
     },
     onfilechunkreceived : function(srcNode, id, file, offset) {
         var progress = (offset / file.fileSize) * 100;
         console.log(file.fileName " : " + progress + "% of file are received from " + srcNode.nodeName);
     },
     onfilereceived : function (srcChannel, srcNode, id, file, tmpFilePath) {
         console.log(file.fileName " from " + srcNode + "are saved at " + tmpFilePath);
     },
     onfilechunksent : function(dstNode, id, file, offset, chunkSize) {
           var progress = (offset / file.fileSize) * 100;
           console.log(file.fileName " : " + progress + "% of file are sent to " + dstNode.nodeName);
     },

     onfilesent : function (dstChannel, dstNode, dstNode, id, file) {
         console.log(file.fileName " transfer to " + dstNode + " are completed");
     },

     onfiletransfererror : function (dstChannel, dstNode, id, file, state) {
         console.log("fail to transfer " + file.fileName + ". reason : " + state);
     }
 };

 function onstatechanged(state) {
     if (state == "STARTED") {
         channel = serviceProvider.joinChannel("com.sec.chord.TESTCHANNEL",channelChangeCallback);
     } else if (state == "RECONNECTED") {
     }
 }

 try {
    var interfaceTypes = webapis.chord.serviceconnector.getAvailableInterfaceTypes();
    serviceProvider = webapis.chord.serviceconnector.startServiceProvider(interfaceTypes[0], onstatechanged, "/Chord");
 } catch (error) {
    console.log(error);
 }
   

METHODS

onnodejoined

Invoked when a node joins to a channel

Signature
void onnodejoined(DOMString channelName, DOMString nodeName);
Parameters
  • channelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of the channel at which an event actually occurs
  • nodeName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of the node

onnodeleft

Invoked when a node is left from a channel.

Signature
void onnodeleft(DOMString channelName, DOMString nodeName);
Parameters
  • channelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of the channel at which an event actually occurs
  • nodeName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of the node that is left from the channel

ondatareceived

Invoked when data arrives from other node

Signature
void ondatareceived(DOMString srcChannelName, DOMString srcNodeName, DOMString[] data, DOMString dataInfo);
Parameters
  • srcChannelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of the channel at which an event actually occurs
  • srcNodeName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of a source chord node.
  • data
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: message from source.
  • dataInfo
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: User defined message type.

onfilewillreceive

Invoked when the recipient gets a notification on file arrival from a sender.

Signature
void onfilewillreceive(DOMString srcChannelName, DOMString srcNodeName, TransferID id, TransferFile file);

User can decide to receive or reject the file.

Parameters
  • srcChannelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of the channel at which an event actually occurs
  • srcNodeName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of a source chord node.
  • id
    • Optional: No.
    • Nullable: No.
    • Type: TransferID.
    • Description: TransferID.
  • file
    • Optional: No.
    • Nullable: No.
    • Type: TransferFile.
    • Description: provide information of a transferred file

onfilechunkreceived

Invoked when a file data chunk arrives from the sender.

Signature
void onfilechunkreceived(DOMString srcChannelName, DOMString srcNodeName, TransferID id, TransferFile file, unsigned long offset);
Parameters
  • srcChannelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of the channel at which an event actually occurs
  • srcNodeName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of a source chord node.
  • id
    • Optional: No.
    • Nullable: No.
    • Type: TransferID.
    • Description: TransferID.
  • file
    • Optional: No.
    • Nullable: No.
    • Type: TransferFile.
    • Description: provide information of a transferred file
  • offset
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: Chunk offset

onfilereceived

Invoked when a file transfer is completed.

Signature
void onfilereceived(DOMString srcChannelName, DOMString srcNodeName, TransferID id, TransferFile file, DOMString tmpFilePath);

A tmpFilePath was registered when startServiceProvider() API was invoked

Parameters
  • srcChannelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of the channel at which an event actually occurs
  • srcNodeName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of a source chord node.
  • id
    • Optional: No.
    • Nullable: No.
    • Type: TransferID.
    • Description: TransferID.
  • file
    • Optional: No.
    • Nullable: No.
    • Type: TransferFile.
    • Description: provide information of a transferred file
  • tmpFilePath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: Temporarily stored file path.

onfilechunksent

Invoked when a file data chunk is sent to the recipient.

Signature
void onfilechunksent(DOMString dstChannelName, DOMString dstNodeName, TransferID id, TransferFile file, unsigned long offset, unsigned long chunkSize);
Parameters
  • dstChannelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of the channel at which an event actually occurs
  • dstNodeName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of a destination chord node.
  • id
    • Optional: No.
    • Nullable: No.
    • Type: TransferID.
    • Description: TransferID.
  • file
    • Optional: No.
    • Nullable: No.
    • Type: TransferFile.
    • Description: provide information of a transferred file
  • offset
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: Chunk offset
  • chunkSize
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: Chunk size

onfilesent

Invoked when a file transfer is completed.

Signature
void onfilesent(DOMString dstChannelName, DOMString dstNodeName, TransferID id, TransferFile file);
Parameters
  • dstChannelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of the channel at which an event actually occurs
  • dstNodeName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of a destination chord node.
  • id
    • Optional: No.
    • Nullable: No.
    • Type: TransferID.
    • Description: TransferID.
  • file
    • Optional: No.
    • Nullable: No.
    • Type: TransferFile.
    • Description: provide information of a transferred file

onfiletransfererror

Invoked when an error occurs during file transfer

Signature
void onfiletransfererror(DOMString dstChannelName, DOMString dstNodeName, TransferID id, TransferFile file, FileTransferState state);
Parameters
  • dstChannelName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of the channel at which an event actually occurs
  • dstNodeName
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the name of a destination chord node.
  • id
    • Optional: No.
    • Nullable: No.
    • Type: TransferID.
    • Description: TransferID.
  • file
    • Optional: No.
    • Nullable: No.
    • Type: TransferFile.
    • Description: provide information of a transferred file
  • state
    • Optional: No.
    • Nullable: No.
    • Type: FileTransferState.
    • Description: State of file transfer : {"FAILTOSEND", "REJECTED", "CANCELED", "FAILTOCREATE", "NORESOURCE", "TIMEOUT"}

2.9. TransferFile

provide information of a transferred file

    [NoInterfaceObject] interface TransferFile {

        readonly attribute DOMString fileName;

        readonly attribute DOMString fileInfo;

        readonly attribute DOMString hash;

        readonly attribute unsigned long fileSize;
    };

ATTRIBUTES

readonly DOMString fileName

The name of file to be transferred

This attribute is read-only.

readonly DOMString fileInfo

The meta information for the transferred file

This attribute is read-only.

readonly DOMString hash

The hash value of the file

This attribute is read-only.

readonly unsigned long fileSize

The size of the file

This attribute is read-only.

3. Full WebIDL

module ChordService {
    

    enum ChordServiceState {"STARTED", "STOPPED", " RECONNECTED ", " DISCONNECTED", "FORCTOESTOP", "FAILSTOTART"};
    

    enum FileTransferState {"FAILTOSEND", "REJECTED", "CANCELED", "FAILTOCREATE", "NORESOURCE", "TIMEOUT" };


    enum NetworkType {"WIFI", "WIFI_AP", "WIFI_DIRECT" };
   

    typedef sequence<NetworkTypeNetworkType> AvailableNetworkTypeArray;


    typedef sequence<ChordChannelChordChannel> ChordChannelArray;


    typedef sequence<DOMString> ChordChannelNameArray;
    

    typedef sequence<DOMString> ChordNodeNameArray;


    typedef DOMString TransferID;


    [NoInterfaceObject] interface WebAPIsChordObject {
          readonly attribute ChordChord chord;
    };
    WebAPIs implements WebAPIsChordObjectWebAPIsChordObject;
    

    [NoInterfaceObject] interface Chord {
    };
    

    [NoInterfaceObject] interface ChordServiceConnectorObject {
        readonly attribute ChordServiceConnectorChordServiceConnector serviceconnector;
    };
    ChordChord implements ChordServiceConnectorObjectChordServiceConnectorObject;



    [NoInterfaceObject] interface ChordServiceConnector {
        

        ChordServiceProviderChordServiceProvider startServiceProvider(NetworkTypeNetworkType type, 
            ChordServiceStatusChangeCallbackChordServiceStatusChangeCallback changeCallback, 
            DOMString fileDirectory, 
            optional unsigned long? keepAliveTime);


        void stopServiceProvider();


        AvailableNetworkTypeArrayAvailableNetworkTypeArray  getAvailableInterfaceTypes();        
    };
    


    [Callback=FunctionOnly, NoInterfaceObject] interface ChordServiceStatusChangeCallback {
       void onstatechanged(ChordServiceStateChordServiceState serviceState);
    };

    

    [NoInterfaceObject] interface ChordServiceProvider {


        ChordChannelChordChannel? joinChannel(DOMString channelName, ChordChannelStatusChangeCallbackChordChannelStatusChangeCallback changeCallback);


        void leaveChannel(DOMString channelName);


        ChordChannelChordChannel? getJoinedChannel(DOMString channelName);


        ChordChannelArrayChordChannelArray getJoinedChannelList();


        ChordChannelChordChannel? getPublicChannel();


        DOMString getLocalNodeName();
    };

    
    

    [NoInterfaceObject] interface ChordChannel {

        TransferIDTransferID sendFile(DOMString dstNodeName, DOMString filePath, DOMString fileType, optional unsigned long timeout);
        

        void cancelFile(TransferIDTransferID id);
        

        void acceptFile(TransferIDTransferID id, 
                                   optional unsigned long timeout, 
                                   optional unsigned short retry, 
                                   optional unsigned long chunkSize);
                

        void rejectFile(TransferIDTransferID id);


        void sendData(DOMString dstNodeName, DOMString[] data, DOMString dataInfo);
        

        void sendDataAll(DOMString[] data, DOMString dataInfo);
                

        DOMString getChannelName();
        

        ChordNodeNameArrayChordNodeNameArray getJoinedNodeList();

    };
    

    [Callback, NoInterfaceObject] interface ChordChannelStatusChangeCallback {
    

        void onnodejoined(DOMString channelName, DOMString nodeName);        
        

        void onnodeleft(DOMString channelName, DOMString nodeName);    


        void ondatareceived(DOMString srcChannelName, DOMString srcNodeName, DOMString[] data, DOMString dataInfo);
        

        void onfilewillreceive(DOMString srcChannelName, DOMString srcNodeName, TransferIDTransferID id, TransferFileTransferFile file);
        

        void onfilechunkreceived(DOMString srcChannelName, DOMString srcNodeName, TransferIDTransferID id, TransferFileTransferFile file, unsigned long offset); 
        

        void onfilereceived(DOMString srcChannelName, DOMString srcNodeName, TransferIDTransferID id, TransferFileTransferFile file, DOMString tmpFilePath);
        

        void onfilechunksent(DOMString dstChannelName, DOMString dstNodeName, TransferIDTransferID id, TransferFileTransferFile file, unsigned long offset, unsigned long chunkSize);
        

        void onfilesent(DOMString dstChannelName, DOMString dstNodeName, TransferIDTransferID id, TransferFileTransferFile file);


        void onfiletransfererror(DOMString dstChannelName, DOMString dstNodeName, TransferIDTransferID id, TransferFileTransferFile file, FileTransferStateFileTransferState state);
        
    };


    [NoInterfaceObject] interface TransferFile {

        readonly attribute DOMString fileName;

        readonly attribute DOMString fileInfo;

        readonly attribute DOMString hash;

        readonly attribute unsigned long fileSize;
    };
};