Tizen Native API  5.5
App Control

The App Control API provides functions to launch other applications.

Required Header

#include <app_control.h>

Overview

Application Controls

Functions

int app_control_create (app_control_h *app_control)
 Creates an app_control handle.
int app_control_create_with_parameters (app_control_h *app_control, const char *operation, const char *uri, const char *mime, const char *category, const char *app_id, app_control_launch_mode_e mode, int extra_data_count,...)
 Creates an app_control handle and sets its attributes.
int app_control_create_from_uri_handle (app_control_h *app_control, app_control_uri_h uri)
 Creates an app_control handle from an app_control_uri handle.
int app_control_destroy (app_control_h app_control)
 Destroys the app_control handle and releases all its resources.
int app_control_set_operation (app_control_h app_control, const char *operation)
 Sets the operation to be performed.
int app_control_get_operation (app_control_h app_control, char **operation)
 Gets the operation to be performed.
int app_control_set_uri (app_control_h app_control, const char *uri)
 Sets the URI of the data.
int app_control_get_uri (app_control_h app_control, char **uri)
 Gets the URI of the data.
int app_control_set_uri_by_handle (app_control_h app_control, app_control_uri_h uri)
 Sets the URI by the app_control_uri handle.
int app_control_set_mime (app_control_h app_control, const char *mime)
 Sets the explicit MIME type of the data.
int app_control_get_mime (app_control_h app_control, char **mime)
 Gets the explicit MIME type of the data.
int app_control_set_category (app_control_h app_control, const char *category)
 Sets the explicit category.
int app_control_get_category (app_control_h app_control, char **category)
 Gets the explicit category.
int app_control_set_app_id (app_control_h app_control, const char *app_id)
 Sets the ID of the application to explicitly launch.
int app_control_get_app_id (app_control_h app_control, char **app_id)
 Gets the ID of the application to explicitly launch.
int app_control_add_extra_data (app_control_h app_control, const char *key, const char *value)
 Adds extra data to the app_control.
int app_control_add_extra_data_array (app_control_h app_control, const char *key, const char *value[], int length)
 Adds the extra data array to the app_control.
int app_control_remove_extra_data (app_control_h app_control, const char *key)
 Removes the extra data from the app_control.
int app_control_get_extra_data (app_control_h app_control, const char *key, char **value)
 Gets the extra data from the app_control.
int app_control_get_extra_data_array (app_control_h app_control, const char *key, char ***value, int *length)
 Gets the extra data array from the app_control.
int app_control_is_extra_data_array (app_control_h app_control, const char *key, bool *array)
 Checks whether the extra data associated with the given key is of array data type.
int app_control_foreach_extra_data (app_control_h app_control, app_control_extra_data_cb callback, void *user_data)
 Retrieves all extra data contained in app_control.
int app_control_foreach_app_matched (app_control_h app_control, app_control_app_matched_cb callback, void *user_data)
 Retrieves all applications that can be launched to handle the given app_control request.
int app_control_send_launch_request (app_control_h app_control, app_control_reply_cb callback, void *user_data)
 Sends the launch request.
int app_control_send_terminate_request (app_control_h app_control)
 Sends the terminate request to the application that is launched by app_control. This API is only effective for some applications that are provided by default for handling platform default app_controls. You are not allowed to terminate other general applications using this API.
int app_control_reply_to_launch_request (app_control_h reply, app_control_h request, app_control_result_e result)
 Replies to the launch request sent by the caller.
int app_control_clone (app_control_h *clone, app_control_h app_control)
 Creates and returns a copy of the given app_control handle.
int app_control_get_caller (app_control_h app_control, char **id)
 Gets the application ID of the caller from the launch request.
int app_control_is_reply_requested (app_control_h app_control, bool *requested)
 Checks whether the caller is requesting a reply from the launch request.
int app_control_set_launch_mode (app_control_h app_control, app_control_launch_mode_e mode)
 Sets the launch mode of the application.
int app_control_get_launch_mode (app_control_h app_control, app_control_launch_mode_e *mode)
 Gets the launch mode of the application.
int app_control_enable_app_started_result_event (app_control_h app_control)
 Enables an additional launch result event on the launch request.
int app_control_send_launch_request_async (app_control_h app_control, app_control_result_cb result_cb, app_control_reply_cb reply_cb, void *user_data)
 Sends the launch request asynchronously.
int app_control_send_launch_request_sync (app_control_h app_control, app_control_h *reply, app_control_result_e *result)
 Sends the launch request synchronously.
int app_control_add_action_handler (const char *action, app_control_action_cb callback, void *user_data, app_control_action_h *handle)
 Adds the action handle of the app_control.
int app_control_remove_action_handler (app_control_action_h handle)
 Removes the registered action handle of the app_control.
int app_control_set_component_id (app_control_h app_control, const char *component_id)
 Sets the ID of the component.
int app_control_get_component_id (app_control_h app_control, char **component_id)
 Gets the ID of the component.

Typedefs

typedef struct app_control_s * app_control_h
 The application control handle.
typedef void(* app_control_reply_cb )(app_control_h request, app_control_h reply, app_control_result_e result, void *user_data)
 Called when the reply of the launch request is delivered.
typedef bool(* app_control_extra_data_cb )(app_control_h app_control, const char *key, void *user_data)
 Called to retrieve the extra data contained in the app_control.
typedef bool(* app_control_app_matched_cb )(app_control_h app_control, const char *appid, void *user_data)
 Called once for each matched application that can be launched to handle the given app_control request.
typedef void(* app_control_result_cb )(app_control_h request, app_control_error_e result, void *user_data)
 Called when the result of the launch request is delivered.
typedef struct
app_control_action_s * 
app_control_action_h
 The application control action handle.
typedef void(* app_control_action_cb )(const char *action, app_control_h app_control, void *user_data)
 Called when another application sends a launch request to the application.

Defines

#define APP_CONTROL_OPERATION_MAIN   "http://tizen.org/appcontrol/operation/main"
 Definition for the app_control operation: An explicit launch for the homescreen application.
#define APP_CONTROL_OPERATION_DEFAULT   "http://tizen.org/appcontrol/operation/default"
 Definition for the app_control operation: An explicit launch for an application that excludes the homescreen application.
#define APP_CONTROL_OPERATION_EDIT   "http://tizen.org/appcontrol/operation/edit"
 Definition for the app_control operation: Provides an editable access to the given data.
#define APP_CONTROL_OPERATION_VIEW   "http://tizen.org/appcontrol/operation/view"
 Definition for the app_control operation: Displays the data.
#define APP_CONTROL_OPERATION_PICK   "http://tizen.org/appcontrol/operation/pick"
 Definition for the app_control operation: Picks the item.
#define APP_CONTROL_OPERATION_CREATE_CONTENT   "http://tizen.org/appcontrol/operation/create_content"
 Definition for the app_control operation: Creates the contents.
#define APP_CONTROL_OPERATION_CALL   "http://tizen.org/appcontrol/operation/call"
 Definition for the app_control operation: Performs a call to someone.
#define APP_CONTROL_OPERATION_SEND   "http://tizen.org/appcontrol/operation/send"
 Definition for the app_control operation: Delivers some data to someone else.
#define APP_CONTROL_OPERATION_SEND_TEXT   "http://tizen.org/appcontrol/operation/send_text"
 Definition for the app_control operation: Delivers text data to someone else.
#define APP_CONTROL_OPERATION_SHARE   "http://tizen.org/appcontrol/operation/share"
 Definition for the app_control operation: Shares an item with someone else.
#define APP_CONTROL_OPERATION_MULTI_SHARE   "http://tizen.org/appcontrol/operation/multi_share"
 Definition for the app_control operation: Shares multiple items with someone else.
#define APP_CONTROL_OPERATION_SHARE_TEXT   "http://tizen.org/appcontrol/operation/share_text"
 Definition for the app_control operation: Shares the text data with someone else.
