Class AppControl

Definition

Namespace:

Tizen.Applications

Assembly:

Tizen.Applications.Common.dll

API Level:

3

Represents the control message to exchange between applications.

public class AppControl

Inheritance

Object

AppControl

Derived

ReceivedAppControl

ReceivedAppControl

Examples

public class AppControlExample : UIApplication
{
    /// ...
    protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
    {
        AppControl appControl = new AppControl();
        appControl.ApplicationId = "org.tizen.calculator";
        AppControl.SendLaunchRequest(appControl, (launchRequest, replyRequest, result) => {
            // ...
        });
    }
}

Constructors

AppControl()

Initializes the instance of the AppControl class.

Declaration

public AppControl()

Exceptions

Type	Condition
InvalidOperationException	Thrown when failed to create the AppControl handle.

API Level: 3

AppControl(Boolean)

Initializes the instance of the AppControl class with a parameter.

Declaration

public AppControl(bool enableAppStartedResultEvent)

Parameters

Type	Name	Description
Boolean	enableAppStartedResultEvent	The flag value to receive an additional launch result event on the launch request.

Exceptions

Type	Condition
InvalidOperationException	Thrown when failed to create the AppControl handle.

API Level: 3

AppControl(SafeAppControlHandle)

Initializes the instance of the AppControl class with the SafeAppControlHandle.

Declaration

public AppControl(SafeAppControlHandle handle)

Parameters

Type	Name	Description
SafeAppControlHandle	handle

API Level: 3

Properties

ApplicationId

Gets and sets the application ID to explicitly launch.

Declaration

public string ApplicationId { get; set; }

Property Value

Type	Description
String	(if the application ID is null for setter, it clears the previous value.)

Examples

AppControl appControl = new AppControl();
appControl.ApplicationId = "org.tizen.calculator";
Log.Debug(LogTag, "ApplicationId: " + appControl.ApplicationId);

API Level: 3

Category

Gets and sets the explicit category.

Declaration

public string Category { get; set; }

Property Value

Type	Description
String	(if the category is null for setter, it clears the previous value.)

API Level: 3

ComponentId

Gets and sets the component ID to explicitly launch a component.

Declaration

public string ComponentId { get; set; }

Property Value

Type	Description
String	(if the component ID is null for setter, it clears the previous value.) From Tizen 5.5, a new application model is supported that is component-based application. This property is for launching component-based application. If it's not set, the main component of component-based application will be launched. If the target app is not component-based application, setting property is meaningless.

Examples

AppControl appControl = new AppControl();
appControl.ApplicationId = "org.tizen.component-based-app"; // component-based application
appControl.ComponentId = "org.tizen.frame-component";
AppControl.SendLaunchRequest(appControl);

API Level: 6

ExtraData

Gets the collection of the extra data.

Declaration

public AppControl.ExtraDataCollection ExtraData { get; }

Property Value

Type	Description
AppControl.ExtraDataCollection	Extra data for communication between AppControls.

Examples

AppControl appControl = new AppControl();
appControl.ExtraData.Add("key", "value");
...

API Level: 3

LaunchMode

Gets and sets the launch mode of the application.

Declaration

public AppControlLaunchMode LaunchMode { get; set; }

Property Value

Type

Description

AppControlLaunchMode

Although, LaunchMode were set as AppControlLaunchMode.Group, the callee application would be launched as a single mode if the manifest file of callee application defined the launch mode as "single". This property can just set the preference of the caller application to launch an application. Sub-applications, which were launched as a group mode always have own process. Since Tizen 3.0, if launch mode is not set in the caller application control, this property returns the AppControlLaunchMode.Single launch mode.

Examples

AppControl appControl = new AppControl();
appControl.LaunchMode = AppControlLaunchMode.Group;

API Level: 3

Mime

Gets and sets the explicit MIME type of the data.

Declaration

public string Mime { get; set; }

Property Value

Type	Description
String	(if the mime is null for setter, it clears the previous value.)

Examples

AppControl appControl = new AppControl();
appControl.Mime = "image/jpg";
Log.Debug(LogTag, "Mime: " + appControl.Mime);

API Level: 3

Operation

Gets and sets the operation to be performed.

Declaration

public string Operation { get; set; }

Property Value

Type	Description
String	The operation is the mandatory information for the launch request. If the operation is not specified, AppControlOperations.Default is used for the launch request. If the operation is AppControlOperations.Default, the package information is mandatory to explicitly launch the application. (if the operation is null for setter, it clears the previous value.)

Examples

AppControl appControl = new AppControl();
appControl.Operation = AppControlOperations.Default;
Log.Debug(LogTag, "Operation: " + appControl.Operation);

API Level: 3

SafeAppControlHandle

Gets the SafeAppControlHandle instance.

Declaration

public SafeAppControlHandle SafeAppControlHandle { get; }

Property Value

Type	Description
SafeAppControlHandle

API Level: 3

Uri

Gets and sets the URI of the data.

Declaration

public string Uri { get; set; }

Property Value

Type

Description

String

Since Tizen 2.4, if the parameter 'uri' is started with 'file://' and it is a regular file in this application's data path, which can be obtained by property DataPath in ApplicationInfo class, it will be shared to the callee application. Framework will grant a temporary permission to the callee application for this file and revoke it when the callee application is terminated. The callee application can just read it. (if the uri is null for setter, it clears the previous value.)

Examples

public class AppControlExample : UIApplication
{
    ...
    protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
    {
        ...
        AppControl appControl = new AppControl();
        appContrl.Uri = this.ApplicationInfo.DataPath + "image.jpg";
        Log.Debug(LogTag, "Set Uri: " + appControl.Uri);
    }
}

