upload tizen1.0 source
[platform/core/appfw/app-svc.git] / include / appsvc.h
1 /*
2  *  app-svc
3  *
4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
5  *
6  * Contact: Jayoun Lee <airjany@samsung.com>, Sewook Park <sewook7.park@samsung.com>, Jaeho Lee <jaeho81.lee@samsung.com>
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  *
20  */
21
22
23
24 #ifndef __APP_SVC_H__
25 #define __APP_SVC_H__
26
27 /**
28  * @file    appsvc.h
29  * @version 1.1
30  * @brief   This file contains APIs of the appsvc library
31  */
32
33 /**
34  * @addtogroup APPLICATION_FRAMEWORK
35  * @{
36  *
37  * @defgroup appsvc Application Service
38  * @version  1.1
39  * @brief    Application Service library
40  *
41  */
42
43 /**
44  * @addtogroup appsvc
45  * @{
46  */
47
48
49 #include <bundle.h>
50
51 #ifdef __cplusplus
52 extern "C" {
53 #endif
54
55
56 /** APP_SVC OPERATION TYPE*/
57 #define APPSVC_OPERATION_DEFAULT                "http://tizen.org/appsvc/operation/default"
58 /** APP_SVC OPERATION TYPE*/
59 #define APPSVC_OPERATION_EDIT                   "http://tizen.org/appsvc/operation/edit"
60 /** APP_SVC OPERATION TYPE*/
61 #define APPSVC_OPERATION_VIEW                   "http://tizen.org/appsvc/operation/view"
62 /** APP_SVC OPERATION TYPE*/
63 #define APPSVC_OPERATION_PICK                   "http://tizen.org/appsvc/operation/pick"
64 /** APP_SVC OPERATION TYPE*/
65 #define APPSVC_OPERATION_CREATE_CONTENT         "http://tizen.org/appsvc/operation/create_content"
66 /** APP_SVC OPERATION TYPE*/
67 #define APPSVC_OPERATION_CALL                   "http://tizen.org/appsvc/operation/call"
68 /** APP_SVC OPERATION TYPE*/
69 #define APPSVC_OPERATION_SEND                   "http://tizen.org/appsvc/operation/send"
70 /** APP_SVC OPERATION TYPE*/
71 #define APPSVC_OPERATION_SEND_TEXT              "http://tizen.org/appsvc/operation/send_text"
72 /** APP_SVC OPERATION TYPE*/
73 #define APPSVC_OPERATION_DIAL                   "http://tizen.org/appsvc/operation/dial"
74 /** APP_SVC OPERATION TYPE*/
75 #define APPSVC_OPERATION_SEARCH                 "http://tizen.org/appsvc/operation/search"
76 /** APP_SVC OPERATION TYPE*/
77 #define APPSVC_OPERATION_DOWNLOAD               "http://tizen.org/appsvc/operation/download"
78
79
80 /** APP_SVC DATA SUBJECT*/
81 #define APPSVC_DATA_SUBJECT             "http://tizen.org/appsvc/data/subject"
82 /** APP_SVC DATA TYPE*/
83 #define APPSVC_DATA_TO                  "http://tizen.org/appsvc/data/to"
84 /** APP_SVC DATA TYPE*/
85 #define APPSVC_DATA_CC                  "http://tizen.org/appsvc/data/cc"
86 /** APP_SVC DATA TYPE*/
87 #define APPSVC_DATA_BCC                 "http://tizen.org/appsvc/data/bcc"
88 /** APP_SVC DATA TYPE*/
89 #define APPSVC_DATA_TEXT                "http://tizen.org/appsvc/data/text"
90 /** APP_SVC DATA TYPE*/
91 #define APPSVC_DATA_TITLE               "http://tizen.org/appsvc/data/title"
92 /** APP_SVC DATA TYPE*/
93 #define APPSVC_DATA_SELECTED            "http://tizen.org/appsvc/data/selected"
94 /** APP_SVC DATA TYPE*/
95 #define APPSVC_DATA_KEYWORD             "http://tizen.org/appsvc/data/keyword"
96
97
98 /**
99  * @brief Return values in appsvc. 
100  */
101 typedef enum _appsvc_return_val {
102         APPSVC_RET_ELAUNCH = -4,                /**< Failure on launching the app */
103         APPSVC_RET_ENOMATCH = -3,               /**< No matching result Error */
104         APPSVC_RET_EINVAL = -2,                 /**< Invalid argument */
105         APPSVC_RET_ERROR = -1,                  /**< General error */
106         APPSVC_RET_OK = 0                       /**< General success */
107 }appsvc_return_val;
108
109
110 /**
111  * @brief result values in appsvc. 
112  */
113 typedef enum _appsvc_result_val {
114         APPSVC_RES_CANCEL = -2,         /**< Cancel by system */
115         APPSVC_RES_NOT_OK = -1,         /**< Fail by user */
116         APPSVC_RES_OK = 0               /**< Success by user */
117 }appsvc_result_val;
118
119
120 /** 
121  * @brief appsvc_res_fn is appsvc result function
122  * @param[out]  b               result bundle   
123  * @param[out]  request_code    request code
124  * @param[out]  result                  result value
125  * @param[out]  data            user-supplied data      
126 */
127 typedef void (*appsvc_res_fn)(bundle *b, int request_code, appsvc_result_val result, void *data);
128
129
130 /** 
131  * @brief iterator function running with appsvc_get_list 
132  * @param[out]  pkg_name        package name retreived by appsvc_get_list
133  * @param[out]  data            user-supplied data      
134 */
135 typedef int (*appsvc_info_iter_fn)(const char *pkg_name, void *data);
136
137
138 /**
139  * @par Description:
140  * This function sets an operation to launch application based on appsvc.
141  *
142  * @param[in] b bundle object 
143  * @param[in] operation operation 
144  *
145  * @return 0 if success, negative value(<0) if fail
146  * @retval APPSVC_RET_OK - success
147  * @retval APPSVC_RET_ERROR - general error 
148  * @retval APPSVC_RET_EINVAL - invalid argument(content)
149  *
150  * @pre None.
151  * @post None.
152  * @see None.
153  * @remarks An application must call this function before using appsvc_run_service API. 
154  *
155  * @par Sample code:
156  * @code
157 #include <appsvc.h>
158
159 ...
160 {
161         bundle *b = NULL;
162
163         b = bundle_create();
164         
165         appsvc_set_operation(b, APPSVC_OPERATION_VIEW);
166 }
167  * @endcode
168  *
169  */
170 int appsvc_set_operation(bundle *b, const char *operation);
171
172 /**
173  * @par Description:
174  * This function sets an uri to launch application based on appsvc.
175  *
176  * @param[in] b bundle object 
177  * @param[in] uri uri 
178  *
179  * @return 0 if success, negative value(<0) if fail
180  * @retval APPSVC_RET_OK - success
181  * @retval APPSVC_RET_ERROR - general error 
182  * @retval APPSVC_RET_EINVAL - invalid argument(content)
183  *
184  * @pre None.
185  * @post None.
186  * @see None.
187  * @remarks None. 
188  *
189  * @par Sample code:
190  * @code
191 #include <appsvc.h>
192
193 ...
194 {
195         bundle *b = NULL;
196
197         b = bundle_create();
198         
199         appsvc_set_operation(b, APPSVC_OPERATION_VIEW);
200         appsvc_set_uri(b,"http://www.samsung.com");
201 }
202  * @endcode
203  *
204  */
205 int appsvc_set_uri(bundle *b, const char *uri);
206
207 /**
208  * @par Description:
209  * This function sets a mime-type to launch application based on appsvc.
210  *
211  * @param[in] b bundle object 
212  * @param[in] mime mime-type 
213  *
214  * @return 0 if success, negative value(<0) if fail
215  * @retval APPSVC_RET_OK - success
216  * @retval APPSVC_RET_ERROR - general error 
217  * @retval APPSVC_RET_EINVAL - invalid argument(content)
218  *
219  * @pre None.
220  * @post None.
221  * @see None.
222  * @remarks None. 
223  *
224  * @par Sample code:
225  * @code
226 #include <appsvc.h>
227
228 ...
229 {
230         bundle *b = NULL;
231
232         b = bundle_create();
233         
234         appsvc_set_operation(b, APPSVC_OPERATION_PICK);
235         appsvc_set_mime(b,"image/jpg");
236 }
237  * @endcode
238  *
239  */
240 int appsvc_set_mime(bundle *b, const char *mime);
241
242 /**
243  * @par Description:
244  * This function sets an extra data to launch application based on appsvc.
245  *
246  * @param[in] b bundle object 
247  * @param[in] key key of extra data 
248  * @param[in] val data 
249  *
250  * @return 0 if success, negative value(<0) if fail
251  *
252  * @pre None.
253  * @post None.
254  * @see None.
255  * @remarks None. 
256  *
257  * @par Sample code:
258  * @code
259 #include <appsvc.h>
260
261 ...
262 {
263         bundle *b = NULL;
264
265         b = bundle_create();
266         
267         appsvc_set_operation(b, APPSVC_OPERATION_SEND);
268         appsvc_set_uri(b,"mailto:xxx1@xxx");
269         appsvc_add_data(b,APPSVC_DATA_CC,"xxx2@xxx");
270 }
271  * @endcode
272  *
273  */
274 int appsvc_add_data(bundle *b, const char *key, const char *val);
275
276 /**
277  * @par Description:
278  * This function sets an extra array data to launch application based on appsvc.
279  *
280  * @param[in] b bundle object 
281  * @param[in] key key of extra data 
282  * @param[in] val_array data 
283  * @param[in] len Length of array
284  *
285  * @return 0 if success, negative value(<0) if fail
286  *
287  * @pre None.
288  * @post None.
289  * @see None.
290  * @remarks None. 
291  *
292  * @par Sample code:
293  * @code
294 #include <appsvc.h>
295
296 ...
297 {
298         bundle *b = NULL;
299         char *images[] = {"/opt/media/a.jpg", "/opt/media/b.jpg", "/opt/media/c.jpg"};
300
301         b = bundle_create();
302
303         appsvc_add_data_array(b, APPSVC_DATA_SELECTED, images, 3);
304 }
305  * @endcode
306  *
307  */
308 int appsvc_add_data_array(bundle *b, const char *key, const char **val_array, int len);
309
310
311 /**
312  * @par Description:
313  * This function sets a package name to launch application based on appsvc.
314  *
315  * @param[in] b bundle object 
316  * @param[in] pkg_name package name for explict launch
317  *
318  * @return 0 if success, negative value(<0) if fail
319  * @retval APPSVC_RET_OK - success
320  * @retval APPSVC_RET_ERROR - general error 
321  * @retval APPSVC_RET_EINVAL - invalid argument(content)
322  *
323  * @pre None.
324  * @post None.
325  * @see None.
326  * @remarks None. 
327  *
328  * @par Sample code:
329  * @code
330 #include <appsvc.h>
331
332 ...
333 {
334         bundle *b = NULL;
335
336         b = bundle_create();
337         
338         appsvc_set_operation(b, APPSVC_OPERATION_PICK);
339         appsvc_set_mime(b,"image/jpg");
340         appsvc_set_pkgname(b, "org.tizen.mygallery");
341 }
342  * @endcode
343  *
344  */
345 int appsvc_set_pkgname(bundle *b, const char *pkg_name);
346
347 /**
348  * @par Description:
349  * This API launch application based on appsvc.
350  *
351  * @param[in] b bundle to be passed to callee
352  * @param[in] request_code request code
353  * @param[in] cbfunc result callback function
354  * @param[in] data user-supplied data passed to callback function
355  *
356  * @return callee's pid if success, negative value(<0) if fail
357  * @retval callee's pid - success
358  * @retval APPSVC_RET_ERROR - general error 
359  * @retval APPSVC_RET_EINVAL - invalid argument(content)
360  * @retval APPSVC_RET_ENOMATCH - no matching result Error 
361  * @retval APPSVC_RET_ELAUNCH - failure on launching the app
362  *
363  * @pre None.
364  * @post None.
365  * @see None.
366  * @remarks None. 
367  *
368  * @par Sample code:
369  * @code
370 #include <appsvc.h>
371
372 ...
373 {
374         bundle *b = NULL;
375         static int num = 0;
376
377         b = bundle_create();
378         
379         appsvc_set_operation(b, APPSVC_OPERATION_PICK);
380         appsvc_set_mime(b,"image/jpg");
381
382         return appsvc_run_service(b, 0, cb_func, (void*)NULL);
383 }
384  * @endcode
385  *
386  */
387 int appsvc_run_service(bundle *b, int request_code, appsvc_res_fn cbfunc, void *data);
388
389 /**
390  * @par Description:
391  * This API use to get application list that is matched with given bundle.
392  *
393  * @param[in] b bundle to resolve application
394  * @param[in] iter_fn iterator function
395  * @param[in] data user-supplied data for iter_fn
396  *
397  * @return 0 if success, negative value(<0) if fail
398  * @retval APPSVC_RET_OK - success
399  * @retval APPSVC_RET_EINVAL - invalid argument(content)
400  * @retval APPSVC_RET_ENOMATCH - no matching result Error 
401  *
402  * @pre None.
403  * @post None.
404  * @see None.
405  * @remarks None. 
406  *
407  * @par Sample code:
408  * @code
409 #include <appsvc.h>
410
411 static int iter_fn(const char* pkg_name, void *data)
412 {
413         printf("\t==========================\n");
414         printf("\t pkg_name: %s\n", pkg_name);
415         printf("\t==========================\n");
416         return 0;
417 }
418
419 ...
420 {
421         bundle *b = NULL;
422         static int num = 0;
423
424         b = bundle_create();
425         
426         appsvc_set_operation(b, APPSVC_OPERATION_PICK);
427         appsvc_set_mime(b,"image/jpg");
428
429         return appsvc_get_list(b, iter_fn, (void*)NULL);
430 }
431  * @endcode
432  *
433  */
434 int appsvc_get_list(bundle *b, appsvc_info_iter_fn iter_fn, void *data);
435
436 /**
437  * @par Description:
438  * This function gets a operation from bundle.
439  *
440  * @param[in] b bundle object 
441  *
442  * @return Pointer for operation string if success, NULL if fail
443  *
444  * @pre None.
445  * @post None.
446  * @see None.
447  * @remarks None. 
448  *
449  * @par Sample code:
450  * @code
451 #include <appsvc.h>
452
453 ...
454 {
455         char *val;      
456         val = appsvc_get_operation(b);
457 }
458  * @endcode
459  *
460  */
461 const char *appsvc_get_operation(bundle *b);
462
463 /**
464  * @par Description:
465  * This function gets a uri from bundle.
466  *
467  * @param[in] b bundle object 
468  *
469  * @return Pointer for uri string if success, NULL if fail
470  *
471  * @pre None.
472  * @post None.
473  * @see None.
474  * @remarks None. 
475  *
476  * @par Sample code:
477  * @code
478 #include <appsvc.h>
479
480 ...
481 {
482         char *val;      
483         val = appsvc_get_uri(b);
484 }
485  * @endcode
486  *
487  */
488 const char *appsvc_get_uri(bundle *b);
489
490 /**
491  * @par Description:
492  * This function gets a mime-type from bundle.
493  *
494  * @param[in] b bundle object 
495  *
496  * @return Pointer for mime-type string if success, NULL if fail
497  *
498  * @pre None.
499  * @post None.
500  * @see None.
501  * @remarks None. 
502  *
503  * @par Sample code:
504  * @code
505 #include <appsvc.h>
506
507 ...
508 {
509         char *val;      
510         val = appsvc_get_mime(b);
511 }
512  * @endcode
513  *
514  */
515 const char *appsvc_get_mime(bundle *b);
516
517 /**
518  * @par Description:
519  * This function gets a package name from bundle.
520  *
521  * @param[in] b bundle object 
522  *
523  * @return Pointer for package name string if success, NULL if fail
524  *
525  * @pre None.
526  * @post None.
527  * @see None.
528  * @remarks None. 
529  *
530  * @par Sample code:
531  * @code
532 #include <appsvc.h>
533
534 ...
535 {
536         char *val;      
537         val = appsvc_get_pkgname(b);
538 }
539  * @endcode
540  *
541  */
542 const char *appsvc_get_pkgname(bundle *b);
543
544 /**
545  * @par Description:
546  * This function gets value from key.
547  *
548  * @param[in] b bundle object 
549  * @param[in] key key
550  *
551  * @return Pointer for value string if success, NULL if fail
552  *
553  * @pre None.
554  * @post None.
555  * @see None.
556  * @remarks None. 
557  *
558  * @par Sample code:
559  * @code
560 #include <appsvc.h>
561
562 ...
563 {
564         char *val;      
565         val = appsvc_get_data(b, APPSVC_DATA_CC);
566 }
567  * @endcode
568  *
569  */
570 const char *appsvc_get_data(bundle *b, const char *key);
571
572 /**
573  * @par Description:
574  * This function gets value from key.
575  *
576  * @param[in] b bundle object 
577  * @param[in] key key
578  * @param[out] len length of array
579  *
580  * @return Pointer for value string array if success, NULL if fail
581  *
582  * @pre None.
583  * @post None.
584  * @see None.
585  * @remarks None. 
586  *
587  * @par Sample code:
588  * @code
589 #include <appsvc.h>
590
591 ...
592 {
593         char **val_array;       
594         int len;
595         char *val;
596
597         if(appsvc_data_is_array(b, APPSVC_DATA_SELECTED))
598                 val_array = appsvc_get_data_array(b, APPSVC_DATA_SELECTED, &len);
599         else 
600                 val = appsvc_get_data(b, APPSVC_DATA_SELECTED);
601 }
602  * @endcode
603  *
604  */
605 const char **appsvc_get_data_array(bundle *b, const char *key, int *len);
606
607 /**
608  * @par Description:
609  * This API create appsvc result bundle based on bundle received in reset event.
610  *
611  * @param[in] inb bundle received in reset event 
612  * @param[in] outb bundle to use for returning result 
613  *
614  * @retval APPSVC_RET_OK - success
615  * @retval APPSVC_RET_ERROR - general error 
616  * @retval APPSVC_RET_EINVAL - invalid argument(content)
617  *
618  * @pre None.
619  * @post None.
620  * @see appsvc_send_result.
621  * @remarks None. 
622  *
623  * @par Sample code:
624  * @code
625 #include <appsvc.h>
626
627 ...
628 {
629         struct appdata *ad = data;
630         bundle* res_bundle;
631         
632         appsvc_create_result_bundle(ad->b,&res_bundle);
633         bundle_add(res_bundle, "result", "1");
634         appsvc_send_result(res_bundle, 0);
635 }
636  * @endcode
637  *
638  */
639 int appsvc_create_result_bundle(bundle *inb, bundle **outb);
640
641 /**
642  * @par Description:
643  * This API send appsvc result to caller with bundle.
644  *
645  * @param[in] b Result data in bundle format
646  * @param[in] result result value
647  *
648  * @retval APPSVC_RET_OK - success
649  * @retval APPSVC_RET_ERROR - general error 
650  * @retval APPSVC_RET_EINVAL - invalid argument(content)
651  *
652  * @pre appsvc_create_result_bundle.
653  * @post None.
654  * @see appsvc_send_result.
655  * @remarks None. 
656  *
657  * @par Sample code:
658  * @code
659 #include <appsvc.h>
660
661 ...
662 {
663         struct appdata *ad = data;
664         bundle* res_bundle;
665         
666         appsvc_create_result_bundle(ad->b,&res_bundle);
667         bundle_add(res_bundle, "result", "1");
668         appsvc_send_result(res_bundle, 0);
669 }
670  * @endcode
671  *
672  */
673 int appsvc_send_result(bundle *b, appsvc_result_val result);
674
675 /**
676  * @par Description:
677  * This API set the default application(package name) associated with op, uri and mime-type.
678  *
679  * @param[in] op                operation
680  * @param[in] mime_type mime-type
681  * @param[in] scheme    scheme of uri
682  * @param[in] defapp    default application
683  *
684  * @retval APPSVC_RET_OK - success
685  * @retval APPSVC_RET_ERROR - general error 
686  * @retval APPSVC_RET_EINVAL - invalid argument(content)
687  *
688  * @pre None.
689  * @post None.
690  * @see None.
691  * @remarks None. 
692  *
693  * @par Sample code:
694  * @code
695 #include <appsvc.h>
696
697 ...
698 {
699         appsvc_set_defapp(APPSVC_OPERATION_VIEW, NULL,"http", "org.tizen.mybrowser");
700 }
701  * @endcode
702  *
703  */
704 int appsvc_set_defapp(const char *op,const char *mime_type,const char *scheme,const char *defapp);
705
706 /**
707  * @par Description:
708  * This API unset the default application(package name) associated with op, uri and mime-type.
709  *
710  * @param[in] defapp    default application
711  *
712  * @retval APPSVC_RET_OK - success
713  * @retval APPSVC_RET_ERROR - general error 
714  *
715  * @pre None.
716  * @post None.
717  * @see None.
718  * @remarks None. 
719  *
720  * @par Sample code:
721  * @code
722 #include <appsvc.h>
723
724 ...
725 {
726         appsvc_unset_defapp("org.tizen.test");
727 }
728  * @endcode
729  *
730  */
731 int appsvc_unset_defapp(const char *defapp);
732
733 /**
734  * @par Description:
735  *      This API ask a application is default application or not.
736  *
737  * @param[in]   pkg_name        application package name
738  * @return      true / false
739  * @retval      1       app_name is default application in appsvc.
740  * @retval      0       app_name is NOT default application in appsvc.
741  *
742   * @pre None.
743   * @post None.
744   * @see None.
745   * @remarks None. 
746   *
747   * @par Sample code:
748   * @code
749 #include <appsvc.h>
750  
751  ...
752
753  * int is_defapp_browser_app()
754  * { 
755  *      return appsvc_is_defapp("org.tizen.browser");
756  * }
757  *
758  * @endcode
759  * @remark
760  *      None
761
762 */
763 int appsvc_is_defapp(const char *pkg_name);
764
765
766 /**
767  * @par Description:
768  *      This API ask a extra data is array or not.
769  *
770  * @param[in] b bundle object 
771  * @param[in] key key of extra data 
772  * @return      true / false
773  * @retval      1       a extra data is array.
774  * @retval      0       a extra data is not array.
775  *
776   * @pre None.
777   * @post None.
778   * @see None.
779   * @remarks None. 
780   *
781   * @par Sample code:
782   * @code
783 #include <appsvc.h>
784  
785  ...
786
787  * int is_defapp_browser_app(bundle *b, char *key)
788  * { 
789  *      return appsvc_data_is_array(b, key);
790  * }
791  *
792  * @endcode
793  * @remark
794  *      None
795
796 */
797 int appsvc_data_is_array(bundle *b, const char *key);
798
799
800 #ifdef __cplusplus
801         }
802 #endif
803
804 /**
805  * @}
806  */
807 /**
808  * @}
809  */
810
811
812 #endif          /* __APP_SVC_H__ */
813
814 /* vi: set ts=8 sts=8 sw=8: */