#define APP_CONTROL_OPERATION_DIAL   "http://tizen.org/appcontrol/operation/dial"
 Definition for the app_control operation: Dials a number. This shows a UI with the number to be dialed, allowing the user to explicitly initiate the call.
#define APP_CONTROL_OPERATION_SEARCH   "http://tizen.org/appcontrol/operation/search"
 Definition for the app_control operation: Performs a search.
#define APP_CONTROL_OPERATION_DOWNLOAD   "http://tizen.org/appcontrol/operation/download"
 Definition for the app_control operation: Downloads the item.
#define APP_CONTROL_OPERATION_PRINT   "http://tizen.org/appcontrol/operation/print"
 Definition for the app_control operation: Prints the content.
#define APP_CONTROL_OPERATION_COMPOSE   "http://tizen.org/appcontrol/operation/compose"
 Definition for the app_control operation: Composes a message.
#define APP_CONTROL_OPERATION_LAUNCH_ON_EVENT   "http://tizen.org/appcontrol/operation/launch_on_event"
 Definition for the app_control operation: Can be launched by an interested system-event.
#define APP_CONTROL_OPERATION_ADD   "http://tizen.org/appcontrol/operation/add"
 Definition for the app_control operation: Adds an item.
#define APP_CONTROL_OPERATION_IMAGE_CAPTURE   "http://tizen.org/appcontrol/operation/image_capture"
 Definition for the app_control operation: Captures images by camera applications.
#define APP_CONTROL_OPERATION_VIDEO_CAPTURE   "http://tizen.org/appcontrol/operation/video_capture"
 Definition for the app_control operation: Captures the videos by camera applications.
#define APP_CONTROL_OPERATION_SETTING_BT_ENABLE   "http://tizen.org/appcontrol/operation/setting/bt_enable"
 Definition for the app_control operation: Shows the settings to enable Bluetooth.
#define APP_CONTROL_OPERATION_SETTING_BT_VISIBILITY   "http://tizen.org/appcontrol/operation/setting/bt_visibility"
 Definition for the app_control operation: Shows the settings to configure Bluetooth visibility.
#define APP_CONTROL_OPERATION_SETTING_LOCATION   "http://tizen.org/appcontrol/operation/setting/location"
 Definition for the app_control operation: Shows the settings to allow configuration of current location sources.
#define APP_CONTROL_OPERATION_SETTING_NFC   "http://tizen.org/appcontrol/operation/setting/nfc"
 Definition for the app_control operation: Shows the NFC settings.
#define APP_CONTROL_OPERATION_SETTING   "http://tizen.org/appcontrol/operation/setting"
 Definition for the app_control operation: Shows the system settings.
#define APP_CONTROL_OPERATION_SETTING_WIFI   "http://tizen.org/appcontrol/operation/setting/wifi"
 Definition for the app_control operation: Shows the settings to allow configuration of Wi-Fi.
#define APP_CONTROL_OPERATION_SETTING_VPN   "http://tizen.org/appcontrol/operation/setting/vpn"
 Definition for the application control operation: Shows the VPN service settings.
#define APP_CONTROL_OPERATION_GET_INPUT   "http://tizen.org/appcontrol/operation/get_input"
 Definition for the application control operation: Select the type of input method to receive an input from the user.
#define APP_CONTROL_OPERATION_MEDIA_CONTROLLER   "http://tizen.org/appcontrol/operation/media_control"
 Definition for the application control operation: launch controller server or client.
#define APP_CONTROL_OPERATION_PRIVACY_SETTING_GUIDE   "http://tizen.org/appcontrol/operation/guide_privacy_setting"
 Definition for the application control operation: Shows guide popup to privacy settings.
#define APP_CONTROL_OPERATION_INTENT   "http://tizen.org/appcontrol/operation/intent"
 Definition for the application control operation: Sends URI.
#define APP_CONTROL_DATA_FEATURE   "http://tizen.org/appcontrol/data/feature"
 Definition for the app_control data: Feature of function name.
#define APP_CONTROL_DATA_PRIVILEGES   "http://tizen.org/appcontrol/data/privileges"
 Definition for the app_control data: List of privileges.
#define APP_CONTROL_DATA_SUBJECT   "http://tizen.org/appcontrol/data/subject"
 Definition for the app_control data: Subject.
#define APP_CONTROL_DATA_TO   "http://tizen.org/appcontrol/data/to"
 Definition for the app_control data: Recipients.
#define APP_CONTROL_DATA_CC   "http://tizen.org/appcontrol/data/cc"
 Definition for the app_control data: Email addresses that should be carbon copied.
#define APP_CONTROL_DATA_BCC   "http://tizen.org/appcontrol/data/bcc"
 Definition for the app_control data: Email addresses that should be blind carbon copied.
#define APP_CONTROL_DATA_TEXT   "http://tizen.org/appcontrol/data/text"
 Definition for the app_control data: Text.
#define APP_CONTROL_DATA_TITLE   "http://tizen.org/appcontrol/data/title"
 Definition for the app_control data: Title.
#define APP_CONTROL_DATA_SELECTED   "http://tizen.org/appcontrol/data/selected"
 Definition for the app_control data: Selected items.
#define APP_CONTROL_DATA_PATH   "http://tizen.org/appcontrol/data/path"
 Definition for the app_control data: Paths of items.
#define APP_CONTROL_DATA_SELECTION_MODE   "http://tizen.org/appcontrol/data/selection_mode"
 Definition for the app_control data: Selection mode ("single" or "multiple").
#define APP_CONTROL_DATA_CALENDAR_ALL_DAY   "http://tizen.org/appcontrol/data/calendar/all_day"
 Definition for the app_control data: All-day mode of the event ("true" or "false").
#define APP_CONTROL_DATA_CALENDAR_START_TIME   "http://tizen.org/appcontrol/data/calendar/start_time"
 Definition for the app_control data: Start time of the event (format: YYYY-MM-DD HH:MM:SS).
#define APP_CONTROL_DATA_CALENDAR_END_TIME   "http://tizen.org/appcontrol/data/calendar/end_time"
 Definition for the app_control data: End time of event (format: YYYY-MM-DD HH:MM:SS).
#define APP_CONTROL_DATA_EMAIL   "http://tizen.org/appcontrol/data/email"
 Definition for the app_control data: Email addresses.
#define APP_CONTROL_DATA_PHONE   "http://tizen.org/appcontrol/data/phone"
 Definition for the app_control data: Phone numbers.
#define APP_CONTROL_DATA_URL   "http://tizen.org/appcontrol/data/url"
 Definition for the app_control data: URLs.
#define APP_CONTROL_DATA_ID   "http://tizen.org/appcontrol/data/id"
 Definition for the app_control data: IDs.
#define APP_CONTROL_DATA_TYPE   "http://tizen.org/appcontrol/data/type"
 Definition for the app_control data: Type.
#define APP_CONTROL_DATA_TOTAL_COUNT   "http://tizen.org/appcontrol/data/total_count"
 Definition for the app_control data: Total count.
#define APP_CONTROL_DATA_TOTAL_SIZE   "http://tizen.org/appcontrol/data/total_size"
 Definition for the app_control data: Total size (unit : bytes).
#define APP_CONTROL_DATA_NAME   "http://tizen.org/appcontrol/data/name"
 Definition for the app_control data: Name.
#define APP_CONTROL_DATA_LOCATION   "http://tizen.org/appcontrol/data/location"
 Definition for the app_control data: Location.
#define APP_CONTROL_DATA_INPUT_TYPE   "http://tizen.org/appcontrol/data/input_type"
 Definition for the app_control data: Selects the type of the input method.
#define APP_CONTROL_DATA_INPUT_DEFAULT_TEXT   "http://tizen.org/appcontrol/data/input_default_text"
 Definition for the app_control data: Sends the pre-input text such as "http://" in web.
#define APP_CONTROL_DATA_INPUT_GUIDE_TEXT   "http://tizen.org/appcontrol/data/input_guide_text"
 Definition for the app_control data: Sends the guide text to show the user such as "Input user name".
