--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
+ <meta http-equiv="X-UA-Compatible" content="IE=9" />
+ <link rel="stylesheet" type="text/css" href="../../css/styles.css" />
+ <link rel="stylesheet" type="text/css" href="../../css/snippet.css" />
+ <script type="text/javascript" src="../../scripts/snippet.js"></script>
+ <script type="text/javascript" src="../../scripts/jquery.util.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/common.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/core.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/search.js" charset="utf-8"></script>
+<title>Convergence Services</title>
+</head>
+<body onload="prettyPrint()" style="overflow: auto;">
+
+<div id="toc-navigation">
+ <div id="profile">
+ <p><img alt="Mobile Web" src="../../images/mobile_s_w_optional.png"/> <img alt="Wearable Web" src="../../images/wearable_s_w_optional.png"/> <img alt="TV Web" src="../../images/tv_s_w.png"/></p>
+ </div>
+
+ <div id="toc_border"><div id="toc">
+ <p class="toc-title">Dependencies</p>
+ <ul class="toc">
+ <li>Tizen 3.0 and Higher for Mobile</li>
+ <li>Tizen 3.0 and Higher for Wearable</li>
+ <li>Tizen 3.0 and Higher for TV</li>
+ </ul>
+ <p class="toc-title">Content</p>
+ <ul class="toc">
+ <li><a href="#Prerequisites">Prerequisites</a></li>
+ <li><a href="#Discovering_Devices">Searching for Nearby Devices</a></li>
+ <li><a href="#Communication_Service">Setting up the AppCommunicationService and Exchanging Messages</a></li>
+ <li><a href="#Launch_App">Launching an Application Remotely</a></li>
+ <li><a href="#App_Control">Sending an Application Control Remotely</a></li>
+ </ul>
+ <p class="toc-title">Related Info</p>
+ <ul class="toc">
+ <li><a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/convergence.html">Convergence API for Mobile Web</a></li>
+ <li><a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/convergence.html">Convergence API for Wearable Web</a></li>
+ <li><a href="../../../../org.tizen.web.apireference/html/device_api/tv/tizen/convergence.html">Convergence API for TV Web</a></li>
+ </ul>
+ </div></div>
+</div>
+
+<div id="container"><div id="contents"><div class="content">
+<h1>Convergence Services</h1>
+
+<p>You can establish connections between different devices as well as propagate data and commands among them using a collection of device-to-device Convergence services. The Convergence services are remote functions to access and control nearby devices. If you implement an application with the Convergence API, the application can discover devices within the same network, obtain information about available device-to-device Convergence services, connect to applicable devices, and execute the services remotely, while you need no understanding of the communication details, such as connectivity type.</p>
+
+ <p>The Convergence API is optional for both Tizen mobile and wearable profiles, which means that it may not be supported in all mobile and wearable devices. The Convergence API is not supported on any Tizen Emulators.</p>
+
+ <p>The main features of the Convergence API include:</p>
+ <ul>
+ <li>Service discovery
+ <p>You can <a href="#Discovering_Devices">discover all Convergence services</a> supported by nearby devices.</p></li>
+ <li>Remote communication
+ <p>You can implement <a href="#Communication_Service">communication between applications</a> in remote devices.</p></li>
+ <li>Remote launch and actions
+ <p>You can <a href="#Launch_App">launch applications remotely</a>, and <a href="#App_Control">request them to take specific actions</a>.</p></li>
+ </ul>
+
+ <p>The following Convergence services are currently provided:</p>
+ <ul>
+ <li>AppCommunicationService
+ <p>You can spawn 2 types of instances: server and client. Typically, the client finds available server services through a discovery, establishes a connection with one of the servers, and launches an application on the server side. The server cannot launch an application on the client side. Both the client and server can exchange text messages and binary payloads.</p>
+ <table class="note">
+ <tbody>
+ <tr>
+ <th class="note">Note</th>
+ </tr>
+ <tr>
+ <td class="note">The AppCommunicationServerService can currently only be instantiated in TV applications.</td>
+ </tr>
+ </tbody>
+ </table>
+ </li>
+ <li>RemoteAppControlService
+ <p>The communication between RemoteAppControlService device instances does not involve servers. If the RemoteAppControlService is available on the device, remote applications can launch applications and send application control requests. The communication between devices begins after a discovery of the RemoteAppControlService.</p>
+ </li>
+ </ul>
+
+
+ <h2>Warm-up</h2>
+
+ <p>Become familiar with the Convergence API basics by learning about:</p>
+ <ul>
+ <li><a href="#Prerequisites">Prerequisites</a>
+ <p>Prepare your application to use the Convergence service functionality.</p></li>
+ <li><a href="#Discovering_Devices">Searching for Nearby Devices</a>
+ <p>Search for devices which offer Convergence services, and connect to one.</p></li>
+ <li><a href="#Communication_Service">Setting up the AppCommunicationService and Exchanging Messages</a>
+ <p>Set up a server service, make the server listen for incoming messages, and make the client send a message to the server. </p></li>
+ <li><a href="#Launch_App">Launching an Application Remotely</a>
+ <p>Launch an application on a remote device.</p></li>
+ <li><a href="#App_Control">Sending an Application Control Remotely</a>
+ <p>Send an application control request to a remote device to perform particular actions.</p></li>
+ </ul>
+
+ <h2 id="Prerequisites">Prerequisites</h2>
+ <p>To use the Convergence API (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/convergence.html">mobile</a>, <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/convergence.html">wearable</a>, and <a href="../../../../org.tizen.web.apireference/html/device_api/tv/tizen/convergence.html">TV</a> applications), the application has to request permission by adding the following privileges to the <span style="font-family: Courier New,Courier,monospace">config.xml</span> file:</p>
+ <pre class="prettyprint">
+<tizen:privilege name="http://tizen.org/privilege/bluetooth"/>
+<tizen:privilege name="http://tizen.org/privilege/internet"/>
+<tizen:privilege name="http://tizen.org/privilege/d2d.datasharing"/>
+</pre>
+
+ <h2 id="Discovering_Devices">Searching for Nearby Devices</h2>
+ <p>A discovery is a search for Convergence services in the same device-to-device network. To launch a discovery procedure and attempt to connect with the found service:</p>
+ <ol>
+ <li>Search for nearby devices with the <span style="font-family: Courier New,Courier,monospace">startDiscovery()</span> method:
+
+ <pre class="prettyprint">
+var timeout = 60 * 60;
+
+try
+{
+ tizen.convergence.startDiscovery(discoverySuccessCallback, onerror, timeout);
+}
+catch (err)
+{
+ console.log(err.name + ': ' + err.message);
+}
+</pre></li>
+
+ <li><p>Implement the <span style="font-family: Courier New,Courier,monospace">discoverySuccessCallback</span> callback defined in the first parameter of the <span style="font-family: Courier New,Courier,monospace">startDiscovery()</span> method.</p>
+ <p>The callback must contain 2 methods:</p>
+ <ul>
+ <li>When a nearby device is detected, the <span style="font-family: Courier New,Courier,monospace">onfound</span> event is triggered. The <span style="font-family: Courier New,Courier,monospace">device</span> parameter holds the services available on the found device. In the following example, the <span style="font-family: Courier New,Courier,monospace">connect()</span> method is called on the found <span style="font-family: Courier New,Courier,monospace">RemoteAppControlService</span>.</li>
+ <li>When the discovery is finished and no more devices are found, the <span style="font-family: Courier New,Courier,monospace">onfinished</span> event is triggered.</li>
+ </ul>
+
+ <pre class="prettyprint">
+var discoverySuccessCallback =
+{
+ onfound: function(device)
+ {
+ console.log('Found a device');
+ console.log(" - id: " + device.id);
+ console.log(" - name: " + device.name);
+ console.log(" - type: " + device.type);
+ console.log(" - service amount: " + device.services.length);
+ for (i in device.services)
+ {
+ if (device.services[i] instanceof RemoteAppControlService)
+ {
+ if (device.services[i].connectionState != "CONNECTED")
+ {
+ device.services[i].connect(onconnected, onerror);
+ }
+ }
+ }
+ },
+
+ onfinished: function(foundDevices)
+ {
+ console.log(' Device discovery has finished');
+ if (foundDevices.length > 0)
+ {
+ console.log(" - devices found: " + foundDevices.length);
+ }
+ }
+};
+
+function onerror(err)
+{
+ console.log(err.name + ': ' + err.message);
+}
+</pre></li>
+ <li><p>When a connection is established, the <span style="font-family: Courier New,Courier,monospace">onconnected</span> callback is invoked with the connected <span style="font-family: Courier New,Courier,monospace">service</span> as a parameter:</p>
+ <pre class="prettyprint">
+function onconnected(service)
+{
+ console.log('Connected to the service');
+}
+</pre>
+ </li>
+ </ol>
+
+
+ <h2 id="Communication_Service">Setting up the AppCommunicationService and Exchanging Messages</h2>
+<p>You can set up a server service, establish a connection between it and a client, and exchange messages.</p>
+ <h3>Launching a Server Service</h3>
+ <p>To instantiate a server service:</p>
+
+ <ol>
+ <li>Create a <span style="font-family: Courier New,Courier,monospace">ChannelInfo</span> object. It identifies the server and is used by the clients to address their demands. The first parameter of the <span style="font-family: Courier New,Courier,monospace">ChannelInfo</span> constructor is the server's application ID, set in its <span style="font-family: Courier New,Courier,monospace">config.xml</span> file. The second parameter is an ID set by you.
+ <pre class="prettyprint">
+var requestChannel = new tizen.ChannelInfo('targetApp0.main', 'chA');
+</pre>
+ </li>
+ <li>Define the success and error callbacks for the server service start:
+ <pre class="prettyprint">
+function onerror(err)
+{
+ console.log(err.name +': ' + err.message);
+}
+
+function onstarted(channel, clientInfo)
+{
+ console.log('Channel started');
+ console.log('channel uri: ' + channel.uri);
+ console.log('channel id: ' + channel.id);
+
+ if (clientInfo)
+ {
+ console.log('clientInfo');
+ console.log('isHost: ' + clientInfo.isHost);
+ console.log('client id: ' + clientInfo.clientId);
+ console.log('connection time: ' + clientInfo.connectionTime);
+ }
+}
+</pre>
+ </li>
+ <li>Instantiate an <span style="font-family: Courier New,Courier,monospace">AppCommunicationServerService</span> object:
+ <pre class="prettyprint">
+var service = new tizen.AppCommunicationServerService();
+</pre>
+ </li>
+ <li>Start the server service. In addition to the <span style="font-family: Courier New,Courier,monospace">ChannelInfo</span> object, you must provide the success and error callbacks defined earlier.
+ <pre class="prettyprint">
+service.start(requestChannel, onstarted, onerror);
+</pre></li>
+ </ol>
+
+ <h3>Listening for Incoming Messages on the Server Side</h3>
+ <p>Applications can transfer data as <strong>payload</strong> objects, consisting of a key string and a data chunk in form of a string or binary values array.</p>
+<p>To wait for incoming messages on the server side:</p>
+ <ol>
+ <li><p>The started server service handles incoming messages through the <span style="font-family: Courier New,Courier,monospace">onnotify</span> callback, which is invoked when another service attempts to communicate with the server. The callback receives the sent payload and data about its sender.</p>
+ <pre class="prettyprint">
+function onnotify(channel, payload, senderclientid)
+{
+ console.log('On service notification');
+ console.log('channel uri: ' + channel.uri);
+ console.log('channel id: ' + channel.id);
+ console.log('client id of sender: ' + senderclientid);
+ for (i in payload)
+ {
+ console.log('payload: ' + payload[i].key + '-' + payload[i].value);
+ }
+}
+</pre></li>
+
+ <li><p>To be able to receive messages, register the <span style="font-family: Courier New,Courier,monospace">onnotify</span> callback with the <span style="font-family: Courier New,Courier,monospace">setListener()</span> method:</p>
+ <pre class="prettyprint">
+service.setListener(onnotify);
+</pre>
+ <p>After the callback has been registered, all incoming data is handled by the <span style="font-family: Courier New,Courier,monospace">onnotify</span> callback.</p></li>
+ </ol>
+
+ <h3>Communicating with the Server</h3>
+ <p>In contrast to the server, a client service does not have to be instantiated. It can communicate with the server after discovering it.</p>
+ <p>To communicate with the server:</p>
+ <ol>
+
+ <li><p>Discover available server services on the client side:</p>
+ <pre class="prettyprint">
+function onerror(err)
+{
+ console.log(err.name +': ' + err.message);
+}
+
+var timeout = 60 * 60;
+
+try
+{
+ tizen.convergence.startDiscovery(discoverySuccessCallback, onerror, timeout);
+}
+catch (err)
+{
+ console.log(err.name + ': ' + err.message);
+}
+</pre></li>
+ <li><p>Create a <span style="font-family: Courier New,Courier,monospace">ChannelInfo</span> instance with the same URI and ID as the channel used on the server side. Then start the available server service and send the payload to it.</p>
+ <pre class="prettyprint">
+var serverService;
+var channel = new tizen.ChannelInfo('targetApp0.main', 'chA');
+
+function onerror(err)
+{
+ console.log(err.name +': ' + err.message);
+}
+
+var requestPayload =
+{
+ key: "testPayload",
+ value: "Hello!"
+};
+
+function sendSuccessCallback(channel)
+{
+ console.log('requestPayload sent');
+ console.log('channel uri: ' + channel.uri);
+ console.log('channel id: ' + channel.id);
+}
+
+function onstarted(channel, clientInfo)
+{
+ serverService.send(channel, requestPayload, sendSuccessCallback, onerror);
+}
+
+var discoverySuccessCallback =
+{
+ onfound: function(device)
+ {
+ for (i in device.services)
+ {
+ if (device.services[i] instanceof AppCommunicationServerService)
+ {
+ serverService = device.services[i];
+ device.services[i].start(channel, onstarted, onerror);
+ }
+ }
+ },
+
+ onfinished: function(foundDevices)
+ {
+ console.log(' Device discovery has finished');
+ }
+};
+</pre></li>
+ </ol>
+ <h2 id="Launch_App">Launching an Application Remotely</h2>
+
+ <p>This use case assumes that a "targetApp0.main" application has been installed on the remote device.</p>
+
+ <p>To launch an application on a remote device:</p>
+
+ <ol>
+ <li><p>Call the <span style="font-family: Courier New,Courier,monospace">startDiscovery()</span> method to establish connections with remote devices:</p>
+ <pre class="prettyprint">
+var discoverySuccessCallback =
+{
+ onfound: function(device)
+ {
+ for (i in device.services)
+ {
+ if (device.services[i].type === "REMOTE_APP_CONTROL")
+ {
+ if (device.services[i].connectionState != "CONNECTED")
+ {
+ device.services[i].connect(onconnected, onerror);
+ }
+ else
+ {
+ device.services[i].start(onstarted, onerror);
+ }
+ }
+ }
+ },
+
+ onfinished: function(foundDevices)
+ {
+ console.log('Device discovery has finished');
+ }
+};
+
+function onerror(err)
+{
+ console.log(err.name +': ' + err.message);
+}
+
+var timeout = 60 * 60;
+
+try
+{
+ tizen.convergence.startDiscovery(discoverySuccessCallback, onerror, timeout);
+}
+catch (err)
+{
+ console.log(err.name + ': ' + err.message);
+}
+</pre></li>
+ <li><p>An application on the remote device is started from the <span style="font-family: Courier New,Courier,monospace">onconnected</span> callback. The <span style="font-family: Courier New,Courier,monospace">remoteAppControlCallback</span> method handles the data sent from the remote device.</p>
+ <pre class="prettyprint">
+var requestAppId = 'targetApp0.main';
+
+function remoteAppControlCallback(data)
+{
+ for (var i = 0; i < data.length; i++)
+ {
+ console.log("key: " + data[i].key + "value: " + data[i].value[0]);
+ }
+ service.disconnect();
+}
+
+function onstarted(service)
+{
+ console.log('Remote app control service started');
+ service.launch(requestAppId, remoteAppControlCallback, onerror);
+}
+
+function onconnected(service)
+{
+ console.log('Connected to the remote app control service');
+ service.start(onstarted, onerror);
+ service.launch(requestAppId, remoteAppControlCallback, onerror);
+}
+</pre></li>
+ </ol>
+
+ <h2 id="App_Control">Sending an Application Control Remotely</h2>
+ <p>The <span style="font-family: Courier New,Courier,monospace">ApplicationControl</span> object is used to request applications to perform particular actions. This use case shows how to ask an image viewer to display a picture. For more information on application controls, see <a href="../../../../org.tizen.guides/html/web/app_management/app_controls_w.htm">Application Controls</a>.</p>
+ <ol>
+ <li><p>Use the <span style="font-family: Courier New,Courier,monospace">startDiscovery()</span> method to search for and connect to a <span style="font-family: Courier New,Courier,monospace">RemoteAppControlService</span>:</p>
+ <pre class="prettyprint">
+var discoverySuccessCallback =
+{
+ onfound: function(device)
+ {
+ for (i in device.services)
+ {
+ if (device.services[i] instanceof RemoteAppControlService)
+ {
+ if (device.services[i].connectionState != "CONNECTED")
+ {
+ device.services[i].connect(onconnected, onerror);
+ }
+ }
+ }
+ },
+
+ onfinished: function(foundDevices)
+ {
+ console.log(' Device discovery has finished');
+ }
+};
+
+function onerror(err)
+{
+ console.log(err.name +': ' + err.message);
+}
+
+try
+{
+ tizen.convergence.startDiscovery(discoverySuccessCallback, onerror, 60 * 60);
+}
+catch (err)
+{
+ console.log(err.name + ': ' + err.message);
+}
+</pre></li>
+ <li><p>Create the <span style="font-family: Courier New,Courier,monospace">ApplicationControl</span> object:</p>
+ <pre class="prettyprint">
+var requestAppControl = new tizen.ApplicationControl('http://tizen.org/appcontrol/operation/view',
+ null, 'image/jpeg', null,
+ [new tizen.ApplicationControlData('images', [testImgData])]);
+</pre></li>
+ <li><p>Use the <span style="font-family: Courier New,Courier,monospace">onconnected()</span> callback to send the application control request to the remote service. The <span style="font-family: Courier New,Courier,monospace">launchAppControl()</span> method takes as parameters the <span style="font-family: Courier New,Courier,monospace">ApplicationControl</span> object, optionally the target application ID, and a callback defining the actions to be taken on the remote service reply.</p><pre class="prettyprint">
+function remoteAppControlCallback(data)
+{
+ for (var i = 0; i < data.length; i++)
+ {
+ console.log("key: " + data[i].key + "value: " + data[i].value[0]);
+ }
+}
+
+function onconnected(service)
+{
+ service.launchAppControl(requestAppControl, null, remoteAppControlCallback, onerror);
+}
+</pre></li>
+ </ol>
+<script type="text/javascript" src="../../scripts/jquery.zclip.min.js"></script>
+<script type="text/javascript" src="../../scripts/showhide.js"></script>
+</div></div></div>
+
+<a class="top sms" href="#"><img src="../../images/btn_top.gif" alt="Go to top" /></a>
+
+<div id="footer">
+<p class="footer">Except as noted, this content - excluding the Code Examples - is licensed under <a href="http://creativecommons.org/licenses/by/3.0/legalcode" target="_blank">Creative Commons Attribution 3.0</a> and all of the Code Examples contained herein are licensed under <a href="https://www.tizen.org/bsd-3-clause-license" target="_blank">BSD-3-Clause</a>.<br/>For details, see the <a href="https://www.tizen.org/content-license" target="_blank">Content License</a>.</p>
+</div>
+
+<script type="text/javascript">
+var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-25976949-1']);
+_gaq.push(['_trackPageview']);
+(function() {
+var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();
+</script>
+
+</body>
+</html>
projects / sdk / online-doc.git / commitdiff