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