Beta release
[framework/api/application.git] / 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 <tizen.h>
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26
27 /**
28  * @addtogroup CAPI_SERVICE_MODULE
29  * @{
30  */
31
32
33 /**
34  * @brief Service handle.
35  */
36 typedef struct service_s *service_h;
37
38
39 /**
40  * @brief Enumerations of error code for Service.
41  */
42 typedef enum
43 {
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 */
51 } service_error_e;
52
53
54 /**
55  * @brief Enumeration of service result.
56  */
57 typedef enum
58 {
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 */
62 } service_result_e;
63
64
65 /**
66  * @brief       Service operation : default operation for explicit launch
67  */
68 #define SERVICE_OPERATION_DEFAULT               "slp.appsvc.operation.DEFAULT"
69
70
71 /**
72  * @brief       Service operation : provide explicit editable access to the given data. 
73  */
74 #define SERVICE_OPERATION_EDIT                  "slp.appsvc.operation.EDIT"
75
76
77 /**
78  * @brief       Service operation : display the data.
79  */
80 #define SERVICE_OPERATION_VIEW                  "slp.appsvc.operation.VIEW"
81
82
83 /**
84  * @brief       Service operation : pick an item from the data, returning what was selected.
85  */
86 #define SERVICE_OPERATION_PICK                  "slp.appsvc.operation.PICK"
87
88
89 /**
90  * @brief       Service operation : create a content, returning what was created.
91  */
92 #define SERVICE_OPERATION_CREATE_CONTENT                "slp.appsvc.operation.CREATE_CONTENT"
93
94
95 /**
96  * @brief       Service operation : perform a call to someone specified by the data.
97  */
98 #define SERVICE_OPERATION_CALL                  "slp.appsvc.operation.CALL"
99
100
101 /**
102  * @brief       Service operation : deliver some data to someone else.
103  */
104 #define SERVICE_OPERATION_SEND                  "slp.appsvc.operation.SEND"
105
106
107 /**
108  * @brief       Service operation : deliver text data to someone else.
109  */
110 #define SERVICE_OPERATION_SEND_TEXT             "slp.appsvc.operation.SEND_TEXT"
111
112
113 /**
114  * @brief       Service operation : dial a number as specified by the data.
115  */
116 #define SERVICE_OPERATION_DIAL                  "slp.appsvc.operation.DIAL"
117
118
119 /**
120  * @brief       Service operation : perform a search. 
121  */
122 #define SERVICE_OPERATION_SEARCH                        "slp.appsvc.operation.SEARCH"
123
124
125 /**
126  * @brief       Service optional data : the subject of a message.
127  */
128 #define SERVICE_DATA_SUBJECT            "slp.appsvc.data.SUBJECT"
129
130
131 /**
132  * @brief       Service optional data : e-mail addresses.
133  */
134 #define SERVICE_DATA_TO                 "slp.appsvc.data.TO"
135
136
137 /**
138  * @brief       Service optional data : e-mail addresses that should be carbon copied.
139  */
140 #define SERVICE_DATA_CC                 "slp.appsvc.data.CC"
141
142
143 /**
144  * @brief       Service optional data : e-mail addresses that should be blind carbon copied.
145  */
146 #define SERVICE_DATA_BCC                        "slp.appsvc.data.BCC"
147
148
149 /**
150  * @brief       Service optional data : the content of the data is associated with #SERVICE_OPERATION_SEND.
151  */
152 #define SERVICE_DATA_TEXT               "slp.appsvc.data.TEXT"
153
154
155 /**
156  * @brief       Service optional data : the title of the data
157  */
158 #define SERVICE_DATA_TITLE              "slp.appsvc.data.TITLE"
159
160
161 /**
162  * @brief       Service optional data : the path of selected item.
163  */
164 #define SERVICE_DATA_SELECTED           "slp.appsvc.data.SELECTED"
165
166
167 /**
168  * @brief   Called when the reply of the launch request is delivered.
169  *
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()
177  */
178 typedef void (*service_reply_cb) (service_h request, service_h reply, service_result_e result, void *user_data);
179
180
181 /**
182 * @brief   Called to retrieve the extra data that are contained in the service
183 *
184 * @remarks The @a key must not be deallocated by an application. 
185 *
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()
192 */
193 typedef bool (*service_extra_data_cb)(service_h service, const char *key, void *user_data);
194
195
196 /**
197 * @brief   Called once for each matched application that can be launched to handle the given service request.
198 *
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()
205 */
206 typedef bool (*service_app_matched_cb)(service_h service, const char *package, void *user_data);
207
208
209 /**
210  * @brief Creates a service handle.
211  *
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()
219  */
220 int service_create(service_h *service);
221
222
223 /**
224  * @brief Destroys the service handle and releases all its resources.
225  *
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()
232  */
233 int service_destroy(service_h service);
234
235
236 /**
237  * @brief Sets the operation to be performed.
238  *
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
259  */
260 int service_set_operation(service_h service, const char *operation);
261
262
263 /**
264  * @brief Gets the operation to be performed.
265  *
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()
274  */
275 int service_get_operation(service_h service, char **operation);
276
277
278 /**
279  * @brief Sets the URI of the data.
280  *
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()
288  */
289 int service_set_uri(service_h service, const char *uri);
290
291
292 /**
293  * @brief Gets the URI of the data.
294  *
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()
303  */
304 int service_get_uri(service_h service, char **uri);
305
306
307 /**
308  * @brief Sets the explicit MIME type of the data
309  *
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()
317  */
318 int service_set_mime(service_h service, const char *mime);
319
320
321 /**
322  * @brief Gets the explicit MIME type of the data.
323  *
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()
332  */
333 int service_get_mime(service_h service, char **uri);
334
335
336 /**
337  * @brief Sets the package name of the application to explicitly launch
338  *
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()
347  */
348 int service_set_package(service_h service, const char *package);
349
350
351 /**
352  * @brief Gets the package name of the application to explicitly launch
353  *
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()
362  */
363 int service_get_package(service_h service, char **package);
364
365
366 /**
367  * @brief Adds the extra data to the service.
368  *
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()
382  */
383 int service_add_extra_data(service_h service, const char *key, const char *value);
384
385
386 /**
387  * @brief Adds the extra data array to the service.
388  *
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()
403  */
404 int service_add_extra_data_array(service_h service, const char *key, const char* value[], int length);
405
406
407 /**
408  * @brief Removes the extra data from the service.
409  *
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()
419  */
420 int service_remove_extra_data(service_h service, const char *key);
421
422
423 /**
424  * @brief Gets the extra data from the service.
425  *
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()
442  */
443 int service_get_extra_data(service_h service, const char *key, char **value);
444
445
446 /**
447  * @brief Gets the extra data array from the service.
448  *
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()
465  */
466 int service_get_extra_data_array(service_h service, const char *key, char ***value, int *length);
467
468
469 /**
470  * @brief Checks whether if the extra data associated with given @a key is array data type.
471  *
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()
482  */
483 int service_is_extra_data_array(service_h service, const char *key, bool *array);
484
485
486 /**
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.
490  *
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()
499  */
500 int service_foreach_extra_data(service_h service, service_extra_data_cb callback, void *user_data);
501
502
503 /**
504  * @brief Retrieves all applications that can be launched to handle the given service request.
505  *
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()
514  */
515 int service_foreach_app_matched(service_h service, service_app_matched_cb callback, void *user_data);
516
517
518 /**
519  * @brief Sends the launch request.
520  *
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()
535  */
536 int service_send_launch_request(service_h service, service_reply_cb callback, void *user_data);
537
538
539 /**
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.
542  *
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()
551  */
552 int service_reply_to_launch_request(service_h reply, service_h request, service_result_e result);
553
554
555 /**
556  * @brief Creates and returns a copy of the given service handle.
557  *
558  * @remarks A newly created service should be destroyed by calling service_destroy() if it is no longer needed.
559  *
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()
567  */
568 int service_clone(service_h *clone, service_h service);
569
570
571
572 /**
573  * @}
574  */
575
576 #ifdef __cplusplus
577 }
578 #endif
579
580 #endif /* __TIZEN_APPFW_SERVICE_H__ */