include/notification_list.h

   1 /*
   2  *  libnotification
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Seungtaek Chung <seungtaek.chung@samsung.com>, Mi-Ju Lee <miju52.lee@samsung.com>, Xi Zhichan <zhichan.xi@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22 #ifndef __NOTIFICATION_LIST_H__
  23 #define __NOTIFICATION_LIST_H__
  24
  25 #include <notification.h>
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /**
  32  * @file notification_list.h
  33  * @brief This file contains the notification list APIs.
  34  */
  35
  36 /**
  37  * @internal
  38  * @addtogroup NOTIFICATION_LIST
  39  * @{
  40  */
  41
  42 /**
  43  * @brief Notification list handle.
  44  * @since_tizen 2.3
  45  */
  46 typedef struct _notification_list *notification_list_h;
  47
  48 /**
  49  * @internal
  50  * @brief Gets the head pointer of the notification list.
  51  * @since_tizen 2.3
  52  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
  53  * @param[in] list Notification list handle
  54  * @return Notification list handle on success, NULL on failure
  55  * @retval #notification_list_h Success
  56  * @retval NULL Failure
  57  * @exception #NOTIFICATION_ERROR_NONE Success
  58  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
  59  * @see #notification_list_h
  60  * @par Sample code:
  61  * @code
  62 #include <notification.h>
  63 ...
  64 {
  65         notification_list_h noti_list = NULL;
  66         int noti_err = NOTIFICATION_ERROR_NONE;
  67
  68         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
  69         if(noti_err != NOTIFICATION_ERROR_NONE) {
  70                 return;
  71         }
  72
  73         noti_list = notification_list_get_head(noti_list);
  74 }
  75  * @endcode
  76  */
  77 notification_list_h notification_list_get_head(notification_list_h list);
  78
  79 /**
  80  * @internal
  81  * @brief Gets the tail pointer to the notification list.
  82  * @since_tizen 2.3
  83  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
  84  * @param[in] list Notification list handle
  85  * @return Notification list handle on success, NULL on failure
  86  * @retval #notification_list_h Success
  87  * @retval NULL Failure
  88  * @exception #NOTIFICATION_ERROR_NONE Success
  89  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
  90  * @see #notification_list_h
  91  * @par Sample code:
  92  * @code
  93 #include <notification.h>
  94 ...
  95 {
  96         notification_list_h noti_list = NULL;
  97         int noti_err = NOTIFICATION_ERROR_NONE;
  98
  99         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 100         if(noti_err != NOTIFICATION_ERROR_NONE) {
 101                 return;
 102         }
 103
 104         noti_list = notification_list_get_tail(noti_list);
 105 }
 106  * @endcode
 107  */
 108 notification_list_h notification_list_get_tail(notification_list_h list);
 109
 110 /**
 111  * @internal
 112  * @brief Gets the previous pointer of the current notification list.
 113  * @since_tizen 2.3
 114  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 115  * @param[in] list Notification list handle
 116  * @return Notification list handle on success, NULL on failure
 117  * @retval #notification_list_h Success
 118  * @retval NULL Failure
 119  * @exception #NOTIFICATION_ERROR_NONE Success
 120  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 121  * @see #notification_list_h
 122  * @par Sample code:
 123  * @code
 124 #include <notification.h>
 125 ...
 126 {
 127         notification_list_h noti_list = NULL;
 128         int noti_err = NOTIFICATION_ERROR_NONE;
 129
 130         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 131         if(noti_err != NOTIFICATION_ERROR_NONE) {
 132                 return;
 133         }
 134
 135         noti_list = notification_list_get_prev(noti_list);
 136 }
 137  * @endcode
 138  */
 139 notification_list_h notification_list_get_prev(notification_list_h list);
 140
 141 /**
 142  * @internal
 143  * @brief Gets the next pointer of the current notification list.
 144  * @since_tizen 2.3
 145  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 146  * @param[in] list Notification list handle
 147  * @return Notification list handle on success, NULL on failure
 148  * @retval #notification_list_h Success
 149  * @retval NULL Failure
 150  * @exception #NOTIFICATION_ERROR_NONE Success
 151  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 152  * @see #notification_list_h
 153  * @par Sample code:
 154  * @code
 155 #include <notification.h>
 156 ...
 157 {
 158         notification_list_h noti_list = NULL;
 159         int noti_err = NOTIFICATION_ERROR_NONE;
 160
 161         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 162         if(noti_err != NOTIFICATION_ERROR_NONE) {
 163                 return;
 164         }
 165
 166         noti_list = notification_list_get_next(noti_list);
 167 }
 168  * @endcode
 169  */
 170 notification_list_h notification_list_get_next(notification_list_h list);
 171
 172 /**
 173  * @internal
 174  * @brief Gets the notification handle that the list has.
 175  * @since_tizen 2.3
 176  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 177  * @param[in] list Notification list handle
 178  * @return Notification handle on success, NULL on failure
 179  * @retval #notification_h Success
 180  * @retval NULL Failure
 181  * @exception #NOTIFICATION_ERROR_NONE Success
 182  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 183  * @see #notification_list_h
 184  * @see #notification_h
 185  * @par Sample code:
 186  * @code
 187 #include <notification.h>
 188 ...
 189 {
 190         notification_h noti = NULL;
 191         notification_list_h noti_list = NULL;
 192         int noti_err = NOTIFICATION_ERROR_NONE;
 193
 194         noti_err  = notification_get_grouping_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
 195         if(noti_err != NOTIFICATION_ERROR_NONE) {
 196                 return;
 197         }
 198
 199         noti = notification_list_get_data(noti_list);
 200 }
 201  * @endcode
 202  */
 203 notification_h notification_list_get_data(notification_list_h list);
 204
 205 /**
 206  * @internal
 207  * @brief Appends notification data to the notification list.
 208  * @since_tizen 2.3
 209  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 210  * @param[in] list Notification list handle
 211  * @param[in] noti Notification handle
 212  * @return Notification handle on success, NULL on failure
 213  * @retval #notification_h Success
 214  * @retval NULL Failure
 215  * @exception #NOTIFICATION_ERROR_NONE Success
 216  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 217  * @exception #NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory
 218  * @see #notification_list_h
 219  * @see #notification_h
 220  * @par Sample code:
 221  * @code
 222 #include <notification.h>
 223 ...
 224 {
 225         notification_h noti = NULL;
 226         notification_list_h noti_list = NULL;
 227         int noti_err = NOTIFICATION_ERROR_NONE;
 228
 229         noti = notification_new(NOTIFICATION_TYPE_NOTI, NOTIFICATION_GROUP_ID_NONE, NOTIFICATION_PRIV_ID_NONE);
 230         if(noti == NULL) {
 231                 return;
 232         }
 233
 234         noti_list = notification_list_append(noti_list, noti);
 235 }
 236  * @endcode
 237  */
 238 notification_list_h notification_list_append(notification_list_h list,
 239                                              notification_h noti);
 240
 241 /**
 242  * @internal
 243  * @brief Removes notification data from the notification list.
 244  * @since_tizen 2.3
 245  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 246  * @param[in] list The notification list handle
 247  * @param[in] noti The notification handle
 248  * @return Notification handle on success,
 249  *         otherwise @c NULL on failure
 250  * @retval #notification_h Success
 251  * @retval NULL Failure
 252  * @exception #NOTIFICATION_ERROR_NONE Success
 253  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 254  * @see #notification_list_h
 255  * @see #notification_h
 256  * @par Sample code:
 257  * @code
 258 #include <notification.h>
 259 ...
 260 {
 261         notification_h noti = NULL;
 262         notification_list_h noti_list = NULL;
 263         int noti_err = NOTIFICATION_ERROR_NONE;
 264
 265         ...
 266
 267         noti_list = notification_list_remove(noti_list, noti);
 268 }
 269  * @endcode
 270  */
 271 notification_list_h notification_list_remove(notification_list_h list,
 272                                              notification_h noti);
 273
 274 /**
 275  * @}
 276  */
 277
 278 #ifdef __cplusplus
 279 }
 280 #endif
 281 #endif                          /* __NOTIFICATION_LIST_H__ */