Wearable native

Remote App Control

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, as needed.

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 functions and data types of the Remote App Control API, include the <remote_app_control.h> header file in your application:
    #include <remote_app_control.h>
    

    To ensure that a Remote App Control function has been executed properly, make sure that the return is equal to REMOTE_APP_CONTROL_ERROR_NONE.

Creating a Remote App Control Object

Before you can launch a remote application, you must create a remote application control object:

  1. Declare the application control handle to be used for the communication:
    remote_app_control_h remote_app_control;
    
  2. Initialize the handle with the remote_app_control_create() function:
    int ret = REMOTE_APP_CONTROL_ERROR_NONE;
    
    ret = remote_app_control_create(&remote_app_control);
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    

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 name with the remote_app_control_set_package() function.

    The package name must be set to the remote application control handle. If it is not set, the REMOTE_APP_CONTROL_ERROR_INVALID_PARAMETER result is returned for the launch.

    ret = remote_app_control_set_package(remote_app_control, "com.your.package");
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    
  2. Set the application name with the remote_app_control_set_application() function.

    The application name must be set to the remote application control handle. If it is not set, the REMOTE_APP_CONTROL_ERROR_INVALID_PARAMETER result is returned for the launch.

    ret = remote_app_control_set_application(remote_app_control, "com.your.package.MainActivity");
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    
  3. Set extra data to the remote application control with the remote_app_control_set_data() function, if needed.

    The caller application can set additional private string data, which is sent to the remote application and can be processed by the remote application.

    ret = remote_app_control_set_data(remote_app_control, "some string data");
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    
  4. Define the remote reply callback (remote_app_control_reply_cb()), 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 under the caller application's default main loop context.

    static void
    remote_reply_cb(remote_app_control_h request, remote_app_control_h reply, remote_app_control_result_e result, void *user_ data)
    {
        if (result == REMOTE_APP_CONTROL_RESULT_SUCCEEDED) {
            if (app_control_get_data(reply, &value) == REMOTE_APP_CONTROL_ERROR_NONE)
                /* Handle reply */
        } else {
            /* Check the return result and handle */
        }
    }
    
  5. Launch the remote application explicitly with the remote application control handle.

    Once the required handle attributes are set, use the remote_app_control_send_launch_request() function to launch the remote application.

    ret = remote_app_control_send_launch_request(remote_app_control, remote_reply_cb, NULL);
    if (ret == REMOTE_APP_CONTROL_ERROR_NONE)
        /* Launch success */
    else
        /* Launch fail */
    
  6. When no longer needed, free the remote application control with the remote_app_control_destroy() function:
    ret = remote_app_control_destroy(remote_app_control);
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    

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 with the remote_app_control_set_operation() function.

    To operation must be set to the remote application control handle. Currently, the REMOTE_APP_CONTROL_OPERATION_VIEW operation is supported to launch the remote application with a URI.

    ret = remote_app_control_set_operation(remote_app_control, REMOTE_APP_CONTROL_OPERATION_VIEW);
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    
  2. Set the URI with the remote_app_control_set_uri() function.

    To URI must be set to the remote application control handle.

    ret = remote_app_control_set_uri(remote_app_control, "http://developer.samsung.com");
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    
  3. Launch the remote application implicitly with the remote application control handle.

    Once the required handle attributes are set, use the remote_app_control_send_launch_request() function to launch the remote application.

    ret = remote_app_control_send_launch_request(remote_app_control, NULL, NULL);
    if (ret == REMOTE_APP_CONTROL_ERROR_NONE)
        /* Launch success */
    else
        /* Launch fail */
    
  4. When no longer needed, free the remote application control with the remote_app_control_destroy() function:
    ret = remote_app_control_destroy(remote_app_control);
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    

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 (remote_app_control_h):

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

    To get the operation, use the remote_app_control_get_operation() function:

    char *operation = NULL;
    ret = remote_app_control_get_operation(remote_app_control, &operation);
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    
  • URI: URI data for launching the remote application

    To get the URI, use the remote_app_control_get_uri() function:

    char *uri = NULL;
    ret = remote_app_control_get_uri(remote_app_control, &uri);
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    
  • Application: Activity name of the remote application

    To get the application, use the remote_app_control_get_application() function:

    char *application = NULL;
    ret = remote_app_control_get_application(remote_app_control, &application);
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    
  • Package: Package name of the remote application

    To get the package, use the remote_app_control_get_package() function:

    char *package = NULL;
    ret = remote_app_control_get_package(remote_app_control, &package);
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    
  • Data: Additional information for the launch request and the result of the request

    To get the data, use the remote_app_control_get_data() function:

    char *application = NULL;
    ret = remote_app_control_get_data(remote_app_control, &data);
    if (ret != REMOTE_APP_CONTROL_ERROR_NONE)
        /* Error handling */
    

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);
    
Go to top