arm/include/push.h

   1 //
   2 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Flora License, Version 1.1 (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://floralicense.org/license/
   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 #ifndef __PUSH_LIB_H__
  18 #define __PUSH_LIB_H__
  19
  20 #include <errno.h>
  21 #include <app.h>
  22
  23 #define PUSH_APP_DATA_KEY  "http://tizen.org/appcontrol/data/push/appdata"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @addtogroup CAPI_MESSAGING_PUSH_MODULE
  31  * @{
  32  */
  33
  34 /**
  35  * @file push.h
  36  * @ingroup CAPI_MESSAGING_FRAMEWORK
  37  * @brief Support to receive push notifications
  38  */
  39
  40 /**
  41  * @brief Enumerations of error codes for push API
  42  */
  43 typedef enum {
  44         PUSH_ERROR_NONE = 0,   /**< Successful */
  45         PUSH_ERROR_OUT_OF_MEMORY = -ENOMEM,   /**< Out of memory */
  46         PUSH_ERROR_INVALID_PARAMETER = -EINVAL,   /**< Invalid parameter */
  47         PUSH_ERROR_NOT_CONNECTED = -ENOTCONN,  /**< Not connected */
  48         PUSH_ERROR_NO_DATA = -ENODATA,  /**< No data available */
  49         PUSH_ERROR_OPERATION_FAILED = -0x00004300, /**< Internal operation failed */
  50 } push_error_e;
  51
  52 /**
  53  * @brief Enumerations of registration state
  54  */
  55 typedef enum {
  56         PUSH_STATE_REGISTERED,   /**< Registred */
  57         PUSH_STATE_UNREGISTERED, /**< Unregistered */
  58         PUSH_STATE_ERROR,       /**< Error */
  59 } push_state_e;
  60
  61 /**
  62  * @brief Enumerations of result
  63  */
  64 typedef enum {
  65         PUSH_RESULT_SUCCESS,  /**< Successful */
  66         PUSH_RESULT_TIMEOUT,  /**< Request timed out */
  67         PUSH_RESULT_SERVER_ERROR,  /**< Push server error */
  68         PUSH_RESULT_SYSTEM_ERROR,  /**< System error */
  69 } push_result_e;
  70
  71 /**
  72  * @brief Handle of a connection to the push service
  73  */
  74 typedef struct push_connection_s *push_connection_h;
  75
  76 /**
  77  * @brief Handle of a notification delivered from the push server
  78  */
  79 typedef struct push_notification_s *push_notification_h;
  80
  81 /**
  82  * @brief State callback
  83  * @remarks This callback will be invoked when the regisration state is
  84  * refreshed. If the registration or degistration has been succeeded,
  85  * then this state callback must be called. In addition, the state
  86  * can be changed if the push server deregisters the application.
  87  * @param[in] state Registration state
  88  * @param[in] err  Error message
  89  * @param[in] user_data User data passed to this callback
  90  * @see push_connect()
  91  */
  92 typedef void (*push_state_cb)(
  93                 push_state_e state, const char *err, void *user_data);
  94
  95 /**
  96  * @brief Notifcation callback
  97  * @param[in] notification A handle of notification containing its payload.
  98  * The handle is available inside this callback only.
  99  * @param[in] user_data User data passed to this callback
 100  * @see push_connect(), push_get_notification_data()
 101  */
 102 typedef void (*push_notify_cb)(
 103                 push_notification_h noti, void *user_data);
 104
 105 /**
 106  * @brief Result callback
 107  * @param[in] result Registration/deregistration result
 108  * @param[in] msg Result message from the push server or NULL
 109  * @param[in] user_data User data passed to this callback
 110  * @see push_register(), push_deregister()
 111  */
 112 typedef void (*push_result_cb)(push_result_e result, const char *msg, void *user_data);
 113
 114 /**
 115  * @brief Connects to the push service and sets callback functions
 116  * @remarks If there is a connection between an application and the push service,
 117  * the notify callback passes the notification upon its arrival.
 118  * Otherwise, the push service posts a UI notification to alert users.
 119  * Connection should be freed with @ref push_disconnect() by you.
 120  * @param[in] app_id The application ID
 121  * @param[in] state_cb State callback function
 122  * @param[in] notify_cb Notify callback function
 123  * @param[in] user_data User data to pass to <I>state_cb</I> and <I>notify_cb</I>
 124  * @param[out] connection The connection handle to the push service
 125  * @return 0 on success, otherwise a negative error value.
 126  * @retval PUSH_ERROR_NONE Successful
 127  * @retval PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 128  * @retval PUSH_ERROR_OUT_OF_MEMORY Out of memory
 129  * @retval PUSH_ERROR_OPERATION_FAILED Operation failed
 130  * @pre There is no connection for the <I>app_id</I> to the push service
 131  * @post The state callback will be called to let you know the current
 132  * registration state immediately.
 133  * @see push_disconnect()
 134  */
 135 int push_connect(const char *app_id, push_state_cb state_callback,
 136                 push_notify_cb notify_callback, void *user_data,
 137                 push_connection_h *connection);
 138
 139 /**
 140  * @brief Closes the connection and releases all its resources
 141  * @remarks If you call this function in the push callback functions,
 142  *          it may cause your application crash.
 143  * @param[in] connection Handle of a connection to the push service
 144  * @see push_connect()
 145  */
 146 void push_disconnect(push_connection_h connection);
 147
 148 /**
 149  * @brief Registers an application to the push server
 150  * @param[in] connection The connection handle to the push service
 151  * @param[in] service A @ref Service handle to launch an application by
 152  * an posted UI notification
 153  * @param[in] result_cb  Result callback function
 154  * @param[in] user_data  User data to pass to <I>result_cb</I>
 155  * @return 0 on success, otherwise a negative error value.
 156  * @retval PUSH_ERROR_NONE Successful
 157  * @retval PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 158  * @retval PUSH_ERROR_OUT_OF_MEMORY Out of memory
 159  * @retval PUSH_ERROR_NOT_CONNECTED No connection to the push service
 160  * @retval PUSH_ERROR_OPERATION_FAILED Operation failed
 161  * @pre The application should be connected to the push service
 162  * @post For successful result, the state callback should be invoked
 163  * @see push_deregister()
 164  */
 165 int push_register(push_connection_h connection, service_h service,
 166                 push_result_cb result_callback, void *user_data);
 167
 168 /**
 169  * @brief Deregisters an application from the Push server
 170  * @param[in] connection The connection handle to the push service
 171  * @param[in] result_cb Result callback function
 172  * @param[in] user_data User data to pass to <I>result_cb</I>
 173  * @return 0 on success, otherwise a negative error value.
 174  * @retval PUSH_ERROR_NONE Successful
 175  * @retval PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 176  * @retval PUSH_ERROR_OUT_OF_MEMORY Out of memory
 177  * @retval PUSH_ERROR_NOT_CONNECTED No connection to the push service
 178  * @retval PUSH_ERROR_OPERATION_FAILED Operation failed
 179  * @pre The application should be connected to the push service
 180  * @post In result, the state callback will be invoked
 181  * @see push_register()
 182  */
 183 int push_deregister(push_connection_h connection, push_result_cb callback,
 184                 void *user_data);
 185
 186 /**
 187  * @brief Gets notification data which its server sent
 188  * @remark The <I>data</I> must be released with free() by you
 189  * @param[in] notification The notification handle
 190  * @param[out] data The notification data\n
 191  *                  Set NULL if error but <I>PUSH_ERROR_INVALID_PARAMETER</I>
 192  * @return 0 on success, otherwise a negative error value.
 193  * @retval PUSH_ERROR_NONE Successful
 194  * @retval PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 195  * @retval PUSH_ERROR_OUT_OF_MEMORY Out of memory
 196  * @retval PUSH_ERROR_NO_DATA No data available
 197  * @see push_notify_cb()
 198  * @see push_get_unread_notification()
 199  */
 200 int push_get_notification_data(push_notification_h notification, char **data);
 201
 202
 203 /**
 204  * @brief Gets the notification message which its server sent
 205  * @remark The <I>msg</I> must be released with free() by you
 206  * @param[in] notification The notification handle
 207  * @param[out] data The notification message\n
 208  *                  Set NULL if error but <I>PUSH_ERROR_INVALID_PARAMETER</I>
 209  * @return 0 on success, otherwise a negative error value.
 210  * @retval PUSH_ERROR_NONE Successful
 211  * @retval PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 212  * @retval PUSH_ERROR_OUT_OF_MEMORY Out of memory
 213  * @retval PUSH_ERROR_NO_DATA No data available
 214  * @see push_notify_cb()
 215  * @see push_get_unread_notification()
 216  */
 217 int push_get_notification_message(push_notification_h notification,
 218                 char **msg);
 219
 220 /**
 221  * @brief Gets the received time of the notification message
 222  *
 223  * @param[in] notification The notification handle
 224  * @param[out] received_time The received time of the notification message. \n
 225  *                           The @a received_time is based on UTC.
 226  * @return 0 on success, otherwise a negative error value.
 227  * @retval PUSH_ERROR_NONE Successful
 228  * @retval PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval PUSH_ERROR_NO_DATA No data available
 230  *
 231  * @see push_notify_cb()
 232  * @see push_get_unread_notification()
 233  */
 234 int push_get_notification_time(push_notification_h notification, long long int *received_time);
 235
 236 /**
 237  * @brief Gets an unread notification message from the push server
 238  *
 239  * @remark This method will be deprecated.
 240  * @remark @a noti must be released with push_free_notification() by you
 241  *
 242  * @details If an application receives an unread message with this method, the message is removed from the system. \n
 243  *          This method can be called repeatedly until it returns <I>PUSH_ERROR_NO_DATA</I> \n
 244  *          But, this method does NOT guarantee order and reliability of notification messages. \n
 245  *          Some notification messages can be dropped when the system message queue is full.
 246  *
 247  * @param[in] connection The connection handle to the push service
 248  * @param[out] noti The notification handle
 249  * @return 0 on success, otherwise a negative error value.
 250  * @retval PUSH_ERROR_NONE Successful
 251  * @retval PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 252  * @retval PUSH_ERROR_OUT_OF_MEMORY Out of memory
 253  * @retval PUSH_ERROR_NO_DATA No data available
 254  *
 255  * @see push_get_notification_message()
 256  * @see push_get_notification_time()
 257  * @see push_get_notification_data()
 258  */
 259 int push_get_unread_notification(push_connection_h connection,
 260                 push_notification_h *noti);
 261
 262
 263 /**
 264  * @brief Gets the registration ID in <I>PUSH_STATE_REGISTERED</I> state
 265  * @remark The <I>reg_id</I> must be released with free() by you
 266  * @param[in] connection The connection handle to the push service
 267  * @param[out] reg_id The registration ID\n
 268  *                    Set NULL if error but <I>PUSH_ERROR_INVALID_PARAMETER</I>
 269  * @return 0 on success, otherwise a negative error value
 270  * @retval PUSH_ERROR_NONE Successful
 271  * @retval PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 272  * @retval PUSH_ERROR_OUT_OF_MEMORY Out of memory
 273  * @retval PUSH_ERROR_NO_DATA No registration ID available
 274  */
 275 int push_get_registration_id(push_connection_h connection, char **reg_id);
 276
 277
 278 /**
 279  * @brief Frees the notification handle
 280  * @param[in] noti The notification handle
 281  */
 282 void push_free_notification(push_notification_h noti);
 283 /**
 284  * @}
 285  */
 286
 287 #ifdef __cplusplus
 288 }
 289 #endif
 290
 291 #endif /* __PUSH_LIB_H__ */