include/app_service.h

   1 /*
   2  * Copyright (c) 2011 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_SERVICE_H__
  19 #define __TIZEN_APPFW_SERVICE_H__
  20
  21 #include <sys/types.h>
  22 #include <tizen.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @addtogroup CAPI_SERVICE_MODULE
  30  * @{
  31  */
  32
  33
  34 /**
  35  * @brief Service handle.
  36  */
  37 typedef struct service_s *service_h;
  38
  39
  40 /**
  41  * @brief Enumerations of error code for Service.
  42  */
  43 typedef enum
  44 {
  45         SERVICE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  46         SERVICE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  47         SERVICE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  48         SERVICE_ERROR_APP_NOT_FOUND = TIZEN_ERROR_APPLICATION_CLASS | 0x21, /**< The application was not found */
  49         SERVICE_ERROR_KEY_NOT_FOUND = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Specified key not found */
  50         SERVICE_ERROR_KEY_REJECTED = TIZEN_ERROR_KEY_REJECTED, /**< Not available key */
  51         SERVICE_ERROR_INVALID_DATA_TYPE = TIZEN_ERROR_APPLICATION_CLASS | 0x22, /**< Invalid data type */
  52 } service_error_e;
  53
  54
  55 /**
  56  * @brief Enumeration of service result.
  57  */
  58 typedef enum
  59 {
  60         SERVICE_RESULT_SUCCEEDED = 0, /**< Operation succeeded */
  61         SERVICE_RESULT_FAILED = -1, /**< Operation failed by the callee */
  62         SERVICE_RESULT_CANCELED = -2, /**< Operation canceled by the framework */
  63 } service_result_e;
  64
  65
  66 /**
  67  * @brief       Service operation : default operation for explicit launch
  68  */
  69 #define SERVICE_OPERATION_DEFAULT "http://tizen.org/appcontrol/operation/default"
  70
  71
  72 /**
  73  * @brief       Service operation : provide explicit editable access to the given data.
  74  */
  75 #define SERVICE_OPERATION_EDIT "http://tizen.org/appcontrol/operation/edit"
  76
  77
  78 /**
  79  * @brief       Service operation : display the data.
  80  */
  81 #define SERVICE_OPERATION_VIEW "http://tizen.org/appcontrol/operation/view"
  82
  83
  84 /**
  85  * @brief       Service operation : pick an item from the data, returning what was selected.
  86  */
  87 #define SERVICE_OPERATION_PICK "http://tizen.org/appcontrol/operation/pick"
  88
  89
  90 /**
  91  * @brief       Service operation : create a content, returning what was created.
  92  */
  93 #define SERVICE_OPERATION_CREATE_CONTENT "http://tizen.org/appcontrol/operation/create_content"
  94
  95
  96 /**
  97  * @brief       Service operation : perform a call to someone specified by the data.
  98  */
  99 #define SERVICE_OPERATION_CALL "http://tizen.org/appcontrol/operation/call"
 100
 101
 102 /**
 103  * @brief       Service operation : deliver some data to someone else.
 104  */
 105 #define SERVICE_OPERATION_SEND "http://tizen.org/appcontrol/operation/send"
 106
 107
 108 /**
 109  * @brief       Service operation : deliver text data to someone else.
 110  */
 111 #define SERVICE_OPERATION_SEND_TEXT "http://tizen.org/appcontrol/operation/send_text"
 112
 113
 114 /**
 115  * @brief       Service operation : dial a number as specified by the data.
 116  */
 117 #define SERVICE_OPERATION_DIAL "http://tizen.org/appcontrol/operation/dial"
 118
 119
 120 /**
 121  * @brief       Service operation : perform a search.
 122  */
 123 #define SERVICE_OPERATION_SEARCH "http://tizen.org/appcontrol/operation/search"
 124
 125
 126 /**
 127  * @brief       Service optional data : the subject of a message.
 128  */
 129 #define SERVICE_DATA_SUBJECT "http://tizen.org/appcontrol/data/subject"
 130
 131
 132 /**
 133  * @brief       Service optional data : e-mail addresses.
 134  */
 135 #define SERVICE_DATA_TO "http://tizen.org/appcontrol/data/to"
 136
 137
 138 /**
 139  * @brief       Service optional data : e-mail addresses that should be carbon copied.
 140  */
 141 #define SERVICE_DATA_CC "http://tizen.org/appcontrol/data/cc"
 142
 143
 144 /**
 145  * @brief       Service optional data : e-mail addresses that should be blind carbon copied.
 146  */
 147 #define SERVICE_DATA_BCC "http://tizen.org/appcontrol/data/bcc"
 148
 149
 150 /**
 151  * @brief       Service optional data : the content of the data is associated with #SERVICE_OPERATION_SEND.
 152  */
 153 #define SERVICE_DATA_TEXT "http://tizen.org/appcontrol/data/text"
 154
 155
 156 /**
 157  * @brief       Service optional data : the title of the data
 158  */
 159 #define SERVICE_DATA_TITLE "http://tizen.org/appcontrol/data/title"
 160
 161
 162 /**
 163  * @brief       Service optional data : the path of selected item.
 164  */
 165 #define SERVICE_DATA_SELECTED "http://tizen.org/appcontrol/data/selected"
 166
 167
 168 /**
 169  * @brief   Called when the reply of the launch request is delivered.
 170  *
 171  * @remarks The @a request and @a reply must not be deallocated by an application.
 172  *
 173  * @param   [in] request The service handle of the launch request that has sent
 174  * @param   [in] reply The service handle in which the results of the callee are contained
 175  * @param   [in] result The result code of the launch request
 176  * @param   [in] user_data      The user data passed from the callback registration function
 177  * @pre When the callee replies to the launch request, this callback will be invoked.
 178  * @see service_send_launch_request()
 179  * @see service_reply_to_launch_request()
 180  */
 181 typedef void (*service_reply_cb) (service_h request, service_h reply, service_result_e result, void *user_data);
 182
 183
 184 /**
 185 * @brief   Called to retrieve the extra data that are contained in the service
 186 *
 187 * @remarks The @a key must not be deallocated by an application.
 188 *
 189 * @param[in] service  The service handle
 190 * @param[in] key The key of the value contained in the service
 191 * @param[in] user_data The user data passed from the foreach function
 192 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
 193 * @pre  service_foreach_extra_data() will invoke this callback.
 194 * @see  service_foreach_extra_data()
 195 */
 196 typedef bool (*service_extra_data_cb)(service_h service, const char *key, void *user_data);
 197
 198
 199 /**
 200 * @brief   Called once for each matched application that can be launched to handle the given service request.
 201 *
 202 * @param [in] service  The service handle
 203 * @param [in] package The package name of the application that can handle the launch request of the given service.
 204 * @param [in] user_data The user data passed from the foreach function
 205 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
 206 * @pre  service_foreach_app_matched() will invoke this callback.
 207 * @see service_foreach_app_matched()
 208 */
 209 typedef bool (*service_app_matched_cb)(service_h service, const char *package, void *user_data);
 210
 211
 212 /**
 213  * @brief Creates a service handle.
 214  *
 215  * @remarks The @a service must be released with service_destroy() by you.
 216  * @param [out] service A service handle to be newly created on success
 217  * @return 0 on success, otherwise a negative error value.
 218  * @retval #SERVICE_ERROR_NONE Successful
 219  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 220  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 221  * @see service_destroy()
 222  */
 223 int service_create(service_h *service);
 224
 225
 226 /**
 227  * @brief Destroys the service handle and releases all its resources.
 228  *
 229  * @param [in] service The service handle
 230  * @return 0 on success, otherwise a negative error value.
 231  * @retval #SERVICE_ERROR_NONE Successful
 232  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 233  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 234  * @see service_create()
 235  */
 236 int service_destroy(service_h service);
 237
 238
 239 /**
 240  * @brief Sets the operation to be performed.
 241  *
 242  * @details The @a operation is the mandatory information for the launch request.
 243  * If the operation is not specified, #SERVICE_OPERATION_DEFAULT is used for the launch request.
 244  * If the operation is #SERVICE_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application
 245  * @param [in] service The service handle
 246  * @param [in] operation The operation to be performed \n
 247  *     If the @a operation is NULL, it clears the previous value.
 248  * @return 0 on success, otherwise a negative error value.
 249  * @retval #SERVICE_ERROR_NONE Successful
 250  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 251  * @see service_get_operation()
 252  * @see SERVICE_OPERATION_DEFAULT
 253  * @see SERVICE_OPERATION_EDIT
 254  * @see SERVICE_OPERATION_VIEW
 255  * @see SERVICE_OPERATION_PICK
 256  * @see SERVICE_OPERATION_CREATE_CONTENT
 257  * @see SERVICE_OPERATION_CALL
 258  * @see SERVICE_OPERATION_SEND
 259  * @see SERVICE_OPERATION_SEND_TEXT
 260  * @see SERVICE_OPERATION_DIAL
 261  * @see SERVICE_OPERATION_SEARCH
 262  */
 263 int service_set_operation(service_h service, const char *operation);
 264
 265
 266 /**
 267  * @brief Gets the operation to be performed.
 268  *
 269  * @remarks The @a operation must be released with free() by you.
 270  * @param [in] service The service handle
 271  * @param [out] operation The operation to be performed
 272  * @return 0 on success, otherwise a negative error value.
 273  * @retval #SERVICE_ERROR_NONE Successful
 274  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 275  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 276  * @see service_set_operation()
 277  */
 278 int service_get_operation(service_h service, char **operation);
 279
 280
 281 /**
 282  * @brief Sets the URI of the data.
 283  *
 284  * @param [in] service The service handle
 285  * @param [in] uri The URI of the data this service is operating on \n
 286  *     If the @a uri is NULL, it clears the previous value.
 287  * @return 0 on success, otherwise a negative error value.
 288  * @retval #SERVICE_ERROR_NONE Successful
 289  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 290  * @see service_get_uri()
 291  */
 292 int service_set_uri(service_h service, const char *uri);
 293
 294
 295 /**
 296  * @brief Gets the URI of the data.
 297  *
 298  * @remarks The @a uri must be released with free() by you.
 299  * @param [in] service The service handle
 300  * @param [out] uri The URI of the data this service is operating on
 301  * @return 0 on success, otherwise a negative error value.
 302  * @retval #SERVICE_ERROR_NONE Successful
 303  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 304  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 305  * @see service_set_uri()
 306  */
 307 int service_get_uri(service_h service, char **uri);
 308
 309
 310 /**
 311  * @brief Sets the explicit MIME type of the data
 312  *
 313  * @param [in] service The service handle
 314  * @param [in] mime the explicit MIME type of the data this service is operating on \n
 315  *     If the @a mime is NULL, it clears the previous value.
 316  * @return 0 on success, otherwise a negative error value.
 317  * @retval #SERVICE_ERROR_NONE Successful
 318  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 319  * @see service_get_mime()
 320  */
 321 int service_set_mime(service_h service, const char *mime);
 322
 323
 324 /**
 325  * @brief Gets the explicit MIME type of the data.
 326  *
 327  * @remarks The @a uri must be released with free() by you.
 328  * @param [in] service The service handle
 329  * @param [out] mime The explicit MIME type of the data this service is operating on
 330  * @return 0 on success, otherwise a negative error value.
 331  * @retval #SERVICE_ERROR_NONE Successful
 332  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 333  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 334  * @see service_set_mime()
 335  */
 336 int service_get_mime(service_h service, char **mime);
 337
 338
 339 /**
 340  * @brief Sets the package name of the application to explicitly launch
 341  *
 342  * @remark This function is @b deprecated. Use service_set_app_id() instead.
 343  * @param [in] service The service handle
 344  * @param [in] package The package name of the application to explicitly launch \n
 345  *     If the @a package is NULL, it clears the previous value.
 346  * @return 0 on success, otherwise a negative error value.
 347  * @retval #SERVICE_ERROR_NONE Successful
 348  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 349  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 350  * @see service_get_package()
 351  */
 352 int service_set_package(service_h service, const char *package);
 353
 354
 355 /**
 356  * @brief Gets the package name of the application to explicitly launch
 357  *
 358  * @remark This function is @b deprecated. Use service_get_app_id() instead.
 359  * @remarks The @a package must be released with free() by you.
 360  * @param [in] service The service handle
 361  * @param [out] package The package name of the application to explicitly launch
 362  * @return 0 on success, otherwise a negative error value.
 363  * @retval #SERVICE_ERROR_NONE Successful
 364  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 365  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 366  * @see service_set_package()
 367  */
 368 int service_get_package(service_h service, char **package);
 369
 370
 371 /**
 372  * @brief Sets the ID of the application to explicitly launch
 373  *
 374  * @param [in] service The service handle
 375  * @param [in] app_id The ID of the application to explicitly launch \n
 376  *     If the @a app_id is NULL, it clears the previous value.
 377  * @return 0 on success, otherwise a negative error value.
 378  * @retval #SERVICE_ERROR_NONE Successful
 379  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 380  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 381  * @see service_get_app_id()
 382  */
 383 int service_set_app_id(service_h service, const char *app_id);
 384
 385
 386 /**
 387  * @brief Gets the ID of the application to explicitly launch
 388  *
 389  * @remarks The @a app_id must be released with free() by you.
 390  * @param [in] service The service handle
 391  * @param [out] app_id The ID of the application to explicitly launch
 392  * @return 0 on success, otherwise a negative error value.
 393  * @retval #SERVICE_ERROR_NONE Successful
 394  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 395  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 396  * @see service_set_app_id()
 397  */
 398 int service_get_app_id(service_h service, char **app_id);
 399
 400 /**
 401  * @brief Sets the window id of the application
 402  *
 403  * @param [in] service The service handle
 404  * @param [in] id the window id of caller application \n
 405  *     If the @a id is not positive, it clears the previous value.
 406  * @return 0 on success, otherwise a negative error value.
 407  * @retval #SERVICE_ERROR_NONE Successful
 408  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 409  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 410  * @see service_get_window()
 411  */
 412 int service_set_window(service_h service, unsigned int id);
 413
 414
 415 /**
 416 * @brief Gets the window id of the application
 417 *
 418 * @param [in] service The service handle
 419 * @param [out] id The window id of caller application
 420 * @return 0 on success, otherwise a negative error value.
 421 * @retval #SERVICE_ERROR_NONE Successful
 422 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 423 * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 424 * @see service_set_package()
 425 */
 426 int service_get_window(service_h service, unsigned int *id);
 427
 428
 429 /**
 430  * @brief Adds the extra data to the service.
 431  *
 432  * @remarks The function replaces any existing value for the given key.
 433  * @remarks The function returns #SERVICE_ERROR_INVALID_PARAMETER if key or value is zero-length string.
 434  * @remarks The function returns #SERVICE_ERROR_KEY_REJECTED if the application tries to use same key with system-defined key
 435  * @param [in] service The service handle
 436  * @param [in] key The name of the extra data
 437  * @param [in] value The value associated with given key
 438  * @return 0 on success, otherwise a negative error value.
 439  * @retval #SERVICE_ERROR_NONE Successful
 440  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 441  * @retval #SERVICE_ERROR_KEY_REJECTED Not available key
 442  * @see service_add_extra_data_array()
 443  * @see service_remove_extra_data()
 444  * @see service_get_extra_data()
 445  */
 446 int service_add_extra_data(service_h service, const char *key, const char *value);
 447
 448
 449 /**
 450  * @brief Adds the extra data array to the service.
 451  *
 452  * @remarks The function replaces any existing value for the given key.
 453  * @remarks The function returns #SERVICE_ERROR_INVALID_PARAMETER if key is zero-length string.
 454  * @remarks The function returns #SERVICE_ERROR_KEY_REJECTED if the application tries to use same key with system-defined key
 455  * @param [in] service The service handle
 456  * @param [in] key The name of the extra data
 457  * @param [in] value The array value associated with given key
 458  * @param [in] length The length of the array
 459  * @return 0 on success, otherwise a negative error value.
 460  * @retval #SERVICE_ERROR_NONE Successful
 461  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 462  * @retval #SERVICE_ERROR_KEY_REJECTED Not available key
 463  * @see service_add_extra_data()
 464  * @see service_remove_extra_data()
 465  * @see service_get_extra_data()
 466  */
 467 int service_add_extra_data_array(service_h service, const char *key, const char* value[], int length);
 468
 469
 470 /**
 471  * @brief Removes the extra data from the service.
 472  *
 473  * @param [in] service The service handle
 474  * @param [in] key The name of the extra data
 475  * @return 0 on success, otherwise a negative error value.
 476  * @retval #SERVICE_ERROR_NONE Successful
 477  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 478  * @retval #SERVICE_ERROR_KEY_NOT_FOUND Specified key not found
 479  * @see service_add_extra_data()
 480  * @see service_add_extra_data_array()
 481  * @see service_get_extra_data()
 482  */
 483 int service_remove_extra_data(service_h service, const char *key);
 484
 485
 486 /**
 487  * @brief Gets the extra data from the service.
 488  *
 489  * @remarks The @a value must be released with free() by you.
 490  * @remarks The function returns #SERVICE_ERROR_INVALID_DATA_TYPE if the value is array data type.
 491  * @param [in] service The service handle
 492  * @param [int] key The name of the extra data
 493  * @param [out] value The value associated with given key
 494  * @return 0 on success, otherwise a negative error value.
 495  * @retval #SERVICE_ERROR_NONE Successful
 496  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 497  * @retval #SERVICE_ERROR_KEY_NOT_FOUND Specified key not found
 498  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 499  * @retval #SERVICE_ERROR_INVALID_DATA_TYPE Invalid data type
 500  * @see service_add_extra_data()
 501  * @see service_add_extra_data_array()
 502  * @see service_get_extra_data()
 503  * @see service_remove_extra_data()
 504  * @see service_foreach_extra_data()
 505  */
 506 int service_get_extra_data(service_h service, const char *key, char **value);
 507
 508
 509 /**
 510  * @brief Gets the extra data array from the service.
 511  *
 512  * @remarks The @a value must be released with free() by you.
 513  * @remarks The function returns #SERVICE_ERROR_INVALID_DATA_TYPE if the value is not array data type.
 514  * @param [in] service The service handle
 515  * @param [int] key The name of the extra data
 516  * @param [out] value The array value associated with given key
 517  * @param [out] length The length of the array
 518  * @return 0 on success, otherwise a negative error value.
 519  * @retval #SERVICE_ERROR_NONE Successful
 520  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 521  * @retval #SERVICE_ERROR_KEY_NOT_FOUND Specified key not found
 522  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 523  * @retval #SERVICE_ERROR_INVALID_DATA_TYPE Invalid data type
 524  * @see service_add_extra_data()
 525  * @see service_add_extra_data_array()
 526  * @see service_remove_extra_data()
 527  * @see service_foreach_extra_data()
 528  */
 529 int service_get_extra_data_array(service_h service, const char *key, char ***value, int *length);
 530
 531
 532 /**
 533  * @brief Checks whether if the extra data associated with given @a key is array data type.
 534  *
 535  * @param [in] service The service handle
 536  * @param [int] key The name of the extra data
 537  * @param [out] array @c True if the extra data is array data type, otherwise @c false
 538  * @return 0 on success, otherwise a negative error value.
 539  * @retval #SERVICE_ERROR_NONE Successful
 540  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 541  * @see service_add_extra_data()
 542  * @see service_add_extra_data_array()
 543  * @see service_remove_extra_data()
 544  * @see service_foreach_extra_data()
 545  */
 546 int service_is_extra_data_array(service_h service, const char *key, bool *array);
 547
 548
 549 /**
 550  * @brief Retrieves all extra data contained in service.
 551  * @details This function calls service_extra_data_cb() once for each key-value pair for extra data contained in service. \n
 552  * If service_extra_data_cb() callback function returns false, then iteration will be finished.
 553  *
 554  * @param [in] service The service handle
 555  * @param [in] callback The iteration callback function
 556  * @param [in] user_data The user data to be passed to the callback function
 557  * @return 0 on success, otherwise a negative error value.
 558  * @retval #SERVICE_ERROR_NONE Successful
 559  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 560  * @post This function invokes service_extra_data_cb().
 561  * @see service_extra_data_cb()
 562  */
 563 int service_foreach_extra_data(service_h service, service_extra_data_cb callback, void *user_data);
 564
 565
 566 /**
 567  * @brief Retrieves all applications that can be launched to handle the given service request.
 568  *
 569  * @param [in] service The service handle
 570  * @param [in] callback The iteration callback function
 571  * @param [in] user_data The user data to be passed to the callback function
 572  * @return 0 on success, otherwise a negative error value.
 573  * @retval #SERVICE_ERROR_NONE Success
 574  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 575  * @post This function invokes service_app_matched_cb().
 576  * @see service_app_matched_cb()
 577  */
 578 int service_foreach_app_matched(service_h service, service_app_matched_cb callback, void *user_data);
 579
 580
 581 /**
 582  * @brief Sends the launch request.
 583  *
 584  * @details The operation is mandatory information for the launch request. \n
 585  * If the operation is not specified, #SERVICE_OPERATION_DEFAULT is used by default.
 586  * If the operation is #SERVICE_OPERATION_DEFAULT, the application ID is mandatory to explicitly launch the application
 587  * @param [in] service The service handle
 588  * @param [in] callback The callback function to be called when the reply is delivered
 589  * @param [in] user_data The user data to be passed to the callback function
 590  * @return 0 on success, otherwise a negative error value.
 591  * @retval #SERVICE_ERROR_NONE Successful
 592  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 593  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 594  * @retval #SERVICE_ERROR_APP_NOT_FOUND The application was not found to run the given launch request
 595  * @post If the launch request is sent for the result, the result will come back through service_reply_cb() from the callee application
 596  * @see service_reply_to_launch_request()
 597  * @see service_reply_cb()
 598  */
 599 int service_send_launch_request(service_h service, service_reply_cb callback, void *user_data);
 600
 601
 602 /**
 603  * @brief Replies to the launch request that the caller sent
 604  * @details If the caller application sent the launch request to receive the result, the callee application can return the result back to the caller.
 605  *
 606  * @param [in] reply The service handle in which the results of the callee are contained
 607  * @param [in] request The service handle that the caller sent
 608  * @param [in] result  The result code of the launch request
 609  * @return 0 on success, otherwise a negative error value.
 610  * @retval #SERVICE_ERROR_NONE Successful
 611  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 612  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 613  * @see service_send_launch_request()
 614  */
 615 int service_reply_to_launch_request(service_h reply, service_h request, service_result_e result);
 616
 617
 618 /**
 619  * @brief Creates and returns a copy of the given service handle.
 620  *
 621  * @remarks A newly created service should be destroyed by calling service_destroy() if it is no longer needed.
 622  *
 623  * @param [out] clone If successful, a newly created service handle will be returned.
 624  * @param [in] service The service handle
 625  * @return 0 on success, otherwise a negative error value.
 626  * @retval #SERVICE_ERROR_NONE Successful
 627  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 628  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 629  * @see service_destroy()
 630  */
 631 int service_clone(service_h *clone, service_h service);
 632
 633
 634 /**
 635  * @brief Gets the application ID of the caller from the launch request
 636  *
 637  * @remarks The @a service must be the launch reqeust from app_service_cb().
 638  * @remarks This function returns #SERVICE_ERROR_INVALID_PARAMETER if the given service is not the launch request.
 639  * @remarks The @a id must be released with free() by you.
 640  * @param [in] service The service handle from app_service_cb()
 641  * @param [out] id The application ID of the caller
 642  * @return 0 on success, otherwise a negative error value.
 643  * @retval #SERVICE_ERROR_NONE Successful
 644  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 645  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 646  */
 647 int service_get_caller(service_h service, char **id);
 648
 649
 650 /**
 651  * @brief Check whether the caller is requesting a reply from the launch reqeust
 652  *
 653  * @remarks The @a service must be the launch reqeust from app_service_cb().
 654  * @remarks This function returns #SERVICE_ERROR_INVALID_PARAMETER if the given service is not the launch request.
 655  * @param [in] service The service handle from app_service_cb()
 656  * @param [out] requested whether a reply is requested by the caller
 657  * @return 0 on success, otherwise a negative error value.
 658  * @retval #SERVICE_ERROR_NONE Successful
 659  * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 660  * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 661  */
 662 int service_is_reply_requested(service_h service, bool *requested);
 663
 664 /**
 665  * @}
 666  */
 667
 668 #ifdef __cplusplus
 669 }
 670 #endif
 671
 672 #endif /* __TIZEN_APPFW_SERVICE_H__ */