4 * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: Jayoun Lee <airjany@samsung.com>, Sewook Park <sewook7.park@samsung.com>, Jaeho Lee <jaeho81.lee@samsung.com>
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
27 * @defgroup AUL Application Utility Library
30 @par AUL Programming Guide
32 <h1 class="pg"> Introduction</h1>
33 <h2 class="pg"> Purpose of this document</h2>
34 The purpose of this document is to describe how applications can use Application Utility Library APIs.\n
35 This document gives only programming guidelines to application engineers.
37 <h2 class="pg"> Scope</h2>
38 The scope of this document is limited to Samsung platform Application Utility Library API usage.
41 @defgroup AUL_Architecture 1.Architecture
44 <h1 class="pg">Application Utility Library Architecture</h1>
45 <h2 class="pg"> Architecture overview</h2>
46 Application Utility Library (AUL) is responsible for launching / resuming / terminating application. It support low-level API for it. AUL also support high-level API to launch default applications based on MIME types and URI(based on regular expression). It also provides the information of applications that are running.\n
48 In single instance model, if a currently running application is requested to be launched again, the AUL sends the reset event to the application. \n
50 Low-level AUL API(primitive APIs) expects the application to provide APN(application package name) it wishes to launch.\n Low-level interface used by AUL are as shown below. Unix Domain Socket is used to send events between launchpad deamon and applications.
51 Launchpad deamon is responsible for setup default configuration of application like "setup authority", " setup application scale",... DB is used to store / retain default configuration of application.
53 @image html low-level2.png "Low-level AUL diagram"
55 High-level APIs support to launch based on MIME types(based on filename, URI, service name). This feature is abstraction of APN. Most develpers want to launch based on filename, URI, service name without knowing APN. Below is example list.
56 - When developer open browser appliction with "http://www.samsung.com".
57 - When developer open application with filename "/usr/share/myimage.png"
58 - When developer launching application with service name "camera" and service command "take_picture"
60 Internally, AUL finds MIME type with given filename, URI, service name. Next, AUL find APN of default application from DB with associated MIME type. and then, AUL launch the application using primitive AUL APIs.
62 @image html high-level2.png "High-Level AUL diagram"
65 @defgroup AUL_Feature 2.Feature
68 <h2 class="pg">Application Utility Library Features</h2>
69 Application Utility Library has the following features:\n
71 - Launch/Resume/Terminate Application (Primitive APIs)
72 - It can launch an application that is not currently running.
73 - It sends reset/resume/terminate event if application is already running
75 - Application List or information
76 - It provides the list of applications that are running.
77 - It provides information of running applications
79 - MIME support (High-Level APIs)
80 - AUL can get MIME type associated with the file and content
81 - AUL can get the default application associated with the MIME type.
82 - AUL can launch default applications associated with the MIME(file or content) when AUL find default application.
83 - AUL automatically launch "application selection popup" when AUL don't find default application associated with the MIME(file or content)
85 - Application Service support (High-Level APIs)
86 - AUL can launch applications based on service name and service command
89 @defgroup AUL_Use_Cases1 Launch/Resume/Terminate an Application
90 @ingroup AUL_Use_Cases
92 <h1 class="pg"> AUL features with sample code</h1>
94 <h2 class="pg"> Launch/Resume/Terminate an application</h2>
97 - LAUNCH or RESET request without return callback function
98 - The first parameter(pkg_name) has to be registered through .desktop file.
99 - The second parameter(bundle) give dictionary style's arguments to launched(callee) application.
102 // the package name of this app is a "org.tizen.caller"
108 kb = bundle_create();
109 bundle_add(kb, "key1", "val1");
110 bundle_add(kb, "key2", "val2");
111 bundle_add(kb, "key3", "val3");
112 aul_launch_app("org.tizen.callee",kb);
117 - Return the application to the foreground
118 - You might want to use aul_open_app when you need to resume,
119 e.g., get it back to foreground, an application
120 - If the application is not running, the application will be launched.
123 // the package name of this app is a "org.tizen.caller"
127 aul_open_app("org.tizen.callee");
134 - Integated with Appcore
135 - If you use Appcore Library, Aul library already was integrated.\n
136 You must implementation Appcore RESET , RESUME, TERMINATE handler.\n
137 This is example code. This is NOT guidance \n
138 - If you want more information,SEE for AppCore document.
141 //Callee application with AppCore
144 #include <appcore-efl.h>
148 static int app_create(void *data)
150 // initialize your app without argument
154 static void _app_initialize_with_arg(bundle *b)
156 // initialize your app with argument
160 // called by window manager event
161 // or called by aul_open_app
162 // create your resume handler
164 static int app_resume(void *data){return 0;}
165 static int app_pause(void *data) {return 0;}
168 // called by aul_terminate_api
170 static int app_terminate(void *data){return 0;}
173 // called by aul_launch_app or aul_launch_api_with_result
174 // this is example code. create your reset handler
176 static int app_reset(bundle *b, void *data)
179 if(bundle_get_val(ad->kb, AUL_K_ARGV0)) // when launch
180 _app_initialize_with_arg(b);
181 else{ // when receiving reset event
182 mime_type = bundle_get_val(b, AUL_K_MIME_TYPE);
184 elm_win_activate(..);
187 update_list(mime_type);
192 int main(int argc, char *argv[])
194 struct appcore_ops ops = {
195 .create = app_create,
196 .terminate = app_terminate,
198 .resume = app_resume,
202 return appcore_efl_main(PACKAGE, &argc, &argv, &ops);
207 - SET with AUL native handler
208 - In special case, if you don't use Appcore library, this is aul callee's example
211 // Callee application
216 static int aul_handler(aul_type type, bundle *kb,void* data)
221 // same to Appcore RESET callback
222 val1 = bundle_get_val(kb, "phone_number");
223 val2 = bundle_get_val(kb, "store");
226 // same to Appcore RESUME callback
229 // same to Appcore TERMINATE callback
235 int main(int argc, char** argv)
239 aul_launch_init(aul_handler,NULL);
240 // enable this if you want to handle at aul_handler when launch
241 aul_launch_argv_handler(argc, argv);
243 ecore_main_loop_begin(); // You must need ecore or glib mainloop
249 @defgroup AUL_Use_Cases2 Get Running Application State
250 @ingroup AUL_Use_Cases
252 <h2 class="pg"> Get Running Application State </h2>
254 - Getting running application list
255 - This AUL function is used to get the list of all the applications that are currently running.
260 int iterfunc(const aul_app_info* info, void* data)
262 printf("package name: %s\n", info->pkg_name);
263 printf("running pid: %d\n", info->pid);
264 printf("application executable path: %s\n", info->app_path);
268 int main (int argc, char **argv)
270 aul_app_get_running_app_info(iterfunc,NULL);
274 - Get application running state
275 - This AUL function is used to get application's state
280 int main (int argc, char **argv)
282 if(aul_app_is_running("org.tizen.app2"))
283 printf("application is running");
287 - Dead Handler (Set dead handler)
288 - aul_listen_app_dead_signal track killed application.
289 For example, 3rd party application can register indicator icon at indicator service. When 3rd party application abnormally terminated after set icon at indicator, indicator service should collect garbage icon set by the application.
294 int dead_tracker(int pid, void* data)
296 printf("the application with %d pid was killed",pid);
300 void set_dead_handler_func()
302 aul_listen_app_dead_signal(dead_tracker,NULL);
307 @defgroup AUL_Use_Cases3 Launch Based on Service Name and Command
308 @ingroup AUL_Use_Cases
310 <h2 class="pg"> High Level APIs - launch based on service name and command </h2>
312 - This AUL functions is used to launch default application based on service name and service command. In addition,AUL package support to set/get default application(package name) associated with service name and service command. This APIs also support to receive result from launched(requested) application.
314 - Launch default application associated with service name and service command.
315 - You can use aul_open_service when you launch an application associated with service name and service command
316 - If the service support to receive result, you can add result callback function.
317 - the API is asynchronous.(non-blocking API)
320 // the package name of this app is a "org.tizen.caller"
323 void cb_func( bundle* kb, int reserved, void* data)
326 id = bundle_get_val(kb, "searched_id");
327 printf("searched id %s", id);
330 void service_launch_func()
335 user_data = (void*)strdup("my_priv_data");
336 kb = bundle_create();
337 bundle_add(kb, "storage_type", "SIM");
338 aul_open_appsvc("contact", "search", kb, cb_func, user_data);
343 - This is sample code to send result to caller in application(callee) given the service.
344 - aul_send_service_result send result msg based on received bundle.
347 // Callee application
348 // the package name of this app is a "org.tizen.callee"
353 void send_result(bundle *recved_bundle, char* id)
356 aul_create_result_bundle(recved_bundle,&res_kb);
357 bundle_add(res_kb, "searched_id", id);
358 aul_send_service_result(res_kb);
369 @defgroup AUL_Use_Cases Use Cases