include/badge.h

   1 /*
   2  * Copyright (c) 2000 - 2017 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
  18 #ifndef __BADGE_DEF_H__
  19 #define __BADGE_DEF_H__
  20
  21 #include <tizen.h>
  22
  23 #include <stdbool.h>
  24 #include <badge_error.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif /* __cplusplus */
  29
  30 /**
  31  * @file badge.h
  32  * @brief This file contains the badge APIs.
  33  */
  34
  35 /**
  36  * @addtogroup BADGE_MODULE
  37  * @{
  38  */
  39
  40 /**
  41  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif Use badge_add instead.
  42  * @brief Creates a badge for the application itself.
  43  * @details Creates new badge to display.
  44  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  45  * @privlevel public
  46  * @privilege %http://tizen.org/privilege/notification
  47  * @param[in] writable_app_id The id of application which is authorized to change the badge
  48  * @return #BADGE_ERROR_NONE if success, other value if failure
  49  * @retval #BADGE_ERROR_NONE Success
  50  * @retval #BADGE_ERROR_INVALID_PARAMETER Invalid parameter
  51  * @retval #BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
  52  * @retval #BADGE_ERROR_IO_ERROR Error from I/O
  53  * @retval #BADGE_ERROR_SERVICE_NOT_READY Service is not ready
  54  * @retval #BADGE_ERROR_NOT_SUPPORTED Not supported
  55  * @see #badge_error_e
  56  * @par Sample code:
  57  * @code
  58 #include <badge.h>
  59
  60 {
  61         int err = BADGE_ERROR_NONE;
  62
  63         err = badge_new(app_id);
  64         if (err != BADGE_ERROR_NONE)
  65                 return;
  66
  67 }
  68  * @endcode
  69  */
  70 int badge_new(const char *writable_app_id) TIZEN_DEPRECATED_API;
  71
  72
  73 /**
  74  * @brief Creates a badge for the application specified by the badge_app_id.
  75  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  76  * @privlevel public
  77  * @privilege %http://tizen.org/privilege/notification
  78  * @remarks Creating and updating a badge of the other application is allowed only when both applications are signed with the same certificate.
  79  * @param[in] badge_app_id The id of the application for which the badge will be created. This parameter can be null when creating a badge for itself.
  80  * @return #BADGE_ERROR_NONE If success, other value if failure
  81  * @retval #BADGE_ERROR_INVALID_PARAMETER Invalid parameter
  82  * @retval #BADGE_ERROR_OUT_OF_MEMORY Out of memory
  83  * @retval #BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
  84  * @retval #BADGE_ERROR_IO_ERROR Error from I/O
  85  * @retval #BADGE_ERROR_FROM_DB Error from DB
  86  * @retval #BADGE_ERROR_ALREADY_EXIST Already exist
  87  * @retval #BADGE_ERROR_SERVICE_NOT_READY Service is not ready
  88  * @retval #BADGE_ERROR_INVALID_PACKAGE The caller application is not signed with the certificate of the badge_app_id
  89  * @retval #BADGE_ERROR_NOT_SUPPORTED Not supported
  90  * @see #badge_error_e
  91  * @par Sample code:
  92  * @code
  93 #include <badge.h>
  94
  95 {
  96         int err = BADGE_ERROR_NONE;
  97
  98         err = badge_add("org.tizen.email");
  99         if (err != BADGE_ERROR_NONE)
 100                 return;
 101 }
 102  * @endcode
 103  */
 104 int badge_add(const char *badge_app_id);
 105
 106
 107 /**
 108  * @brief Removes the badge for the designated application.
 109  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 110  * @privlevel public
 111  * @privilege %http://tizen.org/privilege/notification
 112  * @param[in] app_id The name of the designated application
 113  * @return #BADGE_ERROR_NONE if success, other value if failure
 114  * @retval #BADGE_ERROR_NONE Success
 115  * @retval #BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 116  * @retval #BADGE_ERROR_OUT_OF_MEMORY Out of memory
 117  * @retval #BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 118  * @retval #BADGE_ERROR_IO_ERROR Error from I/O
 119  * @retval #BADGE_ERROR_FROM_DB Error from DB
 120  * @retval #BADGE_ERROR_NOT_EXIST Not exist
 121  * @retval #BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 122  * @retval #BADGE_ERROR_NOT_SUPPORTED Not supported
 123  * @see #badge_error_e
 124  * @par Sample code:
 125  * @code
 126 #include <badge.h>
 127
 128 {
 129         int err = BADGE_ERROR_NONE;
 130
 131         err = badge_remove(app_id);
 132         if (err != BADGE_ERROR_NONE)
 133                 return;
 134
 135 }
 136  * @endcode
 137  */
 138 int badge_remove(const char *app_id);
 139
 140 /**
 141  * @brief Sets badge count for the designated application.
 142  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 143  * @privlevel public
 144  * @privilege %http://tizen.org/privilege/notification
 145  * @param[in] app_id The name of the designated application
 146  * @param[in] count The count of the badge
 147  * @return #BADGE_ERROR_NONE if success, other value if failure
 148  * @retval #BADGE_ERROR_NONE Success
 149  * @retval #BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 150  * @retval #BADGE_ERROR_OUT_OF_MEMORY Out of memory
 151  * @retval #BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 152  * @retval #BADGE_ERROR_IO_ERROR Error from I/O
 153  * @retval #BADGE_ERROR_FROM_DB Error from DB
 154  * @retval #BADGE_ERROR_NOT_EXIST Not exist
 155  * @retval #BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 156  * @retval #BADGE_ERROR_NOT_SUPPORTED Not supported
 157  * @see #badge_error_e
 158  * @see badge_new()
 159  * @par Sample code:
 160  * @code
 161 #include <badge.h>
 162
 163 {
 164         int err = BADGE_ERROR_NONE;
 165
 166         err = badge_set_count(app_id, 1);
 167         if (err != BADGE_ERROR_NONE)
 168                 return;
 169
 170 }
 171  * @endcode
 172  */
 173 int badge_set_count(const char *app_id, unsigned int count);
 174
 175 /**
 176  * @brief Gets badge count for the designated application.
 177  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 178  * @privlevel public
 179  * @privilege %http://tizen.org/privilege/notification
 180  * @param[in] app_id The name of the designated application
 181  * @param[out] count The count of the badge
 182  * @return #BADGE_ERROR_NONE if success, other value if failure
 183  * @retval #BADGE_ERROR_NONE Success
 184  * @retval #BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 185  * @retval #BADGE_ERROR_OUT_OF_MEMORY Out of memory
 186  * @retval #BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 187  * @retval #BADGE_ERROR_IO_ERROR Error from I/O
 188  * @retval #BADGE_ERROR_FROM_DB Error from DB
 189  * @retval #BADGE_ERROR_NOT_EXIST Not exist
 190  * @retval #BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 191  * @retval #BADGE_ERROR_NOT_SUPPORTED Not supported
 192  * @see #badge_error_e
 193  * @see badge_new()
 194  * @see badge_set_count()
 195  * @par Sample code:
 196  * @code
 197 #include <badge.h>
 198
 199 {
 200         int err = BADGE_ERROR_NONE;
 201         int count = 0;
 202
 203         err = badge_get_count(app_id, &count);
 204         if (err != BADGE_ERROR_NONE)
 205                 return;
 206
 207 }
 208  * @endcode
 209  */
 210 int badge_get_count(const char *app_id, unsigned int *count);
 211
 212 /**
 213  * @brief Sets the display option for the designated application.
 214  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 215  * @privlevel public
 216  * @privilege %http://tizen.org/privilege/notification
 217  * @param[in] app_id The name of the designated application
 218  * @param[in] is_display The display option (1 = display, 0 = not display)
 219  * @return #BADGE_ERROR_NONE if success, other value if failure
 220  * @retval #BADGE_ERROR_NONE Success
 221  * @retval #BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 222  * @retval #BADGE_ERROR_OUT_OF_MEMORY Out of memory
 223  * @retval #BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 224  * @retval #BADGE_ERROR_IO_ERROR Error from I/O
 225  * @retval #BADGE_ERROR_FROM_DB Error from DB
 226  * @retval #BADGE_ERROR_NOT_EXIST Not exist
 227  * @retval #BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 228  * @retval #BADGE_ERROR_NOT_SUPPORTED Not supported
 229  * @see #badge_error_e
 230  * @see badge_new()
 231  * @par Sample code:
 232  * @code
 233 #include <badge.h>
 234
 235 {
 236         int err = BADGE_ERROR_NONE;
 237
 238         err = badge_set_display(app_id, 1);
 239         if (err != BADGE_ERROR_NONE)
 240                 return;
 241
 242 }
 243  * @endcode
 244  */
 245 int badge_set_display(const char *app_id, unsigned int is_display);
 246
 247 /**
 248  * @brief Gets the display option for the designated application.
 249  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 250  * @privlevel public
 251  * @privilege %http://tizen.org/privilege/notification
 252  * @param[in] app_id The name of the designated application
 253  * @param[out]  is_display The display option (1 = display, 0 = not display)
 254  * @return #BADGE_ERROR_NONE if success, other value if failure
 255  * @retval #BADGE_ERROR_NONE Success
 256  * @retval #BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 257  * @retval #BADGE_ERROR_OUT_OF_MEMORY Out of memory
 258  * @retval #BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 259  * @retval #BADGE_ERROR_IO_ERROR Error from I/O
 260  * @retval #BADGE_ERROR_FROM_DB Error from DB
 261  * @retval #BADGE_ERROR_NOT_EXIST Not exist
 262  * @retval #BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 263  * @retval #BADGE_ERROR_NOT_SUPPORTED Not supported
 264  * @see #badge_error_e
 265  * @see badge_new()
 266  * @see badge_set_count()
 267  * @par Sample code:
 268  * @code
 269 #include <badge.h>
 270
 271 {
 272         int is_display = 0;
 273         int err = BADGE_ERROR_NONE;
 274
 275         err = badge_get_display(app_id, &is_display);
 276         if (err != BADGE_ERROR_NONE)
 277                 return;
 278 }
 279  * @endcode
 280  */
 281 int badge_get_display(const char *app_id, unsigned int *is_display);
 282
 283 /**
 284  * @brief Callback function for getting result of badge_foreach.
 285  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 286  * @param[in] app_id The id of the application
 287  * @param[in] count The count of the badge
 288  * @param[in] user_data The user data passed from the badge_foreach function
 289  * @return true to continue with the next iteration of the loop, false to break out of the loop
 290  * @pre badge_foreach() will invoke this callback.
 291  * @see badge_foreach()
 292  */
 293 typedef bool (*badge_foreach_cb)(const char *app_id, unsigned int count, void *user_data);
 294
 295
 296 /**
 297  * @brief Retrieves all existing badges.
 298  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 299  * @privlevel public
 300  * @privilege %http://tizen.org/privilege/notification
 301  * @param[in] callback The callback function
 302  * @param[in] user_data The user data to be passed to the callback function
 303  * @return #BADGE_ERROR_NONE if success, other value if failure
 304  * @retval #BADGE_ERROR_NONE Success
 305  * @retval #BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 306  * @retval #BADGE_ERROR_OUT_OF_MEMORY Out of memory
 307  * @retval #BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 308  * @retval #BADGE_ERROR_IO_ERROR Error from I/O
 309  * @retval #BADGE_ERROR_FROM_DB Error form DB
 310  * @retval #BADGE_ERROR_NOT_EXIST Not exist
 311  * @retval #BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 312  * @retval #BADGE_ERROR_NOT_SUPPORTED Not supported
 313  * @see #badge_error_e
 314  * @see badge_foreach_cb()
 315  */
 316 int badge_foreach(badge_foreach_cb callback, void *user_data);
 317
 318 /**
 319  * @brief Enumeration for Badge Action.
 320  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 321  */
 322 enum badge_action {
 323         BADGE_ACTION_CREATE = 0,        /**< Badge created */
 324         BADGE_ACTION_REMOVE,    /**< Badge removed */
 325         BADGE_ACTION_UPDATE,    /**< Badge updated */
 326         BADGE_ACTION_CHANGED_DISPLAY,   /**< The display option of the badge changed  */
 327         BADGE_ACTION_SERVICE_READY,     /**< The badge service is ready */
 328 };
 329
 330 /**
 331  * @brief Called when the badge information is changed.
 332  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 333  * @param[in] action The type of the change. Refer #badge_action
 334  * @param[in] app_id The name of the application
 335  * @param[in] count The count of the badge
 336  * @param[in] user_data The user data passed from the callback register function
 337  * @pre badge_register_changed_cb() will invoke this callback.
 338  * @see badge_unregister_changed_cb()
 339  */
 340 typedef void (*badge_change_cb)(unsigned int action, const char *app_id,
 341                         unsigned int count, void *user_data);
 342 /**
 343  * @brief Registers a callback function to receive badge change event.
 344  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 345  * @privlevel public
 346  * @privilege %http://tizen.org/privilege/notification
 347  * @remarks Should be used in the homescreen.\n
 348  * Prospective Clients : Homescreen.
 349  * @param[in] callback The callback function
 350  * @param[in] user_data The user data to be passed to the callback function
 351  * @return #BADGE_ERROR_NONE if success, other value if failure
 352  * @retval #BADGE_ERROR_NONE Success
 353  * @retval #BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 354  * @retval #BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 355  * @retval #BADGE_ERROR_IO_ERROR Error from I/O
 356  * @retval #BADGE_ERROR_OUT_OF_MEMORY Out of memory
 357  * @retval #BADGE_ERROR_SERVICE_NOT_READY Service is not ready
 358  * @retval #BADGE_ERROR_NOT_SUPPORTED Not supported
 359  * @see #badge_error_e
 360  * @see badge_new()
 361  * @see badge_remove()
 362  * @see badge_set_count()
 363  */
 364 int badge_register_changed_cb(badge_change_cb callback, void *user_data);
 365
 366 /**
 367  * @brief Unregisters a callback function to receive badge change event.
 368  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 369  * @privlevel public
 370  * @privilege %http://tizen.org/privilege/notification
 371  * @param[in] callback The callback function
 372  * @return #BADGE_ERROR_NONE if success, other value if failure
 373  * @retval #BADGE_ERROR_NONE Success
 374  * @retval #BADGE_ERROR_INVALID_PARAMETER Invalid parameter
 375  * @retval #BADGE_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 376  * @retval #BADGE_ERROR_NOT_EXIST Not exist
 377  * @retval #BADGE_ERROR_NOT_SUPPORTED Not supported
 378  * @see #badge_error_e
 379  * @see badge_register_changed_cb()
 380  */
 381 int badge_unregister_changed_cb(badge_change_cb callback);
 382
 383 /**
 384  * @}
 385  */
 386
 387 #ifdef __cplusplus
 388 }
 389 #endif /* __cplusplus */
 390
 391 #endif /* __BADGE_DEF_H__ */
 392
 393