#define APP_CONTROL_DATA_INPUT_PREDICTION_HINT   "http://tizen.org/appcontrol/data/input_prediction_hint"
 Definition for the app_control data: Sends text to receive the result from smart reply.
#define APP_CONTROL_DATA_INPUT_RETURNKEY_TYPE   "http://tizen.org/appcontrol/data/input_returnkey_type"
 Definition for the app_control data: Sends type to set the return key type in the keyboard input type.
#define APP_CONTROL_DATA_INPUT_MAX_TEXT_LENGTH   "http://tizen.org/appcontrol/data/input_max_text_length"
 Definition for the app_control data: Sends the length value to set the max text length in the keyboard input type.
#define APP_CONTROL_DATA_INPUT_CURSOR_POSITION_SET   "http://tizen.org/appcontrol/data/input_cursor_position_set"
 Definition for app_control data: Send value to set cursor position to entry in keyboard input type.
#define APP_CONTROL_DATA_INPUT_CURSOR_POSITION_GET   "http://tizen.org/appcontrol/data/input_cursor_position_get"
 Definition for app_control data: Receive value to get cursor position from entry in keyboard input type.
#define APP_CONTROL_DATA_INPUT_REPLY_TYPE   "http://tizen.org/appcontrol/data/input_reply_type"
 Definition for the app_control data: Receives the reply type from the input method.
#define APP_CONTROL_DATA_WIDGET_INSTANCE_ID   "http://tizen.org/appcontrol/data/widget_instance_id"
 Definition for the app_control data: Sends the widget instance ID to the widget setup application.
#define APP_CONTROL_DATA_WIDGET_CONTENT   "http://tizen.org/appcontrol/data/widget_content"
 Definition for the app_control data: Sends the widget content to the widget setup application.
#define APP_CONTROL_DATA_WIDGET_APP_ID   "http://tizen.org/appcontrol/data/widget_app_id"
 Definition for the app_control data: Sends the widget application ID to the widget setup application.
#define APP_CONTROL_DATA_URI_FRAGMENT   "http://tizen.org/appcontrol/data/uri/fragment"
 Definition for the fragment data of a URI.
#define APP_CONTROL_DATA_URI_PATH   "http://tizen.org/appcontrol/data/uri/path"
 Definition for the path data of a URI.

Define Documentation

#define APP_CONTROL_DATA_BCC   "http://tizen.org/appcontrol/data/bcc"

Definition for the app_control data: Email addresses that should be blind carbon copied.

Since :
2.3
#define APP_CONTROL_DATA_CALENDAR_ALL_DAY   "http://tizen.org/appcontrol/data/calendar/all_day"

Definition for the app_control data: All-day mode of the event ("true" or "false").

Since :
2.4
#define APP_CONTROL_DATA_CALENDAR_END_TIME   "http://tizen.org/appcontrol/data/calendar/end_time"

Definition for the app_control data: End time of event (format: YYYY-MM-DD HH:MM:SS).

Since :
2.4
#define APP_CONTROL_DATA_CALENDAR_START_TIME   "http://tizen.org/appcontrol/data/calendar/start_time"

Definition for the app_control data: Start time of the event (format: YYYY-MM-DD HH:MM:SS).

Since :
2.4
#define APP_CONTROL_DATA_CC   "http://tizen.org/appcontrol/data/cc"

Definition for the app_control data: Email addresses that should be carbon copied.

Since :
2.3
#define APP_CONTROL_DATA_EMAIL   "http://tizen.org/appcontrol/data/email"

Definition for the app_control data: Email addresses.

Since :
2.4
#define APP_CONTROL_DATA_FEATURE   "http://tizen.org/appcontrol/data/feature"

Definition for the app_control data: Feature of function name.

Since :
#define APP_CONTROL_DATA_ID   "http://tizen.org/appcontrol/data/id"

Definition for the app_control data: IDs.

Since :
2.4
#define APP_CONTROL_DATA_INPUT_CURSOR_POSITION_GET   "http://tizen.org/appcontrol/data/input_cursor_position_get"

Definition for app_control data: Receive value to get cursor position from entry in keyboard input type.

Since :
4.0
#define APP_CONTROL_DATA_INPUT_CURSOR_POSITION_SET   "http://tizen.org/appcontrol/data/input_cursor_position_set"

Definition for app_control data: Send value to set cursor position to entry in keyboard input type.

Since :
4.0
#define APP_CONTROL_DATA_INPUT_DEFAULT_TEXT   "http://tizen.org/appcontrol/data/input_default_text"

Definition for the app_control data: Sends the pre-input text such as "http://" in web.

Since :
3.0
#define APP_CONTROL_DATA_INPUT_GUIDE_TEXT   "http://tizen.org/appcontrol/data/input_guide_text"

Definition for the app_control data: Sends the guide text to show the user such as "Input user name".

Since :
3.0
#define APP_CONTROL_DATA_INPUT_MAX_TEXT_LENGTH   "http://tizen.org/appcontrol/data/input_max_text_length"

Definition for the app_control data: Sends the length value to set the max text length in the keyboard input type.

Since :
4.0
#define APP_CONTROL_DATA_INPUT_PREDICTION_HINT   "http://tizen.org/appcontrol/data/input_prediction_hint"

Definition for the app_control data: Sends text to receive the result from smart reply.

Since :
3.0
#define APP_CONTROL_DATA_INPUT_REPLY_TYPE   "http://tizen.org/appcontrol/data/input_reply_type"

Definition for the app_control data: Receives the reply type from the input method.

Type: "input_voice" Receive the result from the voice input type. "input_emoticon" Receive the result from the emoticon input type. "input_keyboard" Receive the result from the keyboard input type. "input_reply" Receive the result from the reply input type. "input_image" Receive the result from the image input type. "input_audio" Receive the result from the audio input type.

Since :
4.0
#define APP_CONTROL_DATA_INPUT_RETURNKEY_TYPE   "http://tizen.org/appcontrol/data/input_returnkey_type"

Definition for the app_control data: Sends type to set the return key type in the keyboard input type.

Type: "Done" Set the type with Done label. "Send" Set the type with Send label. "Join" Set the type with Join label. "Login" Set the type with Login label. "Next" Set the type with Next label. "Sign-in" Set the type with Sign-in label. "Search" Set the type with Search label. "Go" Set the type with Go label.

Since :
4.0
#define APP_CONTROL_DATA_INPUT_TYPE   "http://tizen.org/appcontrol/data/input_type"

Definition for the app_control data: Selects the type of the input method.

Type: "input_voice" Launch the input method with the voice type. "input_emoticon" Launch the input method with the emoticon type. "input_keyboard" Launch the input method with the keyboard type. "input_reply" Launch the input method with the context based reply type. "input_drawing" Launch the input method with the drawing type. "input_recording" Launch the input method with the voice recording type. input_reply, input_drawing and input_recording types are valid since tizen 4.0.

Since :
3.0
#define APP_CONTROL_DATA_LOCATION   "http://tizen.org/appcontrol/data/location"

Definition for the app_control data: Location.

Since :
3.0
#define APP_CONTROL_DATA_NAME   "http://tizen.org/appcontrol/data/name"

Definition for the app_control data: Name.

Since :
2.4
#define APP_CONTROL_DATA_PATH   "http://tizen.org/appcontrol/data/path"

Definition for the app_control data: Paths of items.

Since :
2.3
Remarks:
Since Tizen 2.4, if all added paths with this key are under the caller application's data path which can be obtained by the calling app_get_data_path() function, those will be shared to the callee application. Framework will grant a temporary permission to the callee application for those files and revoke it when the callee application is terminated. Paths should be regular files. The callee application can just read them. Note that the callee application doesn't have read permission of the directory that is obtained by the caller's app_get_data_path(), you should open the file path with the read only mode directly. For example, access() call to the file path will return error because access() needs the read permission of the directory. The callee application can call open() with the O_RDONLY mode for the passed file path, because framework grants the read permission to the passed file path.
#define APP_CONTROL_DATA_PHONE   "http://tizen.org/appcontrol/data/phone"

