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 #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 */
  59
  60 /**
  61  * System global events related to the application
  62  * @see appcore_set_event_callback()
  63  */
  64 enum appcore_event {
  65         APPCORE_EVENT_UNKNOWN,
  66                        /**< Unknown event */
  67         APPCORE_EVENT_LOW_MEMORY,
  68                           /**< Low memory */
  69         APPCORE_EVENT_LOW_BATTERY,
  70                            /**< Low battery */
  71         APPCORE_EVENT_LANG_CHANGE,
  72                            /**< Language setting is changed */
  73         APPCORE_EVENT_REGION_CHANGE,
  74                              /**< Region setting is changed */
  75 };
  76
  77 /**
  78  * Rotaion modes
  79  * @see appcore_set_rotation_cb(), appcore_get_rotation_state()
  80  */
  81 enum appcore_rm {
  82         APPCORE_RM_UNKNOWN,
  83                     /**< Unknown mode */
  84         APPCORE_RM_PORTRAIT_NORMAL,
  85                              /**< Portrait mode */
  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 */
  92 };
  93
  94 /**
  95  * Time format
  96  * @see appcore_get_timeformat()
  97  */
  98 enum appcore_time_format {
  99         APPCORE_TIME_FORMAT_UNKNOWN,
 100         APPCORE_TIME_FORMAT_12,
 101         APPCORE_TIME_FORMAT_24,
 102 };
 103
 104 /**
 105  * Appcore operations which are called during the application life-cycle
 106  * @see appcore_efl_main()
 107  */
 108 struct appcore_ops {
 109         void *data;
 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 */
 123         void *reserved[6];
 124                    /**< Reserved */
 125         };
 126
 127 /**
 128  * @par Description:
 129  * Set the callback function which is called when the event occurs.
 130  *
 131  * @par Purpose:
 132  * This function sets a callback function for events from the system.
 133  * Callback function is invoked every time the event occurs.
 134  *
 135  * @par Typical use case:
 136  * To do something when predefined events (enum appcore_event) occur, use this API
 137  *
 138  * @par Method of function operation:
 139  * Using Heynoti subscription, Vconf changed callback, and AUL, Appcore invokes the registered callback function.
 140  *
 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.
 144  *
 145  * @param[in] event System event
 146  * @param[in] cb callback function
 147  * @param[in] data callback function data
 148  *
 149  * @return 0 on success, -1 on error (<I>errno</I> set)
 150  *
 151  * @par Errors:
 152  * EINVAL - Invalid event type
 153  *
 154  * @pre None.
 155  * @post Callback is set/unset.
 156  * @see None.
 157  * @remarks None.
 158  *
 159  * @par Sample code:
 160  * @code
 161 #include <appcore-common.h>
 162
 163 ...
 164
 165 static int _lang_changed(void *);
 166 static int _low_battery(void *);
 167 static int _low_memory(void *);
 168 static int _region_changed(void *);
 169
 170 int add_callbacks(struct appdata *data)
 171 {
 172         int r;
 173
 174         r = appcore_set_event_callback(APPCORE_EVENT_LANG_CHANGE, _lang_changed,
 175                                                                          data);
 176         if (r == -1) {
 177                 // add exception handling
 178         }
 179
 180         r = appcore_set_event_callback(APPCORE_EVENT_LOW_BATTERY, _low_battery,
 181                                                                          data);
 182         if (r == -1) {
 183                 // add exception handling
 184         }
 185
 186         r = appcore_set_event_callback(APPCORE_EVENT_LOW_MEMORY, _low_memory,
 187                                                                  data);
 188         if (r == -1) {
 189                 // add exception handling
 190         }
 191
 192         r = appcore_set_event_callback(APPCORE_EVENT_REGION_CHANGE,
 193                                          _region_changed, data);
 194         if (r == -1) {
 195                 // add exception handling
 196         }
 197
 198         return 0;
 199 }
 200  * @endcode
 201  *
 202  */
 203 int appcore_set_event_callback(enum appcore_event event,
 204                 int (*cb)(void *), void *data);
 205
 206 /**
 207  * @par Description:
 208  * Set a rotation callback
 209  *
 210  * @par Purpose:
 211  * This function sets a callback function for rotation events. Callback function is invoked every time the rotation mode is changed.
 212  *
 213  * @par Typical use case:
 214  * To do something when the rotation mode is changed, use this API
 215  *
 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.
 218  *
 219  * @par Important notes:
 220  * Locks the rotation mode, the registered callback is not invoked.
 221  *
 222  * @param[in] cb callback function
 223  * @param[in] data callback function data
 224  *
 225  * @return 0 on success, -1 on error (<I>errno</I> set)
 226  *
 227  * @par Errors:
 228  * EINVAL - <I>cb</I> is NULL
 229  * EALREADY - rotation callback function already registered
 230  *
 231  * @pre Callback is not set.
 232  * @post None.
 233  * @see appcore_unset_rotation_cb(), appcore_get_rotation_state()
 234  * @remarks None.
 235  *
 236  * @par Sample code:
 237  * @code
 238 #include <appcore-common.h>
 239
 240 ...
 241
 242 static int _rot_cb(enum appcore_rm, void *);
 243
 244 ...
 245 {
 246         int r;
 247
 248         r = appcore_set_rotation_cb(_rot_cb, data);
 249         if (r == -1) {
 250                 // add exception handling
 251         }
 252
 253         ...
 254 }
 255  * @endcode
 256  *
 257  */
 258 int appcore_set_rotation_cb(int (*cb) (enum appcore_rm, void *),
 259                             void *data);
 260
 261 /**
 262  * @par Description:
 263  * Unset a rotation callback
 264  *
 265  * @par Purpose:
 266  * This function unsets a callback function for rotation events.
 267  *
 268  * @return 0 on success, -1 on error
 269  *
 270  * @pre Callback is set by appcore_set_rotation_cb().
 271  * @post None.
 272  * @see appcore_set_rotation_cb(), appcore_get_rotation_state()
 273  * @remarks None.
 274  *
 275  * @par Sample code:
 276  * @code
 277 #include <appcore-common.h>
 278
 279 ...
 280
 281 {
 282         int r;
 283
 284         ...
 285
 286         r = appcore_unset_rotation_cb();
 287         if (r == -1) {
 288                 // add exception handling
 289         }
 290         ...
 291 }
 292  * @endcode
 293  *
 294  */
 295 int appcore_unset_rotation_cb(void);
 296
 297 /**
 298  * @par Description:
 299  * Get the current rotation mode.
 300  *
 301  * @par Purpose:
 302  * To get the current rotation mode, use this API.
 303  *
 304  * @par Method of function operation:
 305  * This function gets the current rotation mode from Sensor framework.
 306  *
 307  * @param[out] curr current rotation mode\n
 308  * If Sensor framework is not working, curr is set to APPCORE_RM_UNKNOWN.
 309  *
 310  * @return 0 on success, -1 on error (<I>errno</I> set)
 311  *
 312  * @par Errors:
 313  * EINVAL - <I>curr</I> is NULL
 314  *
 315  * @pre None.
 316  * @post None.
 317  * @see appcore_set_rotation_cb(), appcore_unset_rotation_cb()
 318  * @remarks None.
 319  *
 320  * @par Sample code:
 321  * @code
 322 #include <appcore-common.h>
 323
 324 ...
 325
 326 {
 327         int r;
 328         enum appcore_rm curr;
 329
 330         ...
 331
 332         r = appcore_get_rotation_state(&curr);
 333         if (r == -1) {
 334                 // add exception handling
 335         }
 336         ...
 337 }
 338  * @endcode
 339  *
 340  */
 341 int appcore_get_rotation_state(enum appcore_rm *curr);
 342
 343 /**
 344  * @par Description:
 345  * Get the current time format.
 346  *
 347  * @par Purpose:
 348  * To get the current time format, use this API.
 349  *
 350  * @par Method of function operation:
 351  * This function gets the current time format from vconf.
 352  *
 353  * @param[out] timeformat current time format\n
 354  * If vconf is not working, timeformat is set to APPCORE_TIME_FORMAT_UNKNOWN.
 355  *
 356  * @return 0 on success, -1 on error (<I>errno</I> set)
 357  *
 358  * @par Errors:
 359  * EINVAL - <I>timeformat</I> is NULL
 360  *
 361  * @pre None.
 362  * @post None.
 363  * @see None.
 364  * @remarks None.
 365  *
 366  * @par Sample code:
 367  * @code
 368 #include <appcore-common.h>
 369
 370 ...
 371
 372 {
 373         int r;
 374         enum appcore_time_format timeformat;
 375
 376         ...
 377
 378         r = appcore_get_timeformat(&timeformat);
 379         if (r == -1) {
 380                 // add exception handling
 381         }
 382         ...
 383 }
 384  * @endcode
 385  *
 386  */
 387 int appcore_get_timeformat(enum appcore_time_format *timeformat);
 388
 389 /**
 390  * @par Description:
 391  * Set the information for the internationalization.
 392  *
 393  * @par Purpose:
 394  * This function prepares to internationalize. To use gettext, use this API.
 395  *
 396  * @par Typical use case:
 397  * This function provides convenience for using gettext.
 398  *
 399  * @par Method of function operation:
 400  * Calls setlocale(), bindtextdomain() and textdomain() internally.
 401  *
 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.
 404  *
 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
 407  *
 408  * @return 0 on success, -1 on error (<I>errno</I> set)
 409  *
 410  * @par Errors:
 411  * EINVAL - <I>domain</I> is NULL
 412  *
 413  * @pre None.
 414  * @post The environment variable LANG is set or changed.
 415  * @see None.
 416  * @remarks None.
 417  *
 418  * @par Sample code:
 419  * @code
 420 #include <appcore-common.h>
 421
 422 ...
 423
 424 {
 425         int r;
 426
 427         ...
 428
 429         r = appcore_set_i18n("i18n_example", NULL);
 430         if (r == -1) {
 431                 // add exception handling
 432         }
 433         ...
 434 }
 435  * @endcode
 436  *
 437  */
 438 int appcore_set_i18n(const char *domainname, const char *dirname);
 439
 440 /**
 441  * @par Description:
 442  * Set the measuring start time
 443  *
 444  * @par Purpose:
 445  * To measure the time, the start time should be set. This function set the start point.
 446  *
 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.
 451  *
 452  * @see appcore_measure_time()
 453  *
 454  * @par Method of function operation:
 455  * Store the current time to the internal variable.
 456  *
 457  * @pre None.
 458  * @post Current time is saved to the internal space.
 459  * @remarks None.
 460  *
 461  * @par Sample code:
 462  * @code
 463 #include <appcore-common.h>
 464
 465 ...
 466
 467 {
 468         ...
 469         appcore_measure_start();
 470
 471         // do something
 472
 473         printf("it takes %d msec to do something\n", appcore_measure_time());
 474         ...
 475 }
 476  * @endcode
 477  *
 478  */
 479 void appcore_measure_start(void);
 480
 481 /**
 482  * @par Description:
 483  * Measure the time from appcore_measure_start()
 484  *
 485  * @par Purpose:
 486  * To measure the elapsed time from the start point.
 487  *
 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().
 491  *
 492  * @see appcore_measure_start()
 493  *
 494  * @par Method of function operation:
 495  * This function subtracts the current time from the start point.
 496  *
 497  * @par Corner cases/exceptions:
 498  * If the start point is not set, returns 0.
 499  *
 500  * @return Milliseconds from appcore_measure_start()
 501  *
 502  * @pre None.
 503  * @post None.
 504  * @remarks None.
 505  *
 506  * @par Sample code:
 507  * @code
 508 #include <appcore-common.h>
 509
 510 ...
 511
 512 {
 513         ...
 514         appcore_measure_start();
 515
 516         // do something
 517
 518         printf("it takes %d msec to do something\n", appcore_measure_time());
 519         ...
 520 }
 521  * @endcode
 522  *
 523  */
 524 int appcore_measure_time(void);
 525
 526 /**
 527  * @par Description:
 528  * Measure the time from a time specified in environment variable.
 529  *
 530  * @par Purpose:
 531  * To measure the elapsed time from a time specified in environment variable.
 532  *
 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.
 536  *
 537  * @see appcore_measure_start()
 538  *
 539  * @par Method of function operation:
 540  * This function subtracts the current time from a time specified in environment variable.
 541  *
 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.
 545  *
 546  * @param[in] envnm environment variable name which has
 547  *  the start time (format: "%u %u", seconds, micro seconds)
 548  *
 549  * @return Milliseconds from a time specified in environment variable
 550  *
 551  * @pre None.
 552  * @post None.
 553  * @remarks None.
 554  *
 555  * @par Sample code:
 556  * @code
 557 #include <appcore-common.h>
 558
 559 ...
 560
 561 {
 562         ...
 563
 564         // do something
 565
 566         printf("it takes %d msec from APP_START\n",
 567                 appcore_measure_time_from("APP_START_TIME"));
 568         ...
 569 }
 570  * @endcode
 571  *
 572  */
 573 int appcore_measure_time_from(const char *envnm);
 574
 575 /**
 576  * Appcore UI operaions. Internal use only.
 577  */
 578 struct ui_ops;
 579
 580 /**
 581  * @par Description:
 582  * Appcore init. Internal use only
 583  *
 584  * @par Important notes:
 585  * Except special case, NEVER use this. Use the appcore EFL or GTK instead of this.
 586  *
 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
 591  *
 592  * @return 0 on succes, -1 on error (<I>errno</I> set)
 593  *
 594  * @par Errors:
 595  * EINVAL - <I>ops</I> or <I>ops</I>'s callback is NULL \n
 596  * EALREADY - Appcore already in operation \n
 597  *
 598  * @pre None.
 599  * @post None.
 600  * @see appcore_exit()
 601  * @remarks Internal use only.
 602  *
 603  */
 604 int appcore_init(const char *name, const struct ui_ops *ops,
 605                  int argc, char **argv);
 606
 607 /**
 608  * @par Description:
 609  * Appcore exit. Internal use only.
 610  *
 611  * @par Important notes:
 612  * Except special case, NEVER use this.
 613  *
 614  * @pre None.
 615  * @post None.
 616  * @see appcore_init()
 617  * @remarks Internal use only.
 618  *
 619  */
 620 void appcore_exit(void);
 621
 622
 623 /**
 624  * @par Description:
 625  * Utility function for memory flushing
 626  *
 627  * @par Purpose:
 628  * To flush memory
 629  *
 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.
 633  *
 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.
 639  *
 640  * @return 0 on success, -1 on error
 641  *
 642  * @pre Appcore is already initialized.
 643  * @post Memory for the application is flushed.
 644  * @see None.
 645  * @remarks None.
 646  *
 647  * @par Sample code:
 648  * @code
 649 #include <appcore-common.h>
 650
 651 ...
 652
 653 {
 654         int r;
 655
 656         ...
 657         r = appcore_flush_memory();
 658         if (r == -1) {
 659                 // add exception handling
 660         }
 661
 662         ...
 663 }
 664  * @endcode
 665  *
 666  */
 667 int appcore_flush_memory(void);
 668
 669 /**
 670  * @par Description:
 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.
 674  *
 675  * @param[in] cb callback function
 676  * @param[in] data callback function data
 677  *
 678  * @return 0 on success, -1 on error (<I>errno</I> set)
 679  *
 680  * @pre None
 681  * @post None.
 682  * @remarks None.
 683  *
 684  * @par Sample code:
 685  * @code
 686 #include <appcore-common.h>
 687
 688 ...
 689
 690 static int _open_cb(enum appcore_rm, void *);
 691
 692 ...
 693 {
 694         int r;
 695
 696         r = appcore_set_open_cb(_open_cb, data);
 697         if (r == -1) {
 698                 // add exception handling
 699         }
 700
 701         ...
 702 }
 703  * @endcode
 704  *
 705  */
 706 int appcore_set_open_cb(int (*cb) (void *), void *data);
 707
 708
 709 #ifdef __cplusplus
 710 }
 711 #endif
 712 /**
 713  * @}
 714  */
 715 /**
 716  * @}
 717  */
 718 #endif                          /* __APPCORE_COMMON_H__ */