include/push-service.h

   1 /*
   2  * Copyright (c) 2000 - 2012 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 #ifndef __PUSH_PUBLIC_LIB_H__
  18 #define __PUSH_PUBLIC_LIB_H__
  19
  20 #include <tizen_error.h>
  21 #include <app.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file push-service.h
  29  */
  30
  31 /**
  32  * @addtogroup CAPI_MESSAGING_PUSH_PUBLIC_MODULE
  33  * @{
  34  */
  35
  36 /**
  37  * @brief Enumerations of error codes for push API.
  38  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  39  */
  40 typedef enum {
  41         PUSH_SERVICE_ERROR_NONE = TIZEN_ERROR_NONE,   /**< Successful */
  42         PUSH_SERVICE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,   /**< Out of memory */
  43         PUSH_SERVICE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  44         PUSH_SERVICE_ERROR_NOT_CONNECTED = TIZEN_ERROR_CONNECTION,  /**< Not connected */
  45         PUSH_SERVICE_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA,  /**< No data available */
  46         PUSH_SERVICE_ERROR_OPERATION_FAILED = TIZEN_ERROR_UNKNOWN, /**< Internal operation failed */
  47         PUSH_SERVICE_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< No privilege to access the push service */
  48         PUSH_SERVICE_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Push service not supported */
  49 } push_service_error_e;
  50
  51 /**
  52  * @brief Enumeration of registration states.
  53  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  54  */
  55 typedef enum {
  56         PUSH_SERVICE_STATE_REGISTERED,   /**< Registred */
  57         PUSH_SERVICE_STATE_UNREGISTERED, /**< Unregistered */
  58         PUSH_SERVICE_STATE_PROVISIONING_IPCHANGE, /**< To change the provisining server IP */
  59         PUSH_SERVICE_STATE_PING_CHANGE,       /**< Ping interval is changing */
  60         PUSH_SERVICE_STATE_ERROR,       /**< Error */
  61 } push_service_state_e;
  62
  63 /**
  64  * @brief Enumeration of result.
  65  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  66  */
  67 typedef enum {
  68         PUSH_SERVICE_RESULT_SUCCESS,  /**< Successful */
  69         PUSH_SERVICE_RESULT_TIMEOUT,  /**< Request timed out */
  70         PUSH_SERVICE_RESULT_SERVER_ERROR,  /**< Push server error */
  71         PUSH_SERVICE_RESULT_SYSTEM_ERROR,  /**< System error */
  72 } push_service_result_e;
  73
  74 /**
  75  * @brief Connection to the push service handle.
  76  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  77  */
  78 typedef struct push_connection_s *push_service_connection_h;
  79
  80 /**
  81  * @brief Notification delivered from the push server handle.
  82  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  83  */
  84 typedef struct push_notification_s *push_service_notification_h;
  85
  86 /**
  87  * @brief Called when the registration state is refreshed.
  88  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  89  * @remarks This callback will be invoked when the registration state is refreshed. \n
  90  *          If the registration or deregistration has succeeded, then this state callback must be called. \n
  91  *          In addition, the state can be changed if the push server deregisters the application.
  92  * @param[in] state The registration state
  93  * @param[in] err  The error message
  94  * @param[in] user_data The user data passed to this callback
  95  * @see push_service_connect()
  96  */
  97 typedef void (*push_service_state_cb)(
  98                 push_service_state_e state, const char *err, void *user_data);
  99
 100 /**
 101  * @brief Called to handle a notification.
 102  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 103  * @param[in] notification A handle of the notification containing its payload\n
 104  *                         The handle is available inside this callback only.
 105  * @param[in] user_data The user data passed to this callback
 106  * @see push_service_connect()
 107  * @see push_service_get_notification_data()
 108  */
 109 typedef void (*push_service_notify_cb)(
 110                 push_service_notification_h noti, void *user_data);
 111
 112 /**
 113  * @brief Called with the result of a registration/deregistration.
 114  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 115  * @param[in] result The registration/deregistration result
 116  * @param[in] msg The result message from the push server,
 117  *                otherwise @c NULL
 118  * @param[in] user_data The user data passed to this callback
 119  * @see push_service_register()
 120  * @see push_service_deregister()
 121  */
 122 typedef void (*push_service_result_cb)(push_service_result_e result, const char *msg, void *user_data);
 123
 124 /**
 125  * @brief Connects to the push service and sets callback functions.
 126  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 127  * @privlevel public
 128  * @privilege %http://tizen.org/privilege/push
 129  * @remarks If there is a connection between an application and the push service,\n
 130  *          the notify callback passes the notification upon its arrival.\n
 131  *          Otherwise, the push service posts a UI notification to alert users.\n
 132  *          The connection should be freed with push_service_disconnect() by you.
 133  * @param[in] push_app_id App id received from Tizen Push Server team
 134  * @param[in] state_callback State callback function
 135  * @param[in] notify_callback Notify callback function
 136  * @param[in] user_data User data to pass to <I>state_cb</I> and <I>notify_cb</I>
 137  * @param[out] connection The connection handle to the push service
 138  * @return @c 0 on success,
 139  *         otherwise a negative error value
 140  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 141  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 142  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 143  * @retval #PUSH_SERVICE_ERROR_NOT_CONNECTED Connection to the daemon failed
 144  * @retval #PUSH_SERVICE_ERROR_PERMISSION_DENIED No push privilege
 145  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 146  * @pre There is no connection to the push service for the <I>app_id</I>.
 147  * @post The state callback will be called to let you know the current
 148  *       registration state immediately.
 149  * @see push_service_disconnect()
 150  */
 151 int push_service_connect(const char *push_app_id,
 152                 push_service_state_cb state_callback,
 153                 push_service_notify_cb notify_callback, void *user_data,
 154                 push_service_connection_h *connection);
 155
 156 /**
 157  * @brief Closes the connection and releases all its resources
 158  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 159  * @remarks If you call this function in the push callback functions,\n
 160  *          it may cause your application to crash.\n
 161  *                      The specific error code can be obtained using the get_last_result()\n
 162  *                      Error codes are described in the exception section.
 163  * @param[in] connection The connection handle to the push service
 164  * @exception #PUSH_SERVICE_ERROR_NONE Successful
 165  * @exception #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 166  * @exception #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 167  * @see push_service_connect()
 168  */
 169 void push_service_disconnect(push_service_connection_h connection);
 170
 171 /**
 172  * @brief Registers an application to the push server.
 173  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 174  * @param[in] connection The connection handle to the push service
 175  * @param[in] result_callback  Result callback function
 176  * @param[in] user_data  User data to pass to <I>result_cb</I>
 177  * @return @c 0 on success,
 178  *         otherwise a negative error value
 179  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 180  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 181  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 182  * @retval #PUSH_SERVICE_ERROR_NOT_CONNECTED No connection to the push service
 183  * @retval #PUSH_SERVICE_ERROR_OPERATION_FAILED Operation failed
 184  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 185  * @pre The application should be connected to the push service.
 186  * @post As a result, the state callback will be invoked.
 187  * @see push_service_deregister()
 188  */
 189 int push_service_register(push_service_connection_h connection,
 190                 push_service_result_cb result_callback, void *user_data);
 191
 192 /**
 193  * @brief Deregisters an application from the Push server.
 194  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 195  * @param[in] connection The connection handle to the push service
 196  * @param[in] result_callback Result callback function
 197  * @param[in] user_data User data to pass to <I>result_cb</I>
 198  * @return @c 0 on success,
 199  *         otherwise a negative error value
 200  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 201  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 202  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 203  * @retval #PUSH_SERVICE_ERROR_NOT_CONNECTED No connection to the push service
 204  * @retval #PUSH_SERVICE_ERROR_OPERATION_FAILED Operation failed
 205  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 206  * @pre The application should be connected to the push service.
 207  * @post As a result, the state callback will be invoked.
 208  * @see push_service_register()
 209  */
 210 int push_service_deregister(push_service_connection_h connection, push_service_result_cb result_callback,
 211                 void *user_data);
 212
 213 /**
 214  * @brief Retrieves the payload data of a notification that forcibly launched the app.
 215  * @details When a notification arrives at the device with the "LAUNCH"\n
 216  *                      option or a user clicks a notification in the quick panel,\n
 217  *          the push daemon forcibly launches the app and delivers the\n
 218  *          notification to the app as a bundle. This function returns\n
 219  *                      the payload data in the notificaiton.
 220  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 221  * @privlevel public
 222  * @privilege %http://tizen.org/privilege/push
 223  * @remark This function must be called in the app control callback function.\n
 224  *                 You must release the payload data using free().\n
 225  *                 push_service_app_control_to_notification() is preferred to this API.\n
 226  *                 The specific error code can be obtained using the get_last_result()\n
 227  *                 Error codes are described in the exception section.
 228  * @param[in] app_control The app control handle that is handed over in the\n
 229  *                        app control callback function
 230  * @param[in] operation The operation in the app control handle retrieved by\n
 231  *                        app_control_get_operation()
 232  * @return The payload data (appData) in the notification\n
 233  *         NULL if the app is not launched by a push notification.
 234  * @exception #PUSH_SERVICE_ERROR_NONE Successful
 235  * @exception #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 236  * @exception #PUSH_SERVICE_ERROR_NO_DATA       Not launched by a notification
 237  * @exception #PUSH_SERVICE_ERROR_OPERATION_FAILED Operation fail
 238  * @exception #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 239  * @exception #PUSH_SERVICE_ERROR_NOT_CONNECTED Connection to the daemon failed
 240  * @exception #PUSH_SERVICE_ERROR_PERMISSION_DENIED No push privilege
 241  * @exception #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 242  * @see app_control_get_operation()
 243  */
 244 char *push_service_app_control_to_noti_data(app_control_h app_control, char *operation);
 245
 246 /**
 247  * @brief Retrieves the notification that forcibly launched the app.
 248  * @details When a notification arrives at the device with the "LAUNCH"\n
 249  *                      option or a user clicks a notification in the quick panel,\n
 250  *          the push daemon forcibly launches the app and delivers the\n
 251  *          notification to the app as a bundle. This function returns\n
 252  *                      the notificaiton from the bundle.
 253  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 254  * @privlevel public
 255  * @privilege %http://tizen.org/privilege/push
 256  * @remark This function must be called in the app control callback function.\n
 257  *                 You must release the notification using push_service_free_notification().
 258  * @param[in] app_control The app control handle that is handed over in the\n
 259  *                        app control callback function
 260  * @param[in] operation The operation in the app control handle retrieved by\n
 261  *                        app_control_get_operation()
 262  * @param[out] noti     The handle of the notification that forcibly launched the app
 263  * @return @c 0 on success,
 264  *         otherwise a negative error value
 265  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 266  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 267  * @retval #PUSH_SERVICE_ERROR_NO_DATA  Not launched by a notification
 268  * @retval #PUSH_SERVICE_ERROR_OPERATION_FAILED Operation fail
 269  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 270  * @retval #PUSH_SERVICE_ERROR_NOT_CONNECTED Connection to the daemon failed
 271  * @retval #PUSH_SERVICE_ERROR_PERMISSION_DENIED No push privilege
 272  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 273  * @see push_service_free_notificaiton()
 274  * @see app_control_get_operation()
 275  */
 276 int push_service_app_control_to_notification(app_control_h app_control, char *operation, push_service_notification_h *noti);
 277
 278 /**
 279  * @brief Gets notification data sent by the server.
 280  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 281  * @remarks You must release @a data using free().
 282  * @param[in] notification The notification handle
 283  * @param[out] data The notification data\n
 284  *                  Set NULL if error but <I>PUSH_SERVICE_ERROR_INVALID_PARAMETER</I>
 285  * @return @c 0 on success,
 286  *         otherwise a negative error value
 287  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 288  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 289  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 290  * @retval #PUSH_SERVICE_ERROR_NO_DATA No data available
 291  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 292  * @see push_service_notify_cb()
 293  * @see push_service_request_unread_notification()
 294  */
 295 int push_service_get_notification_data(push_service_notification_h notification, char **data);
 296
 297 /**
 298  * @brief Gets the notification message sent by the server.
 299  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 300  * @remark The <I>msg</I> must be released with free().\n
 301  *                 push_service_request_unread_notification() is\n
 302  *                 preferred to this API.
 303  * @param[in] notification The notification handle
 304  * @param[out] msg The notification message\n
 305  *                  Set NULL if error but <I>PUSH_SERVICE_ERROR_INVALID_PARAMETER</I>
 306  * @return @c 0 on success,
 307  *         otherwise a negative error value
 308  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 309  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 310  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 311  * @retval #PUSH_SERVICE_ERROR_NO_DATA No data available
 312  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 313  * @see push_service_notify_cb()
 314  * @see push_service_get_unread_notification()
 315  */
 316 int push_service_get_notification_message(push_service_notification_h notification,
 317                 char **msg);
 318
 319 /**
 320  * @brief Gets the received time of the notification message.
 321  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 322  * @param[in] notification The notification handle
 323  * @param[out] received_time The received time of the notification message \n
 324  *                           The @a received_time is based on UTC.
 325  * @return @c 0 on success,
 326  *         otherwise a negative error value
 327  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 328  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 329  * @retval #PUSH_SERVICE_ERROR_NO_DATA No data available
 330  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 331  * @see push_service_notify_cb()
 332  * @see push_service_request_unread_notification()
 333  */
 334 int push_service_get_notification_time(push_service_notification_h notification, long long int *received_time);
 335
 336 /**
 337  * @brief Gets the sender of the notification.
 338  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 339  * @remarks You must release @a sender using free().
 340  * @param[in] notification The notification handle
 341  * @param[out] sender The sender\n
 342  *                  Set @c NULL if error but #PUSH_SERVICE_ERROR_INVALID_PARAMETER
 343  * @return @c 0 on success,
 344  *         otherwise a negative error value
 345  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 346  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 347  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 348  * @retval #PUSH_SERVICE_ERROR_NO_DATA No data available
 349  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 350  * @see push_service_notify_cb()
 351  * @see push_serivce_get_unread_notification()
 352  */
 353 int push_service_get_notification_sender(push_service_notification_h notification,
 354                 char **sender);
 355
 356 /**
 357  * @brief Gets the session ID of the notification.
 358  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 359  * @remarks You must release @a session_info using free().
 360  * @param[in] notification The notification handle
 361  * @param[out] session_info The session ID\n
 362  *                  Set @c NULL if error but #PUSH_SERVICE_ERROR_INVALID_PARAMETER
 363  * @return @c 0 on success,
 364  *         otherwise a negative error value
 365  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 366  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 367  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 368  * @retval #PUSH_SERVICE_ERROR_NO_DATA No data available
 369  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 370  * @see push_service_notify_cb()
 371  * @see push_service_request_unread_notification()
 372  */
 373 int push_service_get_notification_session_info(push_service_notification_h notification,
 374                 char **session_info);
 375
 376
 377 /**
 378  * @brief Gets the request ID assigned by the sender.
 379  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 380  * @remarks You must release @a request_id using free().
 381  * @param[in] notification The notification handle
 382  * @param[out] request_id The request ID\n
 383  *                  Set @c NULL if error but #PUSH_SERVICE_ERROR_INVALID_PARAMETER
 384  * @return @c 0 on success,
 385  *         otherwise a negative error value
 386  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 387  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 388  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 389  * @retval #PUSH_SERVICE_ERROR_NO_DATA No data available
 390  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 391  * @see push_service_notify_cb()
 392  * @see push_service_request_unread_notification()
 393  */
 394 int push_service_get_notification_request_id(push_service_notification_h notification,
 395                 char **request_id);
 396
 397 /**
 398  * @brief Gets the value in the type field of the notification
 399  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 400  * @param[in] notification The notification handle
 401  * @param[out] type The type value assigned by the sender
 402  * @return @c 0 on success,
 403  *         otherwise a negative error value
 404  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 405  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 406  * @retval #PUSH_SERVICE_ERROR_NO_DATA No data available
 407  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 408  * @see push_service_notify_cb()
 409  * @see push_service_request_unread_notification()
 410  */
 411 int push_service_get_notification_type(push_service_notification_h notification, int *type);
 412
 413 /**
 414  * @brief Gets an unread notification message from the push server.
 415  * @details If an application receives an unread message with this method, the message is removed from the system. \n
 416  *          This method can be called repeatedly until it returns <I>PUSH_SERVICE_ERROR_NO_DATA</I> \n
 417  *          But, this method does NOT guarantee order and reliability of notification messages. \n
 418  *          Some notification messages can be dropped when the system message queue is full.
 419  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 420  * @remarks It is recommended to use push_service_request_unread_notification().
 421  * @remarks You must release @a noti using push_service_free_notification().
 422  * @param[in] connection The connection handle to the push service
 423  * @param[out] noti The notification handle
 424  * @return @c 0 on success,
 425  *         otherwise a negative error value
 426  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 427  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 428  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 429  * @retval #PUSH_SERVICE_ERROR_NO_DATA No data available
 430  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 431  *
 432  * @see push_service_get_notification_message()
 433  * @see push_service_get_notification_time()
 434  * @see push_service_get_notification_data()
 435  */
 436 int push_service_get_unread_notification(push_service_connection_h connection,
 437                 push_service_notification_h *noti);
 438
 439 /**
 440  * @brief Requests unread notification messages to the push server.
 441  * @details When the app wants to receive messages that arrived before it launched, this  \n
 442  *          method should be called. Upon receiving ths request, the daemon sends messages\n
 443  *          stored in its DB to the app. The notify_callback() method assigned in push_service_connect()\n
 444  *          will be called when these messages arrive. No need to call this method multiple\n
 445  *          times to receive multiple messages. This method does NOT guarantee order and\n
 446  *          reliability of notification messages.
 447  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 448  * @remarks This method is preferred to push_service_get_unread_notification().
 449  * @param[in] connection The connection handle to the push service
 450  * @return @c 0 on success,
 451  *         otherwise a negative error value
 452  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 453  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 454  * @retval #PUSH_SERVICE_ERROR_NOT_CONNECTED Not connected to the daemon
 455  * @retval #PUSH_SERVICE_ERROR_OPERATION_FAILED Error when sending the request
 456  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 457  *
 458  * @see push_service_get_unread_notification()
 459  * @see push_service_connect()
 460  */
 461 int push_service_request_unread_notification(push_service_connection_h connection);
 462
 463 /**
 464  * @brief Gets the registration ID in the <I>PUSH_SERVICE_STATE_REGISTERED</I> state.
 465  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 466  * @remarks You must release @a reg_id using free().
 467  * @param[in] connection The connection handle to the push service
 468  * @param[out] reg_id The registration ID\n
 469  *                    Set NULL if error but <I>PUSH_SERVICE_ERROR_INVALID_PARAMETER</I>
 470  * @return @c 0 on success,
 471  *         otherwise a negative error value
 472  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 473  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 474  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 475  * @retval #PUSH_SERVICE_ERROR_NO_DATA No registration ID available
 476  * @retval #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 477  */
 478 int push_service_get_registration_id(push_service_connection_h connection, char **reg_id);
 479
 480 /**
 481  * @brief Frees the notification handle.
 482  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 483  * @remark The specific error code can be obtained using the get_last_result()\n
 484  *                 Error codes are described in the exception section.
 485  * @param[in] noti The notification handle
 486  * @exception #PUSH_SERVICE_ERROR_NONE Successful
 487  * @exception #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 488  * @exception #PUSH_SERVICE_ERROR_NOT_SUPPORTED Not supported feature
 489  */
 490 void push_service_free_notification(push_service_notification_h noti);
 491
 492 /**
 493  * @}
 494  */
 495
 496
 497 #ifdef __cplusplus
 498 }
 499 #endif
 500
 501 #endif /* __PUSH_PUBLIC_LIB_H__ */