Definition for the app_control data: Phone numbers.

Since :
2.4
#define APP_CONTROL_DATA_PRIVILEGES   "http://tizen.org/appcontrol/data/privileges"

Definition for the app_control data: List of privileges.

Since :
#define APP_CONTROL_DATA_SELECTED   "http://tizen.org/appcontrol/data/selected"

Definition for the app_control data: Selected items.

Since :
2.3
Remarks:
Since Tizen 3.0, if all added paths with this key are under the caller application's data path which can be obtained by calling app_get_data_path() function, those will be shared to the callee application. Framework will grant a temporary permission to the callee application for those files and revoke it when the callee application is terminated. Paths should be regular files. The callee application can just read them. Note that the callee application doesn't have read permission of the directory that is obtained by caller's app_get_data_path(), you should open the file path with read only mode directly. For example, access() call to the file path will return error because access() needs the read permission of the directory. The callee application can call open() with O_RDONLY mode for the passed file path, because framework grants read permission to the passed file path.
#define APP_CONTROL_DATA_SELECTION_MODE   "http://tizen.org/appcontrol/data/selection_mode"

Definition for the app_control data: Selection mode ("single" or "multiple").

Since :
2.3
#define APP_CONTROL_DATA_SUBJECT   "http://tizen.org/appcontrol/data/subject"

Definition for the app_control data: Subject.

Since :
2.3
#define APP_CONTROL_DATA_TEXT   "http://tizen.org/appcontrol/data/text"

Definition for the app_control data: Text.

Since :
2.3
#define APP_CONTROL_DATA_TITLE   "http://tizen.org/appcontrol/data/title"

Definition for the app_control data: Title.

Since :
2.3
#define APP_CONTROL_DATA_TO   "http://tizen.org/appcontrol/data/to"

Definition for the app_control data: Recipients.

Since :
2.3
#define APP_CONTROL_DATA_TOTAL_COUNT   "http://tizen.org/appcontrol/data/total_count"

Definition for the app_control data: Total count.

Since :
2.4
#define APP_CONTROL_DATA_TOTAL_SIZE   "http://tizen.org/appcontrol/data/total_size"

Definition for the app_control data: Total size (unit : bytes).

Since :
2.4
#define APP_CONTROL_DATA_TYPE   "http://tizen.org/appcontrol/data/type"

Definition for the app_control data: Type.

Since :
2.4
#define APP_CONTROL_DATA_URI_FRAGMENT   "http://tizen.org/appcontrol/data/uri/fragment"

Definition for the fragment data of a URI.

Since :
5.5
#define APP_CONTROL_DATA_URI_PATH   "http://tizen.org/appcontrol/data/uri/path"

Definition for the path data of a URI.

Since :
5.5
#define APP_CONTROL_DATA_URL   "http://tizen.org/appcontrol/data/url"

Definition for the app_control data: URLs.

Since :
2.4
#define APP_CONTROL_DATA_WIDGET_APP_ID   "http://tizen.org/appcontrol/data/widget_app_id"

Definition for the app_control data: Sends the widget application ID to the widget setup application.

The value is the application ID declared in the widget application manifest file.

Since :
4.0
#define APP_CONTROL_DATA_WIDGET_CONTENT   "http://tizen.org/appcontrol/data/widget_content"

Definition for the app_control data: Sends the widget content to the widget setup application.

The value is the content information of the widget instance.

Since :
4.0
#define APP_CONTROL_DATA_WIDGET_INSTANCE_ID   "http://tizen.org/appcontrol/data/widget_instance_id"

Definition for the app_control data: Sends the widget instance ID to the widget setup application.

The value is the ID of the widget instance.

Since :
4.0
#define APP_CONTROL_OPERATION_ADD   "http://tizen.org/appcontrol/operation/add"

Definition for the app_control operation: Adds an item.

Input: It depends on the application scenario or configuration.
Output: It depends on the application scenario or configuration.

Since :
2.4
#define APP_CONTROL_OPERATION_CALL   "http://tizen.org/appcontrol/operation/call"

Definition for the app_control operation: Performs a call to someone.

Input: URI is the number to be dialed. This is a mandatory field.
Output: Nothing

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/call
Remarks:
When you request this operation, you must declare this privilege.
#define APP_CONTROL_OPERATION_COMPOSE   "http://tizen.org/appcontrol/operation/compose"

Definition for the app_control operation: Composes a message.

Input: It depends on the application scenario or configuration.
Output: Nothing

Since :
2.3
#define APP_CONTROL_OPERATION_CREATE_CONTENT   "http://tizen.org/appcontrol/operation/create_content"

Definition for the app_control operation: Creates the contents.

Input: It depends on application scenario or configuration.
Output: APP_CONTROL_DATA_SELECTED in extra.

Since :
2.3
#define APP_CONTROL_OPERATION_DEFAULT   "http://tizen.org/appcontrol/operation/default"

Definition for the app_control operation: An explicit launch for an application that excludes the homescreen application.

Input: Nothing
Output: Nothing

Since :
2.3
#define APP_CONTROL_OPERATION_DIAL   "http://tizen.org/appcontrol/operation/dial"

Definition for the app_control operation: Dials a number. This shows a UI with the number to be dialed, allowing the user to explicitly initiate the call.

Input: URI is the number to be dialed. If empty, show a UI without the number.
Output: Nothing

Since :
2.3
#define APP_CONTROL_OPERATION_DOWNLOAD   "http://tizen.org/appcontrol/operation/download"

Definition for the app_control operation: Downloads the item.

Input: It depends on the application scenario or configuration.
Output: It depends on the application scenario or configuration.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/download (Since 2.4)
Remarks:
When you request this operation, you must declare this privilege. (Since 2.4)
#define APP_CONTROL_OPERATION_EDIT   "http://tizen.org/appcontrol/operation/edit"

Definition for the app_control operation: Provides an editable access to the given data.

Input: It depends on the application scenario or configuration.
Output: It depends on the application scenario or configuration.

Since :
2.3
#define APP_CONTROL_OPERATION_GET_INPUT   "http://tizen.org/appcontrol/operation/get_input"

Definition for the application control operation: Select the type of input method to receive an input from the user.

Input: It depends on the application scenario or configuration.
Output: APP_CONTROL_DATA_TEXT in extra.

Since :
3.0
#define APP_CONTROL_OPERATION_IMAGE_CAPTURE   "http://tizen.org/appcontrol/operation/image_capture"

Definition for the app_control operation: Captures images by camera applications.

Input: Nothing
Output: APP_CONTROL_DATA_SELECTED in extra.

Since :
2.4
#define APP_CONTROL_OPERATION_INTENT   "http://tizen.org/appcontrol/operation/intent"

Definition for the application control operation: Sends URI.

Input: URI, this is a mandatory field.
Input: APP_CONTROL_DATA_URI_FRAGMENT in extra is the fragment of the URI.
Input: APP_CONTROL_DATA_URI_PATH in extra is the path of the URI.
Output: Nothing

Since :
5.5
#define APP_CONTROL_OPERATION_LAUNCH_ON_EVENT   "http://tizen.org/appcontrol/operation/launch_on_event"

Definition for the app_control operation: Can be launched by an interested system-event.

Input : URI and extras data defined in event module.
Output: Nothing

Since :
2.4
Remarks:
This operation is for handling an event from the platform. This operation cannot be requested through the app_control_send_launch_request().
Refer to the Launch-On-Event section of the event module.
#define APP_CONTROL_OPERATION_MAIN   "http://tizen.org/appcontrol/operation/main"

Definition for the app_control operation: An explicit launch for the homescreen application.

Input: Nothing
Output: Nothing

Since :
2.3
#define APP_CONTROL_OPERATION_MEDIA_CONTROLLER   "http://tizen.org/appcontrol/operation/media_control"

Definition for the application control operation: launch controller server or client.

Input: APP_CONTROL_DATA_TYPE in extra is the text of launch type("server" or "client"). This is a mandatory field.
In some cases, URI is used to inform the path to play for the media controller server.
Output: Nothing

