include/app_control.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_APPFW_APP_CONTROL_H__
  19 #define __TIZEN_APPFW_APP_CONTROL_H__
  20
  21 #include <tizen.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file app_control.h
  29  */
  30
  31 /**
  32  * @addtogroup CAPI_APP_CONTROL_MODULE
  33  * @{
  34  */
  35
  36
  37 typedef struct _bundle_t bundle;
  38 typedef unsigned char bundle_raw;
  39
  40 /**
  41  * @brief App Control handle.
  42  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  43  */
  44 typedef struct app_control_s* app_control_h;
  45
  46
  47 /**
  48  * @brief Enumeration for App Control Error.
  49  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  50  */
  51 typedef enum
  52 {
  53         APP_CONTROL_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  54         APP_CONTROL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  55         APP_CONTROL_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  56         APP_CONTROL_ERROR_APP_NOT_FOUND = TIZEN_ERROR_APPLICATION | 0x21, /**< The application is not found */
  57         APP_CONTROL_ERROR_KEY_NOT_FOUND = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Specified key is not found */
  58         APP_CONTROL_ERROR_KEY_REJECTED = TIZEN_ERROR_KEY_REJECTED, /**< Key is not available */
  59         APP_CONTROL_ERROR_INVALID_DATA_TYPE = TIZEN_ERROR_APPLICATION | 0x22, /**< Invalid data type */
  60         APP_CONTROL_ERROR_LAUNCH_REJECTED = TIZEN_ERROR_APPLICATION | 0x23, /**< The application cannot be launched now*/
  61         APP_CONTROL_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,    /**< Permission denied */
  62         APP_CONTROL_ERROR_LAUNCH_FAILED = TIZEN_ERROR_APPLICATION | 0x24, /**< Internal launch error */
  63         APP_CONTROL_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT, /**< Time out */
  64         APP_CONTROL_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR       /**< IO error */
  65 } app_control_error_e;
  66
  67
  68 /**
  69  * @brief Enumeration for App Control Result.
  70  * @see app_control_enable_app_started_result_event()
  71  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  72  */
  73 typedef enum
  74 {
  75         APP_CONTROL_RESULT_APP_STARTED = 1, /**< Callee application launched actually (Since 2.4) */
  76         APP_CONTROL_RESULT_SUCCEEDED = 0, /**< Operation succeeded */
  77         APP_CONTROL_RESULT_FAILED = -1, /**< Operation failed by the callee */
  78         APP_CONTROL_RESULT_CANCELED = -2, /**< Operation canceled by the platform */
  79 } app_control_result_e;
  80
  81 /**
  82  * @brief Enumeration for App Control Launch Mode.
  83  * @since_tizen 2.4
  84  */
  85 typedef enum {
  86         APP_CONTROL_LAUNCH_MODE_SINGLE = 0, /**< Prefer to launch an application as single mode */
  87         APP_CONTROL_LAUNCH_MODE_GROUP, /**< Prefer to launch an application as group mode */
  88 } app_control_launch_mode_e;
  89
  90 /**
  91  * @brief Definition for the app_control operation: An explicit launch for a homescreen application.
  92  * @details Input: Nothing\n
  93  *          Output: Nothing\n
  94  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  95  */
  96 #define APP_CONTROL_OPERATION_MAIN "http://tizen.org/appcontrol/operation/main"
  97
  98
  99 /**
 100  * @brief Definition for the app_control operation: An explicit launch for an application that excludes a homescreen application.
 101  * @details Input: Nothing\n
 102  *          Output: Nothing\n
 103  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 104  */
 105 #define APP_CONTROL_OPERATION_DEFAULT "http://tizen.org/appcontrol/operation/default"
 106
 107
 108 /**
 109  * @brief Definition for the app_control operation: Provides an editable access to the given data.
 110  * @details Input: It depends on application scenario/configuration.\n
 111  *          Output: It depends on application scenario/configuration.\n
 112  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 113  */
 114 #define APP_CONTROL_OPERATION_EDIT "http://tizen.org/appcontrol/operation/edit"
 115
 116
 117 /**
 118  * @brief Definition for the app_control operation: Displays the data.
 119  * @details Input: URI is usually used to inform the path to show. In some cases, some other data in Extra can be used (e.g., VIEW operation for viewing Contact, Calendar data).\n
 120  *          Output: Nothing\n
 121  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 122  */
 123 #define APP_CONTROL_OPERATION_VIEW "http://tizen.org/appcontrol/operation/view"
 124
 125
 126 /**
 127  * @brief Definition for the app_control operation: Picks items.
 128  * @details Input: It depends on application scenario/configuration.\n
 129  *          Output: APP_CONTROL_DATA_SELECTED in Extra\n
 130  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 131  */
 132 #define APP_CONTROL_OPERATION_PICK "http://tizen.org/appcontrol/operation/pick"
 133
 134
 135 /**
 136  * @brief Definition for the app_control operation: Creates contents.
 137  * @details Input: It depends on application scenario/configuration.\n
 138  *          Output: APP_CONTROL_DATA_SELECTED in Extra\n
 139  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 140  */
 141 #define APP_CONTROL_OPERATION_CREATE_CONTENT "http://tizen.org/appcontrol/operation/create_content"
 142
 143
 144 /**
 145  * @brief Definition for the app_control operation: Performs a call to someone.
 146  * @details Input: URI is the number to be dialed. This is mandatory field.\n
 147  *          Output: Nothing\n
 148  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 149  * @privlevel public
 150  * @privilege %http://tizen.org/privilege/call
 151  * @remarks When you request this operation, you must declare this privilege.
 152  */
 153 #define APP_CONTROL_OPERATION_CALL "http://tizen.org/appcontrol/operation/call"
 154
 155
 156 /**
 157  * @brief Definition for the app_control operation: Delivers some data to someone else.
 158  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 159  * @deprecated Deprecated since 2.4. Use #APP_CONTROL_OPERATION_SHARE instead.
 160  */
 161 #define APP_CONTROL_OPERATION_SEND "http://tizen.org/appcontrol/operation/send"
 162
 163
 164 /**
 165  * @brief Definition for the app_control operation: Delivers text data to someone else.
 166  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 167  * @deprecated Deprecated since 2.4. Use #APP_CONTROL_OPERATION_SHARE_TEXT instead.
 168  */
 169 #define APP_CONTROL_OPERATION_SEND_TEXT "http://tizen.org/appcontrol/operation/send_text"
 170
 171
 172 /**
 173  * @brief Definition for the app_control operation: Shares an item with someone else.
 174  * @details Input: URI is usually used to inform the path to share. In some cases, some other data in Extra can be used (e.g., SHARE operation for sharing Contact data, SHARE operation for sharing an item through Message, Email applications).\n
 175  *          Output: Nothing\n
 176  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 177  */
 178 #define APP_CONTROL_OPERATION_SHARE "http://tizen.org/appcontrol/operation/share"
 179
 180
 181 /**
 182  * @brief Definition for the app_control operation: Shares multiple items with someone else.
 183  * @details 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 (e.g., MULTI_SHARE opeation for sharing Contact data).\n
 184  *          Output: Nothing\n
 185  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 186  */
 187 #define APP_CONTROL_OPERATION_MULTI_SHARE "http://tizen.org/appcontrol/operation/multi_share"
 188
 189
 190 /**
 191  * @brief Definition for the app_control operation: Shares text data with someone else.
 192  * @details Input: APP_CONTROL_DATA_TEXT in Extra is the text to share\n
 193  *          Output: Nothing\n
 194  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 195  */
 196 #define APP_CONTROL_OPERATION_SHARE_TEXT "http://tizen.org/appcontrol/operation/share_text"
 197
 198
 199 /**
 200  * @brief 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.
 201  * @details Input: URI is the number to be dialed. If empty, show a UI without number.\n
 202  *          Output: Nothing\n
 203  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 204  */
 205 #define APP_CONTROL_OPERATION_DIAL "http://tizen.org/appcontrol/operation/dial"
 206
 207
 208 /**
 209  * @brief Definition for the app_control operation: Performs a search.
 210  * @details Input: APP_CONTROL_DATA_TEXT in Extra is the text to search for. If empty, show a search UI.\n
 211  *          Output: Nothing\n
 212  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 213  */
 214 #define APP_CONTROL_OPERATION_SEARCH "http://tizen.org/appcontrol/operation/search"
 215
 216
 217 /**
 218  * @brief Definition for the app_control operation: Downloads items.
 219  * @details Input: It depends on application scenario/configuration.\n
 220  *          Output: It depends on application scenario/configuration.\n
 221  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 222  * @privlevel public
 223  * @privilege %http://tizen.org/privilege/download (Since 2.4)
 224  * @remarks When you request this operation, you must declare this privilege. (Since 2.4)
 225  */
 226 #define APP_CONTROL_OPERATION_DOWNLOAD "http://tizen.org/appcontrol/operation/download"
 227
 228
 229 /**
 230  * @brief Definition for the app_control operation: Prints contents.
 231  * @details Input: It depends on application scenario/configuration.\n
 232  *          Output: It depends on application scenario/configuration.\n
 233  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 234  */
 235 #define APP_CONTROL_OPERATION_PRINT "http://tizen.org/appcontrol/operation/print"
 236
 237 /**
 238  * @brief Definition for the app_control operation: Composes a message.
 239  * @details Input: It depends on application scenario/configuration.\n
 240  *          Output: Nothing\n
 241  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 242  */
 243 #define APP_CONTROL_OPERATION_COMPOSE "http://tizen.org/appcontrol/operation/compose"
 244
 245 /**
 246  * @brief Definition for the app_control operation: Can be launched by interested System-Event.
 247  * @details Input : URI and extras data defined in Event module.\n
 248  *          Output: Nothing\n
 249  * @since_tizen 2.4
 250  * @remarks This operation is for handling event from the platform. This operation can not be requested via app_control_send_launch_request().
 251  * @remarks Refer to Launch-On-Event section of Event module.
 252  */
 253 #define APP_CONTROL_OPERATION_LAUNCH_ON_EVENT "http://tizen.org/appcontrol/operation/launch_on_event"
 254
 255 /**
 256  * @brief Definition for the app_control operation: Adds an item.
 257  * @details Input: It depends on application scenario/configuration.\n
 258  *          Output: It depends on application scenario/configuration.\n
 259  * @since_tizen 2.4
 260  */
 261 #define APP_CONTROL_OPERATION_ADD "http://tizen.org/appcontrol/operation/add"
 262
 263 /**
 264  * @brief Definition for the app_control operation: Captures images by camera applications.
 265  * @details Input: Nothing\n
 266  *          Output: APP_CONTROL_DATA_SELECTED in Extra\n
 267  * @since_tizen 2.4
 268  */
 269 #define APP_CONTROL_OPERATION_IMAGE_CAPTURE "http://tizen.org/appcontrol/operation/image_capture"
 270
 271 /**
 272  * @brief Definition for the app_control operation: Captures videos by camera applications.
 273  * @details Input: Nothing\n
 274  *          Output: APP_CONTROL_DATA_SELECTED in Extra\n
 275  * @since_tizen 2.4
 276  */
 277 #define APP_CONTROL_OPERATION_VIDEO_CAPTURE "http://tizen.org/appcontrol/operation/video_capture"
 278
 279 /**
 280  * @brief Definition for the app_control operation: Shows settings to enable Bluetooth.
 281  * @details Input: Nothing\n
 282  *          Output: Nothing\n
 283  * @since_tizen 2.4
 284  */
 285 #define APP_CONTROL_OPERATION_SETTING_BT_ENABLE "http://tizen.org/appcontrol/operation/setting/bt_enable"
 286
 287 /**
 288  * @brief Definition for the app_control operation: Shows settings to configure Bluetooth visibility.
 289  * @details Input: Nothing\n
 290  *          Output: Nothing\n
 291  * @since_tizen 2.4
 292  */
 293 #define APP_CONTROL_OPERATION_SETTING_BT_VISIBILITY "http://tizen.org/appcontrol/operation/setting/bt_visibility"
 294
 295 /**
 296  * @brief Definition for the app_control operation: Shows settings to allow configuration of current location sources.
 297  * @details Input: Nothing\n
 298  *          Output: Nothing\n
 299  * @since_tizen 2.4
 300  */
 301 #define APP_CONTROL_OPERATION_SETTING_LOCATION "http://tizen.org/appcontrol/operation/setting/location"
 302
 303 /**
 304  * @brief Definition for the app_control operation: Shows NFC settings.
 305  * @details Input: Nothing\n
 306  *          Output: Nothing\n
 307  * @since_tizen 2.4
 308  */
 309 #define APP_CONTROL_OPERATION_SETTING_NFC "http://tizen.org/appcontrol/operation/setting/nfc"
 310
 311 /**
 312  * @brief Definition for the app_control operation: Shows system settings.
 313  * @details Input: Nothing\n
 314  *          Output: Nothing\n
 315  * @since_tizen 2.4
 316  */
 317 #define APP_CONTROL_OPERATION_SETTING "http://tizen.org/appcontrol/operation/setting"
 318
 319 /**
 320  * @brief Definition for the app_control operation: Shows settings to allow configuration of Wi-Fi.
 321  * @details Input: Nothing\n
 322  *          Output: Nothing\n
 323  * @since_tizen 2.4
 324  */
 325 #define APP_CONTROL_OPERATION_SETTING_WIFI "http://tizen.org/appcontrol/operation/setting/wifi"
 326
 327 /**
 328  * @brief Definition for app_control data: Subject
 329  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 330  */
 331 #define APP_CONTROL_DATA_SUBJECT "http://tizen.org/appcontrol/data/subject"
 332
 333
 334 /**
 335  * @brief Definition for app_control data: Recipients
 336  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 337  */
 338 #define APP_CONTROL_DATA_TO "http://tizen.org/appcontrol/data/to"
 339
 340
 341 /**
 342  * @brief Definition for app_control data: E-mail addresses that should be carbon copied
 343  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 344  */
 345 #define APP_CONTROL_DATA_CC "http://tizen.org/appcontrol/data/cc"
 346
 347
 348 /**
 349  * @brief Definition for app_control data: E-mail addresses that should be blind carbon copied
 350  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 351  */
 352 #define APP_CONTROL_DATA_BCC "http://tizen.org/appcontrol/data/bcc"
 353
 354
 355 /**
 356  * @brief Definition for app_control data: Text
 357  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 358  */
 359 #define APP_CONTROL_DATA_TEXT "http://tizen.org/appcontrol/data/text"
 360
 361
 362 /**
 363  * @brief Definition for app_control data: Title
 364  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 365  */
 366 #define APP_CONTROL_DATA_TITLE "http://tizen.org/appcontrol/data/title"
 367
 368
 369 /**
 370  * @brief Definition for app_control data: Selected items
 371  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 372  */
 373 #define APP_CONTROL_DATA_SELECTED "http://tizen.org/appcontrol/data/selected"
 374
 375
 376 /**
 377  * @brief Definition for app_control data: Paths of items
 378  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 379  * @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 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.
 380  */
 381 #define APP_CONTROL_DATA_PATH "http://tizen.org/appcontrol/data/path"
 382
 383
 384 /**
 385  * @brief Definition for app_control data: Selection mode. ("single" or "multiple")
 386  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 387  */
 388 #define APP_CONTROL_DATA_SELECTION_MODE "http://tizen.org/appcontrol/data/selection_mode"
 389
 390
 391 /**
 392  * @brief Definition for app_control data: All-day mode of event ("true" or "false")
 393  * @since_tizen 2.4
 394  */
 395 #define APP_CONTROL_DATA_CALENDAR_ALL_DAY "http://tizen.org/appcontrol/data/calendar/all_day"
 396
 397
 398 /**
 399  * @brief Definition for app_control data: Start time of event (format: YYYY-MM-DD HH:MM:SS)
 400  * @since_tizen 2.4
 401  */
 402 #define APP_CONTROL_DATA_CALENDAR_START_TIME "http://tizen.org/appcontrol/data/calendar/start_time"
 403
 404
 405 /**
 406  * @brief Definition for app_control data: End time of event (format: YYYY-MM-DD HH:MM:SS)
 407  * @since_tizen 2.4
 408  */
 409 #define APP_CONTROL_DATA_CALENDAR_END_TIME "http://tizen.org/appcontrol/data/calendar/end_time"
 410
 411
 412 /**
 413  * @brief Definition for app_control data: E-mail addresses
 414  * @since_tizen 2.4
 415  */
 416 #define APP_CONTROL_DATA_EMAIL "http://tizen.org/appcontrol/data/email"
 417
 418
 419 /**
 420  * @brief Definition for app_control data: Phone numbers
 421  * @since_tizen 2.4
 422  */
 423 #define APP_CONTROL_DATA_PHONE "http://tizen.org/appcontrol/data/phone"
 424
 425
 426 /**
 427  * @brief Definition for app_control data: URLs
 428  * @since_tizen 2.4
 429  */
 430 #define APP_CONTROL_DATA_URL "http://tizen.org/appcontrol/data/url"
 431
 432
 433 /**
 434  * @brief Definition for app_control data: IDs
 435  * @since_tizen 2.4
 436  */
 437 #define APP_CONTROL_DATA_ID "http://tizen.org/appcontrol/data/id"
 438
 439
 440 /**
 441  * @brief Definition for app_control data: Type
 442  * @since_tizen 2.4
 443  */
 444 #define APP_CONTROL_DATA_TYPE "http://tizen.org/appcontrol/data/type"
 445
 446
 447 /**
 448  * @brief Definition for app_control data: Total count
 449  * @since_tizen 2.4
 450  */
 451 #define APP_CONTROL_DATA_TOTAL_COUNT "http://tizen.org/appcontrol/data/total_count"
 452
 453
 454 /**
 455  * @brief Definition for app_control data: Total size (unit : bytes)
 456  * @since_tizen 2.4
 457  */
 458 #define APP_CONTROL_DATA_TOTAL_SIZE "http://tizen.org/appcontrol/data/total_size"
 459
 460 /**
 461  * @brief Definition for app_control data: Name
 462  * @since_tizen 2.4
 463  */
 464 #define APP_CONTROL_DATA_NAME "http://tizen.org/appcontrol/data/name"
 465
 466 /**
 467  * @brief Called when the reply of the launch request is delivered.
 468  *
 469  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 470  *
 471  * @remarks The @a request and @a reply must not be deallocated by the application.
 472  *
 473  * @param[in] request The app_control handle of the launch request that has been sent
 474  * @param[in] reply The app_control handle in which the results of the callee are contained
 475  * @param[in] result The result code of the launch request
 476  * @param[in] user_data The user data passed from the callback registration function
 477  * @pre When the callee replies to the launch request, this callback will be invoked.
 478  * @pre Since 2.4, if #APP_CONTROL_RESULT_APP_STARTED event is enabled,
 479  *      this callback also will be invoked when the callee app actually launched.
 480  * @see app_control_send_launch_request()
 481  * @see app_control_reply_to_launch_request()
 482  * @see app_control_enable_app_started_result_event()
 483  * @see #APP_CONTROL_RESULT_APP_STARTED
 484  */
 485 typedef void (*app_control_reply_cb) (app_control_h request, app_control_h reply, app_control_result_e result, void *user_data);
 486
 487
 488 /**
 489  * @brief Called to retrieve the extra data contained in the app_control.
 490  *
 491  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 492  *
 493  * @remarks The @a key must not be deallocated by the application.
 494  *
 495  * @param[in] app_control  The app_control handle
 496  * @param[in] key The key of the value contained in the app_control
 497  * @param[in] user_data The user data passed from the foreach function
 498  * @return @c true to continue with the next iteration of the loop,
 499  *         otherwise @c false to break out of the loop
 500  * @pre app_control_foreach_extra_data() will invoke this callback.
 501  * @see app_control_foreach_extra_data()
 502  */
 503 typedef bool (*app_control_extra_data_cb)(app_control_h app_control, const char *key, void *user_data);
 504
 505
 506 /**
 507  * @brief Called once for each matched application that can be launched to handle the given app_control request.
 508  *
 509  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 510  * @param[in] app_control  The app_control handle
 511  * @param[in] package The package name of the application that can handle the launch request of the given app_control
 512  * @param[in] user_data The user data passed from the foreach function
 513  * @return @c true to continue with the next iteration of the loop,
 514  *         otherwise @c false to break out of the loop
 515  * @pre app_control_foreach_app_matched() will invoke this callback.
 516  * @see app_control_foreach_app_matched()
 517  */
 518 typedef bool (*app_control_app_matched_cb)(app_control_h app_control, const char *appid, void *user_data);
 519
 520
 521 typedef int (*app_control_host_res_fn)(void *data);
 522
 523 /**
 524  * @brief Creates an app_control handle.
 525  *
 526  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 527  * @remarks The @a app_control must be released using app_control_destroy().
 528  * @param[out] app_control The app_control handle to be newly created on success
 529  * @return @c 0 on success,
 530  *         otherwise a negative error value
 531  * @retval #APP_CONTROL_ERROR_NONE Successful
 532  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 533  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 534  * @see app_control_destroy()
 535  */
 536 int app_control_create(app_control_h *app_control);
 537
 538
 539 /**
 540  * @brief Destroys the app_control handle and releases all its resources.
 541  *
 542  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 543  * @param[in] app_control The app_control handle
 544  * @return @c 0 on success,
 545  *         otherwise a negative error value
 546  * @retval #APP_CONTROL_ERROR_NONE Successful
 547  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 548  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 549  * @see app_control_create()
 550  */
 551 int app_control_destroy(app_control_h app_control);
 552
 553
 554 /**
 555  * @brief Sets the operation to be performed.
 556  *
 557  * @details The @a operation is the mandatory information for the launch request.
 558  *          If the operation is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 559  *          If the operation is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 560  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 561  * @param[in] app_control The app_control handle
 562  * @param[in] operation The operation to be performed (if the @a operation is @c NULL, it clears the previous value)
 563  * @return @c 0 on success,
 564  *         otherwise a negative error value
 565  * @retval #APP_CONTROL_ERROR_NONE Successful
 566  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 567  * @see app_control_get_operation()
 568  * @see APP_CONTROL_OPERATION_DEFAULT
 569  * @see APP_CONTROL_OPERATION_EDIT
 570  * @see APP_CONTROL_OPERATION_VIEW
 571  * @see APP_CONTROL_OPERATION_PICK
 572  * @see APP_CONTROL_OPERATION_CREATE_CONTENT
 573  * @see APP_CONTROL_OPERATION_CALL
 574  * @see APP_CONTROL_OPERATION_SEND
 575  * @see APP_CONTROL_OPERATION_SEND_TEXT
 576  * @see APP_CONTROL_OPERATION_DIAL
 577  * @see APP_CONTROL_OPERATION_SEARCH
 578  */
 579 int app_control_set_operation(app_control_h app_control, const char *operation);
 580
 581
 582 /**
 583  * @brief Gets the operation to be performed.
 584  *
 585  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 586  * @remarks The @a operation must be released using free().
 587  * @param[in] app_control The app_control handle
 588  * @param[out] operation The operation to be performed
 589  * @return @c 0 on success,
 590  *         otherwise a negative error value
 591  * @retval #APP_CONTROL_ERROR_NONE Successful
 592  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 593  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 594  * @see app_control_set_operation()
 595  */
 596 int app_control_get_operation(app_control_h app_control, char **operation);
 597
 598
 599 /**
 600  * @brief Sets the URI of the data.
 601  *
 602  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 603  * @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 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.
 604  * @param[in] app_control The app_control handle
 605  * @param[in] uri The URI of the data this app_control is operating on (if the @a uri is @c NULL, it clears the previous value)
 606  * @return @c 0 on success,
 607  *         otherwise a negative error value
 608  * @retval #APP_CONTROL_ERROR_NONE Successful
 609  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 610  * @see app_control_get_uri()
 611  */
 612 int app_control_set_uri(app_control_h app_control, const char *uri);
 613
 614
 615 /**
 616  * @brief Gets the URI of the data.
 617  *
 618  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 619  * @remarks The @a uri must be released using free().
 620  * @param[in] app_control The app_control handle
 621  * @param[out] uri The URI of the data this app_control is operating on
 622  * @return @c 0 on success,
 623  *         otherwise a negative error value
 624  * @retval #APP_CONTROL_ERROR_NONE Successful
 625  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 626  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 627  * @see app_control_set_uri()
 628  */
 629 int app_control_get_uri(app_control_h app_control, char **uri);
 630
 631
 632 /**
 633  * @brief Sets the explicit MIME type of the data.
 634  *
 635  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 636  * @param[in] app_control The app_control handle
 637  * @param[in] mime The explicit MIME type of the data this app_control is operating on (if the @a mime is @c NULL, it clears the previous value)
 638  * @return @c 0 on success,
 639  *         otherwise a negative error value
 640  * @retval #APP_CONTROL_ERROR_NONE Successful
 641  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 642  * @see app_control_get_mime()
 643  */
 644 int app_control_set_mime(app_control_h app_control, const char *mime);
 645
 646
 647 /**
 648  * @brief Gets the explicit MIME type of the data.
 649  *
 650  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 651  * @remarks The @a uri must be released using free().
 652  * @param[in] app_control The app_control handle
 653  * @param[out] mime The explicit MIME type of the data this app_control is operating on
 654  * @return @c 0 on success,
 655  *         otherwise a negative error value
 656  * @retval #APP_CONTROL_ERROR_NONE Successful
 657  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 658  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 659  * @see app_control_set_mime()
 660  */
 661 int app_control_get_mime(app_control_h app_control, char **mime);
 662
 663
 664 /**
 665  * @brief Sets the explicit category.
 666  *
 667  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 668  * @param[in] app_control The app_control handle
 669  * @param[in] category The explicit category (if the @a category is @c NULL, it clears the previous value)
 670  * @return @c 0 on success,
 671  *         otherwise a negative error value
 672  * @retval #APP_CONTROL_ERROR_NONE Successful
 673  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 674  * @see app_control_get_category()
 675  */
 676 int app_control_set_category(app_control_h app_control, const char *category);
 677
 678
 679 /**
 680  * @brief Gets the explicit category.
 681  *
 682  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 683  * @remarks The @a category must be released using free().
 684  * @param[in] app_control The app_control handle
 685  * @param[out] category The explicit category
 686  * @return @c 0 on success,
 687  *         otherwise a negative error value
 688  * @retval #APP_CONTROL_ERROR_NONE Successful
 689  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 690  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 691  * @see app_control_set_category()
 692  */
 693 int app_control_get_category(app_control_h app_control, char **category);
 694
 695
 696 /**
 697  * @brief Sets the ID of the application to explicitly launch.
 698  *
 699  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 700  * @param[in] app_control The app_control handle
 701  * @param[in] app_id The ID of the application to explicitly launch (if the @a app_id is @c NULL, it clears the previous value)
 702  * @return @c 0 on success,
 703  *         otherwise a negative error value
 704  * @retval #APP_CONTROL_ERROR_NONE Successful
 705  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 706  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 707  * @see app_control_get_app_id()
 708  */
 709 int app_control_set_app_id(app_control_h app_control, const char *app_id);
 710
 711
 712 /**
 713  * @brief Gets the ID of the application to explicitly launch.
 714  *
 715  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 716  * @remarks The @a app_id must be released with free().
 717  * @param[in] app_control The app_control handle
 718  * @param[out] app_id The ID of the application to explicitly launch
 719  * @return @c 0 on success,
 720  *         otherwise a negative error value
 721  * @retval #APP_CONTROL_ERROR_NONE Successful
 722  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 723  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 724  * @see app_control_set_app_id()
 725  */
 726 int app_control_get_app_id(app_control_h app_control, char **app_id);
 727
 728 /**
 729  * @brief Adds extra data to the app_control.
 730  *
 731  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 732  * @remarks The function replaces any existing value for the given key.
 733  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if @a key or @a value is a zero-length string.
 734  * @remarks The function returns #APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with system-defined key.
 735  * @param[in] app_control The app_control handle
 736  * @param[in] key The name of the extra data
 737  * @param[in] value The value associated with the given key
 738  * @return @c 0 on success,
 739  *         otherwise a negative error value
 740  * @retval #APP_CONTROL_ERROR_NONE Successful
 741  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 742  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 743  * @see app_control_add_extra_data_array()
 744  * @see app_control_remove_extra_data()
 745  * @see app_control_get_extra_data()
 746  */
 747 int app_control_add_extra_data(app_control_h app_control, const char *key, const char *value);
 748
 749
 750 /**
 751  * @brief Adds the extra data array to the app_control.
 752  *
 753  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 754  * @remarks The function replaces any existing value for the given key.
 755  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if @a key is a zero-length string.
 756  * @remarks The function returns #APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with system-defined key.
 757  * @param[in] app_control The app_control handle
 758  * @param[in] key The name of the extra data
 759  * @param[in] value The array value associated with the given key
 760  * @param[in] length The length of the array
 761  * @return @c 0 on success,
 762  *         otherwise a negative error value
 763  * @retval #APP_CONTROL_ERROR_NONE Successful
 764  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 765  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 766  * @see app_control_add_extra_data()
 767  * @see app_control_remove_extra_data()
 768  * @see app_control_get_extra_data()
 769  */
 770 int app_control_add_extra_data_array(app_control_h app_control, const char *key, const char* value[], int length);
 771
 772
 773 /**
 774  * @brief Removes the extra data from the app_control.
 775  *
 776  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 777  * @param[in] app_control The app_control handle
 778  * @param[in] key The name of the extra data
 779  * @return @c 0 on success,
 780  *         otherwise a negative error value
 781  * @retval #APP_CONTROL_ERROR_NONE Successful
 782  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 783  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 784  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 785  * @see app_control_add_extra_data()
 786  * @see app_control_add_extra_data_array()
 787  * @see app_control_get_extra_data()
 788  */
 789 int app_control_remove_extra_data(app_control_h app_control, const char *key);
 790
 791
 792 /**
 793  * @brief Gets the extra data from the app_control.
 794  *
 795  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 796  * @remarks The @a value must be released using free().
 797  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_DATA_TYPE if @a value is of array data type.
 798  * @param[in] app_control The app_control handle
 799  * @param[in] key The name of the extra data
 800  * @param[out] value The value associated with the given key
 801  * @return @c 0 on success,
 802  *         otherwise a negative error value
 803  * @retval #APP_CONTROL_ERROR_NONE Successful
 804  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 805  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 806  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 807  * @retval #APP_CONTROL_ERROR_INVALID_DATA_TYPE Invalid data type
 808  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 809  * @see app_control_add_extra_data()
 810  * @see app_control_add_extra_data_array()
 811  * @see app_control_get_extra_data()
 812  * @see app_control_remove_extra_data()
 813  * @see app_control_foreach_extra_data()
 814  */
 815 int app_control_get_extra_data(app_control_h app_control, const char *key, char **value);
 816
 817
 818 /**
 819  * @brief Gets the extra data array from the app_control.
 820  *
 821  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 822  * @remarks The @a value must be released using free().
 823  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_DATA_TYPE if @a value is not of array data type.
 824  * @param[in] app_control The app_control handle
 825  * @param[in] key The name of the extra data
 826  * @param[out] value The array value associated with the given key
 827  * @param[out] length The length of the array
 828  * @return @c 0 on success,
 829  *         otherwise a negative error value
 830  * @retval #APP_CONTROL_ERROR_NONE Successful
 831  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 832  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 833  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 834  * @retval #APP_CONTROL_ERROR_INVALID_DATA_TYPE Invalid data type
 835  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 836  * @see app_control_add_extra_data()
 837  * @see app_control_add_extra_data_array()
 838  * @see app_control_remove_extra_data()
 839  * @see app_control_foreach_extra_data()
 840  */
 841 int app_control_get_extra_data_array(app_control_h app_control, const char *key, char ***value, int *length);
 842
 843
 844 /**
 845  * @brief Checks whether the extra data associated with the given @a key is of array data type.
 846  *
 847  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 848  * @param[in] app_control The app_control handle
 849  * @param[in] key The name of the extra data
 850  * @param[out] array If @c true the extra data is of array data type,
 851  *                   otherwise @c false
 852  * @return @c 0 on success,
 853  *         otherwise a negative error value
 854  * @retval #APP_CONTROL_ERROR_NONE Successful
 855  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 856  * @see app_control_add_extra_data()
 857  * @see app_control_add_extra_data_array()
 858  * @see app_control_remove_extra_data()
 859  * @see app_control_foreach_extra_data()
 860  */
 861 int app_control_is_extra_data_array(app_control_h app_control, const char *key, bool *array);
 862
 863
 864 /**
 865  * @brief Retrieves all extra data contained in app_control.
 866  * @details This function calls app_control_extra_data_cb() once for each key-value pair for extra data contained in app_control. \n
 867  *          If the app_control_extra_data_cb() callback function returns @c false, then iteration will be finished.
 868  *
 869  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 870  * @param[in] app_control The app_control handle
 871  * @param[in] callback The iteration callback function
 872  * @param[in] user_data The user data to be passed to the callback function
 873  * @return @c 0 on success,
 874  *         otherwise a negative error value
 875  * @retval #APP_CONTROL_ERROR_NONE Successful
 876  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 877  * @post This function invokes app_control_extra_data_cb().
 878  * @see app_control_extra_data_cb()
 879  */
 880 int app_control_foreach_extra_data(app_control_h app_control, app_control_extra_data_cb callback, void *user_data);
 881
 882
 883 /**
 884  * @brief Retrieves all applications that can be launched to handle the given app_control request.
 885  *
 886  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 887  * @param[in] app_control The app_control handle
 888  * @param[in] callback The iteration callback function
 889  * @param[in] user_data The user data to be passed to the callback function
 890  * @return @c 0 on success,
 891  *         otherwise a negative error value
 892  * @retval #APP_CONTROL_ERROR_NONE Success
 893  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 894  * @post This function invokes app_control_app_matched_cb().
 895  * @see app_control_app_matched_cb()
 896  */
 897 int app_control_foreach_app_matched(app_control_h app_control, app_control_app_matched_cb callback, void *user_data);
 898
 899
 900 /**
 901  * @brief Sends the launch request.
 902  *
 903  * @details The operation is mandatory information for the launch request. \n
 904  *          If the operation is not specified, #APP_CONTROL_OPERATION_DEFAULT is used by default.
 905  *          If the operation is #APP_CONTROL_OPERATION_DEFAULT, the application ID is mandatory to explicitly launch the application.
 906  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 907  * @privlevel   public
 908  * @privilege   %http://tizen.org/privilege/appmanager.launch
 909  * @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 @a Event module.
 910  * @remarks 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 app_control_set_app_id() MUST be sent.
 911  * @param[in] app_control The app_control handle
 912  * @param[in] callback The callback function to be called when the reply is delivered
 913  * @param[in] user_data The user data to be passed to the callback function
 914  * @return @c 0 on success,
 915  *         otherwise a negative error value
 916  * @retval #APP_CONTROL_ERROR_NONE Successful
 917  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 918  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 919  * @retval #APP_CONTROL_ERROR_APP_NOT_FOUND The application to run the given launch request is not found
 920  * @retval #APP_CONTROL_ERROR_LAUNCH_REJECTED The application cannot be launched in current context
 921  * @retval #APP_CONTROL_ERROR_LAUNCH_FAILED Failed to launch the application
 922  * @retval #APP_CONTROL_ERROR_TIMED_OUT Failed due to timeout. The application that handles @a app_control may be busy
 923  * @retval #APP_CONTROL_ERROR_PERMISSION_DENIED Permission denied
 924  * @post If the launch request is sent for the result, the result will come back through app_control_reply_cb() from the callee application. Additional replies may be delivered on app_control_enable_app_started_result_event() called.
 925  * @see app_control_reply_to_launch_request()
 926  * @see app_control_reply_cb()
 927  * @see app_control_enable_app_started_result_event()
 928  */
 929 int app_control_send_launch_request(app_control_h app_control, app_control_reply_cb callback, void *user_data);
 930
 931
 932 /**
 933  * @brief 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.
 934  *
 935  * @remarks Since Tizen 2.4, this API can be used to terminate sub-applications which were launched as group mode by caller application.
 936  *          Once callee application is being terminated by this API, other applications which were launched by callee application as group mode will be terminated as well.
 937  *
 938  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 939  * @param[in] app_control The app_control handle
 940  * @return @c 0 on success,
 941  *         otherwise a negative error value
 942  * @retval #APP_CONTROL_ERROR_NONE Successful
 943  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 944  * @retval #APP_CONTROL_ERROR_PERMISSION_DENIED Permission denied
 945  * @see app_control_send_launch_request()
 946  * @see app_control_set_launch_mode()
 947  */
 948 int app_control_send_terminate_request(app_control_h app_control);
 949
 950
 951 /**
 952  * @brief Replies to the launch request sent by the caller.
 953  * @details If the caller application sent the launch request to receive the result, the callee application can return the result back to the caller.
 954  *
 955  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 956  * @remarks The function is not allowed to send reply #APP_CONTROL_RESULT_APP_STARTED as @a result which is reserved for platform developers.
 957  * @param[in] reply The app_control handle in which the results of the callee are contained
 958  * @param[in] request The app_control handle sent by the caller
 959  * @param[in] result  The result code of the launch request
 960  * @return @c 0 on success,
 961  *         otherwise a negative error value
 962  * @retval #APP_CONTROL_ERROR_NONE Successful
 963  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 964  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 965  * @see app_control_send_launch_request()
 966  */
 967 int app_control_reply_to_launch_request(app_control_h reply, app_control_h request, app_control_result_e result);
 968
 969
 970 /**
 971  * @brief Creates and returns a copy of the given app_control handle.
 972  *
 973  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 974  * @remarks A newly created app_control should be destroyed by calling app_control_destroy() if it is no longer needed.
 975  *
 976  * @param[out] clone If successful, a newly created app_control handle will be returned
 977  * @param[in] app_control The app_control handle
 978  * @return @c 0 on success,
 979  *         otherwise a negative error value
 980  * @retval #APP_CONTROL_ERROR_NONE Successful
 981  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 982  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 983  * @see app_control_destroy()
 984  */
 985 int app_control_clone(app_control_h *clone, app_control_h app_control);
 986
 987
 988 /**
 989  * @brief Gets the application ID of the caller from the launch request.
 990  *
 991  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 992  * @remarks The @a app_control must be the launch request from app_control_cb().
 993  * @remarks This function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request.
 994  * @remarks The @a id must be released using free().
 995  * @param[in] app_control The app_control handle from app_control_cb()
 996  * @param[out] id The application ID of the caller
 997  * @return @a 0 on success,
 998  *         otherwise a negative error value
 999  * @retval #APP_CONTROL_ERROR_NONE Successful
1000  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1001  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
1002  */
1003 int app_control_get_caller(app_control_h app_control, char **id);
1004
1005
1006 /**
1007  * @brief Checks whether the caller is requesting a reply from the launch request.
1008  *
1009  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1010  * @remarks The @a app_control must be the launch request from app_control_cb().
1011  * @remarks This function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request.
1012  * @param[in] app_control The app_control handle from app_control_cb()
1013  * @param[out] requested If @c true a reply is requested by the caller,
1014  *                       otherwise @c false
1015  * @return @c 0 on success,
1016  *         otherwise a negative error value
1017  * @retval #APP_CONTROL_ERROR_NONE Successful
1018  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1019  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
1020  */
1021 int app_control_is_reply_requested(app_control_h app_control, bool *requested);
1022
1023 /**
1024  * @brief Sets the launch mode of the application.
1025  *
1026  * @details This function allows callee application to be launched as group or single mode.
1027  * @remarks Although launch_mode were set as #APP_CONTROL_LAUNCH_MODE_GROUP, callee application would be launched as single mode if the manifest file of callee application defined the launch mode as "single".
1028  *          This function can just set the preference of caller application to launch an application.
1029  * @remarks Sub-applications which were launched as group mode always have own process.
1030  *
1031  * @since_tizen 2.4
1032  * @param[in] app_control The app_control handle
1033  * @param[in] launch_mode The launch mode of app
1034  *
1035  * @return 0 on success, otherwise a negative error value
1036  * @retval #APP_CONTROL_ERROR_NONE Successful
1037  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1038  * @see app_control_set_launch_mode()
1039  * @see app_control_launch_mode_e
1040  */
1041 int app_control_set_launch_mode(app_control_h app_control,
1042                 app_control_launch_mode_e mode);
1043
1044 /**
1045  * @brief Gets the launch mode of the application.
1046  *
1047  * @since_tizen 2.4
1048  * @param[in] app_control The app_control handle
1049  * @param[out] launch_mode The launch mode of app
1050  *
1051  * @return 0 on success, otherwise a negative error value
1052  * @retval #APP_CONTROL_ERROR_NONE Successful
1053  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1054  * @see app_control_get_launch_mode()
1055  * @see app_control_launch_mode_e
1056  */
1057 int app_control_get_launch_mode(app_control_h app_control,
1058                 app_control_launch_mode_e *mode);
1059
1060 /**
1061  * @brief Enables additional launch result event on launch request.
1062  *
1063  * @details The function allows to receive #APP_CONTROL_RESULT_APP_STARTED event on\n
1064  *         application get launched by app_control.
1065  * @remarks app_control_reply_cb() will be called on APP_CONTROL_RESULT_APP_STARTED event received.
1066  * @since_tizen 2.4
1067  * @param[in] app_control The app_control handle
1068  * @return 0 on success, otherwise a negative error value
1069  * @retval #APP_CONTROL_ERROR_NONE Successful
1070  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1071  * @see app_control_send_launch_request()
1072  * @see #APP_CONTROL_RESULT_APP_STARTED
1073  */
1074 int app_control_enable_app_started_result_event(app_control_h app_control);
1075 /**
1076  * @}
1077  */
1078
1079 #ifdef __cplusplus
1080 }
1081 #endif
1082
1083 #endif /* __TIZEN_APPFW_APP_CONTROL_H__ */