include/app_control.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_APPFW_APP_CONTROL_H__
  19 #define __TIZEN_APPFW_APP_CONTROL_H__
  20
  21 #include <tizen.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file app_control.h
  29  */
  30
  31 /**
  32  * @addtogroup CAPI_APP_CONTROL_MODULE
  33  * @{
  34  */
  35
  36
  37 typedef struct _bundle_t bundle;
  38
  39
  40 /**
  41  * @brief App Control handle.
  42  * @since_tizen 2.3
  43  */
  44 typedef struct app_control_s* app_control_h;
  45
  46
  47 /**
  48  * @brief Enumeration for App Control Error.
  49  * @since_tizen 2.3
  50  */
  51 typedef enum
  52 {
  53         APP_CONTROL_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  54         APP_CONTROL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  55         APP_CONTROL_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  56         APP_CONTROL_ERROR_APP_NOT_FOUND = TIZEN_ERROR_APPLICATION_CLASS | 0x21, /**< The application is not found */
  57         APP_CONTROL_ERROR_KEY_NOT_FOUND = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Specified key is not found */
  58         APP_CONTROL_ERROR_KEY_REJECTED = TIZEN_ERROR_KEY_REJECTED, /**< Key is not available */
  59         APP_CONTROL_ERROR_INVALID_DATA_TYPE = TIZEN_ERROR_APPLICATION_CLASS | 0x22, /**< Invalid data type */
  60         APP_CONTROL_ERROR_LAUNCH_REJECTED = TIZEN_ERROR_APPLICATION_CLASS | 0x23, /**< The application cannot be launched now*/
  61         APP_CONTROL_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,    /**< Permission denied */
  62         APP_CONTROL_ERROR_LAUNCH_FAILED = TIZEN_ERROR_APPLICATION_CLASS | 0x24, /**< Internal launch error */
  63         APP_CONTROL_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT /**< Time out */
  64 } app_control_error_e;
  65
  66
  67 /**
  68  * @brief Enumeration for App Control Result.
  69  * @since_tizen 2.3
  70  */
  71 typedef enum
  72 {
  73         APP_CONTROL_RESULT_SUCCEEDED = 0, /**< Operation succeeded */
  74         APP_CONTROL_RESULT_FAILED = -1, /**< Operation failed by the callee */
  75         APP_CONTROL_RESULT_CANCELED = -2, /**< Operation canceled by the framework */
  76 } app_control_result_e;
  77
  78
  79 /**
  80  * @brief Definition for the app_control operation: main operation for an explicit launch.
  81  * @since_tizen 2.3
  82  */
  83 #define APP_CONTROL_OPERATION_MAIN "http://tizen.org/appcontrol/operation/main"
  84
  85
  86 /**
  87  * @brief Definition for the app_control operation: default operation for an explicit launch.
  88  * @since_tizen 2.3
  89  */
  90 #define APP_CONTROL_OPERATION_DEFAULT "http://tizen.org/appcontrol/operation/default"
  91
  92
  93 /**
  94  * @brief Definition for the app_control operation: provides an explicit editable access to the given data.
  95  * @since_tizen 2.3
  96  */
  97 #define APP_CONTROL_OPERATION_EDIT "http://tizen.org/appcontrol/operation/edit"
  98
  99
 100 /**
 101  * @brief Definition for the app_control operation: displays the data.
 102  * @since_tizen 2.3
 103  */
 104 #define APP_CONTROL_OPERATION_VIEW "http://tizen.org/appcontrol/operation/view"
 105
 106
 107 /**
 108  * @brief Definition for the app_control operation: picks an item from the data, returning what is selected.
 109  * @since_tizen 2.3
 110  */
 111 #define APP_CONTROL_OPERATION_PICK "http://tizen.org/appcontrol/operation/pick"
 112
 113
 114 /**
 115  * @brief Definition for the app_control operation: creates content, returning what is created.
 116  * @since_tizen 2.3
 117  */
 118 #define APP_CONTROL_OPERATION_CREATE_CONTENT "http://tizen.org/appcontrol/operation/create_content"
 119
 120
 121 /**
 122  * @brief Definition for the app_control operation: performs a call to someone specified by the data.
 123  * @since_tizen 2.3
 124  * @privlevel public
 125  * @privilege %http://tizen.org/privilege/call
 126  * @remarks When you request this operation, you must declare this privilege.
 127  */
 128 #define APP_CONTROL_OPERATION_CALL "http://tizen.org/appcontrol/operation/call"
 129
 130
 131 /**
 132  * @brief Definition for the app_control operation: delivers some data to someone else.
 133  * @since_tizen 2.3
 134  */
 135 #define APP_CONTROL_OPERATION_SEND "http://tizen.org/appcontrol/operation/send"
 136
 137
 138 /**
 139  * @brief Definition for the app_control operation: delivers text data to someone else.
 140  * @since_tizen 2.3
 141  */
 142 #define APP_CONTROL_OPERATION_SEND_TEXT "http://tizen.org/appcontrol/operation/send_text"
 143
 144
 145 /**
 146  * @brief Definition for the app_control operation: shares an item with someone else.
 147  * @since_tizen 2.3
 148  */
 149 #define APP_CONTROL_OPERATION_SHARE "http://tizen.org/appcontrol/operation/share"
 150
 151
 152 /**
 153  * @brief Definition for the app_control operation: shares multiple items with someone else.
 154  * @since_tizen 2.3
 155  */
 156 #define APP_CONTROL_OPERATION_MULTI_SHARE "http://tizen.org/appcontrol/operation/multi_share"
 157
 158
 159 /**
 160  * @brief Definition for the app_control operation: shares text data with someone else.
 161  * @since_tizen 2.3
 162  */
 163 #define APP_CONTROL_OPERATION_SHARE_TEXT "http://tizen.org/appcontrol/operation/share_text"
 164
 165
 166 /**
 167  * @brief Definition for the app_control operation: dials a number as specified by the data.
 168  * @since_tizen 2.3
 169  */
 170 #define APP_CONTROL_OPERATION_DIAL "http://tizen.org/appcontrol/operation/dial"
 171
 172
 173 /**
 174  * @brief Definition for the app_control operation: performs a search.
 175  * @since_tizen 2.3
 176  */
 177 #define APP_CONTROL_OPERATION_SEARCH "http://tizen.org/appcontrol/operation/search"
 178
 179
 180 /**
 181  * @brief Definition for the app_control operation: downloads an item.
 182  * @since_tizen 2.3
 183  */
 184 #define APP_CONTROL_OPERATION_DOWNLOAD "http://tizen.org/appcontrol/operation/download"
 185
 186
 187 /**
 188  * @brief Definition for the app_control operation: prints content.
 189  * @since_tizen 2.3
 190  */
 191 #define APP_CONTROL_OPERATION_PRINT "http://tizen.org/appcontrol/operation/print"
 192
 193 /**
 194  * @brief Definition for the app_control operation: composes.
 195  * @since_tizen 2.3
 196  */
 197 #define APP_CONTROL_OPERATION_COMPOSE "http://tizen.org/appcontrol/operation/compose"
 198
 199 /**
 200  * @brief Definition for the app_control operation: can be launched by interested event.
 201  * @since_tizen 2.4
 202  * @remarks This operation is for handling event from the platform or other application. This operation can not be requested via app_control_send_launch_request().
 203  * @remarks Refer to "Launch on Event" section of Event module.
 204  */
 205 #define APP_CONTROL_OPERATION_LAUNCH_ON_EVENT "http://tizen.org/appcontrol/operation/launch_on_event"
 206
 207 /**
 208  * @brief Definition for app_control optional data: the subject of a message.
 209  * @since_tizen 2.3
 210  */
 211 #define APP_CONTROL_DATA_SUBJECT "http://tizen.org/appcontrol/data/subject"
 212
 213
 214 /**
 215  * @brief Definition for app_control optional data: e-mail addresses.
 216  * @since_tizen 2.3
 217  */
 218 #define APP_CONTROL_DATA_TO "http://tizen.org/appcontrol/data/to"
 219
 220
 221 /**
 222  * @brief Definition for app_control optional data: e-mail addresses that should be carbon copied.
 223  * @since_tizen 2.3
 224  */
 225 #define APP_CONTROL_DATA_CC "http://tizen.org/appcontrol/data/cc"
 226
 227
 228 /**
 229  * @brief Definition for app_control optional data: e-mail addresses that should be blind carbon copied.
 230  * @since_tizen 2.3
 231  */
 232 #define APP_CONTROL_DATA_BCC "http://tizen.org/appcontrol/data/bcc"
 233
 234
 235 /**
 236  * @brief Definition for app_control optional data: the content of the data is associated with #APP_CONTROL_OPERATION_SEND.
 237  * @since_tizen 2.3
 238  */
 239 #define APP_CONTROL_DATA_TEXT "http://tizen.org/appcontrol/data/text"
 240
 241
 242 /**
 243  * @brief Definition for app_control optional data: the title of the data.
 244  * @since_tizen 2.3
 245  */
 246 #define APP_CONTROL_DATA_TITLE "http://tizen.org/appcontrol/data/title"
 247
 248
 249 /**
 250  * @brief Definition for app_control optional data: the path of a selected item.
 251  * @since_tizen 2.3
 252  */
 253 #define APP_CONTROL_DATA_SELECTED "http://tizen.org/appcontrol/data/selected"
 254
 255
 256 /**
 257  * @brief Definition for app_control optional data: multiple item path to deliver.
 258  * @since_tizen 2.3
 259  */
 260 #define APP_CONTROL_DATA_PATH "http://tizen.org/appcontrol/data/path"
 261
 262
 263 /**
 264  * @brief Definition for app_control optional data: the selection type.
 265  * @since_tizen 2.3
 266  */
 267 #define APP_CONTROL_DATA_SELECTION_MODE "http://tizen.org/appcontrol/data/selection_mode"
 268
 269
 270 /**
 271  * @brief Called when the reply of the launch request is delivered.
 272  *
 273  * @since_tizen 2.3
 274  *
 275  * @remarks The @a request and @a reply must not be deallocated by the application.
 276  *
 277  * @param[in] request The app_control handle of the launch request that has been sent
 278  * @param[in] reply The app_control handle in which the results of the callee are contained
 279  * @param[in] result The result code of the launch request
 280  * @param[in] user_data The user data passed from the callback registration function
 281  * @pre When the callee replies to the launch request, this callback will be invoked.
 282  * @see app_control_send_launch_request()
 283  * @see app_control_reply_to_launch_request()
 284  */
 285 typedef void (*app_control_reply_cb) (app_control_h request, app_control_h reply, app_control_result_e result, void *user_data);
 286
 287
 288 /**
 289  * @brief Called to retrieve the extra data contained in the app_control.
 290  *
 291  * @since_tizen 2.3
 292  *
 293  * @remarks The @a key must not be deallocated by the application.
 294  *
 295  * @param[in] app_control  The app_control handle
 296  * @param[in] key The key of the value contained in the app_control
 297  * @param[in] user_data The user data passed from the foreach function
 298  * @return @c true to continue with the next iteration of the loop,
 299  *         otherwise @c false to break out of the loop
 300  * @pre app_control_foreach_extra_data() will invoke this callback.
 301  * @see app_control_foreach_extra_data()
 302  */
 303 typedef bool (*app_control_extra_data_cb)(app_control_h app_control, const char *key, void *user_data);
 304
 305
 306 /**
 307  * @brief Called once for each matched application that can be launched to handle the given app_control request.
 308  *
 309  * @since_tizen 2.3
 310  * @param[in] app_control  The app_control handle
 311  * @param[in] package The package name of the application that can handle the launch request of the given app_control
 312  * @param[in] user_data The user data passed from the foreach function
 313  * @return @c true to continue with the next iteration of the loop,
 314  *         otherwise @c false to break out of the loop
 315  * @pre app_control_foreach_app_matched() will invoke this callback.
 316  * @see app_control_foreach_app_matched()
 317  */
 318 typedef bool (*app_control_app_matched_cb)(app_control_h app_control, const char *appid, void *user_data);
 319
 320
 321 typedef int (*app_control_host_res_fn)(void *data);
 322
 323 /**
 324  * @brief Creates an app_control handle.
 325  *
 326  * @since_tizen 2.3
 327  * @remarks The @a app_control must be released using app_control_destroy().
 328  * @param[out] app_control The app_control handle to be newly created on success
 329  * @return @c 0 on success,
 330  *         otherwise a negative error value
 331  * @retval #APP_CONTROL_ERROR_NONE Successful
 332  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 333  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 334  * @see app_control_destroy()
 335  */
 336 int app_control_create(app_control_h *app_control);
 337
 338
 339 /**
 340  * @brief Destroys the app_control handle and releases all its resources.
 341  *
 342  * @since_tizen 2.3
 343  * @param[in] app_control The app_control handle
 344  * @return @c 0 on success,
 345  *         otherwise a negative error value
 346  * @retval #APP_CONTROL_ERROR_NONE Successful
 347  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 348  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 349  * @see app_control_create()
 350  */
 351 int app_control_destroy(app_control_h app_control);
 352
 353
 354 /**
 355  * @internal
 356  * @brief Converts the app_control handle to bundle data.
 357  *
 358  * @since_tizen 2.3
 359  * @param[in] app_control The app_control handle
 360  * @param[out] data The bundle data on success
 361  * @return @c 0 on success,
 362  *         otherwise a negative error value
 363  * @retval #APP_CONTROL_ERROR_NONE Successful
 364  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 365  */
 366 int app_control_to_bundle(app_control_h app_control, bundle **data);
 367
 368 /**
 369  * @brief Sets the operation to be performed.
 370  *
 371  * @details The @a operation is the mandatory information for the launch request.
 372  *          If the operation is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 373  *          If the operation is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 374  * @since_tizen 2.3
 375  * @param[in] app_control The app_control handle
 376  * @param[in] operation The operation to be performed (if the @a operation is @c NULL, it clears the previous value)
 377  * @return @c 0 on success,
 378  *         otherwise a negative error value
 379  * @retval #APP_CONTROL_ERROR_NONE Successful
 380  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 381  * @see app_control_get_operation()
 382  * @see APP_CONTROL_OPERATION_DEFAULT
 383  * @see APP_CONTROL_OPERATION_EDIT
 384  * @see APP_CONTROL_OPERATION_VIEW
 385  * @see APP_CONTROL_OPERATION_PICK
 386  * @see APP_CONTROL_OPERATION_CREATE_CONTENT
 387  * @see APP_CONTROL_OPERATION_CALL
 388  * @see APP_CONTROL_OPERATION_SEND
 389  * @see APP_CONTROL_OPERATION_SEND_TEXT
 390  * @see APP_CONTROL_OPERATION_DIAL
 391  * @see APP_CONTROL_OPERATION_SEARCH
 392  */
 393 int app_control_set_operation(app_control_h app_control, const char *operation);
 394
 395
 396 /**
 397  * @brief Gets the operation to be performed.
 398  *
 399  * @since_tizen 2.3
 400  * @remarks The @a operation must be released using free().
 401  * @param[in] app_control The app_control handle
 402  * @param[out] operation The operation to be performed
 403  * @return @c 0 on success,
 404  *         otherwise a negative error value
 405  * @retval #APP_CONTROL_ERROR_NONE Successful
 406  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 407  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 408  * @see app_control_set_operation()
 409  */
 410 int app_control_get_operation(app_control_h app_control, char **operation);
 411
 412
 413 /**
 414  * @brief Sets the URI of the data.
 415  *
 416  * @since_tizen 2.3
 417  * @param[in] app_control The app_control handle
 418  * @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)
 419  * @return @c 0 on success,
 420  *         otherwise a negative error value
 421  * @retval #APP_CONTROL_ERROR_NONE Successful
 422  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 423  * @see app_control_get_uri()
 424  */
 425 int app_control_set_uri(app_control_h app_control, const char *uri);
 426
 427
 428 /**
 429  * @brief Gets the URI of the data.
 430  *
 431  * @since_tizen 2.3
 432  * @remarks The @a uri must be released using free().
 433  * @param[in] app_control The app_control handle
 434  * @param[out] uri The URI of the data this app_control is operating on
 435  * @return @c 0 on success,
 436  *         otherwise a negative error value
 437  * @retval #APP_CONTROL_ERROR_NONE Successful
 438  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 439  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 440  * @see app_control_set_uri()
 441  */
 442 int app_control_get_uri(app_control_h app_control, char **uri);
 443
 444
 445 /**
 446  * @brief Sets the explicit MIME type of the data.
 447  *
 448  * @since_tizen 2.3
 449  * @param[in] app_control The app_control handle
 450  * @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)
 451  * @return @c 0 on success,
 452  *         otherwise a negative error value
 453  * @retval #APP_CONTROL_ERROR_NONE Successful
 454  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 455  * @see app_control_get_mime()
 456  */
 457 int app_control_set_mime(app_control_h app_control, const char *mime);
 458
 459
 460 /**
 461  * @brief Gets the explicit MIME type of the data.
 462  *
 463  * @since_tizen 2.3
 464  * @remarks The @a uri must be released using free().
 465  * @param[in] app_control The app_control handle
 466  * @param[out] mime The explicit MIME type of the data this app_control is operating on
 467  * @return @c 0 on success,
 468  *         otherwise a negative error value
 469  * @retval #APP_CONTROL_ERROR_NONE Successful
 470  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 471  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 472  * @see app_control_set_mime()
 473  */
 474 int app_control_get_mime(app_control_h app_control, char **mime);
 475
 476
 477 /**
 478  * @brief Sets the explicit category.
 479  *
 480  * @since_tizen 2.3
 481  * @param[in] app_control The app_control handle
 482  * @param[in] category The explicit category (if the @a category is @c NULL, it clears the previous value)
 483  * @return @c 0 on success,
 484  *         otherwise a negative error value
 485  * @retval #APP_CONTROL_ERROR_NONE Successful
 486  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 487  * @see app_control_get_category()
 488  */
 489 int app_control_set_category(app_control_h app_control, const char *category);
 490
 491
 492 /**
 493  * @brief Gets the explicit category.
 494  *
 495  * @since_tizen 2.3
 496  * @remarks The @a category must be released using free().
 497  * @param[in] app_control The app_control handle
 498  * @param[out] category The explicit category
 499  * @return @c 0 on success,
 500  *         otherwise a negative error value
 501  * @retval #APP_CONTROL_ERROR_NONE Successful
 502  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 503  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 504  * @see app_control_set_category()
 505  */
 506 int app_control_get_category(app_control_h app_control, char **category);
 507
 508
 509 /**
 510  * @brief Sets the ID of the application to explicitly launch.
 511  *
 512  * @since_tizen 2.3
 513  * @param[in] app_control The app_control handle
 514  * @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)
 515  * @return @c 0 on success,
 516  *         otherwise a negative error value
 517  * @retval #APP_CONTROL_ERROR_NONE Successful
 518  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 519  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 520  * @see app_control_get_app_id()
 521  */
 522 int app_control_set_app_id(app_control_h app_control, const char *app_id);
 523
 524
 525 /**
 526  * @brief Gets the ID of the application to explicitly launch.
 527  *
 528  * @since_tizen 2.3
 529  * @remarks The @a app_id must be released with free().
 530  * @param[in] app_control The app_control handle
 531  * @param[out] app_id The ID of the application to explicitly launch
 532  * @return @c 0 on success,
 533  *         otherwise a negative error value
 534  * @retval #APP_CONTROL_ERROR_NONE Successful
 535  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 536  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 537  * @see app_control_set_app_id()
 538  */
 539 int app_control_get_app_id(app_control_h app_control, char **app_id);
 540
 541 /**
 542  * @internal
 543  * @brief Sets the window ID of the application.
 544  *
 545  * @since_tizen 2.3
 546  * @param[in] app_control The app_control handle
 547  * @param[in] id The window ID of the caller application (if the @a id is not positive, it clears the previous value)
 548  * @return @c 0 on success,
 549  *         otherwise a negative error value
 550  * @retval #APP_CONTROL_ERROR_NONE Successful
 551  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 552  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 553  * @see app_control_get_window()
 554  */
 555 int app_control_set_window(app_control_h app_control, unsigned int id);
 556
 557
 558 /**
 559  * @internal
 560  * @brief Gets the window ID of the application.
 561  *
 562  * @since_tizen 2.3
 563  * @param[in] app_control The app_control handle
 564  * @param[out] id The window ID of the caller application
 565  * @return @c 0 on success,
 566  *         otherwise a negative error value
 567  * @retval #APP_CONTROL_ERROR_NONE Successful
 568  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 569  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 570  * @see app_control_set_app_id()
 571 */
 572 int app_control_get_window(app_control_h app_control, unsigned int *id);
 573
 574
 575 /**
 576  * @brief Adds extra data to the app_control.
 577  *
 578  * @since_tizen 2.3
 579  * @remarks The function replaces any existing value for the given key.
 580  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if @a key or @a value is a zero-length string.
 581  * @remarks The function returns #APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with system-defined key.
 582  * @param[in] app_control The app_control handle
 583  * @param[in] key The name of the extra data
 584  * @param[in] value The value associated with the given key
 585  * @return @c 0 on success,
 586  *         otherwise a negative error value
 587  * @retval #APP_CONTROL_ERROR_NONE Successful
 588  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 589  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 590  * @see app_control_add_extra_data_array()
 591  * @see app_control_remove_extra_data()
 592  * @see app_control_get_extra_data()
 593  */
 594 int app_control_add_extra_data(app_control_h app_control, const char *key, const char *value);
 595
 596
 597 /**
 598  * @brief Adds the extra data array to the app_control.
 599  *
 600  * @since_tizen 2.3
 601  * @remarks The function replaces any existing value for the given key.
 602  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if @a key is a zero-length string.
 603  * @remarks The function returns #APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with system-defined key.
 604  * @param[in] app_control The app_control handle
 605  * @param[in] key The name of the extra data
 606  * @param[in] value The array value associated with the given key
 607  * @param[in] length The length of the array
 608  * @return @c 0 on success,
 609  *         otherwise a negative error value
 610  * @retval #APP_CONTROL_ERROR_NONE Successful
 611  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 612  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 613  * @see app_control_add_extra_data()
 614  * @see app_control_remove_extra_data()
 615  * @see app_control_get_extra_data()
 616  */
 617 int app_control_add_extra_data_array(app_control_h app_control, const char *key, const char* value[], int length);
 618
 619
 620 /**
 621  * @brief Removes the extra data from the app_control.
 622  *
 623  * @since_tizen 2.3
 624  * @param[in] app_control The app_control handle
 625  * @param[in] key The name of the extra data
 626  * @return @c 0 on success,
 627  *         otherwise a negative error value
 628  * @retval #APP_CONTROL_ERROR_NONE Successful
 629  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 630  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 631  * @see app_control_add_extra_data()
 632  * @see app_control_add_extra_data_array()
 633  * @see app_control_get_extra_data()
 634  */
 635 int app_control_remove_extra_data(app_control_h app_control, const char *key);
 636
 637
 638 /**
 639  * @brief Gets the extra data from the app_control.
 640  *
 641  * @since_tizen 2.3
 642  * @remarks The @a value must be released using free().
 643  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_DATA_TYPE if @a value is of array data type.
 644  * @param[in] app_control The app_control handle
 645  * @param[in] key The name of the extra data
 646  * @param[out] value The value associated with the given key
 647  * @return @c 0 on success,
 648  *         otherwise a negative error value
 649  * @retval #APP_CONTROL_ERROR_NONE Successful
 650  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 651  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 652  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 653  * @retval #APP_CONTROL_ERROR_INVALID_DATA_TYPE Invalid data type
 654  * @see app_control_add_extra_data()
 655  * @see app_control_add_extra_data_array()
 656  * @see app_control_get_extra_data()
 657  * @see app_control_remove_extra_data()
 658  * @see app_control_foreach_extra_data()
 659  */
 660 int app_control_get_extra_data(app_control_h app_control, const char *key, char **value);
 661
 662
 663 /**
 664  * @brief Gets the extra data array from the app_control.
 665  *
 666  * @since_tizen 2.3
 667  * @remarks The @a value must be released using free().
 668  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_DATA_TYPE if @a value is not of array data type.
 669  * @param[in] app_control The app_control handle
 670  * @param[in] key The name of the extra data
 671  * @param[out] value The array value associated with the given key
 672  * @param[out] length The length of the array
 673  * @return @c 0 on success,
 674  *         otherwise a negative error value
 675  * @retval #APP_CONTROL_ERROR_NONE Successful
 676  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 677  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 678  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 679  * @retval #APP_CONTROL_ERROR_INVALID_DATA_TYPE Invalid data type
 680  * @see app_control_add_extra_data()
 681  * @see app_control_add_extra_data_array()
 682  * @see app_control_remove_extra_data()
 683  * @see app_control_foreach_extra_data()
 684  */
 685 int app_control_get_extra_data_array(app_control_h app_control, const char *key, char ***value, int *length);
 686
 687
 688 /**
 689  * @brief Checks whether the extra data associated with the given @a key is of array data type.
 690  *
 691  * @since_tizen 2.3
 692  * @param[in] app_control The app_control handle
 693  * @param[in] key The name of the extra data
 694  * @param[out] array If @c true the extra data is of array data type,
 695  *                   otherwise @c false
 696  * @return @c 0 on success,
 697  *         otherwise a negative error value
 698  * @retval #APP_CONTROL_ERROR_NONE Successful
 699  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 700  * @see app_control_add_extra_data()
 701  * @see app_control_add_extra_data_array()
 702  * @see app_control_remove_extra_data()
 703  * @see app_control_foreach_extra_data()
 704  */
 705 int app_control_is_extra_data_array(app_control_h app_control, const char *key, bool *array);
 706
 707
 708 /**
 709  * @brief Retrieves all extra data contained in app_control.
 710  * @details This function calls app_control_extra_data_cb() once for each key-value pair for extra data contained in app_control. \n
 711  *          If the app_control_extra_data_cb() callback function returns @c false, then iteration will be finished.
 712  *
 713  * @since_tizen 2.3
 714  * @param[in] app_control The app_control handle
 715  * @param[in] callback The iteration callback function
 716  * @param[in] user_data The user data to be passed to the callback function
 717  * @return @c 0 on success,
 718  *         otherwise a negative error value
 719  * @retval #APP_CONTROL_ERROR_NONE Successful
 720  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 721  * @post This function invokes app_control_extra_data_cb().
 722  * @see app_control_extra_data_cb()
 723  */
 724 int app_control_foreach_extra_data(app_control_h app_control, app_control_extra_data_cb callback, void *user_data);
 725
 726
 727 /**
 728  * @brief Retrieves all applications that can be launched to handle the given app_control request.
 729  *
 730  * @since_tizen 2.3
 731  * @param[in] app_control The app_control handle
 732  * @param[in] callback The iteration callback function
 733  * @param[in] user_data The user data to be passed to the callback function
 734  * @return @c 0 on success,
 735  *         otherwise a negative error value
 736  * @retval #APP_CONTROL_ERROR_NONE Success
 737  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 738  * @post This function invokes app_control_app_matched_cb().
 739  * @see app_control_app_matched_cb()
 740  */
 741 int app_control_foreach_app_matched(app_control_h app_control, app_control_app_matched_cb callback, void *user_data);
 742
 743
 744 /**
 745  * @brief Sends the launch request.
 746  *
 747  * @details The operation is mandatory information for the launch request. \n
 748  *          If the operation is not specified, #APP_CONTROL_OPERATION_DEFAULT is used by default.
 749  *          If the operation is #APP_CONTROL_OPERATION_DEFAULT, the application ID is mandatory to explicitly launch the application.
 750  * @since_tizen 2.3
 751  * @privlevel   public
 752  * @privilege   %http://tizen.org/privilege/appmanager.launch
 753  * @param[in] app_control The app_control handle
 754  * @param[in] callback The callback function to be called when the reply is delivered
 755  * @param[in] user_data The user data to be passed to the callback function
 756  * @return @c 0 on success,
 757  *         otherwise a negative error value
 758  * @retval #APP_CONTROL_ERROR_NONE Successful
 759  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 760  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 761  * @retval #APP_CONTROL_ERROR_APP_NOT_FOUND The application to run the given launch request is not found
 762  * @retval #APP_CONTROL_ERROR_LAUNCH_REJECTED The application cannot be launched in current context
 763  * @retval #APP_CONTROL_ERROR_LAUNCH_FAILED Failed to launch the application
 764  * @retval #APP_CONTROL_ERROR_TIMED_OUT Failed due to timeout. The application that handles @a app_control may be busy
 765  * @retval #APP_CONTROL_ERROR_PERMISSION_DENIED Permission denied
 766  * @post If the launch request is sent for the result, the result will come back through app_control_reply_cb() from the callee application.
 767  * @see app_control_reply_to_launch_request()
 768  * @see app_control_reply_cb()
 769  */
 770 int app_control_send_launch_request(app_control_h app_control, app_control_reply_cb callback, void *user_data);
 771
 772
 773 /**
 774  * @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.
 775  *
 776  * @since_tizen 2.3
 777  * @param[in] app_control The app_control handle
 778  * @return @c 0 on success,
 779  *         otherwise a negative error value
 780  * @retval #APP_CONTROL_ERROR_NONE Successful
 781  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 782  * @retval #APP_CONTROL_ERROR_PERMISSION_DENIED Permission denied
 783  * @see app_control_send_launch_request()
 784  */
 785 int app_control_send_terminate_request(app_control_h app_control);
 786
 787
 788 /**
 789  * @brief Replies to the launch request sent by the caller.
 790  * @details If the caller application sent the launch request to receive the result, the callee application can return the result back to the caller.
 791  *
 792  * @since_tizen 2.3
 793  * @param[in] reply The app_control handle in which the results of the callee are contained
 794  * @param[in] request The app_control handle sent by the caller
 795  * @param[in] result  The result code of the launch request
 796  * @return @c 0 on success,
 797  *         otherwise a negative error value
 798  * @retval #APP_CONTROL_ERROR_NONE Successful
 799  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 800  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 801  * @see app_control_send_launch_request()
 802  */
 803 int app_control_reply_to_launch_request(app_control_h reply, app_control_h request, app_control_result_e result);
 804
 805
 806 /**
 807  * @brief Creates and returns a copy of the given app_control handle.
 808  *
 809  * @since_tizen 2.3
 810  * @remarks A newly created app_control should be destroyed by calling app_control_destroy() if it is no longer needed.
 811  *
 812  * @param[out] clone If successful, a newly created app_control handle will be returned
 813  * @param[in] app_control The app_control handle
 814  * @return @c 0 on success,
 815  *         otherwise a negative error value
 816  * @retval #APP_CONTROL_ERROR_NONE Successful
 817  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 818  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 819  * @see app_control_destroy()
 820  */
 821 int app_control_clone(app_control_h *clone, app_control_h app_control);
 822
 823
 824 /**
 825  * @brief Gets the application ID of the caller from the launch request.
 826  *
 827  * @since_tizen 2.3
 828  * @remarks The @a app_control must be the launch request from app_control_cb().
 829  * @remarks This function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request.
 830  * @remarks The @a id must be released using free().
 831  * @param[in] app_control The app_control handle from app_control_cb()
 832  * @param[out] id The application ID of the caller
 833  * @return @a 0 on success,
 834  *         otherwise a negative error value
 835  * @retval #APP_CONTROL_ERROR_NONE Successful
 836  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 837  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 838  */
 839 int app_control_get_caller(app_control_h app_control, char **id);
 840
 841
 842 /**
 843  * @brief Checks whether the caller is requesting a reply from the launch request.
 844  *
 845  * @since_tizen 2.3
 846  * @remarks The @a app_control must be the launch request from app_control_cb().
 847  * @remarks This function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request.
 848  * @param[in] app_control The app_control handle from app_control_cb()
 849  * @param[out] requested If @c true a reply is requested by the caller,
 850  *                       otherwise @c false
 851  * @return @c 0 on success,
 852  *         otherwise a negative error value
 853  * @retval #APP_CONTROL_ERROR_NONE Successful
 854  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 855  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 856  */
 857 int app_control_is_reply_requested(app_control_h app_control, bool *requested);
 858
 859 /**
 860  * @internal
 861  * @brief Requests the specified callee window to be transient for the caller window.
 862  *
 863  * @since_tizen 2.3
 864  * @remarks The @a callee_id window is transient for the top-level caller window and should be handled accordingly.
 865  * @param[in] app_control The app_control handle
 866  * @param[in] callee_id The callee window ID
 867  * @param[in] cbfunc The callback function to be called when the transient is requested
 868  * @param[in] data A data pointer to pass to the callback function
 869  * @return @c 0 on success,
 870  *         otherwise a negative error value.
 871  * @retval #APP_CONTROL_ERROR_NONE Successful
 872  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 873  */
 874 int app_control_request_transient_app(app_control_h app_control, unsigned int callee_id, app_control_host_res_fn cbfunc, void *data);
 875
 876 /**
 877  * @}
 878  */
 879
 880 #ifdef __cplusplus
 881 }
 882 #endif
 883
 884 #endif /* __TIZEN_APPFW_APP_CONTROL_H__ */