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