API Level: 3

Methods

GetMatchedApplicationIds(AppControl)

Retrieves all applications that can be launched to handle the given app_control request.

Declaration

public static IEnumerable<string> GetMatchedApplicationIds(AppControl control)

Parameters

Type	Name	Description
AppControl	control	The AppControl.

Returns

Type	Description
IEnumerable<String>	ApplicationIds.

Examples

IEnumerable<string> applicationIds = AppControl.GetMatchedApplicationIds(control);
if (applicationIds != null)
{
    foreach (string id in applicationIds)
    {
        // ...
    }
}

Exceptions

Type	Condition
InvalidOperationException	Thrown when failed because of an invalid parameter.

API Level: 3

SendLaunchRequest(AppControl)

Sends the launch request.

Declaration

public static void SendLaunchRequest(AppControl launchRequest)

Parameters

Type	Name	Description
AppControl	launchRequest	The AppControl.

Remarks

The operation is mandatory information for the launch request. If the operation is not specified, AppControlOperations.Default is used by default. If the operation is AppControlOperations.Default, the application ID is mandatory to explicitly launch the application.
Since Tizen 2.4, the launch request of the service application over out of packages is restricted by the platform. Also, implicit launch requests are NOT delivered to service applications since 2.4. To launch a service application, an explicit launch request with the application ID given by property ApplicationId MUST be sent.

Examples

AppControl appControl = new AppControl();
appControl.ApplicationId = "org.tizen.calculator";
AppControl.SendLaunchRequest(appControl);

Exceptions

Type	Condition
ArgumentNullException	Thrown when failed because of a null argument.
InvalidOperationException	Thrown when failed because of an invalid operation.
TimeoutException	Thrown when failed because of timeout.

API Level: 3

Privilege Level: public

Privilege: http://tizen.org/privilege/appmanager.launch

SendLaunchRequest(AppControl, AppControlReplyCallback)

Sends the launch request.

Declaration

public static void SendLaunchRequest(AppControl launchRequest, AppControlReplyCallback replyAfterLaunching)

Parameters

Type	Name	Description
AppControl	launchRequest	The AppControl.
AppControlReplyCallback	replyAfterLaunching	The callback function to be called when the reply is delivered.

Remarks

The operation is mandatory information for the launch request. If the operation is not specified, AppControlOperations.Default is used by default. If the operation is AppControlOperations.Default, the application ID is mandatory to explicitly launch the application.
Since Tizen 2.4, the launch request of the service application over out of packages is restricted by the platform. Also, implicit launch requests are NOT delivered to service applications since 2.4. To launch a service application, an explicit launch request with the application ID given by property ApplicationId MUST be sent.

Examples

AppControl appControl = new AppControl();
appControl.ApplicationId = "org.tizen.calculator";
AppControl.SendLaunchRequest(appControl, (launchRequest, replyRequest, result) => {
    // ...
});

Exceptions

Type	Condition
ArgumentException	Thrown when failed because of the argument is invalid.
AppNotFoundException	Thrown when the application to run is not found.
LaunchFailedException	Thrown when the request failed to launch the application.
LaunchRejectedException	Thrown when the launch request is rejected.
OutOfMemoryException	Thrown when the memory is insufficient.
PermissionDeniedException	Thrown when the permission is denied.
TimeoutException	Thrown when failed because of timeout.

API Level: 3

Privilege Level: public

Privilege: http://tizen.org/privilege/appmanager.launch

SendLaunchRequestAsync(AppControl, AppControlReplyCallback)

Sends the launch request asynchronously.

Declaration

public static Task<AppControlResult> SendLaunchRequestAsync(AppControl launchRequest, AppControlReplyCallback replyAfterLaunching)

Parameters

Type	Name	Description
AppControl	launchRequest	The AppControl.
AppControlReplyCallback	replyAfterLaunching	The callback function to be called when the reply is delivered.

Returns

Type	Description
Task<AppControlResult>	A task with the result of the launch request.

Remarks

The operation is mandatory information for the launch request. If the operation is not specified, AppControlOperations.Default is used by default. If the operation is AppControlOperations.Default, the application ID is mandatory to explicitly launch the application.
Since Tizen 2.4, the launch request of the service application over out of packages is restricted by the platform. Also, implicit launch requests are NOT delivered to service applications since 2.4. To launch a service application, an explicit launch request with the application ID given by property ApplicationId MUST be sent.

Exceptions

Type	Condition
ArgumentException	Thrown when failed because of the argument is invalid.
AppNotFoundException	Thrown when the application to run is not found.
LaunchRejectedException	Thrown when the launch request is rejected.

API Level: 6

Privilege Level: public

Privilege: http://tizen.org/privilege/appmanager.launch

SendTerminateRequest(AppControl)

Sends the terminate request to the application that is launched by AppControl.

Declaration

public static void SendTerminateRequest(AppControl terminateRequest)

Parameters

Type	Name	Description
AppControl	terminateRequest	The AppControl.

Remarks

You are not allowed to terminate other general applications using this API. This API can be used to terminate sub-applications, which were launched as a group mode by the caller application. Once the callee application is being terminated by this API, other applications, which were launched by the callee application as a group mode will be terminated as well.

Examples

AppControl terminateRequest = new AppControl();
terminateRequest.ApplicationId = "org.tizen.calculator";
AppControl.SendTerminateRequest(terminateRequest);

Exceptions

Type	Condition
ArgumentException	Thrown when failed because of the argument is invalid.
InvalidOperationException	Thrown when failed because of an invalid operation.
TimeoutException	Thrown when failed because of timeout.

API Level: 3