Since :
4.0
#define APP_CONTROL_OPERATION_MULTI_SHARE   "http://tizen.org/appcontrol/operation/multi_share"

Definition for the app_control operation: Shares multiple items with someone else.

Input: APP_CONTROL_DATA_PATH in extra is usually used to inform the data to share. In some cases, some other data in extra can be used (for example, the MULTI_SHARE operation for sharing the contact data).
Output: Nothing

Since :
2.3
#define APP_CONTROL_OPERATION_PICK   "http://tizen.org/appcontrol/operation/pick"

Definition for the app_control operation: Picks the item.

Input: It depends on the application scenario or configuration.
Output: APP_CONTROL_DATA_SELECTED in extra.

Since :
2.3
#define APP_CONTROL_OPERATION_PRINT   "http://tizen.org/appcontrol/operation/print"

Definition for the app_control operation: Prints the content.

Input: It depends on the application scenario or configuration.
Output: It depends on the application scenario or configuration.

Since :
2.3
#define APP_CONTROL_OPERATION_PRIVACY_SETTING_GUIDE   "http://tizen.org/appcontrol/operation/guide_privacy_setting"

Definition for the application control operation: Shows guide popup to privacy settings.

Input: APP_CONTROL_DATA_TYPE in extra is the text of guide type("open" or "use"). This is a mandatory field.
Input: APP_CONTROL_DATA_FEATURE in extra is the text of the feature or function name which requires privacy privileges.
Input: APP_CONTROL_DATA_PRIVILEGES in extra is the text array of the required privileges. This is a mandatory field.
Output: APP_CONTROL_DATA_SELECTED in extra. The value is "yes" or "no" according to the user response.

Since :
#define APP_CONTROL_OPERATION_SEARCH   "http://tizen.org/appcontrol/operation/search"

Definition for the app_control operation: Performs a search.

Input: APP_CONTROL_DATA_TEXT in extra is the text to search for. If empty, show a search UI.
Output: Nothing

Since :
2.3
#define APP_CONTROL_OPERATION_SEND   "http://tizen.org/appcontrol/operation/send"

Definition for the app_control operation: Delivers some data to someone else.

Deprecated:
Deprecated since 2.4. Use APP_CONTROL_OPERATION_SHARE instead.
Since :
2.3
#define APP_CONTROL_OPERATION_SEND_TEXT   "http://tizen.org/appcontrol/operation/send_text"

Definition for the app_control operation: Delivers text data to someone else.

Deprecated:
Deprecated since 2.4. Use APP_CONTROL_OPERATION_SHARE_TEXT instead.
Since :
2.3
#define APP_CONTROL_OPERATION_SETTING   "http://tizen.org/appcontrol/operation/setting"

Definition for the app_control operation: Shows the system settings.

Input: Nothing
Output: Nothing

Since :
2.4
#define APP_CONTROL_OPERATION_SETTING_BT_ENABLE   "http://tizen.org/appcontrol/operation/setting/bt_enable"

Definition for the app_control operation: Shows the settings to enable Bluetooth.

Input: Nothing
Output: Nothing

Since :
2.4
#define APP_CONTROL_OPERATION_SETTING_BT_VISIBILITY   "http://tizen.org/appcontrol/operation/setting/bt_visibility"

Definition for the app_control operation: Shows the settings to configure Bluetooth visibility.

Input: Nothing
Output: Nothing

Since :
2.4
#define APP_CONTROL_OPERATION_SETTING_LOCATION   "http://tizen.org/appcontrol/operation/setting/location"

Definition for the app_control operation: Shows the settings to allow configuration of current location sources.

Input: Nothing
Output: Nothing

Since :
2.4
#define APP_CONTROL_OPERATION_SETTING_NFC   "http://tizen.org/appcontrol/operation/setting/nfc"

Definition for the app_control operation: Shows the NFC settings.

Input: APP_CONTROL_DATA_TYPE in extra (Since 3.0).
Output: Nothing

Since :
2.4
Remarks:
Prior to Tizen 3.0, no input value was needed.
#define APP_CONTROL_OPERATION_SETTING_VPN   "http://tizen.org/appcontrol/operation/setting/vpn"

Definition for the application control operation: Shows the VPN service settings.

Input: Nothing
Output: Nothing

Since :
3.0
#define APP_CONTROL_OPERATION_SETTING_WIFI   "http://tizen.org/appcontrol/operation/setting/wifi"

Definition for the app_control operation: Shows the settings to allow configuration of Wi-Fi.

Input: Nothing
Output: Nothing

Since :
2.4
#define APP_CONTROL_OPERATION_SHARE   "http://tizen.org/appcontrol/operation/share"

Definition for the app_control operation: Shares an item with someone else.

Input: URI is usually used to inform the path to share. In some cases, some other data in extra can be used (for example, the SHARE operation for sharing the contact data, the SHARE operation for sharing an item through a message and email applications).
Output: Nothing

Since :
2.3
#define APP_CONTROL_OPERATION_SHARE_TEXT   "http://tizen.org/appcontrol/operation/share_text"

Definition for the app_control operation: Shares the text data with someone else.

Input: APP_CONTROL_DATA_TEXT in extra is the text to share
Output: Nothing

Since :
2.3
#define APP_CONTROL_OPERATION_VIDEO_CAPTURE   "http://tizen.org/appcontrol/operation/video_capture"

Definition for the app_control operation: Captures the videos by camera applications.

Input: Nothing
Output: APP_CONTROL_DATA_SELECTED in extra.

Since :
2.4
#define APP_CONTROL_OPERATION_VIEW   "http://tizen.org/appcontrol/operation/view"

Definition for the app_control operation: Displays the data.

Input: URI is usually used to inform the path to show. In some cases, some other data in extra can be used (for example, the VIEW operation for viewing the contact and calendar data).
Output: Nothing

Since :
2.3

Typedef Documentation

typedef void(* app_control_action_cb)(const char *action, app_control_h app_control, void *user_data)

Called when another application sends a launch request to the application.

Before calling app_control_cb() function, this callback function is called.

Since :
5.5
Remarks:
After this callback function returns, the handle of the app_control is released. Therefore, if you want to use the handle after returning this callback function, you MUST copy it by using app_control_clone() function.
The action must not be deallocated by the application. The platform frees the string when the app_control action handle is removed.
Parameters:
[in]actionThe name of the app_control action
[in]app_controlThe handle of the app_control
[in]user_dataThe user data passed from the callback registration function
See also:
app_control_add_action_handler()
Application API
typedef struct app_control_action_s* app_control_action_h

The application control action handle.

Since :
5.5
typedef bool(* app_control_app_matched_cb)(app_control_h app_control, const char *appid, void *user_data)

Called once for each matched application that can be launched to handle the given app_control request.

Since :
2.3
Parameters:
[in]app_controlThe app_control handle
[in]appidThe name of the application that can handle the launch request of the given app_control
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop, otherwise false to break out of the loop
Precondition:
app_control_foreach_app_matched() will invoke this callback.
See also:
app_control_foreach_app_matched()
typedef bool(* app_control_extra_data_cb)(app_control_h app_control, const char *key, void *user_data)

Called to retrieve the extra data contained in the app_control.

Since :
2.3
Remarks:
The key must not be deallocated by the application.
Parameters:
[in]app_controlThe app_control handle
[in]keyThe key of the value contained in the app_control
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop, otherwise false to break out of the loop
Precondition:
app_control_foreach_extra_data() will invoke this callback.
See also:
app_control_foreach_extra_data()
typedef struct app_control_s* app_control_h

The application control handle.

Since :
2.3
typedef void(* app_control_reply_cb)(app_control_h request, app_control_h reply, app_control_result_e result, void *user_data)

Called when the reply of the launch request is delivered.

