include/badge.h

   1 /*
   2  *  libbadge
   3  *
   4  * Copyright (c) 2000 - 2012 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Youngjoo Park <yjoo93.park@samsung.com>,
   7  *      Seungtaek Chung <seungtaek.chung@samsung.com>, Youngsub Ko <ys4610.ko@samsung.com>
   8  *
   9  * Licensed under the Apache License, Version 2.0 (the License);
  10  * you may not use this file except in compliance with the License.
  11  * You may obtain a copy of the License at
  12  *
  13  * http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  * Unless required by applicable law or agreed to in writing, software
  16  * distributed under the License is distributed on an AS IS BASIS,
  17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  * See the License for the specific language governing permissions and
  19  * limitations under the License.
  20  *
  21  */
  22
  23 #ifndef __BADGE_DEF_H__
  24 #define __BADGE_DEF_H__
  25
  26 #include <stdbool.h>
  27 #include <badge_error.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif /* __cplusplus */
  32
  33 /**
  34  * @file badge.h
  35  * @brief This file contains the badge APIs.
  36  */
  37
  38 /**
  39  * @addtogroup BADGE_MODULE
  40  * @{
  41  */
  42
  43
  44 /**
  45  * @internal
  46  * @brief Enumeration for Badge Action.
  47  * @since_tizen 2.3
  48  */
  49 enum badge_action {
  50         BADGE_ACTION_CREATE = 0,        /**< @internal Badge created */
  51         BADGE_ACTION_REMOVE,    /**< @internal Badge removed */
  52         BADGE_ACTION_UPDATE,    /**< @internal Badge updated */
  53         BADGE_ACTION_CHANGED_DISPLAY,   /**< @internal The display option of the badge changed  */
  54         BADGE_ACTION_SERVICE_READY,     /**< @internal The badge service is ready */
  55 };
  56
  57
  58 /**
  59  * @internal
  60  * @brief Called to retrieve the badge existence.
  61  * @since_tizen 2.3
  62  * @param[in] app_id The name of the application
  63  * @param[in] count The count of the badge
  64  * @param[in] data The user data passed from the foreach function
  65  * @pre badge_foreach_existed() will invoke this callback.
  66  * @see badge_foreach_existed()
  67  */
  68 typedef void (*badge_cb)(const char *app_id, unsigned int count, void *data);
  69
  70
  71 /**
  72  * @internal
  73  * @brief Called when the badge information is changed.
  74  * @since_tizen 2.3
  75  * @param[in] action The type of the change
  76  * @param[in] app_id The name of the application
  77  * @param[in] count The count of the badge
  78  * @param[in] data The user data passed from the callback register function
  79  * @pre badge_register_changed_cb() will invoke this callback.
  80  * @see badge_unregister_changed_cb()
  81  */
  82 typedef void (*badge_change_cb)(unsigned int action, const char *app_id,
  83                         unsigned int count, void *data);
  84
  85 /**
  86  * @internal
  87  * @brief Retrieves all existing badges.
  88  * @since_tizen 2.3
  89  * @privlevel public
  90  * @privilege %http://tizen.org/privilege/notification
  91  * @param[in] callback The callback function
  92  * @param[in] data The user data to be passed to the callback function
  93  * @return #BADGE_ERROR_NONE if success, other value if failure
  94  * @retval BADGE_ERROR_NONE Success
  95  * @retval BADGE_ERROR_INVALID_PARAMETER Invalid parameter
  96  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
  97  * @retval BADGE_ERROR_FROM_DB Error form DB
  98  * @retval BADGE_ERROR_OUT_OF_MEMORY Out of memory
  99  * @retval BADGE_ERROR_NOT_EXIST Not exist
 100  * @see #badge_error_e
 101  * @see badge_get_count()
 102  * @see badge_is_existing()
 103  */
 104 int badge_foreach_existed(badge_cb callback, void *data);
 105
 106 /**
 107  * @internal
 108  * @brief Registers a callback function to receive badge change event.
 109  * @since_tizen 2.3
 110  * @privlevel public
 111  * @privilege %http://tizen.org/privilege/notification
 112  * @param[in] callback The callback function
 113  * @param[in] data The user data to be passed to the callback function
 114  * @return #BADGE_ERROR_NONE if success, other value if failure
 115  * @retval BADGE_ERROR_NONE Success
 116  * @retval BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 117  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 118  * @retval BADGE_ERROR_OUT_OF_MEMORY Out of memory
 119  * @see #badge_error_e
 120  * @see badge_new()
 121  * @see badge_remove()
 122  * @see badge_set_count()
 123  */
 124 int badge_register_changed_cb(badge_change_cb callback, void *data);
 125
 126 /**
 127  * @internal
 128  * @brief Unregisters a callback function to receive badge change event.
 129  * @since_tizen 2.3
 130  * @privlevel public
 131  * @privilege %http://tizen.org/privilege/notification
 132  * @param[in] callback The callback function
 133  * @return #BADGE_ERROR_NONE if success, other value if failure
 134  * @retval BADGE_ERROR_NONE Success
 135  * @retval BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 136  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 137  * @retval BADGE_ERROR_NOT_EXIST Not exist
 138  * @see #badge_error_e
 139  * @see badge_register_changed_cb()
 140  */
 141 int badge_unregister_changed_cb(badge_change_cb callback);
 142
 143 /**
 144  * @internal
 145  * @brief This function checks whether badge service is ready
 146  * @since_tizen 2.3
 147  * @privlevel public
 148  * @privilege %http://tizen.org/privilege/notification
 149  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 150  * @return 1 if badge service is ready, other value if badge service isn't ready
 151  * @exception BADGE_ERROR_NONE Success
 152  * @exception BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 153  */
 154 int badge_is_service_ready(void);
 155
 156 /**
 157  * @internal
 158  * @brief This function adds deferred task. the registered task will be executed when badge service become ready
 159  * @since_tizen 2.3
 160  * @privlevel public
 161  * @privilege %http://tizen.org/privilege/notification
 162  * @param[in] badge_add_deferred_task The callback function
 163  * @param[in] user_data The user data to be passed to the callback function
 164  * @return #BADGE_ERROR_NONE if success, other value if failure
 165  * @retval BADGE_ERROR_NONE Success
 166  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 167  * @retval BADGE_ERROR_OUT_OF_MEMORY Out of memory
 168  * @see #badge_error_e
 169  * @see badge_is_service_ready()
 170  */
 171 int badge_add_deferred_task(
 172                 void (*badge_add_deferred_task)(void *data), void *user_data);
 173
 174 /**
 175  * @internal
 176  * @brief This function removes deferred task.
 177  * @since_tizen 2.3
 178  * @privlevel public
 179  * @privilege %http://tizen.org/privilege/notification
 180  * @param[in] badge_add_deferred_task The callback function
 181  * @return #BADGE_ERROR_NONE if success, other value if failure
 182  * @retval BADGE_ERROR_NONE Success
 183  * @retval BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 184  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 185  * @see #badge_error_e
 186  * @see badge_is_service_ready()
 187  */
 188 int badge_del_deferred_task(
 189                 void (*badge_add_deferred_task)(void *data));
 190
 191 /**
 192  * @brief Creates a badge for the application itself.
 193  * @since_tizen 2.3
 194  * @privlevel public
 195  * @privilege %http://tizen.org/privilege/notification
 196  * @details Creates new badge to display.
 197  * @param[in] writable_app_id The id of application which is authorized to change the badge
 198  * @return #BADGE_ERROR_NONE if success, other value if failure
 199  * @retval BADGE_ERROR_NONE Success
 200  * @retval BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 201  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 202  * @retval BADGE_ERROR_IO_ERROR Error from I/O
 203  * @retval BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 204  * @see #badge_error_e
 205  * @par Sample code:
 206  * @code
 207 #include <badge.h>
 208 ...
 209 {
 210         int err = BADGE_ERROR_NONE;
 211
 212         err = badge_new(app_id);
 213         if(err != BADGE_ERROR_NONE) {
 214                 return;
 215         }
 216
 217 }
 218  * @endcode
 219  */
 220 int badge_new(const char *writable_app_id);
 221
 222
 223 /**
 224  * @brief Removes the badge for the designated application.
 225  * @since_tizen 2.3
 226  * @privlevel public
 227  * @privilege %http://tizen.org/privilege/notification
 228  * @param[in] app_id The name of the designated application
 229  * @return #BADGE_ERROR_NONE if success, other value if failure
 230  * @retval BADGE_ERROR_NONE Success
 231  * @retval BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 232  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 233  * @retval BADGE_ERROR_IO_ERROR Error from I/O
 234  * @retval BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 235  * @see #badge_error_e
 236  * @par Sample code:
 237  * @code
 238 #include <badge.h>
 239 ...
 240 {
 241         int err = BADGE_ERROR_NONE;
 242
 243         err = badge_remove(app_id);
 244         if(err != BADGE_ERROR_NONE) {
 245                 return;
 246         }
 247
 248 }
 249  * @endcode
 250  */
 251 int badge_remove(const char *app_id);
 252
 253 /**
 254  * @brief Sets badge count for the designated application.
 255  * @since_tizen 2.3
 256  * @privlevel public
 257  * @privilege %http://tizen.org/privilege/notification
 258  * @param[in] app_id The name of the designated application
 259  * @param[in] count The count of the badge
 260  * @return #BADGE_ERROR_NONE if success, other value if failure
 261  * @retval BADGE_ERROR_NONE Success
 262  * @retval BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 263  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 264  * @retval BADGE_ERROR_IO_ERROR Error from I/O
 265  * @retval BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 266  * @see #badge_error_e
 267  * @see badge_new()
 268  * @par Sample code:
 269  * @code
 270 #include <badge.h>
 271 ...
 272 {
 273         int err = BADGE_ERROR_NONE;
 274
 275         err = badge_set_count(app_id, 1);
 276         if(err != BADGE_ERROR_NONE) {
 277                 return;
 278         }
 279
 280 }
 281  * @endcode
 282  */
 283 int badge_set_count(const char *app_id, unsigned int count);
 284
 285 /**
 286  * @brief Gets badge count for the designated application.
 287  * @since_tizen 2.3
 288  * @privlevel public
 289  * @privilege %http://tizen.org/privilege/notification
 290  * @param[in] app_id The name of the designated application
 291  * @param[out] count The count of the badge
 292  * @return #BADGE_ERROR_NONE if success, other value if failure
 293  * @retval BADGE_ERROR_NONE Success
 294  * @retval BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 295  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 296  * @retval BADGE_ERROR_FROM_DB Error from DB
 297  * @retval BADGE_ERROR_ALREADY_EXIST Already exist
 298  * @retval BADGE_ERROR_OUT_OF_MEMORY Out of memory
 299  * @see #badge_error_e
 300  * @see badge_new()
 301  * @see badge_set_count()
 302  * @par Sample code:
 303  * @code
 304 #include <badge.h>
 305 ...
 306 {
 307         int err = BADGE_ERROR_NONE;
 308         int count = 0;
 309
 310         err = badge_get_count(app_id, &count);
 311         if(err != BADGE_ERROR_NONE) {
 312                 return;
 313         }
 314
 315 }
 316  * @endcode
 317  */
 318 int badge_get_count(const char *app_id, unsigned int *count);
 319
 320 /**
 321  * @brief Sets the display option for the designated application.
 322  * @since_tizen 2.3
 323  * @privlevel public
 324  * @privilege %http://tizen.org/privilege/notification
 325  * @param[in] app_id The name of the designated application
 326  * @param[in] is_display The display option (1 = display, 0 = not display)
 327  * @return #BADGE_ERROR_NONE if success, other value if failure
 328  * @retval BADGE_ERROR_NONE Success
 329  * @retval BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 330  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 331  * @retval BADGE_ERROR_IO_ERROR Error from I/O
 332  * @retval BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 333  * @see #badge_error_e
 334  * @see badge_new()
 335  * @par Sample code:
 336  * @code
 337 #include <badge.h>
 338 ...
 339 {
 340         int err = BADGE_ERROR_NONE;
 341
 342         err = badge_set_display(app_id, 1);
 343         if(err != BADGE_ERROR_NONE) {
 344                 return;
 345         }
 346
 347 }
 348  * @endcode
 349  */
 350 int badge_set_display(const char *app_id, unsigned int is_display);
 351
 352 /**
 353  * @brief Gets the display option for the designated application.
 354  * @since_tizen 2.3
 355  * @privlevel public
 356  * @privilege %http://tizen.org/privilege/notification
 357  * @param[in] app_id The name of the designated application
 358  * @param[out]  is_display The display option (1 = display, 0 = not display)
 359  * @return #BADGE_ERROR_NONE if success, other value if failure
 360  * @retval BADGE_ERROR_NONE Success
 361  * @retval BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 362  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 363  * @retval BADGE_ERROR_FROM_DB Error from DB
 364  * @retval BADGE_ERROR_NOT_EXIST Not exist
 365  * @retval BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 366  * @retval BADGE_ERROR_OUT_OF_MEMORY Out of memory
 367  * @see #badge_error_e
 368  * @see badge_new()
 369  * @see badge_set_count()
 370  * @par Sample code:
 371  * @code
 372 #include <badge.h>
 373 ...
 374 {
 375         int is_display = 0;
 376         int err = BADGE_ERROR_NONE;
 377
 378         err = badge_get_display(app_id, &is_display);
 379         if(err != BADGE_ERROR_NONE) {
 380                 return;
 381         }
 382
 383 }
 384  * @endcode
 385  */
 386 int badge_get_display(const char *app_id, unsigned int *is_display);
 387
 388 /**
 389  * @internal
 390  * @brief Tests if the badge for the designated application exists or not.
 391  * @since_tizen 2.3
 392  * @privlevel public
 393  * @privilege %http://tizen.org/privilege/notification
 394  * @param[in] app_id The name of the designated application
 395  * @param[out] existing The bool value of badge existence status
 396  * @return #BADGE_ERROR_NONE if success, other value if failure
 397  * @retval BADGE_ERROR_NONE Success
 398  * @retval BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 399  * @retval BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 400  * @retval BADGE_ERROR_FROM_DB Error from DB
 401  * @retval BADGE_ERROR_NOT_EXIST Not exist
 402  * @retval BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 403  * @see #badge_error_e
 404  * @see badge_new()
 405  * @see badge_remove()
 406  * @par Sample code:
 407  * @code
 408 #include <badge.h>
 409 ...
 410 {
 411         int err = BADGE_ERROR_NONE;
 412         bool exist;
 413
 414         err = badge_is_existing(app_id, &exist);
 415         if(err != BADGE_ERROR_NONE) {
 416                 return;
 417         }
 418
 419 }
 420  * @endcode
 421  */
 422 int badge_is_existing(const char *app_id, bool *existing);
 423
 424
 425
 426 /**
 427  * @}
 428  */
 429
 430 #ifdef __cplusplus
 431 }
 432 #endif /* __cplusplus */
 433
 434 #endif /* __BADGE_DEF_H__ */
 435
 436