include/appcore-common.h

   1 /*
   2  *  app-core
   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 __APPCORE_COMMON_H__
  25 #define __APPCORE_COMMON_H__
  26
  27 /**
  28  * @file    appcore-common.h
  29  * @version 1.1
  30  * @brief   This file contains APIs of the Appcore library
  31  */
  32
  33 /**
  34  * @addtogroup APPLICATION_FRAMEWORK
  35  * @{
  36  *
  37  * @defgroup Appcore Appcore
  38  * @version  1.1
  39  * @brief    A base library for application
  40  *
  41  */
  42
  43 /**
  44  * @addtogroup Appcore
  45  * @{
  46  */
  47
  48 #include <libintl.h>
  49 #include <bundle.h>
  50
  51 #ifdef __cplusplus
  52 extern "C" {
  53 #endif
  54
  55 #ifndef _
  56 #define _(str) gettext(str)  /**< gettext alias */
  57 #endif
  58 #define gettext_noop(str) (str) /**< keyword for xgettext
  59                                   to extract translatable strings */
  60 #define N_(str) gettext_noop(str)  /**< gettext_noop alias */
  61
  62 /**
  63  * System global events related to the application
  64  * @see appcore_set_event_callback()
  65  */
  66 enum appcore_event {
  67         APPCORE_EVENT_UNKNOWN,
  68                         /**< Unknown event */
  69         APPCORE_EVENT_LOW_MEMORY,
  70                         /**< Low memory */
  71         APPCORE_EVENT_LOW_BATTERY,
  72                         /**< 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 };
  80
  81 /**
  82  * Rotaion modes
  83  * @see appcore_set_rotation_cb(), appcore_get_rotation_state()
  84  */
  85 enum appcore_rm {
  86         APPCORE_RM_UNKNOWN,
  87                     /**< Unknown mode */
  88         APPCORE_RM_PORTRAIT_NORMAL,
  89                              /**< Portrait mode */
  90         APPCORE_RM_PORTRAIT_REVERSE,
  91                               /**< Portrait upside down mode */
  92         APPCORE_RM_LANDSCAPE_NORMAL,
  93                               /**< Left handed landscape mode */
  94         APPCORE_RM_LANDSCAPE_REVERSE,
  95                                 /**< Right handed landscape mode */
  96 };
  97
  98 /**
  99  * Time format
 100  * @see appcore_get_timeformat()
 101  */
 102 enum appcore_time_format {
 103         APPCORE_TIME_FORMAT_UNKNOWN,
 104         APPCORE_TIME_FORMAT_12,
 105         APPCORE_TIME_FORMAT_24,
 106 };
 107
 108 enum appcore_suspended_state {
 109         APPCORE_SUSPENDED_STATE_WILL_ENTER_SUSPEND = 0,
 110         APPCORE_SUSPENDED_STATE_DID_EXIT_FROM_SUSPEND
 111 };
 112
 113 /**
 114  * Appcore operations which are called during the application life-cycle
 115  * @see appcore_efl_main()
 116  */
 117 struct appcore_ops {
 118         void *data;
 119             /**< Callback data */
 120         int (*create) (void *);
 121                        /**< Called before main loop \n
 122                         If this returns non-zero, Appcore does not run the main loop. */
 123         int (*terminate) (void *);
 124                           /**< Called after main loop */
 125         int (*pause) (void *);
 126                       /**< Called when every window goes back */
 127         int (*resume) (void *);
 128                        /**< Called when any window comes on top */
 129         int (*reset) (bundle *, void *);
 130                                 /**< Called at the first idler
 131                                   and every relaunching */
 132         void *reserved[6];
 133                    /**< Reserved */
 134         };
 135
 136 /**
 137  * @par Description:
 138  * Set the callback function which is called when the event occurs.
 139  *
 140  * @par Purpose:
 141  * This function sets a callback function for events from the system.
 142  * Callback function is invoked every time the event occurs.
 143  *
 144  * @par Typical use case:
 145  * To do something when predefined events (enum appcore_event) occur, use this API
 146  *
 147  * @par Method of function operation:
 148  * Using Heynoti subscription, Vconf changed callback, and AUL, Appcore invokes the registered callback function.
 149  *
 150  * @par Important notes:
 151  * Only one callback function can be set. If <I>cb</I> is NULL, unset the callback function about the event.\n
 152  * Default behavior is performed when the specified event callback doesn't have registered.
 153  *
 154  * @param[in] event System event
 155  * @param[in] cb callback function
 156  * @param[in] data callback function data
 157  *
 158  * @return 0 on success, -1 on error (<I>errno</I> set)
 159  *
 160  * @par Errors:
 161  * EINVAL - Invalid event type
 162  *
 163  * @pre None.
 164  * @post Callback is set/unset.
 165  * @see None.
 166  * @remarks None.
 167  *
 168  * @par Sample code:
 169  * @code
 170 #include <appcore-common.h>
 171
 172 ...
 173
 174 static int _lang_changed(void *);
 175 static int _low_battery(void *);
 176 static int _low_memory(void *);
 177 static int _region_changed(void *);
 178
 179 int add_callbacks(struct appdata *data)
 180 {
 181         int r;
 182
 183         r = appcore_set_event_callback(APPCORE_EVENT_LANG_CHANGE, _lang_changed,
 184                                                                          data);
 185         if (r == -1) {
 186                 // add exception handling
 187         }
 188
 189         r = appcore_set_event_callback(APPCORE_EVENT_LOW_BATTERY, _low_battery,
 190                                                                          data);
 191         if (r == -1) {
 192                 // add exception handling
 193         }
 194
 195         r = appcore_set_event_callback(APPCORE_EVENT_LOW_MEMORY, _low_memory,
 196                                                                  data);
 197         if (r == -1) {
 198                 // add exception handling
 199         }
 200
 201         r = appcore_set_event_callback(APPCORE_EVENT_REGION_CHANGE,
 202                                          _region_changed, data);
 203         if (r == -1) {
 204                 // add exception handling
 205         }
 206
 207         return 0;
 208 }
 209  * @endcode
 210  *
 211  */
 212 int appcore_set_event_callback(enum appcore_event event,
 213                 int (*cb)(void *, void *), void *data);
 214
 215 /**
 216  * @par Description:
 217  * Set a rotation callback
 218  *
 219  * @par Purpose:
 220  * This function sets a callback function for rotation events. Callback function is invoked every time the rotation mode is changed.
 221  *
 222  * @par Typical use case:
 223  * To do something when the rotation mode is changed, use this API
 224  *
 225  * @par Method of function operation:
 226  * Appcore receives rotation change from Sensor framework. When Appcore receive the change, it invokes the registered callback function.
 227  *
 228  * @par Important notes:
 229  * Locks the rotation mode, the registered callback is not invoked.
 230  *
 231  * @param[in] cb callback function
 232  * @param[in] data callback function data
 233  *
 234  * @return 0 on success, -1 on error (<I>errno</I> set)
 235  *
 236  * @par Errors:
 237  * EINVAL - <I>cb</I> is NULL
 238  * EALREADY - rotation callback function already registered
 239  *
 240  * @pre Callback is not set.
 241  * @post None.
 242  * @see appcore_unset_rotation_cb(), appcore_get_rotation_state()
 243  * @remarks None.
 244  *
 245  * @par Sample code:
 246  * @code
 247 #include <appcore-common.h>
 248
 249 ...
 250
 251 static int _rot_cb(enum appcore_rm, void *);
 252
 253 ...
 254 {
 255         int r;
 256
 257         r = appcore_set_rotation_cb(_rot_cb, data);
 258         if (r == -1) {
 259                 // add exception handling
 260         }
 261
 262         ...
 263 }
 264  * @endcode
 265  *
 266  */
 267 int appcore_set_rotation_cb(int (*cb) (void *event_info, enum appcore_rm, void *),
 268                             void *data);
 269
 270 /**
 271  * @par Description:
 272  * Unset a rotation callback
 273  *
 274  * @par Purpose:
 275  * This function unsets a callback function for rotation events.
 276  *
 277  * @return 0 on success, -1 on error
 278  *
 279  * @pre Callback is set by appcore_set_rotation_cb().
 280  * @post None.
 281  * @see appcore_set_rotation_cb(), appcore_get_rotation_state()
 282  * @remarks None.
 283  *
 284  * @par Sample code:
 285  * @code
 286 #include <appcore-common.h>
 287
 288 ...
 289
 290 {
 291         int r;
 292
 293         ...
 294
 295         r = appcore_unset_rotation_cb();
 296         if (r == -1) {
 297                 // add exception handling
 298         }
 299         ...
 300 }
 301  * @endcode
 302  *
 303  */
 304 int appcore_unset_rotation_cb(void);
 305
 306 /**
 307  * @par Description:
 308  * Get the current rotation mode.
 309  *
 310  * @par Purpose:
 311  * To get the current rotation mode, use this API.
 312  *
 313  * @par Method of function operation:
 314  * This function gets the current rotation mode from Sensor framework.
 315  *
 316  * @param[out] curr current rotation mode\n
 317  * If Sensor framework is not working, curr is set to APPCORE_RM_UNKNOWN.
 318  *
 319  * @return 0 on success, -1 on error (<I>errno</I> set)
 320  *
 321  * @par Errors:
 322  * EINVAL - <I>curr</I> is NULL
 323  *
 324  * @pre None.
 325  * @post None.
 326  * @see appcore_set_rotation_cb(), appcore_unset_rotation_cb()
 327  * @remarks None.
 328  *
 329  * @par Sample code:
 330  * @code
 331 #include <appcore-common.h>
 332
 333 ...
 334
 335 {
 336         int r;
 337         enum appcore_rm curr;
 338
 339         ...
 340
 341         r = appcore_get_rotation_state(&curr);
 342         if (r == -1) {
 343                 // add exception handling
 344         }
 345         ...
 346 }
 347  * @endcode
 348  *
 349  */
 350 int appcore_get_rotation_state(enum appcore_rm *curr);
 351
 352 /**
 353  * @par Description:
 354  * Get the current time format.
 355  *
 356  * @par Purpose:
 357  * To get the current time format, use this API.
 358  *
 359  * @par Method of function operation:
 360  * This function gets the current time format from vconf.
 361  *
 362  * @param[out] timeformat current time format\n
 363  * If vconf is not working, timeformat is set to APPCORE_TIME_FORMAT_UNKNOWN.
 364  *
 365  * @return 0 on success, -1 on error (<I>errno</I> set)
 366  *
 367  * @par Errors:
 368  * EINVAL - <I>timeformat</I> is NULL
 369  *
 370  * @pre None.
 371  * @post None.
 372  * @see None.
 373  * @remarks None.
 374  *
 375  * @par Sample code:
 376  * @code
 377 #include <appcore-common.h>
 378
 379 ...
 380
 381 {
 382         int r;
 383         enum appcore_time_format timeformat;
 384
 385         ...
 386
 387         r = appcore_get_timeformat(&timeformat);
 388         if (r == -1) {
 389                 // add exception handling
 390         }
 391         ...
 392 }
 393  * @endcode
 394  *
 395  */
 396 int appcore_get_timeformat(enum appcore_time_format *timeformat);
 397
 398 /**
 399  * @par Description:
 400  * Set the information for the internationalization.
 401  *
 402  * @par Purpose:
 403  * This function prepares to internationalize. To use gettext, use this API.
 404  *
 405  * @par Typical use case:
 406  * This function provides convenience for using gettext.
 407  *
 408  * @par Method of function operation:
 409  * Calls setlocale(), bindtextdomain() and textdomain() internally.
 410  *
 411  * @par Corner cases/exceptions:
 412  * If <I>dirname</I> is NULL, the previously set base directory is used. Typically, it is /usr/share/locale.
 413  *
 414  * @param[in] domainname a message domain name(text domain name) \n Must be a non-empty string.
 415  * @param[in] dirname the base directory for message catalogs belonging to the specified domain \n
 416  *
 417  * @return 0 on success, -1 on error (<I>errno</I> set)
 418  *
 419  * @par Errors:
 420  * EINVAL - <I>domain</I> is NULL
 421  *
 422  * @pre None.
 423  * @post The environment variable LANG is set or changed.
 424  * @see None.
 425  * @remarks None.
 426  *
 427  * @par Sample code:
 428  * @code
 429 #include <appcore-common.h>
 430
 431 ...
 432
 433 {
 434         int r;
 435
 436         ...
 437
 438         r = appcore_set_i18n("i18n_example", NULL);
 439         if (r == -1) {
 440                 // add exception handling
 441         }
 442         ...
 443 }
 444  * @endcode
 445  *
 446  */
 447 int appcore_set_i18n(const char *domainname, const char *dirname);
 448
 449 /**
 450  * @par Description:
 451  * Set the measuring start time
 452  *
 453  * @par Purpose:
 454  * To measure the time, the start time should be set. This function set the start point.
 455  *
 456  * @par Typical use case:
 457  * It is used to measure the time for doing something. \n
 458  * This function set the start point. And, appcore_measure_time() returns
 459  * the elapsed time from the start point.
 460  *
 461  * @see appcore_measure_time()
 462  *
 463  * @par Method of function operation:
 464  * Store the current time to the internal variable.
 465  *
 466  * @pre None.
 467  * @post Current time is saved to the internal space.
 468  * @remarks None.
 469  *
 470  * @par Sample code:
 471  * @code
 472 #include <appcore-common.h>
 473
 474 ...
 475
 476 {
 477         ...
 478         appcore_measure_start();
 479
 480         // do something
 481
 482         printf("it takes %d msec to do something\n", appcore_measure_time());
 483         ...
 484 }
 485  * @endcode
 486  *
 487  */
 488 void appcore_measure_start(void);
 489
 490 /**
 491  * @par Description:
 492  * Measure the time from appcore_measure_start()
 493  *
 494  * @par Purpose:
 495  * To measure the elapsed time from the start point.
 496  *
 497  * @par Typical use case:
 498  * It is used to measure the time for doing something. \n
 499  * This function returns the elapsed time from the start point set by appcore_measure_start().
 500  *
 501  * @see appcore_measure_start()
 502  *
 503  * @par Method of function operation:
 504  * This function subtracts the current time from the start point.
 505  *
 506  * @par Corner cases/exceptions:
 507  * If the start point is not set, returns 0.
 508  *
 509  * @return Milliseconds from appcore_measure_start()
 510  *
 511  * @pre None.
 512  * @post None.
 513  * @remarks None.
 514  *
 515  * @par Sample code:
 516  * @code
 517 #include <appcore-common.h>
 518
 519 ...
 520
 521 {
 522         ...
 523         appcore_measure_start();
 524
 525         // do something
 526
 527         printf("it takes %d msec to do something\n", appcore_measure_time());
 528         ...
 529 }
 530  * @endcode
 531  *
 532  */
 533 int appcore_measure_time(void);
 534
 535 /**
 536  * @par Description:
 537  * Measure the time from a time specified in environment variable.
 538  *
 539  * @par Purpose:
 540  * To measure the elapsed time from a time specified in environment variable.
 541  *
 542  * @par Typical use case:
 543  * It is used to measure the time from a time set by external.
 544  * This function returns the elapsed time from a time specified in environment variable.
 545  *
 546  * @see appcore_measure_start()
 547  *
 548  * @par Method of function operation:
 549  * This function subtracts the current time from a time specified in environment variable.
 550  *
 551  * @par Corner cases/exceptions:
 552  * If <I>envnm</I> is NULL, "APP_START_TIME" set by launcher is used.
 553  * If the environment variable is not set or invalid format, returns 0.
 554  *
 555  * @param[in] envnm environment variable name which has
 556  *  the start time (format: "%u %u", seconds, micro seconds)
 557  *
 558  * @return Milliseconds from a time specified in environment variable
 559  *
 560  * @pre None.
 561  * @post None.
 562  * @remarks None.
 563  *
 564  * @par Sample code:
 565  * @code
 566 #include <appcore-common.h>
 567
 568 ...
 569
 570 {
 571         ...
 572
 573         // do something
 574
 575         printf("it takes %d msec from APP_START\n",
 576                 appcore_measure_time_from("APP_START_TIME"));
 577         ...
 578 }
 579  * @endcode
 580  *
 581  */
 582 int appcore_measure_time_from(const char *envnm);
 583
 584 /**
 585  * Appcore UI operaions. Internal use only.
 586  */
 587 struct ui_ops;
 588
 589 /**
 590  * @par Description:
 591  * Appcore init. Internal use only
 592  *
 593  * @par Important notes:
 594  * Except special case, NEVER use this. Use the appcore EFL or GTK instead of this.
 595  *
 596  * @param[in] name Application name used for text domain name
 597  * @param[in] ops UI operations
 598  * @param[in] argc a count of the arguments
 599  * @param[in] argv an array of pointers to the strings which are those arguments
 600  *
 601  * @return 0 on succes, -1 on error (<I>errno</I> set)
 602  *
 603  * @par Errors:
 604  * EINVAL - <I>ops</I> or <I>ops</I>'s callback is NULL \n
 605  * EALREADY - Appcore already in operation \n
 606  *
 607  * @pre None.
 608  * @post None.
 609  * @see appcore_exit()
 610  * @remarks Internal use only.
 611  *
 612  */
 613 int appcore_init(const char *name, const struct ui_ops *ops,
 614                  int argc, char **argv);
 615
 616 /**
 617  * @par Description:
 618  * Appcore exit. Internal use only.
 619  *
 620  * @par Important notes:
 621  * Except special case, NEVER use this.
 622  *
 623  * @pre None.
 624  * @post None.
 625  * @see appcore_init()
 626  * @remarks Internal use only.
 627  *
 628  */
 629 void appcore_exit(void);
 630
 631
 632 /**
 633  * @par Description:
 634  * Utility function for memory flushing
 635  *
 636  * @par Purpose:
 637  * To flush memory
 638  *
 639  * @par Method of function operation:
 640  * Calls application-specific memory flushing tool (e.g., elm_flush_all() for EFL),
 641  * sqlite3_release_memory() if sqlite3 is used, and malloc_trim(). Also, trims native stack.
 642  *
 643  * @par Important notes:
 644  * Currently, this function is automatically called in the following 2 cases:\n
 645  * (1) when the application enters into the pause state and\n
 646  * (2) when low memory event is invoked and the application is on pause.\n
 647  * Developers can use this function when they want extra memory flush utility.
 648  *
 649  * @return 0 on success, -1 on error
 650  *
 651  * @pre Appcore is already initialized.
 652  * @post Memory for the application is flushed.
 653  * @see None.
 654  * @remarks None.
 655  *
 656  * @par Sample code:
 657  * @code
 658 #include <appcore-common.h>
 659
 660 ...
 661
 662 {
 663         int r;
 664
 665         ...
 666         r = appcore_flush_memory();
 667         if (r == -1) {
 668                 // add exception handling
 669         }
 670
 671         ...
 672 }
 673  * @endcode
 674  *
 675  */
 676 int appcore_flush_memory(void);
 677
 678 /**
 679  * @par Description:
 680  * Set a open callback
 681  * Only when application is running, if aul_open api is called, then this callback function is called.
 682  * If your open_cb function return -1, then appcore doesn't raise window.
 683  *
 684  * @param[in] cb callback function
 685  * @param[in] data callback function data
 686  *
 687  * @return 0 on success, -1 on error (<I>errno</I> set)
 688  *
 689  * @pre None
 690  * @post None.
 691  * @remarks None.
 692  *
 693  * @par Sample code:
 694  * @code
 695 #include <appcore-common.h>
 696
 697 ...
 698
 699 static int _open_cb(enum appcore_rm, void *);
 700
 701 ...
 702 {
 703         int r;
 704
 705         r = appcore_set_open_cb(_open_cb, data);
 706         if (r == -1) {
 707                 // add exception handling
 708         }
 709
 710         ...
 711 }
 712  * @endcode
 713  *
 714  */
 715 int appcore_set_open_cb(int (*cb) (void *), void *data);
 716
 717
 718 #ifdef __cplusplus
 719 }
 720 #endif
 721 /**
 722  * @}
 723  */
 724 /**
 725  * @}
 726  */
 727 #endif                          /* __APPCORE_COMMON_H__ */