notification/include/notification_list.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 #ifndef __NOTIFICATION_LIST_H__
  18 #define __NOTIFICATION_LIST_H__
  19
  20 #include <sys/types.h>
  21 #include <notification.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file notification_list.h
  29  * @brief This file contains the notification list APIs.
  30  */
  31
  32 /**
  33  * @internal
  34  * @addtogroup NOTIFICATION_LIST
  35  * @{
  36  */
  37
  38 /**
  39  * @brief Notification list handle.
  40  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
  41  */
  42 typedef struct _notification_list *notification_list_h;
  43
  44
  45 /**
  46  * @internal
  47  * @brief Returns the notification list handle.
  48  * @details If count is equal to @c -1, all notifications are returned.
  49  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  50  * @privlevel public
  51  * @privilege %http://tizen.org/privilege/notification
  52  * @param[in] type The notification type
  53  * @param[in] count The returned notification data number
  54  * @param[out] list The notification list handle
  55  * @return #NOTIFICATION_ERROR_NONE on success,
  56  *         otherwise any other value on failure
  57  * @retval #NOTIFICATION_ERROR_NONE         Success
  58  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
  59  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
  60  * @see #notification_list_h
  61  * @par Sample code:
  62  * @code
  63 #include <notification.h>
  64 ...
  65 {
  66         notification_list_h noti_list = NULL;
  67         int noti_err = NOTIFICATION_ERROR_NONE;
  68
  69         noti_err = notification_get_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
  70         if (noti_err != NOTIFICATION_ERROR_NONE) {
  71                 return;
  72         }
  73 }
  74  * @endcode
  75  */
  76 int notification_get_list(notification_type_e type,
  77                 int count,
  78                 notification_list_h *list);
  79
  80 int notification_get_list_for_uid(notification_type_e type,
  81                 int count,
  82                 notification_list_h *list, uid_t uid);
  83
  84 /**
  85  * @internal
  86  * @brief Gets the notification list associated with the partition into pages.
  87  * @since_tizen 4.0
  88  * @privlevel public
  89  * @privilege %http://tizen.org/privilege/notification
  90  * @param[in]  type            The notification type
  91  * @param[in]  page_number     The page number of the value set \n
  92  *                             It starts from @c 1.
  93  * @param[in]  count_per_page  The desired maximum count of the data items per page
  94  *                             The maximum value is 100, If the value is set more than 100, \n
  95  *                             it is automatically set 100.
  96  * @param[out] list            The notification list handle
  97  * @return #NOTIFICATION_ERROR_NONE on success,
  98  *         otherwise any other value on failure
  99  * @retval #NOTIFICATION_ERROR_NONE         Success
 100  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 101  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 102  * @see #notification_list_h
 103  */
 104 int notification_get_list_by_page(notification_type_e type,
 105                 int page_number, int count_per_page, notification_list_h *list);
 106
 107 int notification_get_list_by_page_for_uid(notification_type_e type,
 108                 int page_number, int count_per_page, notification_list_h *list, uid_t uid);
 109 /**
 110  * @internal
 111  * @brief Returns the notification detail list handle of grouping data.
 112  * @details If count is equal to c -1, all notifications are returned.
 113  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 114  * @privlevel public
 115  * @privilege %http://tizen.org/privilege/notification
 116  * @param[in]  app_id  The caller application ID
 117  * @param[in]  group_id The group ID
 118  * @param[in]  priv_id  The private ID
 119  * @param[in]  count    The returned notification data number
 120  * @param[out] list     The notification list handle
 121  * @return #NOTIFICATION_ERROR_NONE if success,
 122  *         other value if failure
 123  * @retval #NOTIFICATION_ERROR_NONE Success
 124  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 125  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 126  * @see #notification_list_h
 127  * @par Sample code:
 128  * @code
 129 #include <notification.h>
 130 ...
 131 {
 132         notification_list_h noti_list = NULL;
 133         int noti_err = NOTIFICATION_ERROR_NONE;
 134
 135         noti_err = notification_get_detail_list(app_id, group_id, priv_id, -1, &noti_list);
 136         if (noti_err != NOTIFICATION_ERROR_NONE) {
 137                 return;
 138         }
 139 }
 140  * @endcode
 141  */
 142 int notification_get_detail_list(const char *app_id,
 143                 int group_id,
 144                 int priv_id,
 145                 int count,
 146                 notification_list_h *list);
 147
 148 int notification_get_detail_list_for_uid(const char *app_id,
 149                 int group_id,
 150                 int priv_id,
 151                 int count,
 152                 notification_list_h *list,
 153                 uid_t uid);
 154
 155 /**
 156  * @internal
 157  * @brief Frees a notification list.
 158  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 159  * @privlevel public
 160  * @privilege %http://tizen.org/privilege/notification
 161  * @param[in] list The notification list handle
 162  * @return #NOTIFICATION_ERROR_NONE on success,
 163  *         otherwise any other value on failure
 164  * @retval #NOTIFICATION_ERROR_NONE         Success
 165  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 166  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 167  * @pre notification_get_grouping_list() or notification_get_detail_list().
 168  * @see #notification_list_h
 169  * @par Sample code:
 170  * @code
 171 #include <notification.h>
 172 ...
 173 {
 174         notification_list_h noti_list = NULL;
 175         int noti_err = NOTIFICATION_ERROR_NONE;
 176
 177         ...
 178
 179         noti_err = notification_free_list(noti_list);
 180         if (noti_err != NOTIFICATION_ERROR_NONE) {
 181                 return;
 182         }
 183 }
 184  * @endcode
 185  */
 186 int notification_free_list(notification_list_h list);
 187
 188
 189 /**
 190  * @internal
 191  * @brief Gets the head pointer of the notification list.
 192  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 193  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 194  * @param[in] list Notification list handle
 195  * @return Notification list handle on success, NULL on failure
 196  * @retval #notification_list_h Success
 197  * @retval NULL Failure
 198  * @exception #NOTIFICATION_ERROR_NONE Success
 199  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 200  * @see #notification_list_h
 201  * @par Sample code:
 202  * @code
 203 #include <notification.h>
 204 ...
 205 {
 206         notification_list_h noti_list = NULL;
 207         int noti_err = NOTIFICATION_ERROR_NONE;
 208
 209         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 210         if (noti_err != NOTIFICATION_ERROR_NONE) {
 211                 return;
 212         }
 213
 214         noti_list = notification_list_get_head(noti_list);
 215 }
 216  * @endcode
 217  */
 218 notification_list_h notification_list_get_head(notification_list_h list);
 219
 220 /**
 221  * @internal
 222  * @brief Gets the tail pointer to the notification list.
 223  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 224  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 225  * @param[in] list Notification list handle
 226  * @return Notification list handle on success, NULL on failure
 227  * @retval #notification_list_h Success
 228  * @retval NULL Failure
 229  * @exception #NOTIFICATION_ERROR_NONE Success
 230  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 231  * @see #notification_list_h
 232  * @par Sample code:
 233  * @code
 234 #include <notification.h>
 235 ...
 236 {
 237         notification_list_h noti_list = NULL;
 238         int noti_err = NOTIFICATION_ERROR_NONE;
 239
 240         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 241         if (noti_err != NOTIFICATION_ERROR_NONE) {
 242                 return;
 243         }
 244
 245         noti_list = notification_list_get_tail(noti_list);
 246 }
 247  * @endcode
 248  */
 249 notification_list_h notification_list_get_tail(notification_list_h list);
 250
 251 /**
 252  * @internal
 253  * @brief Gets the previous pointer of the current notification list.
 254  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 255  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 256  * @param[in] list Notification list handle
 257  * @return Notification list handle on success, NULL on failure
 258  * @retval #notification_list_h Success
 259  * @retval NULL Failure
 260  * @exception #NOTIFICATION_ERROR_NONE Success
 261  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 262  * @see #notification_list_h
 263  * @par Sample code:
 264  * @code
 265 #include <notification.h>
 266 ...
 267 {
 268         notification_list_h noti_list = NULL;
 269         int noti_err = NOTIFICATION_ERROR_NONE;
 270
 271         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 272         if (noti_err != NOTIFICATION_ERROR_NONE) {
 273                 return;
 274         }
 275
 276         noti_list = notification_list_get_prev(noti_list);
 277 }
 278  * @endcode
 279  */
 280 notification_list_h notification_list_get_prev(notification_list_h list);
 281
 282 /**
 283  * @internal
 284  * @brief Gets the next pointer of the current notification list.
 285  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 286  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 287  * @param[in] list Notification list handle
 288  * @return Notification list handle on success, NULL on failure
 289  * @retval #notification_list_h Success
 290  * @retval NULL Failure
 291  * @exception #NOTIFICATION_ERROR_NONE Success
 292  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 293  * @see #notification_list_h
 294  * @par Sample code:
 295  * @code
 296 #include <notification.h>
 297 ...
 298 {
 299         notification_list_h noti_list = NULL;
 300         int noti_err = NOTIFICATION_ERROR_NONE;
 301
 302         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 303         if (noti_err != NOTIFICATION_ERROR_NONE) {
 304                 return;
 305         }
 306
 307         noti_list = notification_list_get_next(noti_list);
 308 }
 309  * @endcode
 310  */
 311 notification_list_h notification_list_get_next(notification_list_h list);
 312
 313 /**
 314  * @internal
 315  * @brief Gets the notification handle that the list has.
 316  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 317  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 318  * @param[in] list Notification list handle
 319  * @return Notification handle on success, NULL on failure
 320  * @retval #notification_h Success
 321  * @retval NULL Failure
 322  * @exception #NOTIFICATION_ERROR_NONE Success
 323  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 324  * @see #notification_list_h
 325  * @see #notification_h
 326  * @par Sample code:
 327  * @code
 328 #include <notification.h>
 329 ...
 330 {
 331         notification_h noti = NULL;
 332         notification_list_h noti_list = NULL;
 333         int noti_err = NOTIFICATION_ERROR_NONE;
 334
 335         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 336         if (noti_err != NOTIFICATION_ERROR_NONE) {
 337                 return;
 338         }
 339
 340         noti = notification_list_get_data(noti_list);
 341 }
 342  * @endcode
 343  */
 344 notification_h notification_list_get_data(notification_list_h list);
 345
 346
 347 /**
 348  * @internal
 349  * @brief Gets a number of the notification list.
 350  * @since_tizen 3.0
 351  * @param[in] list Notification list handle
 352  * @return A number of notification list handle on success, 0 on failure
 353  * @exception #NOTIFICATION_ERROR_NONE Success
 354  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 355  * @see #notification_list_h
 356  * @see #notification_h
 357  * @par Sample code:
 358  * @code
 359 include <notification.h>
 360 ...
 361 {
 362         int count = 0;
 363         notification_list_h noti_list = NULL;
 364         int noti_err = NOTIFICATION_ERROR_NONE;
 365
 366         noti_err = notification_get_detail_list(app_id, group_id, priv_id, -1, &noti_list);
 367         if (noti_err != NOTIFICATION_ERROR_NONE) {
 368                 return;
 369         }
 370
 371         count = notification_list_get_count(noti_list);
 372 }
 373  * @endcode
 374  */
 375 int notification_list_get_count(notification_list_h list);
 376
 377 /**
 378  * @internal
 379  * @brief Appends notification data to the notification list.
 380  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 381  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 382  * @param[in] list Notification list handle
 383  * @param[in] noti Notification handle
 384  * @return Notification handle on success, NULL on failure
 385  * @retval #notification_h Success
 386  * @retval NULL Failure
 387  * @exception #NOTIFICATION_ERROR_NONE Success
 388  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 389  * @exception #NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory
 390  * @see #notification_list_h
 391  * @see #notification_h
 392  * @par Sample code:
 393  * @code
 394 #include <notification.h>
 395 ...
 396 {
 397         notification_h noti = NULL;
 398         notification_list_h noti_list = NULL;
 399         int noti_err = NOTIFICATION_ERROR_NONE;
 400
 401         noti = notification_new(NOTIFICATION_TYPE_NOTI, NOTIFICATION_GROUP_ID_NONE, NOTIFICATION_PRIV_ID_NONE);
 402         if (noti == NULL) {
 403                 return;
 404         }
 405
 406         noti_list = notification_list_append(noti_list, noti);
 407 }
 408  * @endcode
 409  */
 410 notification_list_h notification_list_append(notification_list_h list,
 411                                              notification_h noti);
 412
 413 /**
 414  * @internal
 415  * @brief Removes notification data from the notification list.
 416  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 417  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 418  * @param[in] list The notification list handle
 419  * @param[in] noti The notification handle
 420  * @return Notification handle on success,
 421  *         otherwise @c NULL on failure
 422  * @retval #notification_h Success
 423  * @retval NULL Failure
 424  * @exception #NOTIFICATION_ERROR_NONE Success
 425  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 426  * @see #notification_list_h
 427  * @see #notification_h
 428  * @par Sample code:
 429  * @code
 430 #include <notification.h>
 431 ...
 432 {
 433         notification_h noti = NULL;
 434         notification_list_h noti_list = NULL;
 435         int noti_err = NOTIFICATION_ERROR_NONE;
 436
 437         ...
 438
 439         noti_list = notification_list_remove(noti_list, noti);
 440 }
 441  * @endcode
 442  */
 443 notification_list_h notification_list_remove(notification_list_h list,
 444                                              notification_h noti);
 445
 446 /**
 447  * @}
 448  */
 449
 450 #ifdef __cplusplus
 451 }
 452 #endif
 453 #endif /* __NOTIFICATION_LIST_H__ */
 454