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 /**
  79  * @brief Returns the notification detail list handle of grouping data.
  80  * @details If count is equal to c -1, all notifications are returned.
  81  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  82  * @privlevel public
  83  * @privilege %http://tizen.org/privilege/notification
  84  * @param[in]  pkgname  The caller application package name
  85  * @param[in]  group_id The group ID
  86  * @param[in]  priv_id  The private ID
  87  * @param[in]  count    The returned notification data number
  88  * @param[out] list     The notification list handle
  89  * @return #NOTIFICATION_ERROR_NONE if success,
  90  *         other value if failure
  91  * @retval #NOTIFICATION_ERROR_NONE Success
  92  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
  93  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
  94  * @see #notification_list_h
  95  * @par Sample code:
  96  * @code
  97 #include <notification.h>
  98 ...
  99 {
 100         notification_list_h noti_list = NULL;
 101         int noti_err = NOTIFICATION_ERROR_NONE;
 102
 103         noti_err = notification_get_detail_list(pkgname, group_id, priv_id, -1, &noti_list);
 104         if(noti_err != NOTIFICATION_ERROR_NONE) {
 105                 return;
 106         }
 107 }
 108  * @endcode
 109  */
 110 int notification_get_detail_list(const char *pkgname,
 111                                                   int group_id,
 112                                                   int priv_id,
 113                                                   int count,
 114                                                   notification_list_h *list);
 115
 116 /**
 117  * @brief Frees a notification list.
 118  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 119  * @privlevel public
 120  * @privilege %http://tizen.org/privilege/notification
 121  * @param[in] list The notification list handle
 122  * @return #NOTIFICATION_ERROR_NONE on success,
 123  *         otherwise any other value on failure
 124  * @retval #NOTIFICATION_ERROR_NONE         Success
 125  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 126  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 127  * @pre notification_get_grouping_list() or notification_get_detail_list().
 128  * @see #notification_list_h
 129  * @par Sample code:
 130  * @code
 131 #include <notification.h>
 132 ...
 133 {
 134         notification_list_h noti_list = NULL;
 135         int noti_err = NOTIFICATION_ERROR_NONE;
 136
 137         ...
 138
 139         noti_err = notification_free_list(noti_list);
 140         if(noti_err != NOTIFICATION_ERROR_NONE) {
 141                 return;
 142         }
 143 }
 144  * @endcode
 145  */
 146 int notification_free_list(notification_list_h list);
 147
 148
 149 /**
 150  * @brief Gets the head pointer of the notification list.
 151  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 152  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 153  * @param[in] list Notification list handle
 154  * @return Notification list handle on success, NULL on failure
 155  * @retval #notification_list_h Success
 156  * @retval NULL Failure
 157  * @exception #NOTIFICATION_ERROR_NONE Success
 158  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 159  * @see #notification_list_h
 160  * @par Sample code:
 161  * @code
 162 #include <notification.h>
 163 ...
 164 {
 165         notification_list_h noti_list = NULL;
 166         int noti_err = NOTIFICATION_ERROR_NONE;
 167
 168         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 169         if(noti_err != NOTIFICATION_ERROR_NONE) {
 170                 return;
 171         }
 172
 173         noti_list = notification_list_get_head(noti_list);
 174 }
 175  * @endcode
 176  */
 177 notification_list_h notification_list_get_head(notification_list_h list);
 178
 179 /**
 180  * @brief Gets the tail pointer to the notification list.
 181  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 182  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 183  * @param[in] list Notification list handle
 184  * @return Notification list handle on success, NULL on failure
 185  * @retval #notification_list_h Success
 186  * @retval NULL Failure
 187  * @exception #NOTIFICATION_ERROR_NONE Success
 188  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 189  * @see #notification_list_h
 190  * @par Sample code:
 191  * @code
 192 #include <notification.h>
 193 ...
 194 {
 195         notification_list_h noti_list = NULL;
 196         int noti_err = NOTIFICATION_ERROR_NONE;
 197
 198         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 199         if(noti_err != NOTIFICATION_ERROR_NONE) {
 200                 return;
 201         }
 202
 203         noti_list = notification_list_get_tail(noti_list);
 204 }
 205  * @endcode
 206  */
 207 notification_list_h notification_list_get_tail(notification_list_h list);
 208
 209 /**
 210  * @brief Gets the previous pointer of the current notification list.
 211  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 212  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 213  * @param[in] list Notification list handle
 214  * @return Notification list handle on success, NULL on failure
 215  * @retval #notification_list_h Success
 216  * @retval NULL Failure
 217  * @exception #NOTIFICATION_ERROR_NONE Success
 218  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 219  * @see #notification_list_h
 220  * @par Sample code:
 221  * @code
 222 #include <notification.h>
 223 ...
 224 {
 225         notification_list_h noti_list = NULL;
 226         int noti_err = NOTIFICATION_ERROR_NONE;
 227
 228         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 229         if(noti_err != NOTIFICATION_ERROR_NONE) {
 230                 return;
 231         }
 232
 233         noti_list = notification_list_get_prev(noti_list);
 234 }
 235  * @endcode
 236  */
 237 notification_list_h notification_list_get_prev(notification_list_h list);
 238
 239 /**
 240  * @brief Gets the next pointer of the current notification list.
 241  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 242  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 243  * @param[in] list Notification list handle
 244  * @return Notification list handle on success, NULL on failure
 245  * @retval #notification_list_h Success
 246  * @retval NULL Failure
 247  * @exception #NOTIFICATION_ERROR_NONE Success
 248  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 249  * @see #notification_list_h
 250  * @par Sample code:
 251  * @code
 252 #include <notification.h>
 253 ...
 254 {
 255         notification_list_h noti_list = NULL;
 256         int noti_err = NOTIFICATION_ERROR_NONE;
 257
 258         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 259         if(noti_err != NOTIFICATION_ERROR_NONE) {
 260                 return;
 261         }
 262
 263         noti_list = notification_list_get_next(noti_list);
 264 }
 265  * @endcode
 266  */
 267 notification_list_h notification_list_get_next(notification_list_h list);
 268
 269 /**
 270  * @brief Gets the notification handle that the list has.
 271  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 272  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 273  * @param[in] list Notification list handle
 274  * @return Notification handle on success, NULL on failure
 275  * @retval #notification_h Success
 276  * @retval NULL Failure
 277  * @exception #NOTIFICATION_ERROR_NONE Success
 278  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 279  * @see #notification_list_h
 280  * @see #notification_h
 281  * @par Sample code:
 282  * @code
 283 #include <notification.h>
 284 ...
 285 {
 286         notification_h noti = NULL;
 287         notification_list_h noti_list = NULL;
 288         int noti_err = NOTIFICATION_ERROR_NONE;
 289
 290         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 291         if(noti_err != NOTIFICATION_ERROR_NONE) {
 292                 return;
 293         }
 294
 295         noti = notification_list_get_data(noti_list);
 296 }
 297  * @endcode
 298  */
 299 notification_h notification_list_get_data(notification_list_h list);
 300
 301 /**
 302  * @brief Appends notification data to the notification list.
 303  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 304  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 305  * @param[in] list Notification list handle
 306  * @param[in] noti Notification handle
 307  * @return Notification handle on success, NULL on failure
 308  * @retval #notification_h Success
 309  * @retval NULL Failure
 310  * @exception #NOTIFICATION_ERROR_NONE Success
 311  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 312  * @exception #NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory
 313  * @see #notification_list_h
 314  * @see #notification_h
 315  * @par Sample code:
 316  * @code
 317 #include <notification.h>
 318 ...
 319 {
 320         notification_h noti = NULL;
 321         notification_list_h noti_list = NULL;
 322         int noti_err = NOTIFICATION_ERROR_NONE;
 323
 324         noti = notification_new(NOTIFICATION_TYPE_NOTI, NOTIFICATION_GROUP_ID_NONE, NOTIFICATION_PRIV_ID_NONE);
 325         if(noti == NULL) {
 326                 return;
 327         }
 328
 329         noti_list = notification_list_append(noti_list, noti);
 330 }
 331  * @endcode
 332  */
 333 notification_list_h notification_list_append(notification_list_h list,
 334                                              notification_h noti);
 335
 336 /**
 337  * @brief Removes notification data from the notification list.
 338  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 339  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 340  * @param[in] list The notification list handle
 341  * @param[in] noti The notification handle
 342  * @return Notification handle on success,
 343  *         otherwise @c NULL on failure
 344  * @retval #notification_h Success
 345  * @retval NULL Failure
 346  * @exception #NOTIFICATION_ERROR_NONE Success
 347  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 348  * @see #notification_list_h
 349  * @see #notification_h
 350  * @par Sample code:
 351  * @code
 352 #include <notification.h>
 353 ...
 354 {
 355         notification_h noti = NULL;
 356         notification_list_h noti_list = NULL;
 357         int noti_err = NOTIFICATION_ERROR_NONE;
 358
 359         ...
 360
 361         noti_list = notification_list_remove(noti_list, noti);
 362 }
 363  * @endcode
 364  */
 365 notification_list_h notification_list_remove(notification_list_h list,
 366                                              notification_h noti);
 367
 368 /**
 369  * @}
 370  */
 371
 372 #ifdef __cplusplus
 373 }
 374 #endif
 375 #endif /* __NOTIFICATION_LIST_H__ */
 376