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_TYPE
  40  * @{
  41  */
  42
  43 /**
  44  * @brief Enumeration for Badge action
  45  */
  46 enum _badge_action {
  47         BADGE_ACTION_CREATE = 0,
  48         BADGE_ACTION_REMOVE,
  49         BADGE_ACTION_UPDATE,
  50         BADGE_ACTION_CHANGED_DISPLAY,
  51         BADGE_ACTION_SERVICE_READY,
  52 };
  53
  54
  55 /**
  56  * @brief Called to retrieve the badge existed.
  57  * @param[in] pkgname The name of package
  58  * @param[in] count The count of badge
  59  * @param[in] user_data The user data passed from the foreach function
  60  * @pre badge_foreach_existed() will invoke this callback.
  61  * @see badge_foreach_existed()
  62  */
  63 typedef void (*badge_cb)(const char *pkgname, unsigned int count, void *data);
  64
  65
  66 /**
  67  * @brief Called when badge information is changed.
  68  * @param[in] action The type of changing
  69  * @param[in] pkgname The name of package
  70  * @param[in] count The count of badge
  71  * @param[in] user_data The user data passed from the callback register function
  72  * @pre badge_register_changed_cb() will invoke this callback.
  73  * @see badge_unregister_changed_cb()
  74  */
  75 typedef void (*badge_change_cb)(unsigned int action, const char *pkgname,
  76                         unsigned int count, void *data);
  77
  78 /**
  79  * @}
  80  */
  81
  82 /**
  83  * @addtogroup BADGE_MODULE
  84  * @{
  85  */
  86
  87 /**
  88  * @brief This function creates badge for designated package.
  89  * @details Creates new badge to display.
  90  * @param[in] pkgname The name of designated package
  91  * @param[in] writable_pkg The name of package which is authorized to change badge
  92  * @return #BADGE_ERROR_NONE if success, other value if failure
  93  * @see #badge_error_e
  94  * @par Sample code:
  95  * @code
  96 #include <badge.h>
  97 ...
  98 {
  99         badge_error_e err = BADGE_ERROR_NONE;
 100
 101         err = badge_create("org.tizen.sms", "org.tizen.sms2");
 102         if(err != BADGE_ERROR_NONE) {
 103                 return;
 104         }
 105
 106 }
 107  * @endcode
 108  */
 109 badge_error_e badge_create(const char *pkgname, const char *writable_pkg);
 110
 111
 112 /**
 113  * @brief This function removes badge for designated package.
 114  * @param[in] pkgname The name of designated package
 115  * @return #BADGE_ERROR_NONE if success, other value if failure
 116  * @see #badge_error_e
 117  * @par Sample code:
 118  * @code
 119 #include <badge.h>
 120 ...
 121 {
 122         badge_error_e err = BADGE_ERROR_NONE;
 123
 124         err = badge_remove("org.tizen.sms");
 125         if(err != BADGE_ERROR_NONE) {
 126                 return;
 127         }
 128
 129 }
 130  * @endcode
 131  */
 132 badge_error_e badge_remove(const char *pkgname);
 133
 134 /**
 135  * @brief This function sets badge count for designated package.
 136  * @param[in] pkgname The name of designated package
 137  * @param[in] count The count of badge
 138  * @return #BADGE_ERROR_NONE if success, other value if failure
 139  * @see #badge_error_e
 140  * @see badge_create()
 141  * @par Sample code:
 142  * @code
 143 #include <badge.h>
 144 ...
 145 {
 146         badge_error_e err = BADGE_ERROR_NONE;
 147
 148         err = badge_set_count("org.tizen.sms", 1);
 149         if(err != BADGE_ERROR_NONE) {
 150                 return;
 151         }
 152
 153 }
 154  * @endcode
 155  */
 156 badge_error_e badge_set_count(const char *pkgname, unsigned int count);
 157
 158 /**
 159  * @brief This function gets badge count for designated package.
 160  * @param[in] pkgname The name of designated package
 161  * @param[out] count The count of badge
 162  * @return #BADGE_ERROR_NONE if success, other value if failure
 163  * @see #badge_error_e
 164  * @see badge_create()
 165  * @see badge_set_count()
 166  * @par Sample code:
 167  * @code
 168 #include <badge.h>
 169 ...
 170 {
 171         badge_error_e err = BADGE_ERROR_NONE;
 172
 173         err = badge_get_count("org.tizen.sms", 1);
 174         if(err != BADGE_ERROR_NONE) {
 175                 return;
 176         }
 177
 178 }
 179  * @endcode
 180  */
 181 badge_error_e badge_get_count(const char *pkgname, unsigned int *count);
 182
 183 /**
 184  * @brief This function sets displaying option for designated package.
 185  * @param[in] pkgname The name of designated package
 186  * @param[in] is_display The displaying option, 1 = display 0 = not display
 187  * @return #BADGE_ERROR_NONE if success, other value if failure
 188  * @see #badge_error_e
 189  * @see badge_create()
 190  * @par Sample code:
 191  * @code
 192 #include <badge.h>
 193 ...
 194 {
 195         badge_error_e err = BADGE_ERROR_NONE;
 196
 197         err = badge_set_display("org.tizen.sms", 1);
 198         if(err != BADGE_ERROR_NONE) {
 199                 return;
 200         }
 201
 202 }
 203  * @endcode
 204  */
 205 badge_error_e badge_set_display(const char *pkgname, unsigned int is_display);
 206
 207 /**
 208  * @brief This function gets displaying option for designated package.
 209  * @param[in] pkgname The name of designated package
 210  * @param[out]  is_display The displaying option, 1 = display 0 = not display
 211  * @return #BADGE_ERROR_NONE if success, other value if failure
 212  * @see #badge_error_e
 213  * @see badge_create()
 214  * @see badge_set_count()
 215  * @par Sample code:
 216  * @code
 217 #include <badge.h>
 218 ...
 219 {
 220         int is_display = 0;
 221         badge_error_e err = BADGE_ERROR_NONE;
 222
 223         err = badge_get_display("org.tizen.sms", &is_display);
 224         if(err != BADGE_ERROR_NONE) {
 225                 return;
 226         }
 227
 228 }
 229  * @endcode
 230  */
 231 badge_error_e badge_get_display(const char *pkgname, unsigned int *is_display);
 232
 233 /**
 234  * @brief This function tests badge for designated package is existed or not.
 235  * @param[in] pkgname The name of designated package
 236  * @param[out] existing The bool value of badge existing status
 237  * @return #BADGE_ERROR_NONE if success, other value if failure
 238  * @see #badge_error_e
 239  * @see badge_create()
 240  * @see badge_remove()
 241  * @par Sample code:
 242  * @code
 243 #include <badge.h>
 244 ...
 245 {
 246         badge_error_e err = BADGE_ERROR_NONE;
 247         bool exist;
 248
 249         err = badge_is_existing("org.tizen.sms", &exist);
 250         if(err != BADGE_ERROR_NONE) {
 251                 return;
 252         }
 253
 254 }
 255  * @endcode
 256  */
 257 badge_error_e badge_is_existing(const char *pkgname, bool *existing);
 258
 259 /**
 260  * @brief This function retrieves all badges which are existed.
 261  * @param[in] callback The callback function
 262  * @param[in] data The user data to be passed to the callback function
 263  * @return #BADGE_ERROR_NONE if success, other value if failure
 264  * @see #badge_error_e
 265  * @see badge_get_count()
 266  * @see badge_is_existing()
 267  */
 268 badge_error_e badge_foreach_existed(badge_cb callback, void *data);
 269
 270 /**
 271  * @brief This function registers callback function to receive badge changed event.
 272  * @param[in] callback The callback function
 273  * @param[in] data The user data to be passed to the callback function
 274  * @return #BADGE_ERROR_NONE if success, other value if failure
 275  * @see #badge_error_e
 276  * @see badge_create()
 277  * @see badge_remove()
 278  * @see badge_set_count()
 279  */
 280 badge_error_e badge_register_changed_cb(badge_change_cb callback, void *data);
 281
 282 /**
 283  * @brief This function unregisters callback function to receive badge changed event.
 284  * @param[in] callback The callback function
 285  * @return #BADGE_ERROR_NONE if success, other value if failure
 286  * @see #badge_error_e
 287  * @see badge_register_changed_cb()
 288  */
 289 badge_error_e badge_unregister_changed_cb(badge_change_cb callback);
 290
 291 /**
 292  * @}
 293  */
 294
 295 int badge_is_service_ready(void);
 296
 297 badge_error_e badge_add_deffered_task(
 298                 void (*deffered_task_cb)(void *data), void *user_data);
 299
 300 badge_error_e badge_del_deffered_task(
 301                 void (*deffered_task_cb)(void *data));
 302
 303 #ifdef __cplusplus
 304 }
 305 #endif /* __cplusplus */
 306
 307 #endif /* __BADGE_DEF_H__ */
 308
 309