Since :
2.3
Remarks:
The request and reply must not be deallocated by the application.
Parameters:
[in]requestThe app_control handle of the launch request that has been sent
[in]replyThe app_control handle in which the results of the callee are contained
[in]resultThe result code of the launch request
[in]user_dataThe user data passed from the callback registration function
Precondition:
When the callee replies to the launch request, this callback will be invoked.
Since 2.4, if APP_CONTROL_RESULT_APP_STARTED event is enabled, this callback will also be invoked when the callee application actually launched.
See also:
app_control_send_launch_request()
app_control_reply_to_launch_request()
app_control_enable_app_started_result_event()
APP_CONTROL_RESULT_APP_STARTED
typedef void(* app_control_result_cb)(app_control_h request, app_control_error_e result, void *user_data)

Called when the result of the launch request is delivered.

Following error codes can be delivered:
APP_CONTROL_ERROR_NONE,
APP_CONTROL_ERROR_APP_NOT_FOUND,
APP_CONTROL_ERROR_PERMISSION_DENIED,
APP_CONTROL_ERROR_INVALID_PARAMETER,
APP_CONTROL_ERROR_LAUNCH_REJECTED

Since :
5.0
Remarks:
The request is the same object for which app_control_send_launch_request_async() was called.
Parameters:
[in]requestThe app_control handle of the launch request that has been sent
[in]resultThe result value of the launch request
[in]user_dataThe user data passed from the callback registration function
See also:
app_control_send_launch_request_async()

Enumeration Type Documentation

Enumeration for the application control error.

Since :
2.3
Enumerator:
APP_CONTROL_ERROR_NONE 

Successful

APP_CONTROL_ERROR_INVALID_PARAMETER 

Invalid parameter

APP_CONTROL_ERROR_OUT_OF_MEMORY 

Out of memory

APP_CONTROL_ERROR_APP_NOT_FOUND 

The application is not found

APP_CONTROL_ERROR_KEY_NOT_FOUND 

Specified key is not found

APP_CONTROL_ERROR_KEY_REJECTED 

Key is not available

APP_CONTROL_ERROR_INVALID_DATA_TYPE 

Invalid data type

APP_CONTROL_ERROR_LAUNCH_REJECTED 

The application cannot be launched now

APP_CONTROL_ERROR_PERMISSION_DENIED 

Permission denied

APP_CONTROL_ERROR_LAUNCH_FAILED 

Internal launch error

APP_CONTROL_ERROR_TIMED_OUT 

Time out

APP_CONTROL_ERROR_IO_ERROR 

IO error

Enumeration for the application control launch mode.

Since :
2.4
Enumerator:
APP_CONTROL_LAUNCH_MODE_SINGLE 

Prefer to launch an application as single mode

APP_CONTROL_LAUNCH_MODE_GROUP 

Prefer to launch an application as group mode

Enumeration for the application control result.

Since :
2.3
See also:
app_control_enable_app_started_result_event()
Enumerator:
APP_CONTROL_RESULT_APP_STARTED 

Callee application launched actually (Since 2.4)

APP_CONTROL_RESULT_SUCCEEDED 

Operation succeeded

APP_CONTROL_RESULT_FAILED 

Operation failed by the callee

APP_CONTROL_RESULT_CANCELED 

Operation canceled by the platform


Function Documentation

int app_control_add_action_handler ( const char *  action,
app_control_action_cb  callback,
void *  user_data,
app_control_action_h handle 
)

Adds the action handle of the app_control.

Since :
5.5
Remarks:
The handle must be released using app_control_remove_action_handler().
Parameters:
[in]actionThe action name of the app_control
[in]callbackThe callback function
[in]user_dataThe user data to be passed to the callback function
[out]handleThe app_control action handle
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
APP_CONTROL_ERROR_KEY_NOT_FOUNDSpecified app_control ID not found
APP_CONTROL_ERROR_IO_ERRORIO error
See also:
app_control_action_cb()
app_control_remove_action_handler()
int app_control_add_extra_data ( app_control_h  app_control,
const char *  key,
const char *  value 
)

Adds extra data to the app_control.

Since :
2.3
Remarks:
The function replaces any existing value for the given key.
The function returns APP_CONTROL_ERROR_INVALID_PARAMETER if key or value is a zero-length string.
The function returns APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with the system-defined key.
Parameters:
[in]app_controlThe app_control handle
[in]keyThe name of the extra data
[in]valueThe value associated with the given key
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_KEY_REJECTEDKey not available
See also:
app_control_add_extra_data_array()
app_control_remove_extra_data()
app_control_get_extra_data()
int app_control_add_extra_data_array ( app_control_h  app_control,
const char *  key,
const char *  value[],
int  length 
)

Adds the extra data array to the app_control.

Since :
2.3
Remarks:
The function replaces any existing value for the given key.
The function returns APP_CONTROL_ERROR_INVALID_PARAMETER if key is a zero-length string.
The function returns APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with the system-defined key.
Parameters:
[in]app_controlThe app_control handle
[in]keyThe name of the extra data
[in]valueThe array value associated with the given key
[in]lengthThe length of the array
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_KEY_REJECTEDKey not available
See also:
app_control_add_extra_data()
app_control_remove_extra_data()
app_control_get_extra_data()
int app_control_clone ( app_control_h clone,
app_control_h  app_control 
)

Creates and returns a copy of the given app_control handle.

Since :
2.3
Remarks:
A newly created app_control should be destroyed by calling the app_control_destroy() if it is no longer needed.
Parameters:
[out]cloneIf successful, a newly created app_control handle will be returned
[in]app_controlThe app_control handle
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_control_destroy()
int app_control_create ( app_control_h app_control)

Creates an app_control handle.

Since :
2.3
Remarks:
The app_control must be released using app_control_destroy().
Parameters:
[out]app_controlThe app_control handle to be newly created on success
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_control_destroy()

Creates an app_control handle from an app_control_uri handle.

Since :
5.5
Remarks:
The app_control must be released using app_control_destroy().
Parameters:
[out]app_controlThe app_control handle to be newly created on success
[in]uriThe URI handle
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_control_destroy()
int app_control_create_with_parameters ( app_control_h app_control,
const char *  operation,
const char *  uri,
const char *  mime,
const char *  category,
const char *  app_id,
app_control_launch_mode_e  mode,
int  extra_data_count,
  ... 
)

Creates an app_control handle and sets its attributes.

Extra data of array type cannot be added with this function. If you need to add arrays to the app_control handle, create the handle with app_control_create_with_parameters() and then add arrays with app_control_add_extra_data_array(). For details on key-value pairs that app_control_create_with_parameters() allows, their types and constraints, see app_control_add_extra_data().

Since :
5.5
Remarks:
The app_control must be released using app_control_destroy().
Setting the type of key-value extra data that the value is an array of strings is not allowed.
Parameters:
[out]app_controlThe app_control handle to be newly created on success
[in]operationThe operation to be performed
[in]uriThe URI of the data this app_control is operating on
[in]mimeThe explicit MIME type of the data this app_control is operating on
[in]categoryThe explicit category
[in]app_idThe ID of the application to explicitly launch
[in]modeThe launch mode of the application
[in]extra_data_countThe count of a extra data
[in]...The key-value pair list of app control extra data
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
APP_CONTROL_ERROR_KEY_REJECTEDKey not available
See also:
app_control_destroy()
app_control_add_extra_data()
static int create_app_control()
{
    app_control_h control;
    int ret = app_control_create_with_parameters(&control, NULL, NULL, NULL, NULL,
        "org.tizen.test", APP_CONTROL_LAUNCH_MODE_SINGLE, 2, "key1", "value1", "key2", "value2");
    return ret;
}
int app_control_destroy ( app_control_h  app_control)

Destroys the app_control handle and releases all its resources.

Since :
2.3
Parameters:
[in]app_controlThe app_control handle
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_control_create()

Enables an additional launch result event on the launch request.

The function allows to receive the APP_CONTROL_RESULT_APP_STARTED event on
application get launched by the app_control.

