include/push.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_LIB_H__
  18 #define __PUSH_LIB_H__
  19
  20 #include <app.h>
  21 #include <tizen_error.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file push.h
  29  */
  30
  31 /**
  32  * @internal
  33  * @addtogroup CAPI_MESSAGING_PUSH_MODULE
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Enumeration of error codes for push API.
  39  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  40  */
  41 typedef enum {
  42         PUSH_ERROR_NONE = TIZEN_ERROR_NONE,   /**< Successful */
  43         PUSH_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,   /**< Out of memory */
  44         PUSH_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  45         PUSH_ERROR_NOT_CONNECTED = TIZEN_ERROR_CONNECTION,  /**< Not connected */
  46         PUSH_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA,  /**< No data available */
  47         PUSH_ERROR_OPERATION_FAILED = TIZEN_ERROR_UNKNOWN, /**< Internal operation failed */
  48         PUSH_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< No privilege to access the push service */
  49         PUSH_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Push not supported */
  50 } push_error_e;
  51
  52 /**
  53  * @brief Enumeration of registration states.
  54  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  55  */
  56 typedef enum {
  57         PUSH_STATE_REGISTERED,   /**< Registered */
  58         PUSH_STATE_UNREGISTERED, /**< Unregistered */
  59         PUSH_STATE_PROVISIONING_IPCHANGE, /**< To change the provisioning server IP */
  60         PUSH_STATE_PING_CHANGE,       /**< Ping interval is changing */
  61         PUSH_STATE_ERROR,       /**< Error */
  62 } push_state_e;
  63
  64 /**
  65  * @brief Enumeration of result.
  66  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  67  */
  68 typedef enum {
  69         PUSH_RESULT_SUCCESS,  /**< Successful */
  70         PUSH_RESULT_TIMEOUT,  /**< Request timed out */
  71         PUSH_RESULT_SERVER_ERROR,  /**< Push server error */
  72         PUSH_RESULT_SYSTEM_ERROR,  /**< System error */
  73 } push_result_e;
  74
  75 /**
  76  * @brief Connection to the push service handle.
  77  */
  78 typedef struct push_connection_s *push_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_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_connect()
  96  */
  97 typedef void (*push_state_cb)(
  98                 push_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_connect()
 107  * @see push_get_notification_data()
 108  */
 109 typedef void (*push_notify_cb)(
 110                 push_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_register()
 120  * @see push_deregister()
 121  */
 122 typedef void (*push_result_cb)(push_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,
 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 using push_disconnect().
 133  * @param[in] app_id The application ID
 134  * @param[in] state_cb The state callback function
 135  * @param[in] notify_cb The notify callback function
 136  * @param[in] user_data The user data to pass to @a state_cb and @a notify_cb
 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_ERROR_NONE Successful
 141  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 142  * @retval #PUSH_ERROR_OUT_OF_MEMORY Out of memory
 143  * @retval #PUSH_ERROR_NOT_CONNECTED Connection to the daemon failed
 144  * @retval #PUSH_ERROR_PERMISSION_DENIED No push privilege
 145  * @pre There is no connection for the @a app_id to the push service.
 146  * @post The state callback will be called to let you know the current
 147  *       registration state immediately.
 148  * @see push_disconnect()
 149  */
 150 int push_connect(const char *push_app_id, push_state_cb state_callback,
 151                 push_notify_cb notify_callback, void *user_data,
 152                 push_connection_h *connection);
 153
 154 /**
 155  * @brief Closes the connection and releases all its resources.
 156  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 157  * @privlevel public
 158  * @remarks If you call this function in the push callback functions,
 159  *          it may cause your application to crash.
 160  * @param[in] connection A connection to the push service handle
 161  * @see push_connect()
 162  */
 163 void push_disconnect(push_connection_h connection);
 164
 165 /**
 166  * @brief Registers an application to the push server.
 167  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 168  * @privlevel public
 169  * @param[in] connection The connection handle to the push service
 170  * @param[in] app_control An @ref CAPI_APP_CONTROL_MODULE handle to launch an application by\n
 171  * an posted UI notification
 172  * @param[in] result_callback  Result callback function
 173  * @param[in] user_data  The user data to pass to @a result_cb
 174  * @return @c 0 on success,
 175  *         otherwise a negative error value
 176  * @retval #PUSH_ERROR_NONE Successful
 177  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 178  * @retval #PUSH_ERROR_OUT_OF_MEMORY Out of memory
 179  * @retval #PUSH_ERROR_NOT_CONNECTED No connection to the push service
 180  * @retval #PUSH_ERROR_OPERATION_FAILED Operation failed
 181  * @pre The application should be connected to the push service.
 182  * @post For successful result, the state callback should be invoked.
 183  * @see push_deregister()
 184  */
 185 int push_register(push_connection_h connection, app_control_h app_control,
 186                 push_result_cb result_callback, void *user_data);
 187
 188 /**
 189  * @brief Deregisters an application from the Push server.
 190  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 191  * @privlevel public
 192  * @param[in] connection The connection handle to the push service
 193  * @param[in] result_callback Result callback function
 194  * @param[in] user_data The user data to pass to @a result_cb
 195  * @return @c 0 on success,
 196  *         otherwise a negative error value
 197  * @retval #PUSH_ERROR_NONE Successful
 198  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 199  * @retval #PUSH_ERROR_OUT_OF_MEMORY Out of memory
 200  * @retval #PUSH_ERROR_NOT_CONNECTED No connection to the push service
 201  * @retval #PUSH_ERROR_OPERATION_FAILED Operation failed
 202  * @pre The application should be connected to the push service.
 203  * @post As a result, the state callback will be invoked.
 204  * @see push_register()
 205  */
 206 int push_deregister(push_connection_h connection, push_result_cb result_callback,
 207                 void *user_data);
 208
 209 /**
 210  * @brief Gets the payload data in the notification.
 211  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 212  * @privlevel public
 213  * @remarks You must release @a data using free().
 214  * @param[in] notification The notification handle
 215  * @param[out] data The notification data\n
 216  *                  Set @c NULL if error but #PUSH_ERROR_INVALID_PARAMETER
 217  * @return @c 0 on success,
 218  *         otherwise a negative error value
 219  * @retval #PUSH_ERROR_NONE Successful
 220  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 221  * @retval #PUSH_ERROR_OUT_OF_MEMORY Out of memory
 222  * @retval #PUSH_ERROR_NO_DATA No data available
 223  * @see push_notify_cb()
 224  * @see push_request_unread_notification()
 225  */
 226 int push_get_notification_data(push_notification_h notification, char **data);
 227
 228 /**
 229  * @brief Gets the message in the notification.
 230  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 231  * @privlevel public
 232  * @remarks You must release @a msg using free().
 233  * @param[in] notification The notification handle
 234  * @param[out] msg The notification message\n
 235  *                  Set @c NULL if error but #PUSH_ERROR_INVALID_PARAMETER
 236  * @return @c 0 on success,
 237  *         otherwise a negative error value
 238  * @retval #PUSH_ERROR_NONE Successful
 239  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 240  * @retval #PUSH_ERROR_OUT_OF_MEMORY Out of memory
 241  * @retval #PUSH_ERROR_NO_DATA No data available
 242  * @see push_notify_cb()
 243  * @see push_request_unread_notification()
 244  */
 245 int push_get_notification_message(push_notification_h notification,
 246                 char **msg);
 247
 248 /**
 249  * @brief Gets the received time of the notification.
 250  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 251  * @privlevel public
 252  * @param[in] notification The notification handle
 253  * @param[out] received_time The received time of the notification message\n
 254  *                           The @a received_time is based on UTC.
 255  * @return @c 0 on success,
 256  *         otherwise a negative error value
 257  * @retval #PUSH_ERROR_NONE Successful
 258  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 259  * @retval #PUSH_ERROR_NO_DATA No data available
 260  *
 261  * @see push_notify_cb()
 262  * @see push_request_unread_notification()
 263  */
 264 int push_get_notification_time(push_notification_h notification, long long int *received_time);
 265
 266 /**
 267  * @brief Gets the sender of the notification.
 268  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 269  * @privlevel public
 270  * @remarks You must release @a sender using free().
 271  * @param[in] notification The notification handle
 272  * @param[out] sender The sender\n
 273  *                  Set @c NULL if error but #PUSH_ERROR_INVALID_PARAMETER
 274  * @return @c 0 on success,
 275  *         otherwise a negative error value
 276  * @retval #PUSH_ERROR_NONE Successful
 277  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 278  * @retval #PUSH_ERROR_OUT_OF_MEMORY Out of memory
 279  * @retval #PUSH_ERROR_NO_DATA No data available
 280  * @see push_notify_cb()
 281  * @see push_request_unread_notification()
 282  */
 283 int push_get_notification_sender(push_notification_h notification,
 284                 char **sender);
 285
 286 /**
 287  * @brief Gets the session ID of the notification.
 288  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 289  * @privlevel public
 290  * @remarks You must release @a session_info using free().
 291  * @param[in] notification The notification handle
 292  * @param[out] session_info The session ID\n
 293  *                  Set @c NULL if error but #PUSH_ERROR_INVALID_PARAMETER
 294  * @return @c 0 on success,
 295  *         otherwise a negative error value
 296  * @retval #PUSH_ERROR_NONE Successful
 297  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 298  * @retval #PUSH_ERROR_OUT_OF_MEMORY Out of memory
 299  * @retval #PUSH_ERROR_NO_DATA No data available
 300  * @see push_notify_cb()
 301  * @see push_request_unread_notification()
 302  */
 303 int push_get_notification_session_info(push_notification_h notification,
 304                 char **session_info);
 305
 306
 307 /**
 308  * @brief Gets the request ID assigned by the sender.
 309  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 310  * @privlevel public
 311  * @remarks You must release @a request_id using free().
 312  * @param[in] notification The notification handle
 313  * @param[out] request_id The request ID\n
 314  *                  Set @c NULL if error but #PUSH_ERROR_INVALID_PARAMETER
 315  * @return @c 0 on success,
 316  *         otherwise a negative error value
 317  * @retval #PUSH_ERROR_NONE Successful
 318  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 319  * @retval #PUSH_ERROR_OUT_OF_MEMORY Out of memory
 320  * @retval #PUSH_ERROR_NO_DATA No data available
 321  * @see push_notify_cb()
 322  * @see push_request_unread_notification()
 323  */
 324 int push_get_notification_request_id(push_notification_h notification,
 325                 char **request_id);
 326
 327 /**
 328  * @brief Gets the value in the type field of the notification
 329  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 330  * @privlevel public
 331  * @param[in] notification The notification handle
 332  * @param[out] type The type value assigned by the sender
 333  * @return @c 0 on success,
 334  *         otherwise a negative error value
 335  * @retval #PUSH_ERROR_NONE Successful
 336  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 337  * @retval #PUSH_ERROR_NO_DATA No data available
 338  * @see push_notify_cb()
 339  * @see push_request_unread_notification()
 340  */
 341 int push_get_notification_type(push_notification_h notification, int *type);
 342
 343 /**
 344  * @brief Gets an unread notification message from the push server.
 345  *
 346  * @details If an application receives an unread message with this method, the message is removed from the system.\n
 347  *          This method can be called repeatedly until it returns #PUSH_ERROR_NO_DATA.\n
 348  *          However, this method does NOT guarantee order and reliability of notification messages.\n
 349  *          Some notification messages can be dropped when the system message queue is full.
 350  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 351  * @privlevel public
 352  * @remarks This method will be deprecated.
 353  * @remarks You must release @a noti using push_free_notification().
 354  *                      push_request_unread_notification() is preferred to this API.
 355  * @param[in] connection The connection handle to the push service
 356  * @param[out] noti The notification handle
 357  * @return @c 0 on success,
 358  *         otherwise a negative error value
 359  * @retval #PUSH_ERROR_NONE Successful
 360  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 361  * @retval #PUSH_ERROR_OUT_OF_MEMORY Out of memory
 362  * @retval #PUSH_ERROR_NO_DATA No data available
 363  *
 364  * @see push_get_notification_message()
 365  * @see push_get_notification_time()
 366  * @see push_get_notification_data()
 367  */
 368 int push_get_unread_notification(push_connection_h connection,
 369                 push_notification_h *noti);
 370
 371 /**
 372  * @brief Requests unread notification messages to the push server.
 373  * @details When the app wants to receive messages that arrived before it launced, this  \n
 374  *          method should be called. Upon receiving ths request, the daemon sends messages\n
 375  *          stored in its DB to the app. The notify_callback() method assigned in push_connect()\n
 376  *          will be called when these messages arrive. No need to call this method multiple\n
 377  *          times to receive multiple messages. This method does NOT guarantee order and\n
 378  *          reliability of notification messages.
 379  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 380  * @privlevel public
 381  * @remark This method is preferred to push_get_unread_notification().
 382  * @param[in] connection The connection handle to the push service
 383  * @return @c 0 on success,
 384  *         otherwise a negative error value
 385  * @retval #PUSH_ERROR_NONE Successful
 386  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 387  * @retval #PUSH_ERROR_NOT_CONNECTED Not connected to the daemon
 388  * @retval #PUSH_ERROR_OPERATION_FAILED Error when sending the request
 389  *
 390  * @see push_get_unread_notification()
 391  * @see push_connect()
 392  */
 393 int push_request_unread_notification(push_connection_h connection);
 394
 395 /**
 396  * @brief Retrieves the notification with the notification token
 397  * @details When the push service forcibly launches the application to\n
 398                         deliver a notification, a unique token for the notification\n
 399                         is generated and delivered to the application as a bundle.\n
 400                         Using this API with this token, the application can get\n
 401                         the notification.
 402  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 403  * @privlevel public
 404  * @privilege %http://tizen.org/privilege/push
 405  * @remark This function must be called in the app control callback function.\n
 406  *                 You must release the notification using push_free_notification().
 407  * @param[in] noti_token The notification token received from the bundle
 408  * @param[out] noti     The handle for the notification that launched this app
 409  * @return @c 0 on success,
 410  *         otherwise a negative error value
 411  * @retval #PUSH_SERVICE_ERROR_NONE Successful
 412  * @retval #PUSH_SERVICE_ERROR_INVALID_PARAMETER Invalid parameter
 413  * @retval #PUSH_SERVICE_ERROR_NO_DATA  No notification for this token
 414  * @retval #PUSH_SERVICE_ERROR_OPERATION_FAILED Operation fail
 415  * @retval #PUSH_SERVICE_ERROR_OUT_OF_MEMORY Out of memory
 416  * @retval #PUSH_SERVICE_ERROR_NOT_CONNECTED Connection to the daemon failed
 417  * @retval #PUSH_SERVICE_ERROR_PERMISSION_DENIED No push privilege
 418  * @see push_free_notificaiton()
 419  * @see app_control_get_operation()
 420  */
 421 int push_get_notification_using_token(const char *noti_token, push_notification_h *noti);
 422
 423
 424 /**
 425  * @brief Gets the registration ID in the @a #PUSH_STATE_REGISTERED state.
 426  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 427  * @privlevel public
 428  * @remarks You must release @a reg_id using free().
 429  * @param[in] connection The connection handle to the push service
 430  * @param[out] reg_id The registration ID
 431  *                    Set @c NULL if error but #PUSH_ERROR_INVALID_PARAMETER
 432  * @return @c 0 on success,
 433  *         otherwise a negative error value
 434  * @retval #PUSH_ERROR_NONE Successful
 435  * @retval #PUSH_ERROR_INVALID_PARAMETER Invalid parameter
 436  * @retval #PUSH_ERROR_OUT_OF_MEMORY Out of memory
 437  * @retval #PUSH_ERROR_NO_DATA No registration ID available
 438  */
 439 int push_get_registration_id(push_connection_h connection, char **reg_id);
 440
 441
 442 /**
 443  * @brief Frees the notification handle.
 444  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 445  * @privlevel public
 446  * @privilege %http://tizen.org/privilege/push
 447  * @param[in] noti The notification handle
 448  */
 449 void push_free_notification(push_notification_h noti);
 450
 451 /**
 452  * @}
 453  */
 454
 455 #ifdef __cplusplus
 456 }
 457 #endif
 458
 459 #endif /* __PUSH_LIB_H__ */