include/service_app.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_APPFW_SERVICE_APP_H__
  19 #define __TIZEN_APPFW_SERVICE_APP_H__
  20
  21 #include <tizen.h>
  22 #include <app_control.h>
  23 #include <app_common.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @addtogroup CAPI_SERVICE_APP_MODULE
  31  * @{
  32  */
  33
  34
  35 /**
  36  * @brief Called at the start of the agent application.
  37  *
  38  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  39  *
  40  * @param[in] user_data The user data passed from the callback registration function
  41  * @return @c true on success,
  42  *         otherwise @c false
  43  * @pre service_app_main() will invoke this callback function.
  44  * @see service_app_main()
  45  * @see #service_app_lifecycle_callback_s
  46  */
  47 typedef bool (*service_app_create_cb) (void *user_data);
  48
  49
  50 /**
  51  * @brief Called once after the main loop of the agent application exits.
  52  *
  53  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  54  *
  55  * @param[in] user_data The user data passed from the callback registration function
  56  * @see service_app_main()
  57  * @see #service_app_lifecycle_callback_s
  58  */
  59 typedef void (*service_app_terminate_cb) (void *user_data);
  60
  61
  62 /**
  63  * @brief Called when another application sends the launch request to the agent application.
  64  *
  65  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  66  *
  67  * @param[in] app_control The handle to the app_control
  68  * @param[in] user_data The user data passed from the callback registration function
  69  * @see service_app_main()
  70  * @see #service_app_lifecycle_callback_s
  71  * @see @ref CAPI_APP_CONTROL_MODULE API
  72  */
  73 typedef void (*service_app_control_cb) (app_control_h app_control, void *user_data);
  74
  75
  76 /**
  77  * @brief The structure type containing the set of callback functions for handling application events.
  78  * @details It is one of the input parameters of the service_app_efl_main() function.
  79  *
  80  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  81  *
  82  * @see service_app_main()
  83  * @see service_app_create_cb()
  84  * @see service_app_terminate_cb()
  85  * @see service_app_control_cb()
  86  */
  87 typedef struct {
  88         service_app_create_cb create; /**< This callback function is called at the start of the application. */
  89         service_app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */
  90         service_app_control_cb app_control; /**< This callback function is called when another application sends the launch request to the application. */
  91 } service_app_lifecycle_callback_s;
  92
  93
  94 /**
  95  * @brief Adds the system event handler
  96  *
  97  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  98  * @remarks The service application can handle low memory event, low battery event, language setting changed event and region format changed event.
  99  * @param[out] handler The event handler
 100  * @param[in] event_type The system event type
 101  * @param[in] callback The callback function
 102  * @param[in] user_data The user data to be passed to the callback function
 103  *
 104  * @return 0 on success, otherwise a negative error value
 105  * @retval #APP_ERROR_NONE Successfull
 106  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 107  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 108  *
 109  * @see app_event_type_e
 110  * @see app_event_cb
 111  * @see service_app_remove_event_handler
 112  */
 113 int service_app_add_event_handler(app_event_handler_h *handler, app_event_type_e event_type, app_event_cb callback, void *user_data);
 114
 115
 116 /**
 117  * @brief Removes registered event handler
 118  *
 119  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 120  * @param[in] event_handler The event handler
 121  *
 122  * @return 0 on success, otherwise a negative error value
 123  * @retval #APP_ERROR_NONE Successfull
 124  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 125  *
 126  * @see service_app_add_event_handler
 127  */
 128 int service_app_remove_event_handler(app_event_handler_h event_handler);
 129
 130
 131 /**
 132  * @brief Runs the main loop of the application until service_app_exit() is called.
 133  *
 134  * @details This function is the main entry point of the Tizen service application.
 135  *          This main loop supports event handling for the GMainLoop and the Ecore Main Loop.
 136  *
 137  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 138  *
 139  * @param[in] argc The argument count
 140  * @param[in] argv The argument vector
 141  * @param[in] callback The set of callback functions to handle application events
 142  * @param[in] user_data The user data to be passed to the callback functions
 143  *
 144  * @return @c 0 on success,
 145  *         otherwise a negative error value.
 146  * @retval #APP_ERROR_NONE Successful
 147  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 148  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system.
 149  * @retval #APP_ERROR_ALREADY_RUNNING The main loop has already started
 150  *
 151  * @see service_app_create_cb()
 152  * @see service_app_terminate_cb()
 153  * @see service_app_control_cb()
 154  * @see service_app_exit()
 155  * @see #service_app_lifecycle_callback_s
 156  */
 157 int service_app_main(int argc, char **argv, service_app_lifecycle_callback_s *callback, void *user_data);
 158
 159
 160 /**
 161  * @brief Exits the main loop of the application.
 162  *
 163  * @details The main loop of the application stops and service_app_terminate_cb() is invoked.
 164  *
 165  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 166  *
 167  * @see service_app_main()
 168  * @see service_app_terminate_cb()
 169  */
 170 void service_app_exit(void);
 171
 172 /**
 173  * @}
 174  */
 175
 176 #ifdef __cplusplus
 177 }
 178 #endif
 179
 180 #endif /* __TIZEN_APPFW_SERVICE_APP_H__ */