Class AppControl

Definition

Namespace:
Tizen.Applications
Assembly:
Tizen.Applications.Common.dll
API Level:
3

Represents the control message to exchange between applications.

C#
Copy
public class AppControl
Inheritance
System.Object
AppControl
Derived
Examples
Copy
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

View Source

AppControl()

Initializes the instance of the AppControl class.

Declaration
C#
Copy
public AppControl()
Exceptions
Type Condition
System.InvalidOperationException

Thrown when failed to create the AppControl handle.

API Level: 3
View Source

AppControl(Boolean)

Initializes the instance of the AppControl class with a parameter.

Declaration
C#
Copy
public AppControl(bool enableAppStartedResultEvent)
Parameters
Type Name Description
System.Boolean enableAppStartedResultEvent

The flag value to receive an additional launch result event on the launch request.

Exceptions
Type Condition
System.InvalidOperationException

Thrown when failed to create the AppControl handle.

API Level: 3
View Source

AppControl(SafeAppControlHandle)

Initializes the instance of the AppControl class with the SafeAppControlHandle.

Declaration
C#
Copy
public AppControl(SafeAppControlHandle handle)
Parameters
Type Name Description
SafeAppControlHandle handle
API Level: 3

Properties

View Source

ApplicationId

Gets and sets the application ID to explicitly launch.

Declaration
C#
Copy
public string ApplicationId { get; set; }
Property Value
Type Description
System.String

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

Examples
Copy
AppControl appControl = new AppControl(); appControl.ApplicationId = "org.tizen.calculator"; Log.Debug(LogTag, "ApplicationId: " + appControl.ApplicationId);
API Level: 3
View Source

Category

Gets and sets the explicit category.

Declaration
C#
Copy
public string Category { get; set; }
Property Value
Type Description
System.String

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

API Level: 3
View Source

ComponentId

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

Declaration
C#
Copy
public string ComponentId { get; set; }
Property Value
Type Description
System.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
Copy
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
View Source

ExtraData

Gets the collection of the extra data.

Declaration
C#
Copy
public AppControl.ExtraDataCollection ExtraData { get; }
Property Value
Type Description
AppControl.ExtraDataCollection

Extra data for communication between AppControls.

Examples
Copy
AppControl appControl = new AppControl(); appControl.ExtraData.Add("key", "value"); ...
API Level: 3
View Source

LaunchMode

Gets and sets the launch mode of the application.

Declaration
C#
Copy
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
Copy
AppControl appControl = new AppControl(); appControl.LaunchMode = AppControlLaunchMode.Group;
API Level: 3
View Source

Mime

Gets and sets the explicit MIME type of the data.

Declaration
C#
Copy
public string Mime { get; set; }
Property Value
Type Description
System.String

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

Examples
Copy
AppControl appControl = new AppControl(); appControl.Mime = "image/jpg"; Log.Debug(LogTag, "Mime: " + appControl.Mime);
API Level: 3
View Source

Operation

Gets and sets the operation to be performed.

Declaration
C#
Copy
public string Operation { get; set; }
Property Value
Type Description
System.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
Copy
AppControl appControl = new AppControl(); appControl.Operation = AppControlOperations.Default; Log.Debug(LogTag, "Operation: " + appControl.Operation);
API Level: 3
View Source

SafeAppControlHandle

Gets the SafeAppControlHandle instance.

Declaration
C#
Copy
public SafeAppControlHandle SafeAppControlHandle { get; }
Property Value
Type Description
SafeAppControlHandle
API Level: 3
View Source

Uri

Gets and sets the URI of the data.

Declaration
C#
Copy
public string Uri { get; set; }
Property Value
Type Description
System.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
Copy
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

View Source

GetMatchedApplicationIds(AppControl)

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

Declaration
C#
Copy
public static IEnumerable<string> GetMatchedApplicationIds(AppControl control)
Parameters
Type Name Description
AppControl control

The AppControl.

Returns
Type Description
System.Collections.Generic.IEnumerable<System.String>

ApplicationIds.

Examples
Copy
IEnumerable<string> applicationIds = AppControl.GetMatchedApplicationIds(control); if (applicationIds != null) { foreach (string id in applicationIds) { // ... } }
Exceptions
Type Condition
System.InvalidOperationException

Thrown when failed because of an invalid parameter.

API Level: 3
View Source

SendLaunchRequest(AppControl)

Sends the launch request.

Declaration
C#
Copy
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
Copy
AppControl appControl = new AppControl(); appControl.ApplicationId = "org.tizen.calculator"; AppControl.SendLaunchRequest(appControl);
Exceptions
Type Condition
System.ArgumentNullException

Thrown when failed because of a null argument.

System.InvalidOperationException

Thrown when failed because of an invalid operation.

System.TimeoutException

Thrown when failed because of timeout.

API Level: 3
Privilege Level: public
Privilege: http://tizen.org/privilege/appmanager.launch
View Source

SendLaunchRequest(AppControl, AppControlReplyCallback)

Sends the launch request.

Declaration
C#
Copy
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
Copy
AppControl appControl = new AppControl(); appControl.ApplicationId = "org.tizen.calculator"; AppControl.SendLaunchRequest(appControl, (launchRequest, replyRequest, result) => { // ... });
Exceptions
Type Condition
System.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.

System.TimeoutException

Thrown when failed because of timeout.

API Level: 3
Privilege Level: public
Privilege: http://tizen.org/privilege/appmanager.launch
View Source

SendLaunchRequestAsync(AppControl, AppControlReplyCallback)

Sends the launch request asynchronously.

Declaration
C#
Copy
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
System.Threading.Tasks.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
System.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
View Source

SendTerminateRequest(AppControl)

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

Declaration
C#
Copy
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
Copy
AppControl terminateRequest = new AppControl(); terminateRequest.ApplicationId = "org.tizen.calculator"; AppControl.SendTerminateRequest(terminateRequest);
Exceptions
Type Condition
System.ArgumentException

Thrown when failed because of the argument is invalid.

System.InvalidOperationException

Thrown when failed because of an invalid operation.

System.TimeoutException

Thrown when failed because of timeout.

API Level: 3