include/app_control.h

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