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