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