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
56 #define _(str) gettext(str) /**< gettext alias */
58 #define gettext_noop(str) (str) /**< keyword for xgettext
59 to extract translatable strings */
60 #define N_(str) gettext_noop(str) /**< gettext_noop alias */
63 * System global events related to the application
64 * @see appcore_set_event_callback()
67 APPCORE_EVENT_UNKNOWN,
69 APPCORE_EVENT_LOW_MEMORY,
71 APPCORE_EVENT_LOW_BATTERY,
73 APPCORE_EVENT_LANG_CHANGE,
74 /**< Language setting is changed */
75 APPCORE_EVENT_REGION_CHANGE,
76 /**< Region setting is changed */
77 APPCORE_EVENT_SUSPENDED_STATE_CHANGE,
78 /**< The suspended state is changed */
79 APPCORE_EVENT_UPDATE_REQUESTED,
80 /**< Update requested */
85 * @see appcore_set_rotation_cb(), appcore_get_rotation_state()
90 APPCORE_RM_PORTRAIT_NORMAL,
92 APPCORE_RM_PORTRAIT_REVERSE,
93 /**< Portrait upside down mode */
94 APPCORE_RM_LANDSCAPE_NORMAL,
95 /**< Left handed landscape mode */
96 APPCORE_RM_LANDSCAPE_REVERSE,
97 /**< Right handed landscape mode */
102 * @see appcore_get_timeformat()
104 enum appcore_time_format {
105 APPCORE_TIME_FORMAT_UNKNOWN,
106 APPCORE_TIME_FORMAT_12,
107 APPCORE_TIME_FORMAT_24,
110 enum appcore_suspended_state {
111 APPCORE_SUSPENDED_STATE_WILL_ENTER_SUSPEND = 0,
112 APPCORE_SUSPENDED_STATE_DID_EXIT_FROM_SUSPEND
116 * Appcore operations which are called during the application life-cycle
117 * @see appcore_efl_main()
121 /**< Callback data */
122 int (*create) (void *);
123 /**< Called before main loop \n
124 If this returns non-zero, Appcore does not run the main loop. */
125 int (*terminate) (void *);
126 /**< Called after main loop */
127 int (*pause) (void *);
128 /**< Called when every window goes back */
129 int (*resume) (void *);
130 /**< Called when any window comes on top */
131 int (*reset) (bundle *, void *);
132 /**< Called at the first idler
133 and every relaunching */
140 * Set the callback function which is called when the event occurs.
143 * This function sets a callback function for events from the system.
144 * Callback function is invoked every time the event occurs.
146 * @par Typical use case:
147 * To do something when predefined events (enum appcore_event) occur, use this API
149 * @par Method of function operation:
150 * Using Heynoti subscription, Vconf changed callback, and AUL, Appcore invokes the registered callback function.
152 * @par Important notes:
153 * Only one callback function can be set. If <I>cb</I> is NULL, unset the callback function about the event.\n
154 * Default behavior is performed when the specified event callback doesn't have registered.
156 * @param[in] event System event
157 * @param[in] cb callback function
158 * @param[in] data callback function data
160 * @return 0 on success, -1 on error (<I>errno</I> set)
163 * EINVAL - Invalid event type
166 * @post Callback is set/unset.
172 #include <appcore-common.h>
176 static int _lang_changed(void *);
177 static int _low_battery(void *);
178 static int _low_memory(void *);
179 static int _region_changed(void *);
181 int add_callbacks(struct appdata *data)
185 r = appcore_set_event_callback(APPCORE_EVENT_LANG_CHANGE, _lang_changed,
188 // add exception handling
191 r = appcore_set_event_callback(APPCORE_EVENT_LOW_BATTERY, _low_battery,
194 // add exception handling
197 r = appcore_set_event_callback(APPCORE_EVENT_LOW_MEMORY, _low_memory,
200 // add exception handling
203 r = appcore_set_event_callback(APPCORE_EVENT_REGION_CHANGE,
204 _region_changed, data);
206 // add exception handling
214 int appcore_set_event_callback(enum appcore_event event,
215 int (*cb)(void *, void *), void *data);
219 * Set a rotation callback
222 * This function sets a callback function for rotation events. Callback function is invoked every time the rotation mode is changed.
224 * @par Typical use case:
225 * To do something when the rotation mode is changed, use this API
227 * @par Method of function operation:
228 * Appcore receives rotation change from Sensor framework. When Appcore receive the change, it invokes the registered callback function.
230 * @par Important notes:
231 * Locks the rotation mode, the registered callback is not invoked.
233 * @param[in] cb callback function
234 * @param[in] data callback function data
236 * @return 0 on success, -1 on error (<I>errno</I> set)
239 * EINVAL - <I>cb</I> is NULL
240 * EALREADY - rotation callback function already registered
242 * @pre Callback is not set.
244 * @see appcore_unset_rotation_cb(), appcore_get_rotation_state()
249 #include <appcore-common.h>
253 static int _rot_cb(enum appcore_rm, void *);
259 r = appcore_set_rotation_cb(_rot_cb, data);
261 // add exception handling
269 int appcore_set_rotation_cb(int (*cb) (void *event_info, enum appcore_rm, void *),
274 * Unset a rotation callback
277 * This function unsets a callback function for rotation events.
279 * @return 0 on success, -1 on error
281 * @pre Callback is set by appcore_set_rotation_cb().
283 * @see appcore_set_rotation_cb(), appcore_get_rotation_state()
288 #include <appcore-common.h>
297 r = appcore_unset_rotation_cb();
299 // add exception handling
306 int appcore_unset_rotation_cb(void);
310 * Get the current rotation mode.
313 * To get the current rotation mode, use this API.
315 * @par Method of function operation:
316 * This function gets the current rotation mode from Sensor framework.
318 * @param[out] curr current rotation mode\n
319 * If Sensor framework is not working, curr is set to APPCORE_RM_UNKNOWN.
321 * @return 0 on success, -1 on error (<I>errno</I> set)
324 * EINVAL - <I>curr</I> is NULL
328 * @see appcore_set_rotation_cb(), appcore_unset_rotation_cb()
333 #include <appcore-common.h>
339 enum appcore_rm curr;
343 r = appcore_get_rotation_state(&curr);
345 // add exception handling
352 int appcore_get_rotation_state(enum appcore_rm *curr);
356 * Get the current time format.
359 * To get the current time format, use this API.
361 * @par Method of function operation:
362 * This function gets the current time format from vconf.
364 * @param[out] timeformat current time format\n
365 * If vconf is not working, timeformat is set to APPCORE_TIME_FORMAT_UNKNOWN.
367 * @return 0 on success, -1 on error (<I>errno</I> set)
370 * EINVAL - <I>timeformat</I> is NULL
379 #include <appcore-common.h>
385 enum appcore_time_format timeformat;
389 r = appcore_get_timeformat(&timeformat);
391 // add exception handling
398 int appcore_get_timeformat(enum appcore_time_format *timeformat);
402 * Set the information for the internationalization.
405 * This function prepares to internationalize. To use gettext, use this API.
407 * @par Typical use case:
408 * This function provides convenience for using gettext.
410 * @par Method of function operation:
411 * Calls setlocale(), bindtextdomain() and textdomain() internally.
413 * @par Corner cases/exceptions:
414 * If <I>dirname</I> is NULL, the previously set base directory is used. Typically, it is /usr/share/locale.
416 * @param[in] domainname a message domain name(text domain name) \n Must be a non-empty string.
417 * @param[in] dirname the base directory for message catalogs belonging to the specified domain \n
419 * @return 0 on success, -1 on error (<I>errno</I> set)
422 * EINVAL - <I>domain</I> is NULL
425 * @post The environment variable LANG is set or changed.
431 #include <appcore-common.h>
440 r = appcore_set_i18n("i18n_example", NULL);
442 // add exception handling
449 int appcore_set_i18n(const char *domainname, const char *dirname);
453 * Set the measuring start time
456 * To measure the time, the start time should be set. This function set the start point.
458 * @par Typical use case:
459 * It is used to measure the time for doing something. \n
460 * This function set the start point. And, appcore_measure_time() returns
461 * the elapsed time from the start point.
463 * @see appcore_measure_time()
465 * @par Method of function operation:
466 * Store the current time to the internal variable.
469 * @post Current time is saved to the internal space.
474 #include <appcore-common.h>
480 appcore_measure_start();
484 printf("it takes %d msec to do something\n", appcore_measure_time());
490 void appcore_measure_start(void);
494 * Measure the time from appcore_measure_start()
497 * To measure the elapsed time from the start point.
499 * @par Typical use case:
500 * It is used to measure the time for doing something. \n
501 * This function returns the elapsed time from the start point set by appcore_measure_start().
503 * @see appcore_measure_start()
505 * @par Method of function operation:
506 * This function subtracts the current time from the start point.
508 * @par Corner cases/exceptions:
509 * If the start point is not set, returns 0.
511 * @return Milliseconds from appcore_measure_start()
519 #include <appcore-common.h>
525 appcore_measure_start();
529 printf("it takes %d msec to do something\n", appcore_measure_time());
535 int appcore_measure_time(void);
539 * Measure the time from a time specified in environment variable.
542 * To measure the elapsed time from a time specified in environment variable.
544 * @par Typical use case:
545 * It is used to measure the time from a time set by external.
546 * This function returns the elapsed time from a time specified in environment variable.
548 * @see appcore_measure_start()
550 * @par Method of function operation:
551 * This function subtracts the current time from a time specified in environment variable.
553 * @par Corner cases/exceptions:
554 * If <I>envnm</I> is NULL, "APP_START_TIME" set by launcher is used.
555 * If the environment variable is not set or invalid format, returns 0.
557 * @param[in] envnm environment variable name which has
558 * the start time (format: "%u %u", seconds, micro seconds)
560 * @return Milliseconds from a time specified in environment variable
568 #include <appcore-common.h>
577 printf("it takes %d msec from APP_START\n",
578 appcore_measure_time_from("APP_START_TIME"));
584 int appcore_measure_time_from(const char *envnm);
587 * Appcore UI operaions. Internal use only.
593 * Appcore init. Internal use only
595 * @par Important notes:
596 * Except special case, NEVER use this. Use the appcore EFL or GTK instead of this.
598 * @param[in] name Application name used for text domain name
599 * @param[in] ops UI operations
600 * @param[in] argc a count of the arguments
601 * @param[in] argv an array of pointers to the strings which are those arguments
603 * @return 0 on succes, -1 on error (<I>errno</I> set)
606 * EINVAL - <I>ops</I> or <I>ops</I>'s callback is NULL \n
607 * EALREADY - Appcore already in operation \n
611 * @see appcore_exit()
612 * @remarks Internal use only.
615 int appcore_init(const char *name, const struct ui_ops *ops,
616 int argc, char **argv);
620 * Appcore exit. Internal use only.
622 * @par Important notes:
623 * Except special case, NEVER use this.
627 * @see appcore_init()
628 * @remarks Internal use only.
631 void appcore_exit(void);
636 * Utility function for memory flushing
641 * @par Method of function operation:
642 * Calls application-specific memory flushing tool (e.g., elm_flush_all() for EFL),
643 * sqlite3_release_memory() if sqlite3 is used, and malloc_trim(). Also, trims native stack.
645 * @par Important notes:
646 * Currently, this function is automatically called in the following 2 cases:\n
647 * (1) when the application enters into the pause state and\n
648 * (2) when low memory event is invoked and the application is on pause.\n
649 * Developers can use this function when they want extra memory flush utility.
651 * @return 0 on success, -1 on error
653 * @pre Appcore is already initialized.
654 * @post Memory for the application is flushed.
660 #include <appcore-common.h>
668 r = appcore_flush_memory();
670 // add exception handling
678 int appcore_flush_memory(void);
682 * Set a open callback
683 * Only when application is running, if aul_open api is called, then this callback function is called.
684 * If your open_cb function return -1, then appcore doesn't raise window.
686 * @param[in] cb callback function
687 * @param[in] data callback function data
689 * @return 0 on success, -1 on error (<I>errno</I> set)
697 #include <appcore-common.h>
701 static int _open_cb(enum appcore_rm, void *);
707 r = appcore_set_open_cb(_open_cb, data);
709 // add exception handling
717 int appcore_set_open_cb(int (*cb) (void *), void *data);
729 #endif /* __APPCORE_COMMON_H__ */