Since :
2.4
Remarks:
app_control_reply_cb() will be called on the APP_CONTROL_RESULT_APP_STARTED event received.
Parameters:
[in]app_controlThe app_control handle
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
app_control_send_launch_request()
APP_CONTROL_RESULT_APP_STARTED
int app_control_foreach_app_matched ( app_control_h  app_control,
app_control_app_matched_cb  callback,
void *  user_data 
)

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

Since :
2.3
Parameters:
[in]app_controlThe app_control handle
[in]callbackThe iteration callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccess
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
Postcondition:
This function invokes app_control_app_matched_cb().
See also:
app_control_app_matched_cb()
int app_control_foreach_extra_data ( app_control_h  app_control,
app_control_extra_data_cb  callback,
void *  user_data 
)

Retrieves all extra data contained in app_control.

This function calls app_control_extra_data_cb() once for each key-value pair for extra data contained in app_control.
If the app_control_extra_data_cb() callback function returns false, then iteration will be finished.

Since :
2.3
Parameters:
[in]app_controlThe app_control handle
[in]callbackThe iteration callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
Postcondition:
This function invokes app_control_extra_data_cb().
See also:
app_control_extra_data_cb()
int app_control_get_app_id ( app_control_h  app_control,
char **  app_id 
)

Gets the ID of the application to explicitly launch.

Since :
2.3
Remarks:
The app_id must be released with free().
Parameters:
[in]app_controlThe app_control handle
[out]app_idThe ID of the application to explicitly launch
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_control_set_app_id()
int app_control_get_caller ( app_control_h  app_control,
char **  id 
)

Gets the application ID of the caller from the launch request.

Since :
2.3
Remarks:
The app_control must be the launch request from app_control_cb().
This function returns APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request.
The id must be released using free().
Parameters:
[in]app_controlThe app_control handle from app_control_cb()
[out]idThe application ID of the caller
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
int app_control_get_category ( app_control_h  app_control,
char **  category 
)

Gets the explicit category.

Since :
2.3
Remarks:
The category must be released using free().
Parameters:
[in]app_controlThe app_control handle
[out]categoryThe explicit category
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_control_set_category()
int app_control_get_component_id ( app_control_h  app_control,
char **  component_id 
)

Gets the ID of the component.

Since :
5.5
Remarks:
The component_id must be released using free().
Parameters:
[in]app_controlThe app_control handle
[out]component_idThe ID of the component which will receive the app_control
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
int app_control_get_extra_data ( app_control_h  app_control,
const char *  key,
char **  value 
)

Gets the extra data from the app_control.

Since :
2.3
Remarks:
The value must be released using free().
The function returns APP_CONTROL_ERROR_INVALID_DATA_TYPE if value is of array data type.
Parameters:
[in]app_controlThe app_control handle
[in]keyThe name of the extra data
[out]valueThe value associated with the given key
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_KEY_NOT_FOUNDSpecified key not found
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
APP_CONTROL_ERROR_INVALID_DATA_TYPEInvalid data type
APP_CONTROL_ERROR_KEY_REJECTEDKey not available
See also:
app_control_add_extra_data()
app_control_add_extra_data_array()
app_control_get_extra_data()
app_control_remove_extra_data()
app_control_foreach_extra_data()
int app_control_get_extra_data_array ( app_control_h  app_control,
const char *  key,
char ***  value,
int *  length 
)

Gets the extra data array from the app_control.

Since :
2.3
Remarks:
The value must be released using free().
The function returns APP_CONTROL_ERROR_INVALID_DATA_TYPE if value is not of array data type.
Parameters:
[in]app_controlThe app_control handle
[in]keyThe name of the extra data
[out]valueThe array value associated with the given key
[out]lengthThe length of the array
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_KEY_NOT_FOUNDSpecified key not found
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
APP_CONTROL_ERROR_INVALID_DATA_TYPEInvalid data type
APP_CONTROL_ERROR_KEY_REJECTEDKey not available
See also:
app_control_add_extra_data()
app_control_add_extra_data_array()
app_control_remove_extra_data()
app_control_foreach_extra_data()

Gets the launch mode of the application.

Since :
2.4
Remarks:
Since Tizen 3.0, if launch mode is not set in the caller application control, the function returns the APP_CONTROL_LAUNCH_MODE_SINGLE launch mode.
Parameters:
[in]app_controlThe app_control handle
[out]modeThe launch mode of the application
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
app_control_get_launch_mode()
app_control_launch_mode_e
int app_control_get_mime ( app_control_h  app_control,
char **  mime 
)

Gets the explicit MIME type of the data.

Since :
2.3
Remarks:
The mime must be released using free().
Parameters:
[in]app_controlThe app_control handle
[out]mimeThe explicit MIME type of the data this app_control is operating on
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_control_set_mime()
int app_control_get_operation ( app_control_h  app_control,
char **  operation 
)

Gets the operation to be performed.

Since :
2.3
Remarks:
The operation must be released using free().
Parameters:
[in]app_controlThe app_control handle
[out]operationThe operation to be performed
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_control_set_operation()
int app_control_get_uri ( app_control_h  app_control,
char **  uri 
)

Gets the URI of the data.

Since :
2.3
Remarks:
The uri must be released using free().
Parameters:
[in]app_controlThe app_control handle
[out]uriThe URI of the data this app_control is operating on
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_control_set_uri()
int app_control_is_extra_data_array ( app_control_h  app_control,
const char *  key,
bool *  array 
)

Checks whether the extra data associated with the given key is of array data type.

Since :
2.3
Parameters:
[in]app_controlThe app_control handle
[in]keyThe name of the extra data
[out]arrayIf true the extra data is of array data type, otherwise false
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
app_control_add_extra_data()
app_control_add_extra_data_array()
app_control_remove_extra_data()
app_control_foreach_extra_data()
int app_control_is_reply_requested ( app_control_h  app_control,
bool *  requested 
)

Checks whether the caller is requesting a reply from the launch request.

Since :
2.3
Remarks:
The app_control must be the launch request from app_control_cb().
This function returns APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request.
Parameters:
[in]app_controlThe app_control handle from app_control_cb()
[out]requestedIf true a reply is requested by the caller, otherwise false
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory

Removes the registered action handle of the app_control.

Since :
5.5
Parameters:
[in]handleThe app_control action handle
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
app_control_add_action_handler()
int app_control_remove_extra_data ( app_control_h  app_control,
const char *  key 
)

Removes the extra data from the app_control.

Since :
2.3
Parameters:
[in]app_controlThe app_control handle
[in]keyThe name of the extra data
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_KEY_NOT_FOUNDSpecified key not found
APP_CONTROL_ERROR_KEY_REJECTEDKey not available
See also:
app_control_add_extra_data()
app_control_add_extra_data_array()
app_control_get_extra_data()

Replies to the launch request sent by the caller.

If the caller application sent the launch request to receive the result, the callee application can return the result back to the caller.

Since :
2.3
Remarks:
The function is not allowed to send reply APP_CONTROL_RESULT_APP_STARTED as result which is reserved for platform developers.
Parameters:
[in]replyThe app_control handle in which the results of the callee are contained
[in]requestThe app_control handle sent by the caller
[in]resultThe result code of the launch request
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_control_send_launch_request()
int app_control_send_launch_request ( app_control_h  app_control,
app_control_reply_cb  callback,
void *  user_data 
)

Sends the launch request.

