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 */
81 * @see appcore_set_rotation_cb(), appcore_get_rotation_state()
86 APPCORE_RM_PORTRAIT_NORMAL,
88 APPCORE_RM_PORTRAIT_REVERSE,
89 /**< Portrait upside down mode */
90 APPCORE_RM_LANDSCAPE_NORMAL,
91 /**< Left handed landscape mode */
92 APPCORE_RM_LANDSCAPE_REVERSE,
93 /**< Right handed landscape mode */
98 * @see appcore_get_timeformat()
100 enum appcore_time_format {
101 APPCORE_TIME_FORMAT_UNKNOWN,
102 APPCORE_TIME_FORMAT_12,
103 APPCORE_TIME_FORMAT_24,
107 * Appcore operations which are called during the application life-cycle
108 * @see appcore_efl_main()
112 /**< Callback data */
113 int (*create) (void *);
114 /**< Called before main loop \n
115 If this returns non-zero, Appcore does not run the main loop. */
116 int (*terminate) (void *);
117 /**< Called after main loop */
118 int (*pause) (void *);
119 /**< Called when every window goes back */
120 int (*resume) (void *);
121 /**< Called when any window comes on top */
122 int (*reset) (bundle *, void *);
123 /**< Called at the first idler
124 and every relaunching */
131 * Set the callback function which is called when the event occurs.
134 * This function sets a callback function for events from the system.
135 * Callback function is invoked every time the event occurs.
137 * @par Typical use case:
138 * To do something when predefined events (enum appcore_event) occur, use this API
140 * @par Method of function operation:
141 * Using Heynoti subscription, Vconf changed callback, and AUL, Appcore invokes the registered callback function.
143 * @par Important notes:
144 * Only one callback function can be set. If <I>cb</I> is NULL, unset the callback function about the event.\n
145 * Default behavior is performed when the specified event callback doesn't have registered.
147 * @param[in] event System event
148 * @param[in] cb callback function
149 * @param[in] data callback function data
151 * @return 0 on success, -1 on error (<I>errno</I> set)
154 * EINVAL - Invalid event type
157 * @post Callback is set/unset.
163 #include <appcore-common.h>
167 static int _lang_changed(void *);
168 static int _low_battery(void *);
169 static int _low_memory(void *);
170 static int _region_changed(void *);
172 int add_callbacks(struct appdata *data)
176 r = appcore_set_event_callback(APPCORE_EVENT_LANG_CHANGE, _lang_changed,
179 // add exception handling
182 r = appcore_set_event_callback(APPCORE_EVENT_LOW_BATTERY, _low_battery,
185 // add exception handling
188 r = appcore_set_event_callback(APPCORE_EVENT_LOW_MEMORY, _low_memory,
191 // add exception handling
194 r = appcore_set_event_callback(APPCORE_EVENT_REGION_CHANGE,
195 _region_changed, data);
197 // add exception handling
205 int appcore_set_event_callback(enum appcore_event event,
206 int (*cb)(void *, void *), void *data);
210 * Set a rotation callback
213 * This function sets a callback function for rotation events. Callback function is invoked every time the rotation mode is changed.
215 * @par Typical use case:
216 * To do something when the rotation mode is changed, use this API
218 * @par Method of function operation:
219 * Appcore receives rotation change from Sensor framework. When Appcore receive the change, it invokes the registered callback function.
221 * @par Important notes:
222 * Locks the rotation mode, the registered callback is not invoked.
224 * @param[in] cb callback function
225 * @param[in] data callback function data
227 * @return 0 on success, -1 on error (<I>errno</I> set)
230 * EINVAL - <I>cb</I> is NULL
231 * EALREADY - rotation callback function already registered
233 * @pre Callback is not set.
235 * @see appcore_unset_rotation_cb(), appcore_get_rotation_state()
240 #include <appcore-common.h>
244 static int _rot_cb(enum appcore_rm, void *);
250 r = appcore_set_rotation_cb(_rot_cb, data);
252 // add exception handling
260 int appcore_set_rotation_cb(int (*cb) (void *event_info, enum appcore_rm, void *),
265 * Unset a rotation callback
268 * This function unsets a callback function for rotation events.
270 * @return 0 on success, -1 on error
272 * @pre Callback is set by appcore_set_rotation_cb().
274 * @see appcore_set_rotation_cb(), appcore_get_rotation_state()
279 #include <appcore-common.h>
288 r = appcore_unset_rotation_cb();
290 // add exception handling
297 int appcore_unset_rotation_cb(void);
301 * Get the current rotation mode.
304 * To get the current rotation mode, use this API.
306 * @par Method of function operation:
307 * This function gets the current rotation mode from Sensor framework.
309 * @param[out] curr current rotation mode\n
310 * If Sensor framework is not working, curr is set to APPCORE_RM_UNKNOWN.
312 * @return 0 on success, -1 on error (<I>errno</I> set)
315 * EINVAL - <I>curr</I> is NULL
319 * @see appcore_set_rotation_cb(), appcore_unset_rotation_cb()
324 #include <appcore-common.h>
330 enum appcore_rm curr;
334 r = appcore_get_rotation_state(&curr);
336 // add exception handling
343 int appcore_get_rotation_state(enum appcore_rm *curr);
347 * Get the current time format.
350 * To get the current time format, use this API.
352 * @par Method of function operation:
353 * This function gets the current time format from vconf.
355 * @param[out] timeformat current time format\n
356 * If vconf is not working, timeformat is set to APPCORE_TIME_FORMAT_UNKNOWN.
358 * @return 0 on success, -1 on error (<I>errno</I> set)
361 * EINVAL - <I>timeformat</I> is NULL
370 #include <appcore-common.h>
376 enum appcore_time_format timeformat;
380 r = appcore_get_timeformat(&timeformat);
382 // add exception handling
389 int appcore_get_timeformat(enum appcore_time_format *timeformat);
393 * Set the information for the internationalization.
396 * This function prepares to internationalize. To use gettext, use this API.
398 * @par Typical use case:
399 * This function provides convenience for using gettext.
401 * @par Method of function operation:
402 * Calls setlocale(), bindtextdomain() and textdomain() internally.
404 * @par Corner cases/exceptions:
405 * If <I>dirname</I> is NULL, the previously set base directory is used. Typically, it is /usr/share/locale.
407 * @param[in] domainname a message domain name(text domain name) \n Must be a non-empty string.
408 * @param[in] dirname the base directory for message catalogs belonging to the specified domain \n
410 * @return 0 on success, -1 on error (<I>errno</I> set)
413 * EINVAL - <I>domain</I> is NULL
416 * @post The environment variable LANG is set or changed.
422 #include <appcore-common.h>
431 r = appcore_set_i18n("i18n_example", NULL);
433 // add exception handling
440 int appcore_set_i18n(const char *domainname, const char *dirname);
444 * Set the measuring start time
447 * To measure the time, the start time should be set. This function set the start point.
449 * @par Typical use case:
450 * It is used to measure the time for doing something. \n
451 * This function set the start point. And, appcore_measure_time() returns
452 * the elapsed time from the start point.
454 * @see appcore_measure_time()
456 * @par Method of function operation:
457 * Store the current time to the internal variable.
460 * @post Current time is saved to the internal space.
465 #include <appcore-common.h>
471 appcore_measure_start();
475 printf("it takes %d msec to do something\n", appcore_measure_time());
481 void appcore_measure_start(void);
485 * Measure the time from appcore_measure_start()
488 * To measure the elapsed time from the start point.
490 * @par Typical use case:
491 * It is used to measure the time for doing something. \n
492 * This function returns the elapsed time from the start point set by appcore_measure_start().
494 * @see appcore_measure_start()
496 * @par Method of function operation:
497 * This function subtracts the current time from the start point.
499 * @par Corner cases/exceptions:
500 * If the start point is not set, returns 0.
502 * @return Milliseconds from appcore_measure_start()
510 #include <appcore-common.h>
516 appcore_measure_start();
520 printf("it takes %d msec to do something\n", appcore_measure_time());
526 int appcore_measure_time(void);
530 * Measure the time from a time specified in environment variable.
533 * To measure the elapsed time from a time specified in environment variable.
535 * @par Typical use case:
536 * It is used to measure the time from a time set by external.
537 * This function returns the elapsed time from a time specified in environment variable.
539 * @see appcore_measure_start()
541 * @par Method of function operation:
542 * This function subtracts the current time from a time specified in environment variable.
544 * @par Corner cases/exceptions:
545 * If <I>envnm</I> is NULL, "APP_START_TIME" set by launcher is used.
546 * If the environment variable is not set or invalid format, returns 0.
548 * @param[in] envnm environment variable name which has
549 * the start time (format: "%u %u", seconds, micro seconds)
551 * @return Milliseconds from a time specified in environment variable
559 #include <appcore-common.h>
568 printf("it takes %d msec from APP_START\n",
569 appcore_measure_time_from("APP_START_TIME"));
575 int appcore_measure_time_from(const char *envnm);
578 * Appcore UI operaions. Internal use only.
584 * Appcore init. Internal use only
586 * @par Important notes:
587 * Except special case, NEVER use this. Use the appcore EFL or GTK instead of this.
589 * @param[in] name Application name used for text domain name
590 * @param[in] ops UI operations
591 * @param[in] argc a count of the arguments
592 * @param[in] argv an array of pointers to the strings which are those arguments
594 * @return 0 on succes, -1 on error (<I>errno</I> set)
597 * EINVAL - <I>ops</I> or <I>ops</I>'s callback is NULL \n
598 * EALREADY - Appcore already in operation \n
602 * @see appcore_exit()
603 * @remarks Internal use only.
606 int appcore_init(const char *name, const struct ui_ops *ops,
607 int argc, char **argv);
611 * Appcore exit. Internal use only.
613 * @par Important notes:
614 * Except special case, NEVER use this.
618 * @see appcore_init()
619 * @remarks Internal use only.
622 void appcore_exit(void);
627 * Utility function for memory flushing
632 * @par Method of function operation:
633 * Calls application-specific memory flushing tool (e.g., elm_flush_all() for EFL),
634 * sqlite3_release_memory() if sqlite3 is used, and malloc_trim(). Also, trims native stack.
636 * @par Important notes:
637 * Currently, this function is automatically called in the following 2 cases:\n
638 * (1) when the application enters into the pause state and\n
639 * (2) when low memory event is invoked and the application is on pause.\n
640 * Developers can use this function when they want extra memory flush utility.
642 * @return 0 on success, -1 on error
644 * @pre Appcore is already initialized.
645 * @post Memory for the application is flushed.
651 #include <appcore-common.h>
659 r = appcore_flush_memory();
661 // add exception handling
669 int appcore_flush_memory(void);
673 * Set a open callback
674 * Only when application is running, if aul_open api is called, then this callback function is called.
675 * If your open_cb function return -1, then appcore doesn't raise window.
677 * @param[in] cb callback function
678 * @param[in] data callback function data
680 * @return 0 on success, -1 on error (<I>errno</I> set)
688 #include <appcore-common.h>
692 static int _open_cb(enum appcore_rm, void *);
698 r = appcore_set_open_cb(_open_cb, data);
700 // add exception handling
708 int appcore_set_open_cb(int (*cb) (void *), void *data);
710 char *appcore_get_caller_appid(void);
721 #endif /* __APPCORE_COMMON_H__ */