2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef __TIZEN_APPFW_SERVICE_H__
19 #define __TIZEN_APPFW_SERVICE_H__
28 * @addtogroup CAPI_SERVICE_MODULE
34 * @brief Service handle.
36 typedef struct service_s *service_h;
40 * @brief Enumerations of error code for Service.
44 SERVICE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
45 SERVICE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
46 SERVICE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
47 SERVICE_ERROR_APP_NOT_FOUND = TIZEN_ERROR_APPLICATION_CLASS | 0x21, /**< The application was not found */
48 SERVICE_ERROR_KEY_NOT_FOUND = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Specified key not found */
49 SERVICE_ERROR_KEY_REJECTED = TIZEN_ERROR_KEY_REJECTED, /**< Not available key */
50 SERVICE_ERROR_INVALID_DATA_TYPE = TIZEN_ERROR_APPLICATION_CLASS | 0x22, /**< Invalid data type */
55 * @brief Enumeration of service result.
59 SERVICE_RESULT_SUCCEEDED = 0, /**< Operation succeeded */
60 SERVICE_RESULT_FAILED = -1, /**< Operation failed by the callee */
61 SERVICE_RESULT_CANCELED = -2, /**< Operation canceled by the framework */
66 * @brief Service operation : default operation for explicit launch
68 #define SERVICE_OPERATION_DEFAULT "slp.appsvc.operation.DEFAULT"
72 * @brief Service operation : provide explicit editable access to the given data.
74 #define SERVICE_OPERATION_EDIT "slp.appsvc.operation.EDIT"
78 * @brief Service operation : display the data.
80 #define SERVICE_OPERATION_VIEW "slp.appsvc.operation.VIEW"
84 * @brief Service operation : pick an item from the data, returning what was selected.
86 #define SERVICE_OPERATION_PICK "slp.appsvc.operation.PICK"
90 * @brief Service operation : create a content, returning what was created.
92 #define SERVICE_OPERATION_CREATE_CONTENT "slp.appsvc.operation.CREATE_CONTENT"
96 * @brief Service operation : perform a call to someone specified by the data.
98 #define SERVICE_OPERATION_CALL "slp.appsvc.operation.CALL"
102 * @brief Service operation : deliver some data to someone else.
104 #define SERVICE_OPERATION_SEND "slp.appsvc.operation.SEND"
108 * @brief Service operation : deliver text data to someone else.
110 #define SERVICE_OPERATION_SEND_TEXT "slp.appsvc.operation.SEND_TEXT"
114 * @brief Service operation : dial a number as specified by the data.
116 #define SERVICE_OPERATION_DIAL "slp.appsvc.operation.DIAL"
120 * @brief Service operation : perform a search.
122 #define SERVICE_OPERATION_SEARCH "slp.appsvc.operation.SEARCH"
126 * @brief Service optional data : the subject of a message.
128 #define SERVICE_DATA_SUBJECT "slp.appsvc.data.SUBJECT"
132 * @brief Service optional data : e-mail addresses.
134 #define SERVICE_DATA_TO "slp.appsvc.data.TO"
138 * @brief Service optional data : e-mail addresses that should be carbon copied.
140 #define SERVICE_DATA_CC "slp.appsvc.data.CC"
144 * @brief Service optional data : e-mail addresses that should be blind carbon copied.
146 #define SERVICE_DATA_BCC "slp.appsvc.data.BCC"
150 * @brief Service optional data : the content of the data is associated with #SERVICE_OPERATION_SEND.
152 #define SERVICE_DATA_TEXT "slp.appsvc.data.TEXT"
156 * @brief Service optional data : the title of the data
158 #define SERVICE_DATA_TITLE "slp.appsvc.data.TITLE"
162 * @brief Service optional data : the path of selected item.
164 #define SERVICE_DATA_SELECTED "slp.appsvc.data.SELECTED"
168 * @brief Called when the reply of the launch request is delivered.
170 * @param [in] request The service handle of the launch request that has sent
171 * @param [in] reply The service handle in which the results of the callee are contained
172 * @param [in] result The result code of the launch request
173 * @param [in] user_data The user data passed from the callback registration function
174 * @pre When the callee replies to the launch request, this callback will be invoked.
175 * @see service_send_launch_request()
176 * @see service_reply_to_launch_request()
178 typedef void (*service_reply_cb) (service_h request, service_h reply, service_result_e result, void *user_data);
182 * @brief Called to retrieve the extra data that are contained in the service
184 * @remarks The @a key must not be deallocated by an application.
186 * @param[in] service The service handle
187 * @param[in] key The key of the value contained in the service
188 * @param[in] user_data The user data passed from the foreach function
189 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
190 * @pre service_foreach_extra_data() will invoke this callback.
191 * @see service_foreach_extra_data()
193 typedef bool (*service_extra_data_cb)(service_h service, const char *key, void *user_data);
197 * @brief Called once for each matched application that can be launched to handle the given service request.
199 * @param [in] service The service handle
200 * @param [in] package The package name of the application that can handle the launch request of the given service.
201 * @param [in] user_data The user data passed from the foreach function
202 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
203 * @pre service_foreach_app_matched() will invoke this callback.
204 * @see service_foreach_app_matched()
206 typedef bool (*service_app_matched_cb)(service_h service, const char *package, void *user_data);
210 * @brief Creates a service handle.
212 * @remarks The @a service must be released with service_destroy() by you.
213 * @param [out] service A service handle to be newly created on success
214 * @return 0 on success, otherwise a negative error value.
215 * @retval #SERVICE_ERROR_NONE Successful
216 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
217 * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
218 * @see service_destroy()
220 int service_create(service_h *service);
224 * @brief Destroys the service handle and releases all its resources.
226 * @param [in] service The service handle
227 * @return 0 on success, otherwise a negative error value.
228 * @retval #SERVICE_ERROR_NONE Successful
229 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
230 * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
231 * @see service_create()
233 int service_destroy(service_h service);
237 * @brief Sets the operation to be performed.
239 * @details The @a operation is the mandatory information for the launch request.
240 * If the operation is not specified, #SERVICE_OPERATION_DEFAULT is used for the launch request.
241 * If the operation is #SERVICE_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application
242 * @param [in] service The service handle
243 * @param [in] operation The operation to be performed \n
244 * If the @a operation is NULL, it clears the previous value.
245 * @return 0 on success, otherwise a negative error value.
246 * @retval #SERVICE_ERROR_NONE Successful
247 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
248 * @see service_get_operation()
249 * @see SERVICE_OPERATION_DEFAULT
250 * @see SERVICE_OPERATION_EDIT
251 * @see SERVICE_OPERATION_VIEW
252 * @see SERVICE_OPERATION_PICK
253 * @see SERVICE_OPERATION_CREATE_CONTENT
254 * @see SERVICE_OPERATION_CALL
255 * @see SERVICE_OPERATION_SEND
256 * @see SERVICE_OPERATION_SEND_TEXT
257 * @see SERVICE_OPERATION_DIAL
258 * @see SERVICE_OPERATION_SEARCH
260 int service_set_operation(service_h service, const char *operation);
264 * @brief Gets the operation to be performed.
266 * @remarks The @a operation must be released with free() by you.
267 * @param [in] service The service handle
268 * @param [out] operation The operation to be performed
269 * @return 0 on success, otherwise a negative error value.
270 * @retval #SERVICE_ERROR_NONE Successful
271 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
272 * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
273 * @see service_set_operation()
275 int service_get_operation(service_h service, char **operation);
279 * @brief Sets the URI of the data.
281 * @param [in] service The service handle
282 * @param [in] uri The URI of the data this service is operating on \n
283 * If the @a uri is NULL, it clears the previous value.
284 * @return 0 on success, otherwise a negative error value.
285 * @retval #SERVICE_ERROR_NONE Successful
286 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
287 * @see service_get_uri()
289 int service_set_uri(service_h service, const char *uri);
293 * @brief Gets the URI of the data.
295 * @remarks The @a uri must be released with free() by you.
296 * @param [in] service The service handle
297 * @param [out] uri The URI of the data this service is operating on
298 * @return 0 on success, otherwise a negative error value.
299 * @retval #SERVICE_ERROR_NONE Successful
300 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
301 * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
302 * @see service_set_uri()
304 int service_get_uri(service_h service, char **uri);
308 * @brief Sets the explicit MIME type of the data
310 * @param [in] service The service handle
311 * @param [in] mime the explicit MIME type of the data this service is operating on \n
312 * If the @a mime is NULL, it clears the previous value.
313 * @return 0 on success, otherwise a negative error value.
314 * @retval #SERVICE_ERROR_NONE Successful
315 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
316 * @see service_get_mime()
318 int service_set_mime(service_h service, const char *mime);
322 * @brief Gets the explicit MIME type of the data.
324 * @remarks The @a uri must be released with free() by you.
325 * @param [in] service The service handle
326 * @param [out] mime The explicit MIME type of the data this service is operating on
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_mime()
333 int service_get_mime(service_h service, char **uri);
337 * @brief Sets the package name of the application to explicitly launch
339 * @param [in] service The service handle
340 * @param [in] package The package name of the application to explicitly launch \n
341 * If the @a package 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 * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
346 * @see service_get_package()
348 int service_set_package(service_h service, const char *package);
352 * @brief Gets the package name of the application to explicitly launch
354 * @remarks The @a package must be released with free() by you.
355 * @param [in] service The service handle
356 * @param [out] package The package name of the application to explicitly launch
357 * @return 0 on success, otherwise a negative error value.
358 * @retval #SERVICE_ERROR_NONE Successful
359 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
360 * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
361 * @see service_set_package()
363 int service_get_package(service_h service, char **package);
367 * @brief Adds the extra data to the service.
369 * @remarks The function replaces any existing value for the given key.
370 * @remarks The function returns #SERVICE_ERROR_INVALID_PARAMETER if key or value is zero-length string.
371 * @remarks The function returns #SERVICE_ERROR_KEY_REJECTED if the application tries to use same key with system-defined key
372 * @param [in] service The service handle
373 * @param [in] key The name of the extra data
374 * @param [in] value The value associated with given key
375 * @return 0 on success, otherwise a negative error value.
376 * @retval #SERVICE_ERROR_NONE Successful
377 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
378 * @retval #SERVICE_ERROR_KEY_REJECTED Not available key
379 * @see service_add_extra_data_array()
380 * @see service_remove_extra_data()
381 * @see service_get_extra_data()
383 int service_add_extra_data(service_h service, const char *key, const char *value);
387 * @brief Adds the extra data array to the service.
389 * @remarks The function replaces any existing value for the given key.
390 * @remarks The function returns #SERVICE_ERROR_INVALID_PARAMETER if key is zero-length string.
391 * @remarks The function returns #SERVICE_ERROR_KEY_REJECTED if the application tries to use same key with system-defined key
392 * @param [in] service The service handle
393 * @param [in] key The name of the extra data
394 * @param [in] value The array value associated with given key
395 * @param [in] length The length of the array
396 * @return 0 on success, otherwise a negative error value.
397 * @retval #SERVICE_ERROR_NONE Successful
398 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
399 * @retval #SERVICE_ERROR_KEY_REJECTED Not available key
400 * @see service_add_extra_data()
401 * @see service_remove_extra_data()
402 * @see service_get_extra_data()
404 int service_add_extra_data_array(service_h service, const char *key, const char* value[], int length);
408 * @brief Removes the extra data from the service.
410 * @param [in] service The service handle
411 * @param [in] key The name of the extra data
412 * @return 0 on success, otherwise a negative error value.
413 * @retval #SERVICE_ERROR_NONE Successful
414 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
415 * @retval #SERVICE_ERROR_KEY_NOT_FOUND Specified key not found
416 * @see service_add_extra_data()
417 * @see service_add_extra_data_array()
418 * @see service_get_extra_data()
420 int service_remove_extra_data(service_h service, const char *key);
424 * @brief Gets the extra data from the service.
426 * @remarks The @a value must be released with free() by you.
427 * @remarks The function returns #SERVICE_ERROR_INVALID_DATA_TYPE if the value is array data type.
428 * @param [in] service The service handle
429 * @param [int] key The name of the extra data
430 * @param [out] value The value associated with given key
431 * @return 0 on success, otherwise a negative error value.
432 * @retval #SERVICE_ERROR_NONE Successful
433 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
434 * @retval #SERVICE_ERROR_KEY_NOT_FOUND Specified key not found
435 * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
436 * @retval #SERVICE_ERROR_INVALID_DATA_TYPE Invalid data type
437 * @see service_add_extra_data()
438 * @see service_add_extra_data_array()
439 * @see service_get_extra_data()
440 * @see service_remove_extra_data()
441 * @see service_foreach_extra_data()
443 int service_get_extra_data(service_h service, const char *key, char **value);
447 * @brief Gets the extra data array from the service.
449 * @remarks The @a value must be released with free() by you.
450 * @remarks The function returns #SERVICE_ERROR_INVALID_DATA_TYPE if the value is not array data type.
451 * @param [in] service The service handle
452 * @param [int] key The name of the extra data
453 * @param [out] value The array value associated with given key
454 * @param [out] length The length of the array
455 * @return 0 on success, otherwise a negative error value.
456 * @retval #SERVICE_ERROR_NONE Successful
457 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
458 * @retval #SERVICE_ERROR_KEY_NOT_FOUND Specified key not found
459 * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
460 * @retval #SERVICE_ERROR_INVALID_DATA_TYPE Invalid data type
461 * @see service_add_extra_data()
462 * @see service_add_extra_data_array()
463 * @see service_remove_extra_data()
464 * @see service_foreach_extra_data()
466 int service_get_extra_data_array(service_h service, const char *key, char ***value, int *length);
470 * @brief Checks whether if the extra data associated with given @a key is array data type.
472 * @param [in] service The service handle
473 * @param [int] key The name of the extra data
474 * @param [out] array @c True if the extra data is array data type, otherwise @c false
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 * @see service_add_extra_data()
479 * @see service_add_extra_data_array()
480 * @see service_remove_extra_data()
481 * @see service_foreach_extra_data()
483 int service_is_extra_data_array(service_h service, const char *key, bool *array);
487 * @brief Retrieves all extra data contained in service.
488 * @details This function calls service_extra_data_cb() once for each key-value pair for extra data contained in service. \n
489 * If service_extra_data_cb() callback function returns false, then iteration will be finished.
491 * @param [in] service The service handle
492 * @param [in] callback The iteration callback function
493 * @param [in] user_data The user data to be passed to the callback function
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 * @post This function invokes service_extra_data_cb().
498 * @see service_extra_data_cb()
500 int service_foreach_extra_data(service_h service, service_extra_data_cb callback, void *user_data);
504 * @brief Retrieves all applications that can be launched to handle the given service request.
506 * @param [in] service The service handle
507 * @param [in] callback The iteration callback function
508 * @param [in] user_data The user data to be passed to the callback function
509 * @return 0 on success, otherwise a negative error value.
510 * @retval #SERVICE_ERROR_NONE Success
511 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
512 * @post This function invokes service_app_matched_cb().
513 * @see service_app_matched_cb()
515 int service_foreach_app_matched(service_h service, service_app_matched_cb callback, void *user_data);
519 * @brief Sends the launch request.
521 * @details The operation is mandatory information for the launch request. \n
522 * If the operation is not specified, #SERVICE_OPERATION_DEFAULT is used by default.
523 * If the operation is #SERVICE_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application
524 * @param [in] service The service handle
525 * @param [in] callback The callback function to be called when the reply is delivered
526 * @param [in] user_data The user data to be passed to the callback function
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_OUT_OF_MEMORY Out of memory
531 * @retval #SERVICE_ERROR_APP_NOT_FOUND The application was not found to run the given launch request
532 * @post If the launch request is sent for the result, the result will come back through service_reply_cb() from the callee application
533 * @see service_reply_to_launch_request()
534 * @see service_reply_cb()
536 int service_send_launch_request(service_h service, service_reply_cb callback, void *user_data);
540 * @brief Replies to the launch request that the caller sent
541 * @details If the caller application sent the launch request to receive the result, the callee application can return the result back to the caller.
543 * @param [in] reply The service handle in which the results of the callee are contained
544 * @param [in] request The service handle that the caller sent
545 * @param [in] result The result code of the launch request
546 * @return 0 on success, otherwise a negative error value.
547 * @retval #SERVICE_ERROR_NONE Successful
548 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
549 * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
550 * @see service_send_launch_request()
552 int service_reply_to_launch_request(service_h reply, service_h request, service_result_e result);
556 * @brief Creates and returns a copy of the given service handle.
558 * @remarks A newly created service should be destroyed by calling service_destroy() if it is no longer needed.
560 * @param [out] clone If successful, a newly created service handle will be returned.
561 * @param [in] service The service handle
562 * @return 0 on success, otherwise a negative error value.
563 * @retval #SERVICE_ERROR_NONE Successful
564 * @retval #SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
565 * @retval #SERVICE_ERROR_OUT_OF_MEMORY Out of memory
566 * @see service_destroy()
568 int service_clone(service_h *clone, service_h service);
580 #endif /* __TIZEN_APPFW_SERVICE_H__ */