+++ /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</title>
- </head>
- <body onload="prettyPrint()" style="overflow: auto;">
-
- <div id="toc-navigation">
- <div id="profile">
- <p><img alt="Mobile native" src="../../images/mobile_s_n.png"/> <img alt="Wearable native" src="../../images/wearable_s_n.png"/></p>
- </div>
-
- <div id="toc_border"><div id="toc">
- <p class="toc-title">Dependencies</p>
- <ul class="toc">
- <li>Tizen 4.0 and Higher for Mobile</li>
- <li>Tizen 4.0 and Higher for Wearable</li>
- </ul>
- <p class="toc-title">Content</p>
- <ul class="toc">
- <li><a href="#app_communication">App Communication Service</a></li>
- <li><a href="#remote_app_control">Remote App Control Service</a></li>
- <li><a href="#prerequisites">Prerequisites</a></li>
- <li><a href="#discovery">Discovering Devices</a></li>
- <li>App Communication Service
- <ul class="toc">
- <li><a href="#connect_service">Connecting to the App Communication Service</a></li>
- <li><a href="#init_app_communication">Initializing the App Communication Service</a></li>
- <li><a href="#send_message">Sending Messages to the Server Application</a></li>
- </ul></li>
- <li>Remote App Control Service
- <ul class="toc">
- <li><a href="#init_remote">Using the Remote App Control Service</a></li>
- </ul></li>
- <li><a href="#payload">Predefined Payload Fields</a></li>
- </ul>
- <p class="toc-title">Related Info</p>
- <ul class="toc">
- <li><a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__CONVERGENCE__FRAMEWORK.html">Convergence API for Mobile Native</a></li>
- <li><a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__CONVERGENCE__FRAMEWORK.html">Convergence API for Wearable Native</a></li>
- </ul>
- </div></div>
-</div>
-
-<div id="container"><div id="contents"><div class="content">
-<h1>Convergence</h1>
-
-<p>As the number of Tizen devices is increasing, platform features that allow connections between different devices as well as sharing data and commands among them is required. Tizen device-to-device (D2D) connectivity framework provides this feature through a collection of D2D convergence services and the Convergence API. Being a part of the platform, the D2D connectivity framework is available on all Tizen TV, mobile, and wearable devices. The D2D connectivity features are aimed at streamlining the application development process and guaranteeing the compatibility and extensibility in the future.</p>
-
-<p>The D2D connectivity framework allows applications and devices in the network to discover, connect, and communicate to each other through convergence services. The app communication service opens logical channels for exchanging messages across devices, while the remote app control service starts and controls an application on a remote device.</p>
-
-<div class="note">
- <strong>Note</strong>
- The D2D connectivity framework supports only Wi-Fi networks. More connectivity types, such as Bluetooth, Bluetooth Low Energy, and Wi-Fi Direct™, are going to be added in future versions.
- <p>Only 2 services, app communication and remote app control, are currently supported. More services are going to be introduced in the future versions of Tizen. All convergence services are predefined in the platform, which means that you cannot add new ones on your own.</p>
-</div>
-
-<p>The main features of the Convergence API include:</p>
-<ul>
-<li>Discovering and connecting to devices
-<p>You can <a href="#discovery">discover nearby devices</a> and get information about them. After discovering a device that provides a service you need, you can <a href="#connect_service">connect to the device service</a>.</p></li>
-<li>Communicating with remote devices
-<p>You can use the <a href="#app_communication">app communication service</a> to connect to remote services and communicate with remote applications by sending a payload.</p></li>
-<li>Launching applications on remote devices
-<p>You can use the <a href="#remote_app_control">remote app control service</a> to launch applications on a remote device. The access to the remote device is <a href="#access_control">controlled using passcodes</a>.</p></li>
-</ul>
-
-
-<p>The Convergence API includes features to implement a typical convergence application workflow: discovering nearby devices and browsing available services, connecting to a specific service, and using the service. The payload functions defined for packaging data and transferring messages between end-points accept plain strings, byte arrays, and application control data. The payload also contains several <a href="#payload">predefined fields</a> for your use.</p>
-<p>The following figure illustrates the workflow of the D2D connectivity features.</p>
-
-<p align="center"><strong>Figure: D2D connectivity workflow</strong></p>
-<p align="center"><img src="../../images/d2d_workflow.png" alt="D2D connectivity workflow" /></p>
-
-
-
-<h2 id="app_communication">App Communication Service</h2>
-
-<p>The convergence architecture allows the app communication service to launch an application on a device equipped with the remote server, and communicate with the server application by <a href="#send_message">sending a payload</a>. The remote server application can also use the app communication service to send responses to the local (client-side) application. In this way, a sophisticated data exchange protocol can be established. Before using the app communication service, <a href="#init_app_communication">set up the listener callbacks and initialize the application</a>.</p>
-
-<p>The following figure illustrates the architecture.</p>
-
-<p align="center"><strong>Figure: App communication service</strong></p>
-<p align="center"><img src="../../images/d2d_app_communication.png" alt="App communication service" /></p>
-
-<div class="note">
- <strong>Note</strong>
- Currently, the remote server can only be implemented on a TV device based on Tizen 3.0, which means that you can remotely launch applications on TV devices only. You can develop a mobile or wearable client for the app communication service, if a server exists.
-</div>
-
-<p>A typical app communication service work flow starts with the discovery step, in which the mobile or wearable device discovers the service provided by the TV. When the service is found, the mobile or wearable device launches an application in the TV remotely and communicates with it. The app-to-app communication is bidirectional, so both local and remote applications usually play the roles of sender and listener.</p>
-
-<p>The app communication service has a client-server architecture:</p>
-
-<ul>
-<li>The app communication service relies on the remote server. This means that the server application (the application on the remote server, such as TV) initialization and execution differs slightly from the client application (the application on the mobile or wearable device).</li>
-<li>The client application can remotely launch the application on the server side or connect to the already running server application, but not the other way round. Both client and server side applications can send payloads and listen to each other.</li>
-<li>More than 1 client can be connected to a server application. For example, multiple players on mobile devices can connect to a game application on the TV, which takes a role of a server.</li>
-</ul>
-
-<p>The app communication service channel specifies the server application the client wants to connect with. The channel data is composed of a URI and channel ID, which are assigned to the channel handle:</p>
-<pre class="prettyprint">
-conv_channel_set_string(channel_handle, "uri", "org.example.d2d_test");
-conv_channel_set_string(channel_handle, "channel_id", "test");
-</pre>
-<p>The channel URI is the URI of the server side application, while the channel ID is a developer-defined value. Note that both URI and ID fields are mandatory for using the app communication service. If not provided, the <code>CONV_ERROR_INVALID_PARAMETER</code> error occurs. You must know the server side application URI: you either develop both the client and server application yourself, or acquire the server application URI from other sources.</p>
-
-<h2 id="remote_app_control">Remote App Control Service</h2>
-
-<p>In contrast to the app communication service, the remote app control service does not need a server. The service is based on a peer-to-peer scheme, which means that the communication between 2 remote devices is symmetric. In addition, the remote app control service does not provide channels.</p>
-
-<p>The connection between applications is based on <a href="https://www.iotivity.org/" target="_blank">IoTivity</a>, as illustrated in the following figure.</p>
-
-<p align="center"><strong>Figure: Remote app control service</strong></p>
-<p align="center"><img src="../../images/d2d_remote_app_control.png" alt="Remote app control service" /></p>
-
-<p>In Tizen 3.0, the remote app control service is supported in mobile and wearable profiles. With this service, you can <a href="#init_remote">use the Tizen App Control feature across remote devices</a>.</p>
-<p>The typical remote app control service workflow starts with the discovery of the remote app control service on the nearby devices. When the service is found, the <a href="../app_management/app_controls_n.htm">application control</a> feature can be used to launch an application on the remote device and receive results of operations performed by the launched application.</p>
-
-<h3 id="access_control">Access Control</h3>
-
-<p>The remote app control service can attempt to launch an application on a remote device without user permission. To prevent this, an access control module is implemented within the D2D connectivity framework.</p>
-<p>The access control setup is similar to the pairing of Bluetooth devices. When a device tries to access a remote device with the <code>conv_service_start()</code> function, a passcode pops up on the remote device screen and the user must enter that passcode on the original device. Once the passcode is entered correctly, the remote device is managed as an allowed device and a passcode is not asked for again.</p>
-
-<p>The following figure shows the device on the left trying to access the device on the right.</p>
-
-<p align="center"><strong>Figure: Access control</strong></p>
-<p align="center"><img src="../../images/d2d_access_control.png" alt="Access control" /></p>
-
-<p>You can manage allowed devices in the <strong>Tizen Connect</strong> tab of the Tizen settings application. When the Tizen Connect feature is enabled, all discovered nearby devices are presented to the user in 3 lists: allowed, denied, and available. The user can allow or deny each device by selecting the device name in the list.</p>
-<p>All remote devices in the <strong>Allowed devices</strong> list can access the original device without the passcode, while all devices in <strong>Denied devices</strong> list cannot access the original device at all. The user can refresh the list of available nearby devices by clicking <strong>Scan</strong>.</p>
-
-<p align="center"><strong>Figure: Tizen Connect</strong></p>
-<p align="center"><img src="../../images/d2d_tizen_connect.png" alt="Tizen Connect" /></p>
-
-<h2 id="prerequisites">Prerequisites</h2>
-
-<p>To enable your application to use the D2D connectivity functionality:</p>
-<ol>
-<li>To use the Convergence API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__CONVERGENCE__FRAMEWORK.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__CONVERGENCE__FRAMEWORK.html">wearable</a> applications), the application has to request permission by adding the following privileges to the <code>tizen-manifest.xml</code> file:
-<pre class="prettyprint">
-<privileges>
- <privilege>http://tizen.org/privilege/internet</privilege>
- <privilege>http://tizen.org/privilege/bluetooth</privilege>
- <privilege>http://tizen.org/privilege/d2d.datasharing</privilege>
-</privileges>
-</pre>
-</li>
-<li>To use the functions and data types of the Convergence API, include the <code><d2d_conv_manager.h></code> header file in your application:
-<pre class="prettyprint">
-#include <d2d_conv_manager.h>
-</pre>
-</li>
-</ol>
-
-<h2 id="discovery">Discovering Devices</h2>
-
-<p>Discovery is a procedure for searching for convergence services provided by nearby devices in the same device-to-device network.</p>
-<p>To discover devices:</p>
-<ol>
-<li>Create the device handle.
-<p>During the discovery process, the framework returns handles of found devices (JSON objects with basic device information and lists of available services). The following example shows the conceptual structure of device handle:</p>
-<pre class="prettyprint">
-{
- "device_id": "DEVICE_ID", /* Unique device ID */
- "device_name": "DEVICE_NAME", /* Unique device name */
- "device_type": "DEVICE_TYPE", /* Device profile, such as mobile or wearable */
- [
- /* Handle for service A */
- {
- service_type: TYPE_A,
- jservice: JSON auxiliary data of service A
- },
- /* Handle for service B */
- {
- service_type: TYPE_B,
- jservice: JSON auxiliary of service B
- },
- ]
-}
-</pre>
-
-<ul>
-<li>The device ID is a unique identifier string, generated with the following rule: if a remote server is installed on the device (such as TV), the device ID is assigned by the app communication service. Usually, it has a format of service name and version. Otherwise (such as on mobile or wearable devices), the device ID is the device MAC address.</li>
-<li>Device name is the one that is set in the device settings (<strong>Settings > About Devices > Device Name</strong>).</li>
-<li>The service list includes all services supported by the device.
-<p>Each service has either the <code>CONV_SERVICE_APP_TO_APP_COMMUNICATION</code> or <code>CONV_SERVICE_REMOTE_APP_CONTROL</code> type and auxiliary data. The service type constants are defined in the <code>conv_service_e</code> enumeration (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__D2D__CONVERGENCE__MANAGER__SERVICE__MODULE.html#gaea7544e24c248a658abc06d7015719a6">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__D2D__CONVERGENCE__MANAGER__SERVICE__MODULE.html#gaea7544e24c248a658abc06d7015719a6">wearable</a> applications).</p>
-</li></ul>
-
-<div class="note">
- <strong>Note</strong>
- The device ID and device type are defined in the platform, and cannot be changed.
- <p>The <code>jservice</code> data is used by the framework internally for the connection and execution of the service. You as a developer do not need to know these details.</p>
-</div>
-</li>
-<li>Start the discovery by calling the <code>conv_discovery_start()</code> function. The discovered device handles are retrieved in the <code>conv_discovery_cb()</code> callback.
-<p>In the following example, the <code>conv_discovery_start()</code> function runs a 30 seconds long discovery procedure. Each time a nearby device is discovered, the framework invokes the <code>discovery_cb()</code> callback with the device handle and the <code>CONV_DISCOVERY_RESULT_SUCCESS</code> result code. At the end of discovery procedure, the callback is invoked with the <code>CONV_DISCOVERY_RESULT_FINISHED</code> result code and an empty device handle.</p>
-<p>The result codes are defined in the <code>conv_discovery_result_e</code> enumeration (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__D2D__CONVERGENCE__MANAGER__FRAMEWORK.html#gaac8da8a6d95bf9c77039c4d9360b31e3">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__D2D__CONVERGENCE__MANAGER__FRAMEWORK.html#gaac8da8a6d95bf9c77039c4d9360b31e3">wearable</a> applications).</p>
-<p>The device ID, name, and type can be read from the device handle by passing the <code>CONV_DEVICE_ID</code>, <code>CONV_DEVICE_NAME</code>, and <code>CONV_DEVICE_TYPE</code> keys to the <code>conv_device_get_property_string()</code> function. To use the discovered device handle outside the callback, it must be cloned with the <code>conv_device_clone()</code> function.</p>
-<pre class="prettyprint">
-static void
-discovery_cb(conv_device_h device, int result, void *user_data)
-{
- if (result == CONV_DISCOVERY_RESULT_SUCCESS) {
- /* Discovered device */
- char* device_id = NULL;
- char* device_name = NULL;
- char* device_type = NULL;
-
- conv_device_get_property_string(device, CONV_DEVICE_ID, &device_id);
- printf("device id = %s\n", device_id);
- free(device_id);
-
- conv_device_get_property_string(device, CONV_DEVICE_NAME, &device_name);
- printf("device name = %s\n", device_name);
- free(device_name);
-
- conv_device_get_property_string(device, CONV_DEVICE_TYPE, &device_type);
- printf("device TYPE = %s\n", device_type);
- free(device_type);
-
- /* Clone the device handle for use outside this callback */
- conv_device_h clone_device;
- conv_device_clone(device, &clone_device);
- } else if (result == CONV_DISCOVERY_RESULT_FINISHED) {
- /* Discovery has finished */
- /* Do something */
- } else if (result == CONV_DISCOVERY_RESULT_ERROR) {
- /* Discovery has triggered an error */
- /* Error handling */
- }
-}
-
-static void
-start_discovery_example()
-{
- /* Create a convergence manager */
- int error = conv_create(&conv_h);
- if (error != CONV_ERROR_NONE)
- /* Error handling */
-
- /* Start discovery */
- error = conv_discovery_start(conv_h, 30, discovery_cb, NULL);
- if (error != CONV_ERROR_NONE)
- /* Error handling */
-}
-</pre>
-<p>To stop the ongoing discovery process, call the <code>conv_discovery_stop()</code> function.</p>
-</li>
-<li>Get the list of services.
-<p>The remaining part of the device handle is a list of services. Pull this information by using the <code>conv_device_foreach_service()</code> function:</p>
-<pre class="prettyprint">
-static void
-service_foreach_cb(conv_service_h service_handle, void *user_data)
-{
- conv_service_e e = CONV_SERVICE_NONE;
-
- conv_service_get_type(service_handle, &e);
- printf("service_get_type = %d\n", (int)e);
-
- conv_service_h clone_service_handle;
- conv_service_clone(service_handle, &clone_service_handle);
-}
-
-static void
-foreach_service_example()
-{
- conv_device_h device = data;
- conv_device_foreach_service(device, service_foreach_cb, NULL);
-}
-</pre>
-<p>While iterating through the available services, the framework generates a new handle for each service and passes it to the <code>conv_service_foreach_cb()</code> type callback. To use the service handle outside the callback, clone it with the <code>conv_service_clone()</code> function.</p>
-</li>
-</ol>
-
-<h2 id="connect_service">Connecting to the App Communication Service</h2>
-
-<p>To connect to the app communication service provided by a remote device, call the <code>conv_service_connect()</code> function.</p>
-<p>The first parameter is the service handle extracted from the list in the device handle received during the discovery process. The second parameter is the <code>conv_service_connected_cb</code> type callback function, by which the <code>Connecting</code>, <code>Connected</code>, and <code>Disconnected</code> states of the remote service are delivered.</p>
-
-<pre class="prettyprint">
-conv_service_connection_state_e state = CONV_SERVICE_CONNECTION_STATE_NONE;
-conv_service_get_connection_state(service_handle, &state);
-if (state == CONV_SERVICE_CONNECTION_STATE_NOT_CONNECTED)
- conv_service_connect(service_handle, callback, NULL);
-</pre>
-<p>You can check the connection state with the <code>conv_service_get_connection()</code> function, which returns one of values defined in the <code>conv_service_connection_state_e</code> enumeration (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__D2D__CONVERGENCE__MANAGER__SERVICE__MODULE.html#ga5da79e1a7ca434991e5ff6d28c0b0e13">mobile</a> and <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__D2D__CONVERGENCE__MANAGER__SERVICE__MODULE.html#ga5da79e1a7ca434991e5ff6d28c0b0e13">wearable</a> applications). If the service is not connected yet, the connection state is <code>CONV_SERVICE_CONNECTION_STATE_NOT_CONNECTED</code> and the service must be connected using the <code>conv_service_connect()</code> function.</p>
-
-<div class="note">
- <strong>Note</strong>
- Repeated attempts to connect to an already connected service result in the invalid state error. Attempts to start, publish, read, or stop a disconnected service also result in the invalid state error.
-</div>
-
-<p>Technically, in case of the Wi-Fi network, when the framework runs the discovery procedure, all devices are already connected to the Access Point (AP), which means that the <code>conv_service_get_connection_state()</code> function always returns the <code>Connected</code> state and the <code>conv_service_connect()</code> function can be omitted. It is especially applied for the Tizen 3.0 convergence framework, which supports only Wi-Fi networks. In future versions with support for Bluetooth, Bluetooth Low Energy, or Wi-Fi Direct™, the connection procedure is mandatory. For the sake of future extensibility and compatibility, use the <code>conv_service_connect()</code> function even in Tizen 3.0.</p>
-
-
-<h2 id="init_app_communication">Initializing the App Communication Service</h2>
-<p>To initialize the app communication service:</p>
-<ol>
-<li id="listener_callback">Register the listener callback with the <code>conv_service_set_listener_cb()</code> function. This function must be called only once, regardless of the number of used service channels. In the runtime, all payloads from all channels are delivered there.
-
-<div class="note">
- <strong>Note</strong>
- The listener callback must be registered before the service starts, because the <code>conv_service_start()</code> function result can only be received in the listener callback.
-</div>
-<ul>
-<li>In the callback, the first parameter is the service handle, and it corresponds to the service, used in the <code>conv_set_listener_cb()</code> callback. The second parameter is the channel handle that indicates the particular channel through which the payload is delivered. The third parameter is the error parameter that indicates if the request is processed successfully on the remote device.
-<p>The main role of the listener callback is to parse the payload:</p>
-<pre class="prettyprint">
-/* Client side callback */
-void
-listener_example(conv_service_h handle, conv_channel_h channel, int error,
- conv_payload_h result, void *user_data)
-{
- char *result_type = NULL;
- char *payload_type = NULL; /* User-defined payload key */
-
- conv_payload_get_string(result, "result_type", &result_type);
-
- if (!strcmp(result_type, "onConnect"))
- /* Do something for onConnect */
- else if (!strcmp(result_type, "onStart"))
- /* Do something for onStart */
- else if (!strcmp(result_type, "onPublish"))
- /* Do something for onPublish */
- else if (!strcmp(result_type, "onStop"))
- /* Do something for onStop */
- else if (!strcmp(result_type, "onDisconnect"))
- /* Do something for onDisconnect */
- else if (!strcmp(result_type, "onClientDisconnect"))
- /* Do something for onClientDisconnect */
- else if (!strcmp(result_type, "onRead"))
- /* Do something for onRead */
- else
- /* Parsing user-defined portion of the payload */
-}
-</pre>
-<p>The structure of the listener is the same for both server and client sides.</p>
-</li>
-<li>If the application sends a payload using the <code>conv_service_publish()</code> function, the listener callback on the receiver side gets the following packet:
-<pre class="prettyprint">
-"result_type": "onMessage"
-"from": unique ID of a client which sends the message
-"user_defined_key": custom user-defined key in the payload
-</pre>
-<p>The following example demonstrates how to process a custom payload:</p>
-<pre class="prettyprint">
-void
-custom_listener_example(conv_service_h handle, conv_channel_h channel,
- int error, conv_payload_h result, void *user_data)
-{
- char *result_type = NULL;
- char *payload_type = NULL; /* User-defined payload key */
-
- conv_payload_get_string(result, "result_type", &result_type);
-
- if (!strcmp(result_type, "onMessage")) {
- /* Parsing user-defined portion of the payload */
- conv_payload_get_string(result, "payload_type", &payload_type);
- if (!strcmp(payload_type, "Good_News"))
- /* Do something for the payload of the "Good News" type */
- else if (!strcmp(payload_type, "Bad_News"))
- /* Do something for the payload of the "Bad News" type */
- }
-}
-</pre>
-<p>The example assumes that the message has a custom <code>payload_type</code> key and a string value that takes 1 of 2 variants: <code>"Good_News"</code> and <code>"Bad_News"</code>.</p>
-<p>In addition to strings, you can use a raw byte array payload. The <code>conv_payload_set_string()</code>, <code>conv_payload_get_string()</code>, <code>conv_payload_set_byte()</code>, and <code>conv_payload_get_byte()</code> functions are useful for working with payload types.</p>
-</li>
-</ul>
-</li>
-<li>
-<p>On the server side, an instance of the app communication service must be created and started by the application.</p>
-<p>At first, a service handle is created and assigned with the <code>CONV_SERVICE_APP_TO_APP_COMMUNICATION</code> type. Then, a channel is constructed with a pair of parameters: URI of the application, or the value specified in the application manifest, and a developer-defined channel ID. Finally, the listener is registered and the service is started.</p>
-<p>The following example demonstrates the server application creation and start:</p>
-<pre class="prettyprint">
-static void
-server_application_initialization_example()
-{
- /* Creating an instance of the app communication service */
- conv_service_create(&service_handle);
- conv_service_set_type(service_handle, CONV_SERVICE_APP_TO_APP_COMMUNICATION);
-
- /* Specifying service channel */
- /* Note, the URI value corresponds to URI of your server-side app */
- conv_channel_create(&channel_handle);
- conv_channel_set_string(channel_handle, "uri", "org.example.d2d_test");
- conv_channel_set_string(channel_handle, "channel_id", "test");
-
- /* Starting the service */
- /* Note that the listener must be set before starting the service */
- conv_service_set_listener_cb(service_handle, server_message_listener, NULL);
- conv_service_start(service_handle, channel_handle, NULL);
-}
-</pre>
-</li>
-<li>On the client side, the app communication service handle must not be created, but obtained during the discovery. This means that no separate initialization is required on the client side.
-<p>The client application can start the service and remotely launch the application on the server side using the obtained service handle.</p>
-
-<p>A client application registers a listener callback and starts the service:</p>
-<pre class="prettyprint">
-int
-app_communication_start_client_example()
-{
- conv_service_connect(service_handle, connect_cb, NULL);
-
- conv_channel_h channel_handle = NULL;
- conv_channel_create(&channel_handle);
- conv_channel_set_string(channel_handle, "uri", "org.example.d2d_test");
- conv_channel_set_string(channel_handle, "channel_id", "test");
-
- conv_service_set_listener_cb(service_handle, message_listener, NULL);
- conv_service_start(service_handle, channel_handle, NULL);
-
- conv_channel_destroy(channel_handle);
-}
-</pre>
-<p>The service must be connected to the remote device using the <code>conv_service_connect()</code> function. The <code>service_handle</code> in this example is the one that the client application discovered earlier. The connection callback is omitted in this example for simplicity. However, it is meaningful to carefully implement it and observe that the connection result is <code>CONV_ERROR_NONE</code>. The payload retrieved to the callback is typically empty.</p>
-<p>A channel is set using the <code>conv_channel_set_string()</code> function. The start command goes to the server side, where the app communication service launches the application by the URI specified in the channel. The command result is asynchronously retrieved in the listener callback.</p>
-</li>
-<li>
-<p>When you finish using the service channel, stop it using the <code>conv_service_stop()</code> function. When all clients have stopped using the service channel, the server side automatically terminates the application.</p>
-<p>The server listener is automatically deregistered by the framework in the <code>conv_service_stop()</code> function, so you do not need to do it explicitly. The use of the <code>conv_service_stop()</code> function is almost the same as the service start:</p>
-<pre class="prettyprint">
-int
-app_communication_stop_client_example()
-{
- conv_channel_h channel_handle = NULL;
- conv_channel_create(&channel_handle);
- conv_channel_set_string(channel_handle, "uri", "org.example.d2d_test");
- conv_channel_set_string(channel_handle, "channel_id", "test");
-
- conv_service_stop(service_handle, channel_handle, NULL);
-
- conv_channel_destroy(channel_handle);
-}
-</pre>
-</li>
-</ol>
-
-<h2 id="send_message">Sending Messages to the Server Application</h2>
-
-<p>After starting a service channel, you can send a message or data to the remote server application. A payload to send to the other side must be packaged as shown in the following example. The app communication service accepts both string and byte types of payload, using the <code>conv_payload_set_string()</code> and <code>conv_payload_set_byte()</code> functions.</p>
-
-<p>You can design a set of application-specific key-value pairs for maintaining the communication protocol between remote applications. It requires implementing a publishing routine for sending messages and a <a href="#listener_callback">listener routine</a> for receiving and recognizing the messages on both client and server sides.</p>
-
-<pre class="prettyprint">
-int
-publish_example()
-{
- conv_service_h service_handle = (conv_service_h)data;
- conv_channel_h channel_handle;
- conv_payload_h payload_handle;
-
- conv_channel_create(&channel_handle);
- conv_channel_set_string(channel_handle, "uri", "org.example.d2d_test");
- conv_channel_set_string(channel_handle, "channel_id", "test");
-
- conv_payload_create(&payload_handle);
- conv_payload_set_string(payload_handle, "user_defined_key", "user_defined_value");
-
- conv_service_publish(service_handle, channel_handle, payload_handle);
- /* or conv_service_read(service_handle, channel_handle, NULL); */
-}
-</pre>
-<p>The channel used in this example is the same as described before. The <code>conv_service_publish()</code> function delivers the payload, composed of the <code>"user_defined_key"</code> and <code>"user_defined_value"</code> pairs, through the network to the remote server application where it is passed in the listener callback.</p>
-
-<p>In the app communication service, the <code>conv_service_read()</code> function is only a command to get the information about the clients connected to the same channel. The <code>conv_service_read()</code> is called with <code>NULL</code> payload and it does not require additional parameters. You can <a href="#result_type">receive various information</a> in the <code>conv_service_read()</code> function.</p>
-
-
-<h2 id="init_remote">Using the Remote App Control Service</h2>
-
-<p>The basic flow for the remote app control service is to build a payload with an application control handle, send it to a remote device and, optionally, receive a remote application control result.</p>
-<p>To start the remote app control service, publish a message, and stop the service:</p>
-<ol>
-<li>Register a listener callback.
-<p>In the remote app control service, the application control, delivered to a remote device, is directly processed just like a local application control. It means that there is no need for a receiver to implement a special receiving routine on the remote device, and no need to register a listener callback on the receiver side. Instead, the listener callback is useful on the sender side to check whether the function is delivered to the remote device and processed correctly.</p>
-
-<p>The following example shows a listener callback, which handled the result of the access control process related to the remote app control service. After the user of the remote device has decided to allow or deny access with the passcode, the user choice is delivered to the remote device with the <code>"onStart"</code> result type and predefined error types:</p>
-<ul><li>If the passcode is entered correctly, the <code>"onStart"</code> returns with the <code>CONV_ERROR_NONE</code> value.</li>
-<li>Otherwise, the <code>"onStart"</code> comes with the <code>CONV_ERROR_INVALID_OPERATION</code> value.</li></ul>
-<pre class="prettyprint">
-static void
-service_result_callback(conv_service_h service_handle, conv_channel_h channel_handle,
- conv_error_e error, conv_payload_h result, void* user_data)
-{
- char *reply_result = NULL;
- conv_payload_get_string(result, "result_type", &reply_result);
- if (!strcmp(reply_result, "onStart")) {
- if (error == CONV_ERROR_NONE) {
- /* Allowed */
- conv_service_publish(service_handle, NULL, payload_handle);
- conv_service_stop(service_handle, NULL, payload_handle);
- conv_payload_destroy(payload_handle);
- payload_handle = NULL;
- } else if (error == CONV_ERROR_INVALID_OPERATION) {
- /* Denied */
- conv_service_stop(service_handle, NULL, payload_handle);
- conv_payload_destroy(payload_handle);
- payload_handle = NULL;
- }
- }
- free(reply_result);
-}
-</pre>
-</li>
-<li>Start the remote app control service.
-<p>After registering the listener callback, start the service with the service handle, obtained from the near-by device discovery previously. Build an application control handle in a payload to launch an application on a remote device.</p>
-<p>The following example launches the <code>"org.example.d2d_test"</code> application:</p>
-<pre class="prettyprint">
-int
-app_control_service()
-{
- conv_service_set_listener_cb(service_handle, message_listener, NULL);
- conv_service_start(service_handle, NULL, NULL);
-
- conv_payload_h payload_handle;
- conv_payload_create(&payload_handle);
-
- app_control_h app_control = NULL;
- app_control_create(&app_control);
- app_control_set_app_id(app_control, "org.example.d2d_test");
- app_control_set_operation(app_control, APP_CONTROL_OPERATION_MAIN);
-
- conv_payload_set_app_control(payload_handle, "app_control", app_control);
- conv_payload_set_string(payload_handle, "reply", "1");
-
- conv_service_publish(service_handle, NULL, payload_handle);
-}
-</pre>
-<p>The application control handle can be built <a href="../app_management/app_controls_n.htm">using the App Control functions</a>. In the payload, there is a special <code>"reply"</code> string field, which indicates if an application control reply is returned after the sent application control is processed remotely. In other words, if <code>"reply"</code> is <code>"1"</code>, the remote device processes the application control and sends the resulting application control to the original device. In this case, the listener callback on the original device waits for an application control reply. This can be useful in designing interactive applications, such as chatting applications, in which bi-directional interplay service is required. If <code>"reply"</code> is <code>"0"</code> or this field is omitted, no response is received in the listener.</p>
-</li>
-</ol>
-
-<h2 id="payload">Predefined Payload Fields</h2>
-
-<p>To send payloads, you can use various functions: use the <code>conv_service_start()</code> function to start a service, the <code>conv_service_read()</code> function to read information from the remote device, the <code>conv_service publish()</code> function to send data or messages, and the <code>conv_service_stop()</code> function to stop the service. The app communication service recognizes several predefined payload fields, including the <code>result_type</code>, which are used to specify the payload type or the quick response of some functions. The service implicitly adds these fields to the payload.</p>
-
-<div class="note">
- <strong>Note</strong>
- The <code>conv_service_read()</code> function is not used in the remote app control service.
-</div>
-
-<p>When the <code>conv_service_start()</code>, <code>conv_service_publish()</code>, or <code>conv_service_stop()</code> function is called, a quick notice for success or failure with a specific <code>result_type</code> and extra information returns back to the function caller. For example, in case of the <code>conv_service_read()</code> function, the response includes the <code>result_type</code> of <code>onRead</code> and a list of connected clients. For the general payload sent from the other device with the <code>conv_service_publish()</code> and received in the client device listener, the <code>result_type</code> is <code>onMessage</code> and the message or data is stored in the payload argument. The detailed information for the predefined fields and payload formats is summarized in the following tables.</p>
-
-<p>The success or failure result (including the correctness of the passcode input in the access control popup in the remote app control service) is delivered by the <code>conv_error_e</code> error parameter (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__D2D__CONVERGENCE__MANAGER__FRAMEWORK.html#ga37d3a4410cd70ca1253f20ce4005ac60">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__D2D__CONVERGENCE__MANAGER__FRAMEWORK.html#ga37d3a4410cd70ca1253f20ce4005ac60">wearable</a> applications) of the listener callback.</p>
-
-<p align="center" class="Table"><strong>Table: Predefined fields for the app communication service payloads</strong></p>
-<table id="result_type">
- <tbody>
- <tr>
- <th>Function</th>
- <th>Predefined payload field</th>
- </tr>
- <tr>
- <td rowspan="3"><code>conv_service_start()</code></td>
- <td>Sent to the device that calls the function when connected to the remote server:
- <ul>
- <li><code>"result_type"</code>: <code>"onConnect"</code></li>
- <li><code>"client_is_host"</code>: Whether the device is a server application (remote server). The possible values are 0 and 1.</li>
- <li><code>"client_connect_time"</code>: Connection time</li>
- <li><code>"client_id"</code>: Unique client ID</li>
- </ul>
- </td>
- </tr>
- <tr>
- <td>Sent to the device that calls the function when the application launch succeeds or fails:
- <ul>
- <li><code>"result_type"</code>: <code>"onStart"</code></li>
- </ul>
- </td>
- </tr>
- <tr>
- <td>Sent to other clients connected to the remote server:
- <ul>
- <li><code>"result_type"</code>: <code>"onClientConnect"</code></li>
- <li><code>"client_is_host"</code>: Whether the device is a server application (remote server). The possible values are 0 and 1.</li>
- <li><code>"client_connect_time"</code>: Connection time</li>
- <li><code>"client_id"</code>: Unique client ID</li>
- </ul>
- </td>
- </tr>
- <tr>
- <td><code>conv_service_publish()</code></td>
- <td><code>"result_type"</code>: <code>"onPublish"</code></td>
- </tr>
- <tr>
- <td rowspan="3"><code>conv_service_stop()</code></td>
- <td>Sent to the device which calls the function when the server application stops:
- <ul>
- <li><code>"result_type": "onStop"</code></li>
- </ul>
- </td>
- </tr>
- <tr>
- <td>Sent to the device which calls the function when disconnected from the remote server:
- <ul>
- <li><code>"result_type"</code>: <code>"onDisconnect"</code></li>
- <li><code>"client_is_host"</code>: Whether the device is a server application (remote server). The possible values are 0 and 1.</li>
- <li><code>"client_connect_time"</code>: Connection time</li>
- <li><code>"client_id"</code>: Unique client ID</li>
- </ul>
- </td>
- </tr>
- <tr>
- <td>Sent to other clients connected to the remote server:
- <ul>
- <li><code>"result_type"</code>: <code>"onClientDisconnect"</code></li>
- <li><code>"client_is_host"</code>: Whether the device is a server application (remote server). The possible values are 0 and 1.</li>
- <li><code>"client_connect_time"</code>: Connection time</li>
- <li><code>"client_id"</code>: Unique client ID</li>
- </ul>
- </td>
- </tr>
- <tr>
- <td><code>conv_service_read()</code></td>
- <td>
- <ul>
- <li><code>"result_type"</code>: <code>"onRead"</code></li>
- <li><code>"read_type"</code>: <code>"getClients"</code></li>
- <li><code>"client_list"</code>: <code>json-array</code> type client lists
- <p><code>[ {"client_is_host"</code>: Whether the device is a server application (remote server). The possible values are 0 and 1.</p>
- <p><code>"client_connect_time"</code>: Connection time</p>
- <p><code>"client_id"</code>: Unique client ID</p>
- <p><code>}, ... ]</code></p>
- </li>
- </ul>
- </td>
- </tr>
- <tr>
- <td><code>conv_service_listener_cb()</code>
- <p>(When a message is received)</p>
- </td>
- <td>Sent to other clients and server applications, registered listener callback:
- <ul>
- <li><code>"result_type"</code>: <code>"onMessage"</code></li>
- <li><code>"from"</code>: Unique client ID which sends the message</li>
- </ul>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p align="center" class="Table"><strong>Table: Predefined fields for receiving the remote app control service payloads</strong></p>
-<table>
- <tbody>
- <tr>
- <th>Function</th>
- <th>Predefined fields</th>
- </tr>
- <tr>
- <td><code>conv_service_start()</code></td>
- <td><code>"result_type"</code>: <code>"onStart"</code></td>
- </tr>
- <tr>
- <td><code>conv_service_publish()</code></td>
- <td>
- <ul>
- <li><code>"result_type"</code>: <code>"onPublish"</code></li>
- <li><code>"app_control_reply"</code>: Application control data, only valid if the receiver replied with an <code>app_control</code>, which means that the sender sent a payload with a <code>"reply"</code> of <code>"1"</code>.</li>
- <li><code>"app_control_request"</code>: Requested application control data, only valid if the receiver replied with an <code>app_control</code> value, which means that the sender sent a payload with a <code>"reply"</code> of <code>"1"</code>.</li>
- <li><code>"app_control_result"</code>: The <code>app_control_result_e</code> value for the request, only valid if the receiver replied with a value, which means that the sender sent a payload with a <code>"reply"</code> of <code>"1"</code>.</li>
- </ul>
- </td>
- </tr>
- <tr>
- <td><code>conv_service_stop()</code></td>
- <td><code>"result_type"</code>: <code>"onStop"</code></td>
- </tr>
- </tbody>
-</table>
-
-<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>
\ No newline at end of file
projects / sdk / online-doc.git / commitdiff
