Class AppControl

Definition

Namespace:
Tizen.Applications
Assembly:
Tizen.Applications.Common.dll

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

View Source

AppControl()

Initializes the instance of the AppControl class.

Declaration
public AppControl()
Exceptions
Type Condition
System.InvalidOperationException

Thrown when failed to create the AppControl handle.
View Source

AppControl(bool)

Initializes the instance of the AppControl class with a parameter.

Declaration
public AppControl(bool enableAppStartedResultEvent)
Parameters
Type Name Description
bool 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.
View Source

AppControl(SafeAppControlHandle)

Initializes the instance of the AppControl class with the SafeAppControlHandle.

Declaration
public AppControl(SafeAppControlHandle handle)
Parameters
Type Name Description
SafeAppControlHandle handle

A reference to the SafeAppControlHandle object.

Properties

View Source

ApplicationId

Gets and sets the application ID to explicitly launch.

Declaration
public string ApplicationId { get; set; }
Property Value
Type Description
string

This property returns the explicitly set application ID. If no explicit application ID is set, it will return null. (Setting this property to null will clear any previously set explicit application IDs.)
Examples
AppControl appControl = new AppControl();
appControl.ApplicationId = "org.tizen.calculator";
Log.Debug(LogTag, "ApplicationId: " + appControl.ApplicationId);
View Source

Category

Gets and sets the explicit category.

Declaration
public string Category { get; set; }
Property Value
Type Description
string

This property returns the explicitly set category. If no explicit category is set, it will return null. (Setting this property to null will clear any previously set explicit categories.)
View Source

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);
View Source

ExtraData

Gets the collection of the extra data.

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

The ExtraData property provides access to a collection of key-value pairs representing additional data associated with the application control.
Examples
AppControl appControl = new AppControl();
appControl.ExtraData.Add("key", "value");
...
View Source

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;
View Source

Mime

Gets and sets the explicit MIME type of the data.

Declaration
public string Mime { get; set; }
Property Value
Type Description
string

This property returns the explicitly set MIME type of the data. If no explicit MIME type is set, it will return null. (Setting this property to null will clear any previously set explicit MIME types.)
Examples
AppControl appControl = new AppControl();
appControl.Mime = "image/jpg";
Log.Debug(LogTag, "Mime: " + appControl.Mime);
View Source

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);
View Source

SafeAppControlHandle

Gets the SafeAppControlHandle instance.

Declaration
public SafeAppControlHandle SafeAppControlHandle { get; }
Property Value
Type Description
SafeAppControlHandle

This property returns a reference to the underlying SafeAppControlHandle object.
View Source

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);
    }
}

Methods

View Source

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
System.Collections.Generic.IEnumerable<T><string>

ApplicationIds.
Examples
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.
View Source

GetWindowPosition()

Gets the window position.

Declaration
public WindowPosition GetWindowPosition()
Returns
Type Description
WindowPosition

A structure containing the coordinates and dimensions of the window.
Exceptions
Type Condition
System.InvalidOperationException

Thrown when the invalid operation error occurs.
View Source

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
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.
View Source

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
System.ArgumentNullException

Thrown when failed because of a null argument.
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.
View Source

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
System.Threading.Tasks.Task<TResult><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.
View Source

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
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.
View Source

SetWindowPosition(WindowPosition)

Sets the position and size of the window.

Declaration
public void SetWindowPosition(WindowPosition windowPosition)
Parameters
Type Name Description
WindowPosition windowPosition

A structure containing the coordinates and dimensions of the window.
Exceptions
Type Condition
System.ArgumentNullException

Thrown when the argument is null.
System.ArgumentException

Thrown when the argument is invalid.
System.InvalidOperationException

Thrown when the invalid operation error occurs.