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
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()
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.
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

ScreenName

Gets and sets the screen name of the application.

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

This property returns the explicitly set screen name. If no explicit screen name is set, it will return null. (Setting this property to null will clear any previously set explicit screen name.)
Examples
AppControl appControl = new AppControl();
appControl.ScreenName = "main_screen";
Log.Debug(LogTag, "ScreenName: " + appControl.ScreenName);
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

GetDefaultApplicationIds()

Gets all default applications.

Declaration
public static IEnumerable<string> GetDefaultApplicationIds()
Returns
Type Description
IEnumerable<><string>

ApplicationIds.
Examples
IEnumerable<string> applicationIds = AppControl.GetDefaultApplicationIds();
if (applicationIds != null)
{
    foreach (string id in applicationIds)
    {
        // ...
    }
}
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
IEnumerable<><string>

ApplicationIds.
Examples
IEnumerable<string> applicationIds = AppControl.GetMatchedApplicationIds(control);
if (applicationIds != null)
{
    foreach (string id in applicationIds)
    {
        // ...
    }
}
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.
View Source

SendLaunchRequest(AppControl, uint, AppControlReplyCallback)

Sends the launch request with setting timeout

Declaration
public static void SendLaunchRequest(AppControl launchRequest, uint timeout, AppControlReplyCallback replyAfterLaunching)
Parameters
Type Name Description
AppControl launchRequest

The AppControl.
uint timeout

The timeout in milliseconds, the timeout range is 5000 to 30000.
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.
To launch a service application, an explicit launch request with the application ID given by property ApplicationId MUST be sent.
It can set receiving timeout interval using timeout parameter. If there is an error that is not related to timeout, the error is returned immediately regardless of the timeout value.

Examples
AppControl appControl = new AppControl();
appControl.ApplicationId = "org.tizen.calculator";
AppControl.SendLaunchRequest(appControl, 10000, (launchRequest, replyRequest, result) => {
    // ...
});
Exceptions
Type Condition
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.
View Source

SendLaunchRequest(AppControl, uint)

Sends the launch request with setting timeout.

Declaration
public static void SendLaunchRequest(AppControl launchRequest, uint timeout)
Parameters
Type Name Description
AppControl launchRequest

The AppControl.
uint timeout

The timeout in milliseconds, the timeout range is 5000 to 30000.
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.
To launch a service application, an explicit launch request with the application ID given by property ApplicationId MUST be sent.
It can set receiving timeout interval using timeout parameter. If there is an error that is not related to timeout, the error is returned immediately regardless of the timeout value.

Examples
AppControl appControl = new AppControl();
appControl.ApplicationId = "org.tizen.calculator";
AppControl.SendLaunchRequest(appControl, 10000);
Exceptions
Type Condition
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.
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
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.
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
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.
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
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
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);
View Source

SetAutoRestart(AppControl)

Sets the auto restart.

Declaration
public static void SetAutoRestart(AppControl appControl)
Parameters
Type Name Description
AppControl appControl

The AppControl.
Remarks

The functionality of this method only applies to the caller application. The auto restart cannot be applied to other applications. The application ID set in the AppControl is ignored. This method is only available for platform level signed applications.

Exceptions
Type Condition
PermissionDeniedException

Thrown when the permission is denied.
OutOfMemoryException

Thrown when the memory is insufficient.
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.
View Source

UnsetAutoRestart()

Unsets the auto restart.

Declaration
public static void UnsetAutoRestart()
Remarks

The functionality of this method only applies to the caller application. This method is only available for platform level signed applications.

Exceptions
Type Condition
PermissionDeniedException

Thrown when the permission is denied.
OutOfMemoryException

Thrown when the memory is insufficient.

Extension Methods