The operation is mandatory information for the launch request.
If the operation is not specified, APP_CONTROL_OPERATION_DEFAULT is used by default. If the operation is APP_CONTROL_OPERATION_DEFAULT, the application ID is mandatory to explicitly launch the application.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/appmanager.launch
Remarks:
The function returns APP_CONTROL_ERROR_LAUNCH_REJECTED if the operation value is APP_CONTROL_OPERATION_LAUNCH_ON_EVENT which is only for handling the event from the platform or other application, refer to the Event module.
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 application ID given by the app_control_set_app_id() must be sent.
Parameters:
[in]app_controlThe app_control handle
[in]callbackThe callback function to be called when the reply is delivered
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
APP_CONTROL_ERROR_APP_NOT_FOUNDThe application to run the given launch request is not found
APP_CONTROL_ERROR_LAUNCH_REJECTEDThe application cannot be launched in current context
APP_CONTROL_ERROR_LAUNCH_FAILEDFailed to launch the application
APP_CONTROL_ERROR_TIMED_OUTFailed due to timeout. The application that handles app_control may be busy
APP_CONTROL_ERROR_PERMISSION_DENIEDPermission denied
Postcondition:
If the launch request is sent for the result, the result will come back through the app_control_reply_cb() from the callee application. Additional replies may be delivered on the app_control_enable_app_started_result_event() called.
See also:
app_control_reply_to_launch_request()
app_control_reply_cb()
app_control_enable_app_started_result_event()
int app_control_send_launch_request_async ( app_control_h  app_control,
app_control_result_cb  result_cb,
app_control_reply_cb  reply_cb,
void *  user_data 
)

Sends the launch request asynchronously.

The operation is mandatory information for the launch request.
If the operation is not specified, APP_CONTROL_OPERATION_DEFAULT is used by default. If the operation is APP_CONTROL_OPERATION_DEFAULT, the application ID is mandatory to explicitly launch the application.

After the callee application is initialized or the launch request is delivered to the running application successfully, the result callback function will be invoked.

Since :
5.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/appmanager.launch
Remarks:
The function returns APP_CONTROL_ERROR_LAUNCH_REJECTED if the operation value is APP_CONTROL_OPERATION_LAUNCH_ON_EVENT which is only for handling the event from the platform or other application, refer to the Event Module.
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 application ID given by the app_control_set_app_id() must be sent.
Parameters:
[in]app_controlThe app_control handle
[in]result_cbThe callback function to be called when the result is delivered
[in]reply_cbThe callback function to be called when the reply is delivered
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
APP_CONTROL_ERROR_APP_NOT_FOUNDThe application to run the given launch request is not found
APP_CONTROL_ERROR_LAUNCH_REJECTEDThe application cannot be launched in current context
APP_CONTROL_ERROR_LAUNCH_FAILEDFailed to launch the application
APP_CONTROL_ERROR_TIMED_OUTFailed due to timeout. The application that handles app_control may be busy
APP_CONTROL_ERROR_PERMISSION_DENIEDPermission denied
Postcondition:
If the launch request is sent for the result, the result will come back through the app_control_reply_cb() from the callee application. Additional replies may be delivered if app_control_enable_app_started_result_event() was called.
See also:
app_control_result_cb()
app_control_reply_to_launch_request()
app_control_reply_cb()
app_control_enable_app_started_result_event()

Sends the launch request synchronously.

The operation is mandatory information for the launch request.
If the operation is not specified, APP_CONTROL_OPERATION_DEFAULT is used by default. If the operation is APP_CONTROL_OPERATION_DEFAULT, the application ID is mandatory to explicitly launch the application.

Since :
5.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/appmanager.launch
Remarks:
The function returns APP_CONTROL_ERROR_LAUNCH_REJECTED if the operation value is APP_CONTROL_OPERATION_LAUNCH_ON_EVENT, which is only for handling the event from the platform or other applications, refer to the Event Module.
The platform does not allow launching service applications from packages other than the requesting application's package. Also, implicit launch requests are NOT delivered to service applications since 2.4. To launch a service application, an explicit launch request with application ID set by app_control_set_app_id() must be sent.
If the callee application doesn't respond, the function returns a negative error value.
The reply must be released using app_control_destroy().
Parameters:
[in]app_controlThe app_control handle
[out]replyThe app_control handle in which the results of the callee are contained
[out]resultThe result code of the launch request
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
APP_CONTROL_ERROR_APP_NOT_FOUNDThe application to run the given launch request is not found
APP_CONTROL_ERROR_LAUNCH_REJECTEDThe application cannot be launched in current context
APP_CONTROL_ERROR_LAUNCH_FAILEDFailed to launch the application
APP_CONTROL_ERROR_TIMED_OUTFailed due to timeout. The application that handles app_control may be busy
APP_CONTROL_ERROR_PERMISSION_DENIEDPermission denied
See also:
app_control_destroy()

Sends the terminate request to the application that is launched by app_control. This API is only effective for some applications that are provided by default for handling platform default app_controls. You are not allowed to terminate other general applications using this API.

Since :
2.3
Remarks:
Since Tizen 2.4, this API can be used to terminate sub-applications which were launched as group mode by the caller application. Once 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.
Parameters:
[in]app_controlThe app_control handle
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_PERMISSION_DENIEDPermission denied
See also:
app_control_send_launch_request()
app_control_set_launch_mode()
int app_control_set_app_id ( app_control_h  app_control,
const char *  app_id 
)

Sets the ID of the application to explicitly launch.

Since :
2.3
Parameters:
[in]app_controlThe app_control handle
[in]app_idThe ID of the application to explicitly launch (if the app_id is NULL, it clears the previous value)
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_control_get_app_id()
int app_control_set_category ( app_control_h  app_control,
const char *  category 
)

Sets the explicit category.

Since :
2.3
Parameters:
[in]app_controlThe app_control handle
[in]categoryThe explicit category (if the category is NULL, it clears the previous value)
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
app_control_get_category()
int app_control_set_component_id ( app_control_h  app_control,
const char *  component_id 
)

Sets the ID of the component.

Since :
5.5
Remarks:
If the component_id is null, the component_id set previously will be removed.
The component_id is declared by the component-based app, and it is unique globally.
Parameters:
[in]app_controlThe app_control handle
[in]component_idThe ID of the component which will receive the app_control
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
APP_CONTROL_ERROR_OUT_OF_MEMORYOut of memory

Sets the launch mode of the application.

This function allows the callee application to be launched as a group or as a single mode.

Since :
2.4
Remarks:
Although launch_mode were set as APP_CONTROL_LAUNCH_MODE_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 function 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.
Parameters:
[in]app_controlThe app_control handle
[in]modeThe launch mode of the application
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
app_control_set_launch_mode()
app_control_launch_mode_e
int app_control_set_mime ( app_control_h  app_control,
const char *  mime 
)

Sets the explicit MIME type of the data.

Since :
2.3
Parameters:
[in]app_controlThe app_control handle
[in]mimeThe explicit MIME type of the data this app_control is operating on (if the mime is NULL, it clears the previous value)
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
app_control_get_mime()
int app_control_set_operation ( app_control_h  app_control,
const char *  operation 
)

Sets the operation to be performed.

The operation is the mandatory information for the launch request. If the operation is not specified, APP_CONTROL_OPERATION_DEFAULT is used for the launch request. If the operation is APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.

Since :
2.3
Parameters:
[in]app_controlThe app_control handle
[in]operationThe operation to be performed (if the operation is NULL, it clears the previous value)
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
app_control_get_operation()
APP_CONTROL_OPERATION_DEFAULT
APP_CONTROL_OPERATION_EDIT
APP_CONTROL_OPERATION_VIEW
APP_CONTROL_OPERATION_PICK
APP_CONTROL_OPERATION_CREATE_CONTENT
APP_CONTROL_OPERATION_CALL
APP_CONTROL_OPERATION_SEND
APP_CONTROL_OPERATION_SEND_TEXT
APP_CONTROL_OPERATION_DIAL
APP_CONTROL_OPERATION_SEARCH
int app_control_set_uri ( app_control_h  app_control,
const char *  uri 
)

Sets the URI of the data.

Since :
2.3
Remarks:
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 calling the app_get_data_path() function, 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.
Parameters:
[in]app_controlThe app_control handle
[in]uriThe URI of the data this app_control is operating on (if the uri is NULL, it clears the previous value)
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
app_control_get_uri()

Sets the URI by the app_control_uri handle.

Since :
5.5
Parameters:
[in]app_controlThe app_control handle
[in]uriThe URI handle
Returns:
0 on success, otherwise a negative error value
Return values:
APP_CONTROL_ERROR_NONESuccessful
APP_CONTROL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
app_control_set_uri()