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.
24 #ifndef __APPCORE_COMMON_H__
25 #define __APPCORE_COMMON_H__
28 * @file appcore-common.h
30 * @brief This file contains APIs of the Appcore library
34 * @addtogroup APPLICATION_FRAMEWORK
37 * @defgroup Appcore Appcore
39 * @brief A base library for application
55 #define _(str) gettext(str) /**< gettext alias */
56 #define gettext_noop(str) (str) /**< keyword for xgettext
57 to extract translatable strings */
58 #define N_(str) gettext_noop(str) /**< gettext_noop alias */
61 * System global events related to the application
62 * @see appcore_set_event_callback()
65 APPCORE_EVENT_UNKNOWN,
67 APPCORE_EVENT_LOW_MEMORY,
69 APPCORE_EVENT_LOW_BATTERY,
71 APPCORE_EVENT_LANG_CHANGE,
72 /**< Language setting is changed */
73 APPCORE_EVENT_REGION_CHANGE,
74 /**< Region setting is changed */
79 * @see appcore_set_rotation_cb(), appcore_get_rotation_state()
84 APPCORE_RM_PORTRAIT_NORMAL,
86 APPCORE_RM_PORTRAIT_REVERSE,
87 /**< Portrait upside down mode */
88 APPCORE_RM_LANDSCAPE_NORMAL,
89 /**< Left handed landscape mode */
90 APPCORE_RM_LANDSCAPE_REVERSE,
91 /**< Right handed landscape mode */
96 * @see appcore_get_timeformat()
98 enum appcore_time_format {
99 APPCORE_TIME_FORMAT_UNKNOWN,
100 APPCORE_TIME_FORMAT_12,
101 APPCORE_TIME_FORMAT_24,
105 * Appcore operations which are called during the application life-cycle
106 * @see appcore_efl_main()
110 /**< Callback data */
111 int (*create) (void *);
112 /**< Called before main loop \n
113 If this returns non-zero, Appcore does not run the main loop. */
114 int (*terminate) (void *);
115 /**< Called after main loop */
116 int (*pause) (void *);
117 /**< Called when every window goes back */
118 int (*resume) (void *);
119 /**< Called when any window comes on top */
120 int (*reset) (bundle *, void *);
121 /**< Called at the first idler
122 and every relaunching */
129 * Set the callback function which is called when the event occurs.
132 * This function sets a callback function for events from the system.
133 * Callback function is invoked every time the event occurs.
135 * @par Typical use case:
136 * To do something when predefined events (enum appcore_event) occur, use this API
138 * @par Method of function operation:
139 * Using Heynoti subscription, Vconf changed callback, and AUL, Appcore invokes the registered callback function.
141 * @par Important notes:
142 * Only one callback function can be set. If <I>cb</I> is NULL, unset the callback function about the event.\n
143 * Default behavior is performed when the specified event callback doesn't have registered.
145 * @param[in] event System event
146 * @param[in] cb callback function
147 * @param[in] data callback function data
149 * @return 0 on success, -1 on error (<I>errno</I> set)
152 * EINVAL - Invalid event type
155 * @post Callback is set/unset.
161 #include <appcore-common.h>
165 static int _lang_changed(void *);
166 static int _low_battery(void *);
167 static int _low_memory(void *);
168 static int _region_changed(void *);
170 int add_callbacks(struct appdata *data)
174 r = appcore_set_event_callback(APPCORE_EVENT_LANG_CHANGE, _lang_changed,
177 // add exception handling
180 r = appcore_set_event_callback(APPCORE_EVENT_LOW_BATTERY, _low_battery,
183 // add exception handling
186 r = appcore_set_event_callback(APPCORE_EVENT_LOW_MEMORY, _low_memory,
189 // add exception handling
192 r = appcore_set_event_callback(APPCORE_EVENT_REGION_CHANGE,
193 _region_changed, data);
195 // add exception handling
203 int appcore_set_event_callback(enum appcore_event event,
204 int (*cb)(void *), void *data);
208 * Set a rotation callback
211 * This function sets a callback function for rotation events. Callback function is invoked every time the rotation mode is changed.
213 * @par Typical use case:
214 * To do something when the rotation mode is changed, use this API
216 * @par Method of function operation:
217 * Appcore receives rotation change from Sensor framework. When Appcore receive the change, it invokes the registered callback function.
219 * @par Important notes:
220 * Locks the rotation mode, the registered callback is not invoked.
222 * @param[in] cb callback function
223 * @param[in] data callback function data
225 * @return 0 on success, -1 on error (<I>errno</I> set)
228 * EINVAL - <I>cb</I> is NULL
229 * EALREADY - rotation callback function already registered
231 * @pre Callback is not set.
233 * @see appcore_unset_rotation_cb(), appcore_get_rotation_state()
238 #include <appcore-common.h>
242 static int _rot_cb(enum appcore_rm, void *);
248 r = appcore_set_rotation_cb(_rot_cb, data);
250 // add exception handling
258 int appcore_set_rotation_cb(int (*cb) (enum appcore_rm, void *),
263 * Unset a rotation callback
266 * This function unsets a callback function for rotation events.
268 * @return 0 on success, -1 on error
270 * @pre Callback is set by appcore_set_rotation_cb().
272 * @see appcore_set_rotation_cb(), appcore_get_rotation_state()
277 #include <appcore-common.h>
286 r = appcore_unset_rotation_cb();
288 // add exception handling
295 int appcore_unset_rotation_cb(void);
299 * Get the current rotation mode.
302 * To get the current rotation mode, use this API.
304 * @par Method of function operation:
305 * This function gets the current rotation mode from Sensor framework.
307 * @param[out] curr current rotation mode\n
308 * If Sensor framework is not working, curr is set to APPCORE_RM_UNKNOWN.
310 * @return 0 on success, -1 on error (<I>errno</I> set)
313 * EINVAL - <I>curr</I> is NULL
317 * @see appcore_set_rotation_cb(), appcore_unset_rotation_cb()
322 #include <appcore-common.h>
328 enum appcore_rm curr;
332 r = appcore_get_rotation_state(&curr);
334 // add exception handling
341 int appcore_get_rotation_state(enum appcore_rm *curr);
345 * Get the current time format.
348 * To get the current time format, use this API.
350 * @par Method of function operation:
351 * This function gets the current time format from vconf.
353 * @param[out] timeformat current time format\n
354 * If vconf is not working, timeformat is set to APPCORE_TIME_FORMAT_UNKNOWN.
356 * @return 0 on success, -1 on error (<I>errno</I> set)
359 * EINVAL - <I>timeformat</I> is NULL
368 #include <appcore-common.h>
374 enum appcore_time_format timeformat;
378 r = appcore_get_timeformat(&timeformat);
380 // add exception handling
387 int appcore_get_timeformat(enum appcore_time_format *timeformat);
391 * Set the information for the internationalization.
394 * This function prepares to internationalize. To use gettext, use this API.
396 * @par Typical use case:
397 * This function provides convenience for using gettext.
399 * @par Method of function operation:
400 * Calls setlocale(), bindtextdomain() and textdomain() internally.
402 * @par Corner cases/exceptions:
403 * If <I>dirname</I> is NULL, the previously set base directory is used. Typically, it is /usr/share/locale.
405 * @param[in] domainname a message domain name(text domain name) \n Must be a non-empty string.
406 * @param[in] dirname the base directory for message catalogs belonging to the specified domain \n
408 * @return 0 on success, -1 on error (<I>errno</I> set)
411 * EINVAL - <I>domain</I> is NULL
414 * @post The environment variable LANG is set or changed.
420 #include <appcore-common.h>
429 r = appcore_set_i18n("i18n_example", NULL);
431 // add exception handling
438 int appcore_set_i18n(const char *domainname, const char *dirname);
442 * Set the measuring start time
445 * To measure the time, the start time should be set. This function set the start point.
447 * @par Typical use case:
448 * It is used to measure the time for doing something. \n
449 * This function set the start point. And, appcore_measure_time() returns
450 * the elapsed time from the start point.
452 * @see appcore_measure_time()
454 * @par Method of function operation:
455 * Store the current time to the internal variable.
458 * @post Current time is saved to the internal space.
463 #include <appcore-common.h>
469 appcore_measure_start();
473 printf("it takes %d msec to do something\n", appcore_measure_time());
479 void appcore_measure_start(void);
483 * Measure the time from appcore_measure_start()
486 * To measure the elapsed time from the start point.
488 * @par Typical use case:
489 * It is used to measure the time for doing something. \n
490 * This function returns the elapsed time from the start point set by appcore_measure_start().
492 * @see appcore_measure_start()
494 * @par Method of function operation:
495 * This function subtracts the current time from the start point.
497 * @par Corner cases/exceptions:
498 * If the start point is not set, returns 0.
500 * @return Milliseconds from appcore_measure_start()
508 #include <appcore-common.h>
514 appcore_measure_start();
518 printf("it takes %d msec to do something\n", appcore_measure_time());
524 int appcore_measure_time(void);
528 * Measure the time from a time specified in environment variable.
531 * To measure the elapsed time from a time specified in environment variable.
533 * @par Typical use case:
534 * It is used to measure the time from a time set by external.
535 * This function returns the elapsed time from a time specified in environment variable.
537 * @see appcore_measure_start()
539 * @par Method of function operation:
540 * This function subtracts the current time from a time specified in environment variable.
542 * @par Corner cases/exceptions:
543 * If <I>envnm</I> is NULL, "APP_START_TIME" set by launcher is used.
544 * If the environment variable is not set or invalid format, returns 0.
546 * @param[in] envnm environment variable name which has
547 * the start time (format: "%u %u", seconds, micro seconds)
549 * @return Milliseconds from a time specified in environment variable
557 #include <appcore-common.h>
566 printf("it takes %d msec from APP_START\n",
567 appcore_measure_time_from("APP_START_TIME"));
573 int appcore_measure_time_from(const char *envnm);
576 * Appcore UI operaions. Internal use only.
582 * Appcore init. Internal use only
584 * @par Important notes:
585 * Except special case, NEVER use this. Use the appcore EFL or GTK instead of this.
587 * @param[in] name Application name used for text domain name
588 * @param[in] ops UI operations
589 * @param[in] argc a count of the arguments
590 * @param[in] argv an array of pointers to the strings which are those arguments
592 * @return 0 on succes, -1 on error (<I>errno</I> set)
595 * EINVAL - <I>ops</I> or <I>ops</I>'s callback is NULL \n
596 * EALREADY - Appcore already in operation \n
600 * @see appcore_exit()
601 * @remarks Internal use only.
604 int appcore_init(const char *name, const struct ui_ops *ops,
605 int argc, char **argv);
609 * Appcore exit. Internal use only.
611 * @par Important notes:
612 * Except special case, NEVER use this.
616 * @see appcore_init()
617 * @remarks Internal use only.
620 void appcore_exit(void);
625 * Utility function for memory flushing
630 * @par Method of function operation:
631 * Calls application-specific memory flushing tool (e.g., elm_flush_all() for EFL),
632 * sqlite3_release_memory() if sqlite3 is used, and malloc_trim(). Also, trims native stack.
634 * @par Important notes:
635 * Currently, this function is automatically called in the following 2 cases:\n
636 * (1) when the application enters into the pause state and\n
637 * (2) when low memory event is invoked and the application is on pause.\n
638 * Developers can use this function when they want extra memory flush utility.
640 * @return 0 on success, -1 on error
642 * @pre Appcore is already initialized.
643 * @post Memory for the application is flushed.
649 #include <appcore-common.h>
657 r = appcore_flush_memory();
659 // add exception handling
667 int appcore_flush_memory(void);
671 * Set a open callback
672 * Only when application is running, if aul_open api is called, then this callback function is called.
673 * If your open_cb function return -1, then appcore doesn't raise window.
675 * @param[in] cb callback function
676 * @param[in] data callback function data
678 * @return 0 on success, -1 on error (<I>errno</I> set)
686 #include <appcore-common.h>
690 static int _open_cb(enum appcore_rm, void *);
696 r = appcore_set_open_cb(_open_cb, data);
698 // add exception handling
706 int appcore_set_open_cb(int (*cb) (void *), void *data);
718 #endif /* __APPCORE_COMMON_H__ */