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 the app control operation: Select the type of input method to receive input from user.
 335  * @details Input: It depends on application scenario/configuration.\n
 336  *          Output: APP_CONTROL_DATA_TEXT in Extra.\n
 337  * @since_tizen @if WEARABLE 2.3.2 @elseif MOBILE 3.0 @endif
 338  */
 339 #define APP_CONTROL_OPERATION_GET_INPUT "http://tizen.org/appcontrol/operation/get_input"
 340
 341 /**
 342  * @brief Definition for app_control data: Subject
 343  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 344  */
 345 #define APP_CONTROL_DATA_SUBJECT "http://tizen.org/appcontrol/data/subject"
 346
 347
 348 /**
 349  * @brief Definition for app_control data: Recipients
 350  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 351  */
 352 #define APP_CONTROL_DATA_TO "http://tizen.org/appcontrol/data/to"
 353
 354
 355 /**
 356  * @brief Definition for app_control data: E-mail addresses that should be carbon copied
 357  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 358  */
 359 #define APP_CONTROL_DATA_CC "http://tizen.org/appcontrol/data/cc"
 360
 361
 362 /**
 363  * @brief Definition for app_control data: E-mail addresses that should be blind carbon copied
 364  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 365  */
 366 #define APP_CONTROL_DATA_BCC "http://tizen.org/appcontrol/data/bcc"
 367
 368
 369 /**
 370  * @brief Definition for app_control data: Text
 371  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 372  */
 373 #define APP_CONTROL_DATA_TEXT "http://tizen.org/appcontrol/data/text"
 374
 375
 376 /**
 377  * @brief Definition for app_control data: Title
 378  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 379  */
 380 #define APP_CONTROL_DATA_TITLE "http://tizen.org/appcontrol/data/title"
 381
 382
 383 /**
 384  * @brief Definition for app_control data: Selected items
 385  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 386  * @remarks Since Tizen 3.0, if all added paths with this key are under the caller application's data path which can be obtained by calling app_get_data_path() function, those will be shared to the callee application. Framework will grant a temporary permission to the callee application for those files and revoke it when the callee application is terminated. Paths should be regular files. The callee application can just read them. Note that the callee application doesn't have read permission of the directory that is obtained by caller's app_get_data_path(), you should open the file path with read only mode directly. For example, access() call to the file path will return error because access() needs the read permission of the directory. The callee application can call open() with O_RDONLY mode for the passed file path, because framework grants read permission to the passed file path.
 387  */
 388 #define APP_CONTROL_DATA_SELECTED "http://tizen.org/appcontrol/data/selected"
 389
 390
 391 /**
 392  * @brief Definition for app_control data: Paths of items
 393  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 394  * @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. Note that the callee application doesn't have read permission of the directory that is obtained by caller's app_get_data_path(), you should open the file path with read only mode directly. For example, access() call to the file path will return error because access() needs the read permission of the directory. The callee application can call open() with O_RDONLY mode for the passed file path, because framework grants read permission to the passed file path.
 395  */
 396 #define APP_CONTROL_DATA_PATH "http://tizen.org/appcontrol/data/path"
 397
 398
 399 /**
 400  * @brief Definition for app_control data: Selection mode. ("single" or "multiple")
 401  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 402  */
 403 #define APP_CONTROL_DATA_SELECTION_MODE "http://tizen.org/appcontrol/data/selection_mode"
 404
 405
 406 /**
 407  * @brief Definition for app_control data: All-day mode of event ("true" or "false")
 408  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 409  */
 410 #define APP_CONTROL_DATA_CALENDAR_ALL_DAY "http://tizen.org/appcontrol/data/calendar/all_day"
 411
 412
 413 /**
 414  * @brief Definition for app_control data: Start time of event (format: YYYY-MM-DD HH:MM:SS)
 415  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 416  */
 417 #define APP_CONTROL_DATA_CALENDAR_START_TIME "http://tizen.org/appcontrol/data/calendar/start_time"
 418
 419
 420 /**
 421  * @brief Definition for app_control data: End time of event (format: YYYY-MM-DD HH:MM:SS)
 422  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 423  */
 424 #define APP_CONTROL_DATA_CALENDAR_END_TIME "http://tizen.org/appcontrol/data/calendar/end_time"
 425
 426
 427 /**
 428  * @brief Definition for app_control data: E-mail addresses
 429  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 430  */
 431 #define APP_CONTROL_DATA_EMAIL "http://tizen.org/appcontrol/data/email"
 432
 433
 434 /**
 435  * @brief Definition for app_control data: Phone numbers
 436  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 437  */
 438 #define APP_CONTROL_DATA_PHONE "http://tizen.org/appcontrol/data/phone"
 439
 440
 441 /**
 442  * @brief Definition for app_control data: URLs
 443  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 444  */
 445 #define APP_CONTROL_DATA_URL "http://tizen.org/appcontrol/data/url"
 446
 447
 448 /**
 449  * @brief Definition for app_control data: IDs
 450  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 451  */
 452 #define APP_CONTROL_DATA_ID "http://tizen.org/appcontrol/data/id"
 453
 454
 455 /**
 456  * @brief Definition for app_control data: Type
 457  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.2 @endif
 458  */
 459 #define APP_CONTROL_DATA_TYPE "http://tizen.org/appcontrol/data/type"
 460
 461
 462 /**
 463  * @brief Definition for app_control data: Total count
 464  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 465  */
 466 #define APP_CONTROL_DATA_TOTAL_COUNT "http://tizen.org/appcontrol/data/total_count"
 467
 468
 469 /**
 470  * @brief Definition for app_control data: Total size (unit : bytes)
 471  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 472  */
 473 #define APP_CONTROL_DATA_TOTAL_SIZE "http://tizen.org/appcontrol/data/total_size"
 474
 475 /**
 476  * @brief Definition for app_control data: Name
 477  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 478  */
 479 #define APP_CONTROL_DATA_NAME "http://tizen.org/appcontrol/data/name"
 480
 481 /**
 482  * @brief Definition for app_control data: Location
 483  * @since_tizen 3.0
 484  */
 485 #define APP_CONTROL_DATA_LOCATION "http://tizen.org/appcontrol/data/location"
 486
 487 /**
 488  * @brief Definition for app_control data: Select the type of input method
 489  * @details Type: "input_voice"       Launch input method with voice type.
 490  *                "input_emoticon"    Launch input method with emoticon type.
 491  *                "input_keyboard"    Launch input method with keyboard type.
 492  * @since_tizen @if WEARABLE 2.3.2 @elseif MOBILE 3.0 @endif
 493  */
 494 #define APP_CONTROL_DATA_INPUT_TYPE "http://tizen.org/appcontrol/data/input_type"
 495
 496 /**
 497  * @brief Definition for app_control data: Send the pre inputted text such as "http://" in web
 498  * @since_tizen @if WEARABLE 2.3.2 @elseif MOBILE 3.0 @endif
 499  */
 500 #define APP_CONTROL_DATA_INPUT_DEFAULT_TEXT "http://tizen.org/appcontrol/data/input_default_text"
 501
 502 /**
 503  * @brief Definition for app_control data: Send guide text to show to user such as "Input user name"
 504  * @since_tizen @if WEARABLE 2.3.2 @elseif MOBILE 3.0 @endif
 505  */
 506 #define APP_CONTROL_DATA_INPUT_GUIDE_TEXT "http://tizen.org/appcontrol/data/input_guide_text"
 507
 508 /**
 509  * @brief Definition for app_control data: Send text to receive answer result from smart reply
 510  * @since_tizen @if WEARABLE 2.3.2 @elseif MOBILE 3.0 @endif
 511  */
 512 #define APP_CONTROL_DATA_INPUT_PREDICTION_HINT "http://tizen.org/appcontrol/data/input_prediction_hint"
 513
 514 /**
 515  * @brief Called when the reply of the launch request is delivered.
 516  *
 517  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 518  *
 519  * @remarks The @a request and @a reply must not be deallocated by the application.
 520  *
 521  * @param[in] request The app_control handle of the launch request that has been sent
 522  * @param[in] reply The app_control handle in which the results of the callee are contained
 523  * @param[in] result The result code of the launch request
 524  * @param[in] user_data The user data passed from the callback registration function
 525  * @pre When the callee replies to the launch request, this callback will be invoked.
 526  * @pre Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, if #APP_CONTROL_RESULT_APP_STARTED event is enabled,
 527  *      this callback also will be invoked when the callee app actually launched.
 528  * @see app_control_send_launch_request()
 529  * @see app_control_reply_to_launch_request()
 530  * @see app_control_enable_app_started_result_event()
 531  * @see #APP_CONTROL_RESULT_APP_STARTED
 532  */
 533 typedef void (*app_control_reply_cb) (app_control_h request, app_control_h reply, app_control_result_e result, void *user_data);
 534
 535
 536 /**
 537  * @brief Called to retrieve the extra data contained in the app_control.
 538  *
 539  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 540  *
 541  * @remarks The @a key must not be deallocated by the application.
 542  *
 543  * @param[in] app_control  The app_control handle
 544  * @param[in] key The key of the value contained in the app_control
 545  * @param[in] user_data The user data passed from the foreach function
 546  * @return @c true to continue with the next iteration of the loop,
 547  *         otherwise @c false to break out of the loop
 548  * @pre app_control_foreach_extra_data() will invoke this callback.
 549  * @see app_control_foreach_extra_data()
 550  */
 551 typedef bool (*app_control_extra_data_cb)(app_control_h app_control, const char *key, void *user_data);
 552
 553
 554 /**
 555  * @brief Called once for each matched application that can be launched to handle the given app_control request.
 556  *
 557  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 558  * @param[in] app_control  The app_control handle
 559  * @param[in] package The package name of the application that can handle the launch request of the given app_control
 560  * @param[in] user_data The user data passed from the foreach function
 561  * @return @c true to continue with the next iteration of the loop,
 562  *         otherwise @c false to break out of the loop
 563  * @pre app_control_foreach_app_matched() will invoke this callback.
 564  * @see app_control_foreach_app_matched()
 565  */
 566 typedef bool (*app_control_app_matched_cb)(app_control_h app_control, const char *appid, void *user_data);
 567
 568
 569 typedef int (*app_control_host_res_fn)(void *data);
 570
 571 /**
 572  * @brief Creates an app_control handle.
 573  *
 574  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 575  * @remarks The @a app_control must be released using app_control_destroy().
 576  * @param[out] app_control The app_control handle to be newly created on success
 577  * @return @c 0 on success,
 578  *         otherwise a negative error value
 579  * @retval #APP_CONTROL_ERROR_NONE Successful
 580  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 581  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 582  * @see app_control_destroy()
 583  */
 584 int app_control_create(app_control_h *app_control);
 585
 586
 587 /**
 588  * @brief Destroys the app_control handle and releases all its resources.
 589  *
 590  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 591  * @param[in] app_control The app_control handle
 592  * @return @c 0 on success,
 593  *         otherwise a negative error value
 594  * @retval #APP_CONTROL_ERROR_NONE Successful
 595  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 596  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 597  * @see app_control_create()
 598  */
 599 int app_control_destroy(app_control_h app_control);
 600
 601
 602 /**
 603  * @brief Sets the operation to be performed.
 604  *
 605  * @details The @a operation is the mandatory information for the launch request.
 606  *          If the operation is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 607  *          If the operation is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 608  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 609  * @param[in] app_control The app_control handle
 610  * @param[in] operation The operation to be performed (if the @a operation is @c NULL, it clears the previous value)
 611  * @return @c 0 on success,
 612  *         otherwise a negative error value
 613  * @retval #APP_CONTROL_ERROR_NONE Successful
 614  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 615  * @see app_control_get_operation()
 616  * @see APP_CONTROL_OPERATION_DEFAULT
 617  * @see APP_CONTROL_OPERATION_EDIT
 618  * @see APP_CONTROL_OPERATION_VIEW
 619  * @see APP_CONTROL_OPERATION_PICK
 620  * @see APP_CONTROL_OPERATION_CREATE_CONTENT
 621  * @see APP_CONTROL_OPERATION_CALL
 622  * @see APP_CONTROL_OPERATION_SEND
 623  * @see APP_CONTROL_OPERATION_SEND_TEXT
 624  * @see APP_CONTROL_OPERATION_DIAL
 625  * @see APP_CONTROL_OPERATION_SEARCH
 626  */
 627 int app_control_set_operation(app_control_h app_control, const char *operation);
 628
 629
 630 /**
 631  * @brief Gets the operation to be performed.
 632  *
 633  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 634  * @remarks The @a operation must be released using free().
 635  * @param[in] app_control The app_control handle
 636  * @param[out] operation The operation to be performed
 637  * @return @c 0 on success,
 638  *         otherwise a negative error value
 639  * @retval #APP_CONTROL_ERROR_NONE Successful
 640  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 641  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 642  * @see app_control_set_operation()
 643  */
 644 int app_control_get_operation(app_control_h app_control, char **operation);
 645
 646
 647 /**
 648  * @brief Sets the URI of the data.
 649  *
 650  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 651  * @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.
 652  * @param[in] app_control The app_control handle
 653  * @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)
 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  * @see app_control_get_uri()
 659  */
 660 int app_control_set_uri(app_control_h app_control, const char *uri);
 661
 662
 663 /**
 664  * @brief Gets the URI of the data.
 665  *
 666  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 667  * @remarks The @a uri must be released using free().
 668  * @param[in] app_control The app_control handle
 669  * @param[out] uri The URI of the data this app_control is operating on
 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  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 675  * @see app_control_set_uri()
 676  */
 677 int app_control_get_uri(app_control_h app_control, char **uri);
 678
 679
 680 /**
 681  * @brief Sets the explicit MIME type of the data.
 682  *
 683  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 684  * @param[in] app_control The app_control handle
 685  * @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)
 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  * @see app_control_get_mime()
 691  */
 692 int app_control_set_mime(app_control_h app_control, const char *mime);
 693
 694
 695 /**
 696  * @brief Gets the explicit MIME type of the data.
 697  *
 698  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 699  * @remarks The @a uri must be released using free().
 700  * @param[in] app_control The app_control handle
 701  * @param[out] mime The explicit MIME type of the data this app_control is operating on
 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_set_mime()
 708  */
 709 int app_control_get_mime(app_control_h app_control, char **mime);
 710
 711
 712 /**
 713  * @brief Sets the explicit category.
 714  *
 715  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 716  * @param[in] app_control The app_control handle
 717  * @param[in] category The explicit category (if the @a category is @c NULL, it clears the previous value)
 718  * @return @c 0 on success,
 719  *         otherwise a negative error value
 720  * @retval #APP_CONTROL_ERROR_NONE Successful
 721  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 722  * @see app_control_get_category()
 723  */
 724 int app_control_set_category(app_control_h app_control, const char *category);
 725
 726
 727 /**
 728  * @brief Gets the explicit category.
 729  *
 730  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 731  * @remarks The @a category must be released using free().
 732  * @param[in] app_control The app_control handle
 733  * @param[out] category The explicit category
 734  * @return @c 0 on success,
 735  *         otherwise a negative error value
 736  * @retval #APP_CONTROL_ERROR_NONE Successful
 737  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 738  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 739  * @see app_control_set_category()
 740  */
 741 int app_control_get_category(app_control_h app_control, char **category);
 742
 743
 744 /**
 745  * @brief Sets the ID of the application to explicitly launch.
 746  *
 747  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 748  * @param[in] app_control The app_control handle
 749  * @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)
 750  * @return @c 0 on success,
 751  *         otherwise a negative error value
 752  * @retval #APP_CONTROL_ERROR_NONE Successful
 753  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 754  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 755  * @see app_control_get_app_id()
 756  */
 757 int app_control_set_app_id(app_control_h app_control, const char *app_id);
 758
 759
 760 /**
 761  * @brief Gets the ID of the application to explicitly launch.
 762  *
 763  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 764  * @remarks The @a app_id must be released with free().
 765  * @param[in] app_control The app_control handle
 766  * @param[out] app_id The ID of the application to explicitly launch
 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_OUT_OF_MEMORY Out of memory
 772  * @see app_control_set_app_id()
 773  */
 774 int app_control_get_app_id(app_control_h app_control, char **app_id);
 775
 776 /**
 777  * @brief Adds extra data to the app_control.
 778  *
 779  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 780  * @remarks The function replaces any existing value for the given key.
 781  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if @a key or @a value is a zero-length string.
 782  * @remarks The function returns #APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with system-defined key.
 783  * @param[in] app_control The app_control handle
 784  * @param[in] key The name of the extra data
 785  * @param[in] value The value associated with the given key
 786  * @return @c 0 on success,
 787  *         otherwise a negative error value
 788  * @retval #APP_CONTROL_ERROR_NONE Successful
 789  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 790  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 791  * @see app_control_add_extra_data_array()
 792  * @see app_control_remove_extra_data()
 793  * @see app_control_get_extra_data()
 794  */
 795 int app_control_add_extra_data(app_control_h app_control, const char *key, const char *value);
 796
 797
 798 /**
 799  * @brief Adds the extra data array to the app_control.
 800  *
 801  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 802  * @remarks The function replaces any existing value for the given key.
 803  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if @a key is a zero-length string.
 804  * @remarks The function returns #APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with system-defined key.
 805  * @param[in] app_control The app_control handle
 806  * @param[in] key The name of the extra data
 807  * @param[in] value The array value associated with the given key
 808  * @param[in] length The length of the array
 809  * @return @c 0 on success,
 810  *         otherwise a negative error value
 811  * @retval #APP_CONTROL_ERROR_NONE Successful
 812  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 813  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 814  * @see app_control_add_extra_data()
 815  * @see app_control_remove_extra_data()
 816  * @see app_control_get_extra_data()
 817  */
 818 int app_control_add_extra_data_array(app_control_h app_control, const char *key, const char* value[], int length);
 819
 820
 821 /**
 822  * @brief Removes the extra data from the app_control.
 823  *
 824  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 825  * @param[in] app_control The app_control handle
 826  * @param[in] key The name of the extra data
 827  * @return @c 0 on success,
 828  *         otherwise a negative error value
 829  * @retval #APP_CONTROL_ERROR_NONE Successful
 830  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 831  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 832  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 833  * @see app_control_add_extra_data()
 834  * @see app_control_add_extra_data_array()
 835  * @see app_control_get_extra_data()
 836  */
 837 int app_control_remove_extra_data(app_control_h app_control, const char *key);
 838
 839
 840 /**
 841  * @brief Gets the extra data from the app_control.
 842  *
 843  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 844  * @remarks The @a value must be released using free().
 845  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_DATA_TYPE if @a value is of array data type.
 846  * @param[in] app_control The app_control handle
 847  * @param[in] key The name of the extra data
 848  * @param[out] value The value associated with the given key
 849  * @return @c 0 on success,
 850  *         otherwise a negative error value
 851  * @retval #APP_CONTROL_ERROR_NONE Successful
 852  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 853  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 854  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 855  * @retval #APP_CONTROL_ERROR_INVALID_DATA_TYPE Invalid data type
 856  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 857  * @see app_control_add_extra_data()
 858  * @see app_control_add_extra_data_array()
 859  * @see app_control_get_extra_data()
 860  * @see app_control_remove_extra_data()
 861  * @see app_control_foreach_extra_data()
 862  */
 863 int app_control_get_extra_data(app_control_h app_control, const char *key, char **value);
 864
 865
 866 /**
 867  * @brief Gets the extra data array from the app_control.
 868  *
 869  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 870  * @remarks The @a value must be released using free().
 871  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_DATA_TYPE if @a value is not of array data type.
 872  * @param[in] app_control The app_control handle
 873  * @param[in] key The name of the extra data
 874  * @param[out] value The array value associated with the given key
 875  * @param[out] length The length of the array
 876  * @return @c 0 on success,
 877  *         otherwise a negative error value
 878  * @retval #APP_CONTROL_ERROR_NONE Successful
 879  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 880  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 881  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 882  * @retval #APP_CONTROL_ERROR_INVALID_DATA_TYPE Invalid data type
 883  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 884  * @see app_control_add_extra_data()
 885  * @see app_control_add_extra_data_array()
 886  * @see app_control_remove_extra_data()
 887  * @see app_control_foreach_extra_data()
 888  */
 889 int app_control_get_extra_data_array(app_control_h app_control, const char *key, char ***value, int *length);
 890
 891
 892 /**
 893  * @brief Checks whether the extra data associated with the given @a key is of array data type.
 894  *
 895  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 896  * @param[in] app_control The app_control handle
 897  * @param[in] key The name of the extra data
 898  * @param[out] array If @c true the extra data is of array data type,
 899  *                   otherwise @c false
 900  * @return @c 0 on success,
 901  *         otherwise a negative error value
 902  * @retval #APP_CONTROL_ERROR_NONE Successful
 903  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 904  * @see app_control_add_extra_data()
 905  * @see app_control_add_extra_data_array()
 906  * @see app_control_remove_extra_data()
 907  * @see app_control_foreach_extra_data()
 908  */
 909 int app_control_is_extra_data_array(app_control_h app_control, const char *key, bool *array);
 910
 911
 912 /**
 913  * @brief Retrieves all extra data contained in app_control.
 914  * @details This function calls app_control_extra_data_cb() once for each key-value pair for extra data contained in app_control. \n
 915  *          If the app_control_extra_data_cb() callback function returns @c false, then iteration will be finished.
 916  *
 917  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 918  * @param[in] app_control The app_control handle
 919  * @param[in] callback The iteration callback function
 920  * @param[in] user_data The user data to be passed to the callback function
 921  * @return @c 0 on success,
 922  *         otherwise a negative error value
 923  * @retval #APP_CONTROL_ERROR_NONE Successful
 924  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 925  * @post This function invokes app_control_extra_data_cb().
 926  * @see app_control_extra_data_cb()
 927  */
 928 int app_control_foreach_extra_data(app_control_h app_control, app_control_extra_data_cb callback, void *user_data);
 929
 930
 931 /**
 932  * @brief Retrieves all applications that can be launched to handle the given app_control request.
 933  *
 934  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 935  * @param[in] app_control The app_control handle
 936  * @param[in] callback The iteration callback function
 937  * @param[in] user_data The user data to be passed to the callback function
 938  * @return @c 0 on success,
 939  *         otherwise a negative error value
 940  * @retval #APP_CONTROL_ERROR_NONE Success
 941  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 942  * @post This function invokes app_control_app_matched_cb().
 943  * @see app_control_app_matched_cb()
 944  */
 945 int app_control_foreach_app_matched(app_control_h app_control, app_control_app_matched_cb callback, void *user_data);
 946
 947
 948 /**
 949  * @brief Sends the launch request.
 950  *
 951  * @details The operation is mandatory information for the launch request. \n
 952  *          If the operation is not specified, #APP_CONTROL_OPERATION_DEFAULT is used by default.
 953  *          If the operation is #APP_CONTROL_OPERATION_DEFAULT, the application ID is mandatory to explicitly launch the application.
 954  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 955  * @privlevel   public
 956  * @privilege   %http://tizen.org/privilege/appmanager.launch
 957  * @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.
 958  * @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.
 959  * @param[in] app_control The app_control handle
 960  * @param[in] callback The callback function to be called when the reply is delivered
 961  * @param[in] user_data The user data to be passed to the callback function
 962  * @return @c 0 on success,
 963  *         otherwise a negative error value
 964  * @retval #APP_CONTROL_ERROR_NONE Successful
 965  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 966  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 967  * @retval #APP_CONTROL_ERROR_APP_NOT_FOUND The application to run the given launch request is not found
 968  * @retval #APP_CONTROL_ERROR_LAUNCH_REJECTED The application cannot be launched in current context
 969  * @retval #APP_CONTROL_ERROR_LAUNCH_FAILED Failed to launch the application
 970  * @retval #APP_CONTROL_ERROR_TIMED_OUT Failed due to timeout. The application that handles @a app_control may be busy
 971  * @retval #APP_CONTROL_ERROR_PERMISSION_DENIED Permission denied
 972  * @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.
 973  * @see app_control_reply_to_launch_request()
 974  * @see app_control_reply_cb()
 975  * @see app_control_enable_app_started_result_event()
 976  */
 977 int app_control_send_launch_request(app_control_h app_control, app_control_reply_cb callback, void *user_data);
 978
 979
 980 /**
 981  * @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.
 982  *
 983  * @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.
 984  *          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.
 985  *
 986  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 987  * @param[in] app_control The app_control handle
 988  * @return @c 0 on success,
 989  *         otherwise a negative error value
 990  * @retval #APP_CONTROL_ERROR_NONE Successful
 991  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 992  * @retval #APP_CONTROL_ERROR_PERMISSION_DENIED Permission denied
 993  * @see app_control_send_launch_request()
 994  * @see app_control_set_launch_mode()
 995  */
 996 int app_control_send_terminate_request(app_control_h app_control);
 997
 998
 999 /**
1000  * @brief Replies to the launch request sent by the caller.
1001  * @details If the caller application sent the launch request to receive the result, the callee application can return the result back to the caller.
1002  *
1003  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1004  * @remarks The function is not allowed to send reply #APP_CONTROL_RESULT_APP_STARTED as @a result which is reserved for platform developers.
1005  * @param[in] reply The app_control handle in which the results of the callee are contained
1006  * @param[in] request The app_control handle sent by the caller
1007  * @param[in] result  The result code of the launch request
1008  * @return @c 0 on success,
1009  *         otherwise a negative error value
1010  * @retval #APP_CONTROL_ERROR_NONE Successful
1011  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1012  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
1013  * @see app_control_send_launch_request()
1014  */
1015 int app_control_reply_to_launch_request(app_control_h reply, app_control_h request, app_control_result_e result);
1016
1017
1018 /**
1019  * @brief Creates and returns a copy of the given app_control handle.
1020  *
1021  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1022  * @remarks A newly created app_control should be destroyed by calling app_control_destroy() if it is no longer needed.
1023  *
1024  * @param[out] clone If successful, a newly created app_control handle will be returned
1025  * @param[in] app_control The app_control handle
1026  * @return @c 0 on success,
1027  *         otherwise a negative error value
1028  * @retval #APP_CONTROL_ERROR_NONE Successful
1029  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1030  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
1031  * @see app_control_destroy()
1032  */
1033 int app_control_clone(app_control_h *clone, app_control_h app_control);
1034
1035
1036 /**
1037  * @brief Gets the application ID of the caller from the launch request.
1038  *
1039  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1040  * @remarks The @a app_control must be the launch request from app_control_cb().
1041  * @remarks This function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request.
1042  * @remarks The @a id must be released using free().
1043  * @param[in] app_control The app_control handle from app_control_cb()
1044  * @param[out] id The application ID of the caller
1045  * @return @a 0 on success,
1046  *         otherwise a negative error value
1047  * @retval #APP_CONTROL_ERROR_NONE Successful
1048  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1049  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
1050  */
1051 int app_control_get_caller(app_control_h app_control, char **id);
1052
1053
1054 /**
1055  * @brief Checks whether the caller is requesting a reply from the launch request.
1056  *
1057  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1058  * @remarks The @a app_control must be the launch request from app_control_cb().
1059  * @remarks This function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request.
1060  * @param[in] app_control The app_control handle from app_control_cb()
1061  * @param[out] requested If @c true a reply is requested by the caller,
1062  *                       otherwise @c false
1063  * @return @c 0 on success,
1064  *         otherwise a negative error value
1065  * @retval #APP_CONTROL_ERROR_NONE Successful
1066  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1067  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
1068  */
1069 int app_control_is_reply_requested(app_control_h app_control, bool *requested);
1070
1071 /**
1072  * @brief Sets the launch mode of the application.
1073  *
1074  * @details This function allows callee application to be launched as group or single mode.
1075  * @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".
1076  *          This function can just set the preference of caller application to launch an application.
1077  * @remarks Sub-applications which were launched as group mode always have own process.
1078  *
1079  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
1080  * @param[in] app_control The app_control handle
1081  * @param[in] mode The launch mode of app
1082  *
1083  * @return 0 on success, otherwise a negative error value
1084  * @retval #APP_CONTROL_ERROR_NONE Successful
1085  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1086  * @see app_control_set_launch_mode()
1087  * @see app_control_launch_mode_e
1088  */
1089 int app_control_set_launch_mode(app_control_h app_control,
1090                 app_control_launch_mode_e mode);
1091
1092 /**
1093  * @brief Gets the launch mode of the application.
1094  *
1095  * @remarks Since Tizen 3.0, if launch mode not set in the caller app control,
1096  *      the function returns #APP_CONTROL_LAUNCH_MODE_SINGLE launch mode.
1097  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
1098  * @param[in] app_control The app_control handle
1099  * @param[out] mode The launch mode of app
1100  *
1101  * @return 0 on success, otherwise a negative error value
1102  * @retval #APP_CONTROL_ERROR_NONE Successful
1103  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1104  * @see app_control_get_launch_mode()
1105  * @see app_control_launch_mode_e
1106  */
1107 int app_control_get_launch_mode(app_control_h app_control,
1108                 app_control_launch_mode_e *mode);
1109
1110 /**
1111  * @brief Enables additional launch result event on launch request.
1112  *
1113  * @details The function allows to receive #APP_CONTROL_RESULT_APP_STARTED event on\n
1114  *         application get launched by app_control.
1115  * @remarks app_control_reply_cb() will be called on APP_CONTROL_RESULT_APP_STARTED event received.
1116  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
1117  * @param[in] app_control The app_control handle
1118  * @return 0 on success, otherwise a negative error value
1119  * @retval #APP_CONTROL_ERROR_NONE Successful
1120  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
1121  * @see app_control_send_launch_request()
1122  * @see #APP_CONTROL_RESULT_APP_STARTED
1123  */
1124 int app_control_enable_app_started_result_event(app_control_h app_control);
1125
1126 /**
1127  * @}
1128  */
1129
1130 #ifdef __cplusplus
1131 }
1132 #endif
1133
1134 #endif /* __TIZEN_APPFW_APP_CONTROL_H__ */
1135