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