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 | 0x21, /**< The application is not found */
  57         APP_CONTROL_ERROR_KEY_NOT_FOUND = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Specified key is not found */
  58         APP_CONTROL_ERROR_KEY_REJECTED = TIZEN_ERROR_KEY_REJECTED, /**< Key is not available */
  59         APP_CONTROL_ERROR_INVALID_DATA_TYPE = TIZEN_ERROR_APPLICATION | 0x22, /**< Invalid data type */
  60         APP_CONTROL_ERROR_LAUNCH_REJECTED = TIZEN_ERROR_APPLICATION | 0x23, /**< The application cannot be launched now*/
  61         APP_CONTROL_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,    /**< Permission denied */
  62         APP_CONTROL_ERROR_LAUNCH_FAILED = TIZEN_ERROR_APPLICATION | 0x24, /**< Internal launch error */
  63         APP_CONTROL_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT /**< Time out */
  64 } app_control_error_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 app_control optional data: the subject of a message.
 201  * @since_tizen 2.3
 202  */
 203 #define APP_CONTROL_DATA_SUBJECT "http://tizen.org/appcontrol/data/subject"
 204
 205
 206 /**
 207  * @brief Definition for app_control optional data: e-mail addresses.
 208  * @since_tizen 2.3
 209  */
 210 #define APP_CONTROL_DATA_TO "http://tizen.org/appcontrol/data/to"
 211
 212
 213 /**
 214  * @brief Definition for app_control optional data: e-mail addresses that should be carbon copied.
 215  * @since_tizen 2.3
 216  */
 217 #define APP_CONTROL_DATA_CC "http://tizen.org/appcontrol/data/cc"
 218
 219
 220 /**
 221  * @brief Definition for app_control optional data: e-mail addresses that should be blind carbon copied.
 222  * @since_tizen 2.3
 223  */
 224 #define APP_CONTROL_DATA_BCC "http://tizen.org/appcontrol/data/bcc"
 225
 226
 227 /**
 228  * @brief Definition for app_control optional data: the content of the data is associated with #APP_CONTROL_OPERATION_SEND.
 229  * @since_tizen 2.3
 230  */
 231 #define APP_CONTROL_DATA_TEXT "http://tizen.org/appcontrol/data/text"
 232
 233
 234 /**
 235  * @brief Definition for app_control optional data: the title of the data.
 236  * @since_tizen 2.3
 237  */
 238 #define APP_CONTROL_DATA_TITLE "http://tizen.org/appcontrol/data/title"
 239
 240
 241 /**
 242  * @brief Definition for app_control optional data: the path of a selected item.
 243  * @since_tizen 2.3
 244  */
 245 #define APP_CONTROL_DATA_SELECTED "http://tizen.org/appcontrol/data/selected"
 246
 247
 248 /**
 249  * @brief Definition for app_control optional data: multiple item path to deliver.
 250  * @since_tizen 2.3
 251  */
 252 #define APP_CONTROL_DATA_PATH "http://tizen.org/appcontrol/data/path"
 253
 254
 255 /**
 256  * @brief Definition for app_control optional data: the selection type.
 257  * @since_tizen 2.3
 258  */
 259 #define APP_CONTROL_DATA_SELECTION_MODE "http://tizen.org/appcontrol/data/selection_mode"
 260
 261
 262 /**
 263  * @brief Called when the reply of the launch request is delivered.
 264  *
 265  * @since_tizen 2.3
 266  *
 267  * @remarks The @a request and @a reply must not be deallocated by the application.
 268  *
 269  * @param[in] request The app_control handle of the launch request that has been sent
 270  * @param[in] reply The app_control handle in which the results of the callee are contained
 271  * @param[in] result The result code of the launch request
 272  * @param[in] user_data The user data passed from the callback registration function
 273  * @pre When the callee replies to the launch request, this callback will be invoked.
 274  * @see app_control_send_launch_request()
 275  * @see app_control_reply_to_launch_request()
 276  */
 277 typedef void (*app_control_reply_cb) (app_control_h request, app_control_h reply, app_control_result_e result, void *user_data);
 278
 279
 280 /**
 281  * @brief Called to retrieve the extra data contained in the app_control.
 282  *
 283  * @since_tizen 2.3
 284  *
 285  * @remarks The @a key must not be deallocated by the application.
 286  *
 287  * @param[in] app_control  The app_control handle
 288  * @param[in] key The key of the value contained in the app_control
 289  * @param[in] user_data The user data passed from the foreach function
 290  * @return @c true to continue with the next iteration of the loop,
 291  *         otherwise @c false to break out of the loop
 292  * @pre app_control_foreach_extra_data() will invoke this callback.
 293  * @see app_control_foreach_extra_data()
 294  */
 295 typedef bool (*app_control_extra_data_cb)(app_control_h app_control, const char *key, void *user_data);
 296
 297
 298 /**
 299  * @brief Called once for each matched application that can be launched to handle the given app_control request.
 300  *
 301  * @since_tizen 2.3
 302  * @param[in] app_control  The app_control handle
 303  * @param[in] package The package name of the application that can handle the launch request of the given app_control
 304  * @param[in] user_data The user data passed from the foreach function
 305  * @return @c true to continue with the next iteration of the loop,
 306  *         otherwise @c false to break out of the loop
 307  * @pre app_control_foreach_app_matched() will invoke this callback.
 308  * @see app_control_foreach_app_matched()
 309  */
 310 typedef bool (*app_control_app_matched_cb)(app_control_h app_control, const char *appid, void *user_data);
 311
 312
 313 typedef int (*app_control_host_res_fn)(void *data);
 314
 315 /**
 316  * @brief Creates an app_control handle.
 317  *
 318  * @since_tizen 2.3
 319  * @remarks The @a app_control must be released using app_control_destroy().
 320  * @param[out] app_control The app_control handle to be newly created on success
 321  * @return @c 0 on success,
 322  *         otherwise a negative error value
 323  * @retval #APP_CONTROL_ERROR_NONE Successful
 324  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 325  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 326  * @see app_control_destroy()
 327  */
 328 int app_control_create(app_control_h *app_control);
 329
 330
 331 /**
 332  * @brief Destroys the app_control handle and releases all its resources.
 333  *
 334  * @since_tizen 2.3
 335  * @param[in] app_control The app_control handle
 336  * @return @c 0 on success,
 337  *         otherwise a negative error value
 338  * @retval #APP_CONTROL_ERROR_NONE Successful
 339  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 340  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 341  * @see app_control_create()
 342  */
 343 int app_control_destroy(app_control_h app_control);
 344
 345
 346 /**
 347  * @internal
 348  * @brief Converts the app_control handle to bundle data.
 349  *
 350  * @since_tizen 2.3
 351  * @param[in] app_control The app_control handle
 352  * @param[out] data The bundle data on success
 353  * @return @c 0 on success,
 354  *         otherwise a negative error value
 355  * @retval #APP_CONTROL_ERROR_NONE Successful
 356  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 357  */
 358 int app_control_to_bundle(app_control_h app_control, bundle **data);
 359
 360 /**
 361  * @brief Sets the operation to be performed.
 362  *
 363  * @details The @a operation is the mandatory information for the launch request.
 364  *          If the operation is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 365  *          If the operation is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 366  * @since_tizen 2.3
 367  * @param[in] app_control The app_control handle
 368  * @param[in] operation The operation to be performed (if the @a operation is @c NULL, it clears the previous value)
 369  * @return @c 0 on success,
 370  *         otherwise a negative error value
 371  * @retval #APP_CONTROL_ERROR_NONE Successful
 372  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 373  * @see app_control_get_operation()
 374  * @see APP_CONTROL_OPERATION_DEFAULT
 375  * @see APP_CONTROL_OPERATION_EDIT
 376  * @see APP_CONTROL_OPERATION_VIEW
 377  * @see APP_CONTROL_OPERATION_PICK
 378  * @see APP_CONTROL_OPERATION_CREATE_CONTENT
 379  * @see APP_CONTROL_OPERATION_CALL
 380  * @see APP_CONTROL_OPERATION_SEND
 381  * @see APP_CONTROL_OPERATION_SEND_TEXT
 382  * @see APP_CONTROL_OPERATION_DIAL
 383  * @see APP_CONTROL_OPERATION_SEARCH
 384  */
 385 int app_control_set_operation(app_control_h app_control, const char *operation);
 386
 387
 388 /**
 389  * @brief Gets the operation to be performed.
 390  *
 391  * @since_tizen 2.3
 392  * @remarks The @a operation must be released using free().
 393  * @param[in] app_control The app_control handle
 394  * @param[out] operation The operation to be performed
 395  * @return @c 0 on success,
 396  *         otherwise a negative error value
 397  * @retval #APP_CONTROL_ERROR_NONE Successful
 398  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 399  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 400  * @see app_control_set_operation()
 401  */
 402 int app_control_get_operation(app_control_h app_control, char **operation);
 403
 404
 405 /**
 406  * @brief Sets the URI of the data.
 407  *
 408  * @since_tizen 2.3
 409  * @param[in] app_control The app_control handle
 410  * @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)
 411  * @return @c 0 on success,
 412  *         otherwise a negative error value
 413  * @retval #APP_CONTROL_ERROR_NONE Successful
 414  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 415  * @see app_control_get_uri()
 416  */
 417 int app_control_set_uri(app_control_h app_control, const char *uri);
 418
 419
 420 /**
 421  * @brief Gets the URI of the data.
 422  *
 423  * @since_tizen 2.3
 424  * @remarks The @a uri must be released using free().
 425  * @param[in] app_control The app_control handle
 426  * @param[out] uri The URI of the data this app_control is operating on
 427  * @return @c 0 on success,
 428  *         otherwise a negative error value
 429  * @retval #APP_CONTROL_ERROR_NONE Successful
 430  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 431  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 432  * @see app_control_set_uri()
 433  */
 434 int app_control_get_uri(app_control_h app_control, char **uri);
 435
 436
 437 /**
 438  * @brief Sets the explicit MIME type of the data.
 439  *
 440  * @since_tizen 2.3
 441  * @param[in] app_control The app_control handle
 442  * @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)
 443  * @return @c 0 on success,
 444  *         otherwise a negative error value
 445  * @retval #APP_CONTROL_ERROR_NONE Successful
 446  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 447  * @see app_control_get_mime()
 448  */
 449 int app_control_set_mime(app_control_h app_control, const char *mime);
 450
 451
 452 /**
 453  * @brief Gets the explicit MIME type of the data.
 454  *
 455  * @since_tizen 2.3
 456  * @remarks The @a uri must be released using free().
 457  * @param[in] app_control The app_control handle
 458  * @param[out] mime The explicit MIME type of the data this app_control is operating on
 459  * @return @c 0 on success,
 460  *         otherwise a negative error value
 461  * @retval #APP_CONTROL_ERROR_NONE Successful
 462  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 463  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 464  * @see app_control_set_mime()
 465  */
 466 int app_control_get_mime(app_control_h app_control, char **mime);
 467
 468
 469 /**
 470  * @brief Sets the explicit category.
 471  *
 472  * @since_tizen 2.3
 473  * @param[in] app_control The app_control handle
 474  * @param[in] category The explicit category (if the @a category is @c NULL, it clears the previous value)
 475  * @return @c 0 on success,
 476  *         otherwise a negative error value
 477  * @retval #APP_CONTROL_ERROR_NONE Successful
 478  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 479  * @see app_control_get_category()
 480  */
 481 int app_control_set_category(app_control_h app_control, const char *category);
 482
 483
 484 /**
 485  * @brief Gets the explicit category.
 486  *
 487  * @since_tizen 2.3
 488  * @remarks The @a category must be released using free().
 489  * @param[in] app_control The app_control handle
 490  * @param[out] category The explicit category
 491  * @return @c 0 on success,
 492  *         otherwise a negative error value
 493  * @retval #APP_CONTROL_ERROR_NONE Successful
 494  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 495  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 496  * @see app_control_set_category()
 497  */
 498 int app_control_get_category(app_control_h app_control, char **category);
 499
 500
 501 /**
 502  * @brief Sets the ID of the application to explicitly launch.
 503  *
 504  * @since_tizen 2.3
 505  * @param[in] app_control The app_control handle
 506  * @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)
 507  * @return @c 0 on success,
 508  *         otherwise a negative error value
 509  * @retval #APP_CONTROL_ERROR_NONE Successful
 510  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 511  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 512  * @see app_control_get_app_id()
 513  */
 514 int app_control_set_app_id(app_control_h app_control, const char *app_id);
 515
 516
 517 /**
 518  * @brief Gets the ID of the application to explicitly launch.
 519  *
 520  * @since_tizen 2.3
 521  * @remarks The @a app_id must be released with free().
 522  * @param[in] app_control The app_control handle
 523  * @param[out] app_id The ID of the application to explicitly launch
 524  * @return @c 0 on success,
 525  *         otherwise a negative error value
 526  * @retval #APP_CONTROL_ERROR_NONE Successful
 527  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 528  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 529  * @see app_control_set_app_id()
 530  */
 531 int app_control_get_app_id(app_control_h app_control, char **app_id);
 532
 533 /**
 534  * @internal
 535  * @brief Sets the window ID of the application.
 536  *
 537  * @since_tizen 2.3
 538  * @param[in] app_control The app_control handle
 539  * @param[in] id The window ID of the caller application (if the @a id is not positive, it clears the previous value)
 540  * @return @c 0 on success,
 541  *         otherwise a negative error value
 542  * @retval #APP_CONTROL_ERROR_NONE Successful
 543  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 544  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 545  * @see app_control_get_window()
 546  */
 547 int app_control_set_window(app_control_h app_control, unsigned int id);
 548
 549
 550 /**
 551  * @internal
 552  * @brief Gets the window ID of the application.
 553  *
 554  * @since_tizen 2.3
 555  * @param[in] app_control The app_control handle
 556  * @param[out] id The window ID of the caller application
 557  * @return @c 0 on success,
 558  *         otherwise a negative error value
 559  * @retval #APP_CONTROL_ERROR_NONE Successful
 560  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 561  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 562  * @see app_control_set_app_id()
 563 */
 564 int app_control_get_window(app_control_h app_control, unsigned int *id);
 565
 566
 567 /**
 568  * @brief Adds extra data to the app_control.
 569  *
 570  * @since_tizen 2.3
 571  * @remarks The function replaces any existing value for the given key.
 572  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if @a key or @a value is a zero-length string.
 573  * @remarks The function returns #APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with system-defined key.
 574  * @param[in] app_control The app_control handle
 575  * @param[in] key The name of the extra data
 576  * @param[in] value The value associated with the given key
 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_KEY_REJECTED Key not available
 582  * @see app_control_add_extra_data_array()
 583  * @see app_control_remove_extra_data()
 584  * @see app_control_get_extra_data()
 585  */
 586 int app_control_add_extra_data(app_control_h app_control, const char *key, const char *value);
 587
 588
 589 /**
 590  * @brief Adds the extra data array to the app_control.
 591  *
 592  * @since_tizen 2.3
 593  * @remarks The function replaces any existing value for the given key.
 594  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if @a key is a zero-length string.
 595  * @remarks The function returns #APP_CONTROL_ERROR_KEY_REJECTED if the application tries to use the same key with system-defined key.
 596  * @param[in] app_control The app_control handle
 597  * @param[in] key The name of the extra data
 598  * @param[in] value The array value associated with the given key
 599  * @param[in] length The length of the array
 600  * @return @c 0 on success,
 601  *         otherwise a negative error value
 602  * @retval #APP_CONTROL_ERROR_NONE Successful
 603  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 604  * @retval #APP_CONTROL_ERROR_KEY_REJECTED Key not available
 605  * @see app_control_add_extra_data()
 606  * @see app_control_remove_extra_data()
 607  * @see app_control_get_extra_data()
 608  */
 609 int app_control_add_extra_data_array(app_control_h app_control, const char *key, const char* value[], int length);
 610
 611
 612 /**
 613  * @brief Removes the extra data from the app_control.
 614  *
 615  * @since_tizen 2.3
 616  * @param[in] app_control The app_control handle
 617  * @param[in] key The name of the extra data
 618  * @return @c 0 on success,
 619  *         otherwise a negative error value
 620  * @retval #APP_CONTROL_ERROR_NONE Successful
 621  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 622  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 623  * @see app_control_add_extra_data()
 624  * @see app_control_add_extra_data_array()
 625  * @see app_control_get_extra_data()
 626  */
 627 int app_control_remove_extra_data(app_control_h app_control, const char *key);
 628
 629
 630 /**
 631  * @brief Gets the extra data from the app_control.
 632  *
 633  * @since_tizen 2.3
 634  * @remarks The @a value must be released using free().
 635  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_DATA_TYPE if @a value is of array data type.
 636  * @param[in] app_control The app_control handle
 637  * @param[in] key The name of the extra data
 638  * @param[out] value The value associated with the given key
 639  * @return @c 0 on success,
 640  *         otherwise a negative error value
 641  * @retval #APP_CONTROL_ERROR_NONE Successful
 642  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 643  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 644  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 645  * @retval #APP_CONTROL_ERROR_INVALID_DATA_TYPE Invalid data type
 646  * @see app_control_add_extra_data()
 647  * @see app_control_add_extra_data_array()
 648  * @see app_control_get_extra_data()
 649  * @see app_control_remove_extra_data()
 650  * @see app_control_foreach_extra_data()
 651  */
 652 int app_control_get_extra_data(app_control_h app_control, const char *key, char **value);
 653
 654
 655 /**
 656  * @brief Gets the extra data array from the app_control.
 657  *
 658  * @since_tizen 2.3
 659  * @remarks The @a value must be released using free().
 660  * @remarks The function returns #APP_CONTROL_ERROR_INVALID_DATA_TYPE if @a value is not of array data type.
 661  * @param[in] app_control The app_control handle
 662  * @param[in] key The name of the extra data
 663  * @param[out] value The array value associated with the given key
 664  * @param[out] length The length of the array
 665  * @return @c 0 on success,
 666  *         otherwise a negative error value
 667  * @retval #APP_CONTROL_ERROR_NONE Successful
 668  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 669  * @retval #APP_CONTROL_ERROR_KEY_NOT_FOUND Specified key not found
 670  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 671  * @retval #APP_CONTROL_ERROR_INVALID_DATA_TYPE Invalid data type
 672  * @see app_control_add_extra_data()
 673  * @see app_control_add_extra_data_array()
 674  * @see app_control_remove_extra_data()
 675  * @see app_control_foreach_extra_data()
 676  */
 677 int app_control_get_extra_data_array(app_control_h app_control, const char *key, char ***value, int *length);
 678
 679
 680 /**
 681  * @brief Checks whether the extra data associated with the given @a key is of array data type.
 682  *
 683  * @since_tizen 2.3
 684  * @param[in] app_control The app_control handle
 685  * @param[in] key The name of the extra data
 686  * @param[out] array If @c true the extra data is of array data type,
 687  *                   otherwise @c false
 688  * @return @c 0 on success,
 689  *         otherwise a negative error value
 690  * @retval #APP_CONTROL_ERROR_NONE Successful
 691  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 692  * @see app_control_add_extra_data()
 693  * @see app_control_add_extra_data_array()
 694  * @see app_control_remove_extra_data()
 695  * @see app_control_foreach_extra_data()
 696  */
 697 int app_control_is_extra_data_array(app_control_h app_control, const char *key, bool *array);
 698
 699
 700 /**
 701  * @brief Retrieves all extra data contained in app_control.
 702  * @details This function calls app_control_extra_data_cb() once for each key-value pair for extra data contained in app_control. \n
 703  *          If the app_control_extra_data_cb() callback function returns @c false, then iteration will be finished.
 704  *
 705  * @since_tizen 2.3
 706  * @param[in] app_control The app_control handle
 707  * @param[in] callback The iteration callback function
 708  * @param[in] user_data The user data to be passed to the callback function
 709  * @return @c 0 on success,
 710  *         otherwise a negative error value
 711  * @retval #APP_CONTROL_ERROR_NONE Successful
 712  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 713  * @post This function invokes app_control_extra_data_cb().
 714  * @see app_control_extra_data_cb()
 715  */
 716 int app_control_foreach_extra_data(app_control_h app_control, app_control_extra_data_cb callback, void *user_data);
 717
 718
 719 /**
 720  * @brief Retrieves all applications that can be launched to handle the given app_control request.
 721  *
 722  * @since_tizen 2.3
 723  * @param[in] app_control The app_control handle
 724  * @param[in] callback The iteration callback function
 725  * @param[in] user_data The user data to be passed to the callback function
 726  * @return @c 0 on success,
 727  *         otherwise a negative error value
 728  * @retval #APP_CONTROL_ERROR_NONE Success
 729  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 730  * @post This function invokes app_control_app_matched_cb().
 731  * @see app_control_app_matched_cb()
 732  */
 733 int app_control_foreach_app_matched(app_control_h app_control, app_control_app_matched_cb callback, void *user_data);
 734
 735
 736 /**
 737  * @brief Sends the launch request.
 738  *
 739  * @details The operation is mandatory information for the launch request. \n
 740  *          If the operation is not specified, #APP_CONTROL_OPERATION_DEFAULT is used by default.
 741  *          If the operation is #APP_CONTROL_OPERATION_DEFAULT, the application ID is mandatory to explicitly launch the application.
 742  * @since_tizen 2.3
 743  * @privlevel   public
 744  * @privilege   %http://tizen.org/privilege/appmanager.launch
 745  * @param[in] app_control The app_control handle
 746  * @param[in] callback The callback function to be called when the reply is delivered
 747  * @param[in] user_data The user data to be passed to the callback function
 748  * @return @c 0 on success,
 749  *         otherwise a negative error value
 750  * @retval #APP_CONTROL_ERROR_NONE Successful
 751  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 752  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 753  * @retval #APP_CONTROL_ERROR_APP_NOT_FOUND The application to run the given launch request is not found
 754  * @retval #APP_CONTROL_ERROR_LAUNCH_REJECTED The application cannot be launched in current context
 755  * @retval #APP_CONTROL_ERROR_LAUNCH_FAILED Failed to launch the application
 756  * @retval #APP_CONTROL_ERROR_TIMED_OUT Failed due to timeout. The application that handles @a app_control may be busy
 757  * @retval #APP_CONTROL_ERROR_PERMISSION_DENIED Permission denied
 758  * @post If the launch request is sent for the result, the result will come back through app_control_reply_cb() from the callee application.
 759  * @see app_control_reply_to_launch_request()
 760  * @see app_control_reply_cb()
 761  */
 762 int app_control_send_launch_request(app_control_h app_control, app_control_reply_cb callback, void *user_data);
 763
 764
 765 /**
 766  * @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.
 767  *
 768  * @since_tizen 2.3
 769  * @param[in] app_control The app_control handle
 770  * @return @c 0 on success,
 771  *         otherwise a negative error value
 772  * @retval #APP_CONTROL_ERROR_NONE Successful
 773  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 774  * @retval #APP_CONTROL_ERROR_PERMISSION_DENIED Permission denied
 775  * @see app_control_send_launch_request()
 776  */
 777 int app_control_send_terminate_request(app_control_h app_control);
 778
 779
 780 /**
 781  * @brief Replies to the launch request sent by the caller.
 782  * @details If the caller application sent the launch request to receive the result, the callee application can return the result back to the caller.
 783  *
 784  * @since_tizen 2.3
 785  * @param[in] reply The app_control handle in which the results of the callee are contained
 786  * @param[in] request The app_control handle sent by the caller
 787  * @param[in] result  The result code of the launch request
 788  * @return @c 0 on success,
 789  *         otherwise a negative error value
 790  * @retval #APP_CONTROL_ERROR_NONE Successful
 791  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 792  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 793  * @see app_control_send_launch_request()
 794  */
 795 int app_control_reply_to_launch_request(app_control_h reply, app_control_h request, app_control_result_e result);
 796
 797
 798 /**
 799  * @brief Creates and returns a copy of the given app_control handle.
 800  *
 801  * @since_tizen 2.3
 802  * @remarks A newly created app_control should be destroyed by calling app_control_destroy() if it is no longer needed.
 803  *
 804  * @param[out] clone If successful, a newly created app_control handle will be returned
 805  * @param[in] app_control The app_control handle
 806  * @return @c 0 on success,
 807  *         otherwise a negative error value
 808  * @retval #APP_CONTROL_ERROR_NONE Successful
 809  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 810  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 811  * @see app_control_destroy()
 812  */
 813 int app_control_clone(app_control_h *clone, app_control_h app_control);
 814
 815
 816 /**
 817  * @brief Gets the application ID of the caller from the launch request.
 818  *
 819  * @since_tizen 2.3
 820  * @remarks The @a app_control must be the launch request from app_control_cb().
 821  * @remarks This function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request.
 822  * @remarks The @a id must be released using free().
 823  * @param[in] app_control The app_control handle from app_control_cb()
 824  * @param[out] id The application ID of the caller
 825  * @return @a 0 on success,
 826  *         otherwise a negative error value
 827  * @retval #APP_CONTROL_ERROR_NONE Successful
 828  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 829  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 830  */
 831 int app_control_get_caller(app_control_h app_control, char **id);
 832
 833
 834 /**
 835  * @brief Checks whether the caller is requesting a reply from the launch request.
 836  *
 837  * @since_tizen 2.3
 838  * @remarks The @a app_control must be the launch request from app_control_cb().
 839  * @remarks This function returns #APP_CONTROL_ERROR_INVALID_PARAMETER if the given app_control is not the launch request.
 840  * @param[in] app_control The app_control handle from app_control_cb()
 841  * @param[out] requested If @c true a reply is requested by the caller,
 842  *                       otherwise @c false
 843  * @return @c 0 on success,
 844  *         otherwise a negative error value
 845  * @retval #APP_CONTROL_ERROR_NONE Successful
 846  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 847  * @retval #APP_CONTROL_ERROR_OUT_OF_MEMORY Out of memory
 848  */
 849 int app_control_is_reply_requested(app_control_h app_control, bool *requested);
 850
 851 /**
 852  * @internal
 853  * @brief Requests the specified callee window to be transient for the caller window.
 854  *
 855  * @since_tizen 2.3
 856  * @remarks The @a callee_id window is transient for the top-level caller window and should be handled accordingly.
 857  * @param[in] app_control The app_control handle
 858  * @param[in] callee_id The callee window ID
 859  * @param[in] cbfunc The callback function to be called when the transient is requested
 860  * @param[in] data A data pointer to pass to the callback function
 861  * @return @c 0 on success,
 862  *         otherwise a negative error value.
 863  * @retval #APP_CONTROL_ERROR_NONE Successful
 864  * @retval #APP_CONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 865  */
 866 int app_control_request_transient_app(app_control_h app_control, unsigned int callee_id, app_control_host_res_fn cbfunc, void *data);
 867
 868 /**
 869  * @}
 870  */
 871
 872 #ifdef __cplusplus
 873 }
 874 #endif
 875
 876 #endif /* __TIZEN_APPFW_APP_CONTROL_H__ */