Remote App Control Guide

A remote application control (app control) is a way of interacting with a remote application installed on a remote host device. The remote app control can be used to invoke or launch a remote application explicitly or implicitly based on the available information, such as operation, application package name, and URI, and to receive a reply from the remote device's launched application. The remote application can be launched in 2 ways, after you have created a remote application control object:

  • Explicit launch: The remote application can be launched by explicitly defining the package and application name of the remote application in the app control request.
  • Implicit launch: The remote application can be launched implicitly by defining the operation and URI of the remote application in the app control request. You can use either of the launch methods, based on the available knowledge of remote application attributes, such as the package name, application name, operation, and URI. You can also retrieve the remote application attribute values, if needed.
  • Remote App Control API Reference : Download

Prerequisites

To enable your application to use the remote application control functionality:

  1. To use the Remote App Control API, the application has to request permission by adding the following privileges to the tizen-manifest.xml file:

    <privileges>
     <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
     <privilege>http://developer.samsung.com/tizen/privilege/accessoryprotocol</privilege>
</privileges>

  2. To use the methods and properties of the RemoteAppControl classes, include the Samsung.RemoteAppControl namespace in your application:

    using Samsung.RemoteAppControl;

Creating Remote App Control Object

Create RemoteAppControl to be used for the communication:

RemoteAppControl remoteAppControl = new RemoteAppControl();

Launching a Remote Application Explicitly

If you know the remote application package and application names, you can use the explicit launch method, and you do not need to define the operation. The explicit launch is currently supported on the Android platform.

  1. Set the Package instance
  • The package name of the remote device to explicitly launch.
    The package name must be set to the remote application control handle.
    remoteAppControl.Package = "com.your.package";
  1. Set the ApplicationId instance
  • The application identifier of the remote device to explicitly launch.
    The application name must be set to the remote application control handle.
    remoteAppControl.ApplicationId = "com.your.package.MainActivity";
  1. Set the Data instance
  • The data which will be sent to the remote application. The caller application can set additional private string data, which is sent to the remote application and can be processed by the remote application.
    remoteAppControl.Data = "some string data";

  1. Define the remote reply callback(RemoteAppControlReplyCallback), if needed. If the caller application wants to receive a reply from the launched remote application, it must register a callback function under the remote application control handle. When the remote application sends a reply, the callback is executed.

    RemoteAppControlReplyCallback remoteAppControlReplyCallback;
void Remotecallback(RemoteAppControl reqest, RemoteAppControl reply, RemoteAppControlReplyResult result)
{
	/* Handle reply */
};
remoteAppControlReplyCallback = Remotecallback;

  2. Launch the remote application explicitly with the remote application control handle. Once the required handle attributes are set, use the SendLaunchRequest() function to launch the remote application.

    RemoteAppControl.SendLaunchRequest(remoteAppControl, remoteAppControlReplyCallback);

Launching a Remote Application Implicitly

If you know the operation and URI registered by the remote application, you can use the implicit launch method. The implicit launch does not support sending results back from the launched remote application, and you cannot send any extra data to the remote application.

  1. Set the Operation instance. The operation must be set to the remote application control handle. Currently, the OPERATION_VIEW operation is supported to launch the remote application with a URI.

    remoteAppControl.Operation = RemoteAppControl.OPERATION_VIEW;

  2. The URI instance must be set to the remote application control handle.

    remoteAppControl.Uri = "http://developer.samsung.com";

  3. Launch the remote application implicitly with the remote application control handle. Once the required handle attributes are set, use the SendLaunchRequest() function to launch the remote application.

    RemoteAppControl.SendLaunchRequest(remoteAppControl, null);

Retrieving Remote Application Control Attribute Values

The remote application control can hold various attributes, and you can access their values from the remote application control handle instance

  • Operation: Action to be performed by the remote application control

  • URI: URI data for launching the remote application

  • ApplicationId: Activity name of the remote application

  • Package: Package name of the remote application

  • Data: Additional information for the launch request and the result of the request

    string operation = remoteAppControl.Operation;
string uri = remoteAppControl.Uri;
string applicationId = remoteAppControl.ApplicationId;
string package = remoteAppControl.Package;
string data = remoteAppControl.Data;

Developing the Remote Android Application

When you develop a remote Android host application that can be launched through remote application control requests, you must take the following remote application control features into account:

The host application Android Activity receives data when it is explicitly launched through a remote application control. The following table lists the information data received by Android Activity. The information applies to explicit launches only.

Table: Data received by the host application

Key Description
remote_device_id Bluetooth/Wi-Fi address of the remote device
remote_app_id Application ID of the caller application on a Galaxy Watch device that invoked the launch request
remote_extra_data Extra data explicitly added by the caller application on the Galaxy Watch device that invoked the launch request

  • Galaxy Watch App can launch Android Activity to send data to the Android Host App. Android app can receive the data using getIntent() method and can determine if this data is required by the caller application. To receive the String sent from Galaxy Watch App, you can use intent object's getStringExtra() method.

    Intent intent = getIntent();
String extraData = intent.getStringExtra("remote_extra_data");
if(extraData != null){
	/*...*/
}

  • The Android host application can send a reply result back to the Galaxy Watch application that initiated an explicit launch request. Use the getCallingActivity() Android method to determine whether a reply is required by the caller application. When sending the reply, you can add extra data on the intent data object:

    Intent newintent = new Intent();
newintent.putExtra("remote_extra_data", data);
setResult(RESULT_OK, newintent);