include/notification_list.h

   1 /*
   2  * Copyright (c) 2000 - 2016 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 <notification.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /**
  27  * @file notification_list.h
  28  * @brief This file contains the notification list APIs.
  29  */
  30
  31 /**
  32  * @internal
  33  * @addtogroup NOTIFICATION_LIST
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Notification list handle.
  39  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
  40  */
  41 typedef struct _notification_list *notification_list_h;
  42
  43
  44 /**
  45  * @brief Returns the notification list handle.
  46  * @details If count is equal to @c -1, all notifications are returned.
  47  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  48  * @privlevel public
  49  * @privilege %http://tizen.org/privilege/notification
  50  * @param[in]  type  The notification type
  51  * @param[in]  count The returned notification data number
  52  * @param[out] #NOTIFICATION_ERROR_NONE on success, other value on failure
  53  * @return #NOTIFICATION_ERROR_NONE on success,
  54  *         otherwise any other value on failure
  55  * @retval #NOTIFICATION_ERROR_NONE         Success
  56  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
  57  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
  58  * @see #notification_list_h
  59  * @par Sample code:
  60  * @code
  61 #include <notification.h>
  62 ...
  63 {
  64         notification_list_h noti_list = NULL;
  65         int noti_err = NOTIFICATION_ERROR_NONE;
  66
  67         noti_err = notification_get_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
  68         if(noti_err != NOTIFICATION_ERROR_NONE) {
  69                 return;
  70         }
  71 }
  72  * @endcode
  73  */
  74 int notification_get_list(notification_type_e type,
  75                 int count,
  76                 notification_list_h *list);
  77
  78 int notification_get_list_for_uid(notification_type_e type,
  79                 int count,
  80                 notification_list_h *list, uid_t uid);
  81
  82 /**
  83  * @brief Returns the notification detail list handle of grouping data.
  84  * @details If count is equal to c -1, all notifications are returned.
  85  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  86  * @privlevel public
  87  * @privilege %http://tizen.org/privilege/notification
  88  * @param[in]  pkgname  The caller application package name
  89  * @param[in]  group_id The group ID
  90  * @param[in]  priv_id  The private ID
  91  * @param[in]  count    The returned notification data number
  92  * @param[out] list     The notification list handle
  93  * @return #NOTIFICATION_ERROR_NONE if success,
  94  *         other value if failure
  95  * @retval #NOTIFICATION_ERROR_NONE Success
  96  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
  97  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
  98  * @see #notification_list_h
  99  * @par Sample code:
 100  * @code
 101 #include <notification.h>
 102 ...
 103 {
 104         notification_list_h noti_list = NULL;
 105         int noti_err = NOTIFICATION_ERROR_NONE;
 106
 107         noti_err = notification_get_detail_list(pkgname, group_id, priv_id, -1, &noti_list);
 108         if(noti_err != NOTIFICATION_ERROR_NONE) {
 109                 return;
 110         }
 111 }
 112  * @endcode
 113  */
 114 int notification_get_detail_list(const char *pkgname,
 115                 int group_id,
 116                 int priv_id,
 117                 int count,
 118                 notification_list_h *list);
 119
 120 int notification_get_detail_list_for_uid(const char *pkgname,
 121                 int group_id,
 122                 int priv_id,
 123                 int count,
 124                 notification_list_h *list,
 125                 uid_t uid);
 126
 127 /**
 128  * @brief Frees a notification list.
 129  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 130  * @privlevel public
 131  * @privilege %http://tizen.org/privilege/notification
 132  * @param[in] list The notification list handle
 133  * @return #NOTIFICATION_ERROR_NONE on success,
 134  *         otherwise any other value on failure
 135  * @retval #NOTIFICATION_ERROR_NONE         Success
 136  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 137  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 138  * @pre notification_get_grouping_list() or notification_get_detail_list().
 139  * @see #notification_list_h
 140  * @par Sample code:
 141  * @code
 142 #include <notification.h>
 143 ...
 144 {
 145         notification_list_h noti_list = NULL;
 146         int noti_err = NOTIFICATION_ERROR_NONE;
 147
 148         ...
 149
 150         noti_err = notification_free_list(noti_list);
 151         if(noti_err != NOTIFICATION_ERROR_NONE) {
 152                 return;
 153         }
 154 }
 155  * @endcode
 156  */
 157 int notification_free_list(notification_list_h list);
 158
 159
 160 /**
 161  * @brief Gets the head pointer of the notification list.
 162  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 163  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 164  * @param[in] list Notification list handle
 165  * @return Notification list handle on success, NULL on failure
 166  * @retval #notification_list_h Success
 167  * @retval NULL Failure
 168  * @exception #NOTIFICATION_ERROR_NONE Success
 169  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 170  * @see #notification_list_h
 171  * @par Sample code:
 172  * @code
 173 #include <notification.h>
 174 ...
 175 {
 176         notification_list_h noti_list = NULL;
 177         int noti_err = NOTIFICATION_ERROR_NONE;
 178
 179         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 180         if(noti_err != NOTIFICATION_ERROR_NONE) {
 181                 return;
 182         }
 183
 184         noti_list = notification_list_get_head(noti_list);
 185 }
 186  * @endcode
 187  */
 188 notification_list_h notification_list_get_head(notification_list_h list);
 189
 190 /**
 191  * @brief Gets the tail pointer to the notification list.
 192  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @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_tail(noti_list);
 215 }
 216  * @endcode
 217  */
 218 notification_list_h notification_list_get_tail(notification_list_h list);
 219
 220 /**
 221  * @brief Gets the previous pointer of the current notification list.
 222  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 223  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 224  * @param[in] list Notification list handle
 225  * @return Notification list handle on success, NULL on failure
 226  * @retval #notification_list_h Success
 227  * @retval NULL Failure
 228  * @exception #NOTIFICATION_ERROR_NONE Success
 229  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 230  * @see #notification_list_h
 231  * @par Sample code:
 232  * @code
 233 #include <notification.h>
 234 ...
 235 {
 236         notification_list_h noti_list = NULL;
 237         int noti_err = NOTIFICATION_ERROR_NONE;
 238
 239         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 240         if(noti_err != NOTIFICATION_ERROR_NONE) {
 241                 return;
 242         }
 243
 244         noti_list = notification_list_get_prev(noti_list);
 245 }
 246  * @endcode
 247  */
 248 notification_list_h notification_list_get_prev(notification_list_h list);
 249
 250 /**
 251  * @brief Gets the next pointer of the current notification list.
 252  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 253  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 254  * @param[in] list Notification list handle
 255  * @return Notification list handle on success, NULL on failure
 256  * @retval #notification_list_h Success
 257  * @retval NULL Failure
 258  * @exception #NOTIFICATION_ERROR_NONE Success
 259  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 260  * @see #notification_list_h
 261  * @par Sample code:
 262  * @code
 263 #include <notification.h>
 264 ...
 265 {
 266         notification_list_h noti_list = NULL;
 267         int noti_err = NOTIFICATION_ERROR_NONE;
 268
 269         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 270         if(noti_err != NOTIFICATION_ERROR_NONE) {
 271                 return;
 272         }
 273
 274         noti_list = notification_list_get_next(noti_list);
 275 }
 276  * @endcode
 277  */
 278 notification_list_h notification_list_get_next(notification_list_h list);
 279
 280 /**
 281  * @brief Gets the notification handle that the list has.
 282  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 283  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 284  * @param[in] list Notification list handle
 285  * @return Notification handle on success, NULL on failure
 286  * @retval #notification_h Success
 287  * @retval NULL Failure
 288  * @exception #NOTIFICATION_ERROR_NONE Success
 289  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 290  * @see #notification_list_h
 291  * @see #notification_h
 292  * @par Sample code:
 293  * @code
 294 #include <notification.h>
 295 ...
 296 {
 297         notification_h noti = NULL;
 298         notification_list_h noti_list = NULL;
 299         int noti_err = NOTIFICATION_ERROR_NONE;
 300
 301         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 302         if(noti_err != NOTIFICATION_ERROR_NONE) {
 303                 return;
 304         }
 305
 306         noti = notification_list_get_data(noti_list);
 307 }
 308  * @endcode
 309  */
 310 notification_h notification_list_get_data(notification_list_h list);
 311
 312 /**
 313  * @brief Appends notification data to the notification list.
 314  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 315  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 316  * @param[in] list Notification list handle
 317  * @param[in] noti Notification handle
 318  * @return Notification handle on success, NULL on failure
 319  * @retval #notification_h Success
 320  * @retval NULL Failure
 321  * @exception #NOTIFICATION_ERROR_NONE Success
 322  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 323  * @exception #NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory
 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 = notification_new(NOTIFICATION_TYPE_NOTI, NOTIFICATION_GROUP_ID_NONE, NOTIFICATION_PRIV_ID_NONE);
 336         if(noti == NULL) {
 337                 return;
 338         }
 339
 340         noti_list = notification_list_append(noti_list, noti);
 341 }
 342  * @endcode
 343  */
 344 notification_list_h notification_list_append(notification_list_h list,
 345                                              notification_h noti);
 346
 347 /**
 348  * @brief Removes notification data from the notification list.
 349  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 350  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 351  * @param[in] list The notification list handle
 352  * @param[in] noti The notification handle
 353  * @return Notification handle on success,
 354  *         otherwise @c NULL on failure
 355  * @retval #notification_h Success
 356  * @retval NULL Failure
 357  * @exception #NOTIFICATION_ERROR_NONE Success
 358  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 359  * @see #notification_list_h
 360  * @see #notification_h
 361  * @par Sample code:
 362  * @code
 363 #include <notification.h>
 364 ...
 365 {
 366         notification_h noti = NULL;
 367         notification_list_h noti_list = NULL;
 368         int noti_err = NOTIFICATION_ERROR_NONE;
 369
 370         ...
 371
 372         noti_list = notification_list_remove(noti_list, noti);
 373 }
 374  * @endcode
 375  */
 376 notification_list_h notification_list_remove(notification_list_h list,
 377                                              notification_h noti);
 378
 379 /**
 380  * @}
 381  */
 382
 383 #ifdef __cplusplus
 384 }
 385 #endif
 386 #endif /* __NOTIFICATION_LIST_H__ */
 387