include/notification.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_H__
  23 #define __NOTIFICATION_H__
  24
  25 #include <time.h>
  26 #include <bundle.h>
  27
  28 #include <notification_error.h>
  29 #include <notification_type.h>
  30 #include <notification_list.h>
  31 #include <notification_status.h>
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38  * @file notification.h
  39  * @brief This file contains the notification API.
  40  */
  41
  42 /**
  43  * @addtogroup NOTIFICATION_MODULE
  44  * @{
  45  */
  46
  47 /**
  48  * @brief Sets an absolute path for an image file to display on the notification view.
  49  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
  50  * @param[in] noti       The notification handle
  51  * @param[in] type       The notification image type
  52  * @param[in] image_path The image file full path
  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  * @pre Notification handle should be created by notification_create().
  58  * @see #notification_image_type_e
  59  * @see notification_create()
  60  * @par Sample code:
  61  * @code
  62 #include <notification.h>
  63 ...
  64 {
  65         notification_h noti = NULL;
  66         int noti_err = NOTIFICATION_ERROR_NONE;
  67
  68         noti = notification_create(NOTIFICATION_TYPE_NOTI);
  69         if(noti == NULL) {
  70                 return;
  71         }
  72
  73         noti_err  = notification_set_image(noti, NOTIFICATION_IMAGE_TYPE_ICON, APP_IMAGE_FULL_PATH);
  74         if(noti_err != NOTIFICATION_ERROR_NONE) {
  75                 notification_free(noti);
  76                 return;
  77         }
  78 }
  79  * @endcode
  80  */
  81 int notification_set_image(notification_h noti,
  82                                             notification_image_type_e type,
  83                                             const char *image_path);
  84
  85 /**
  86  * @brief Gets the absolute path of an image file.
  87  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
  88  * @remarks Do not free @a image_path. It will be freed when notification_free() is called.
  89  * @param[in] noti Notification handle
  90  * @param[in] type Notification image type
  91  * @param[out] image_path image file full path
  92  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
  93  * @retval NOTIFICATION_ERROR_NONE Success
  94  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
  95  * @pre Notification handle should be created by notification_create().
  96  * @see #notification_image_type_e
  97  * @see notification_create()
  98  * @par Sample code:
  99  * @code
 100  #include <notification.h>
 101  ...
 102  {
 103         char *image_path = NULL;
 104         int noti_err = NOTIFICATION_ERROR_NONE;
 105
 106         noti_err  = notification_get_image(noti, NOTIFICATION_IMAGE_TYPE_ICON, &image_path);
 107         if(noti_err != NOTIFICATION_ERROR_NONE) {
 108                 return;
 109         }
 110 }
 111  * @endcode
 112  */
 113 int notification_get_image(notification_h noti,
 114                                             notification_image_type_e type,
 115                                             char **image_path);
 116
 117 /**
 118  * @brief Sets a timestamp.
 119  * @details If input_time is @c 0, time information is taken from the current time.
 120  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 121  * @param[in] noti       The notification handle
 122  * @param[in] input_time The input time
 123  * @return #NOTIFICATION_ERROR_NONE on success,
 124  *         otherwise any other value on failure
 125  * @retval #NOTIFICATION_ERROR_NONE         Success
 126  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 127  * @pre Notification handle should be created by notification_create().
 128  * @see notification_create()
 129  * @par Sample code:
 130  * @code
 131 #include <notification.h>
 132  ...
 133   {
 134          notification_h noti = NULL;
 135          int noti_err = NOTIFICATION_ERROR_NONE;
 136
 137          noti = notification_create(NOTIFICATION_TYPE_NOTI);
 138          if(noti == NULL) {
 139                  return;
 140          }
 141
 142          noti_err  = notification_set_time(noti, time(NULL));
 143          if(noti_err != NOTIFICATION_ERROR_NONE) {
 144                 notification_free(noti);
 145                  return;
 146          }
 147  }
 148  * @endcode
 149  */
 150 int notification_set_time(notification_h noti,
 151                                            time_t input_time);
 152
 153 /**
 154  * @brief Gets a timestamp.
 155  * @details If ret_time is @c 0, time information is not set before.
 156  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 157  * @param[in]  noti     The notification handle
 158  * @param[out] ret_time The return time value
 159  * @return #NOTIFICATION_ERROR_NONE on success,
 160  *         otherwise any other value on failure
 161  * @retval #NOTIFICATION_ERROR_NONE         Success
 162  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 163  * @pre Notification handle should be created by notification_create().
 164  * @see notification_create()
 165  * @par Sample code:
 166  * @code
 167  #include <notification.h>
 168  ...
 169  {
 170         time_t ret_time;
 171         int noti_err = NOTIFICATION_ERROR_NONE;
 172
 173         noti_err  = notification_get_time(noti, &ret_time);
 174         if(noti_err != NOTIFICATION_ERROR_NONE) {
 175                 return;
 176         }
 177 }
 178  * @endcode
 179  */
 180 int notification_get_time(notification_h noti,
 181                                            time_t * ret_time);
 182
 183 /**
 184  * @brief Gets an insertion timestamp of the notification.
 185  * @details If ret_time is @c 0, this notification data is not inserted before.
 186  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 187  * @param[in]  noti      The notification handle
 188  * @param[out] ret_time  The return time value
 189  * @return #NOTIFICATION_ERROR_NONE on success,
 190  *         otherwise any other value on failure
 191  * @retval #NOTIFICATION_ERROR_NONE         Success
 192  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 193  * @par Sample code:
 194  * @code
 195  #include <notification.h>
 196   ...
 197   {
 198          time_t ret_time;
 199          int noti_err = NOTIFICATION_ERROR_NONE;
 200
 201          noti_err  = notification_get_insert_time(noti, &ret_time);
 202          if(noti_err != NOTIFICATION_ERROR_NONE) {
 203                  return;
 204          }
 205  }
 206  * @endcode
 207  */
 208 int notification_get_insert_time(notification_h noti,
 209                                                   time_t * ret_time);
 210
 211 /**
 212  * @brief Sets the text to display on the notification view.
 213  * @details Sets title, content string. If the text is formatted data (only %d, %f, %s are supported), type - value pair should be set.
 214  * If %d, the type #NOTIFICATION_VARIABLE_TYPE_INT and the value is an integer.
 215  * If %f, the type #NOTIFICATION_VARIABLE_TYPE_DOUBLE and the value is a double.
 216  * If %s, the type #NOTIFICATION_VARIABLE_TYPE_STRING and the value is a string.
 217  * If the type is #NOTIFICATION_VARIABLE_TYPE_COUNT, notification count is displaying with text.
 218  * If the value is #NOTIFICATION_COUNT_POS_LEFT, count is displayed at the left of the text.
 219  * If the value is #NOTIFICATION_COUNT_POS_IN, count is displayed in the text when text has %d format.
 220  * If the value is #NOTIFICATION_COUNT_POS_RIGHT, count is displayed at the right of the text.
 221  * Variable parameters should be terminated #NOTIFICATION_VARIABLE_TYPE_NONE.
 222  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 223  * @param[in] noti      The notification handle
 224  * @param[in] type      The notification text type
 225  * @param[in] text      The basic text
 226  * @param[in] key       The text key for localization
 227  * @param[in] args_type The variable parameter that type - value pair
 228  * @return #NOTIFICATION_ERROR_NONE on success,
 229  *         otherwise any other value on failure
 230  * @retval #NOTIFICATION_ERROR_NONE         Success
 231  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 232  * @pre notification handle should be created by notification_create().
 233  * @par Sample code:
 234  * @code
 235 #include <notification.h>
 236 ...
 237 {
 238         notification_h noti = NULL;
 239         int noti_err = NOTIFICATION_ERROR_NONE;
 240
 241         noti = notification_create(NOTIFICATION_TYPE_NOTI);
 242         if(noti == NULL) {
 243                 return;
 244         }
 245
 246         noti_err  = notification_set_text(noti, NOTIFICATION_TEXT_TYPE_TITLE, "I'm Title", "IDS_APP_BODY_IM_TITLE", NOTIFICATION_VARIABLE_TYPE_NONE);
 247         if(noti_err != NOTIFICATION_ERROR_NONE) {
 248                 notification_free(noti);
 249                 return;
 250         }
 251 }
 252  * @endcode
 253  */
 254 int notification_set_text(notification_h noti,
 255                                            notification_text_type_e type,
 256                                            const char *text,
 257                                            const char *key,
 258                                            int args_type, ...);
 259
 260 /**
 261  * @brief Gets the text from the notification handle.
 262  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 263  * @param[in]  noti The notification handle
 264  * @param[in]  type The notification text type
 265  * @param[out] text The notification text
 266  * @return #NOTIFICATION_ERROR_NONE on success,
 267  *         otherwise any other value on failure
 268  * @retval #NOTIFICATION_ERROR_NONE         Success
 269  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 270  * @par Sample code:
 271  * @code
 272 #include <notification.h>
 273 ...
 274 {
 275         notification_h noti = NULL;
 276         int noti_err = NOTIFICATION_ERROR_NONE;
 277         char *text = NULL;
 278
 279         noti_err  = notification_get_text(noti, NOTIFICATION_TEXT_TYPE_TITLE, &text);
 280         if(noti_err != NOTIFICATION_ERROR_NONE) {
 281                 return;
 282         }
 283 }
 284  * @endcode
 285  */
 286 int notification_get_text(notification_h noti,
 287                                            notification_text_type_e type,
 288                                            char **text);
 289
 290 /**
 291  * @brief Sets the timestamp to display on the notification view.
 292  * @details The timestamp will be converted to a formatted string and it will be displayed on the set text area.
 293  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 294  * @param[in] noti The notification handle
 295  * @param[in] type The notification text type
 296  * @param[in] time The timestamp
 297  * @return #NOTIFICATION_ERROR_NONE on success,
 298  *         otherwise any other value on failure
 299  * @retval #NOTIFICATION_ERROR_NONE         Success
 300  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 301  * @pre Notification handle should be created by notification_create().
 302  */
 303 int notification_set_time_to_text(notification_h noti, notification_text_type_e type,
 304                                                                 time_t time);
 305
 306 /**
 307  * @brief Gets the timestamp from the notification handle.
 308  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 309  * @param[in] noti The notification handle
 310  * @param[in] type The notification text type
 311  * @param[in] time The pointer of time stamp
 312  * @return #NOTIFICATION_ERROR_NONE on success,
 313  *         otherwise any other value on failure
 314  * @retval #NOTIFICATION_ERROR_NONE         Success
 315  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 316  * @pre Notification handle should be created by notification_create().
 317  */
 318 int notification_get_time_from_text(notification_h noti, notification_text_type_e type,
 319                                                                 time_t *time);
 320
 321 /**
 322  * @internal
 323  * @brief Sets the text domain to localize the notification.
 324  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 325  * @param[in] noti   The notification handle
 326  * @param[in] domain The text domain
 327  * @param[in] dir    The text dir
 328  * @return #NOTIFICATION_ERROR_NONE on success,
 329  *         otherwise any other value on failure
 330  * @retval #NOTIFICATION_ERROR_NONE         Success
 331  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 332  * @par Sample code:
 333  * @code
 334 #include <notification.h>
 335 ...
 336 {
 337         notification_h noti = NULL;
 338         int noti_err = NOTIFICATION_ERROR_NONE;
 339
 340         noti = notification_create(NOTIFICATION_TYPE_NOTI);
 341         if(noti == NULL) {
 342                 return;
 343         }
 344
 345         noti_err  = notification_set_text_domain(noti, PACKAGE, LOCALEDIR);
 346         if(noti_err != NOTIFICATION_ERROR_NONE) {
 347                 notification_free(noti);
 348                 return;
 349         }
 350 }
 351  * @endcode
 352  */
 353 int notification_set_text_domain(notification_h noti,
 354                                                   const char *domain,
 355                                                   const char *dir);
 356
 357 /**
 358  * @internal
 359  * @brief Gets the text domain from the notification handle.
 360  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 361  * @remarks Do not free returned domain and dir. They are freed when notification_free() or notification_free_list() is called.
 362  * @param[in]  noti   The notification handle
 363  * @param[out] domain The domain
 364  * @param[out] dir    The locale dir
 365  * @return #NOTIFICATION_ERROR_NONE on success,
 366  *         otherwise any other value on failure
 367  * @retval #NOTIFICATION_ERROR_NONE         Success
 368  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 369  * @par Sample code:
 370  * @code
 371 #include <notification.h>
 372 ...
 373 {
 374         notification_h noti = NULL;
 375         int noti_err = NOTIFICATION_ERROR_NONE;
 376         char *domain = NULL;
 377         char *dir = NULL;
 378
 379         noti_err  = notification_get_text_domain(noti, &domain, &dir);
 380         if(noti_err != NOTIFICATION_ERROR_NONE) {
 381                 return;
 382         }
 383 }
 384  * @endcode
 385  */
 386 int notification_get_text_domain(notification_h noti,
 387                                                   char **domain,
 388                                                   char **dir);
 389
 390 /**
 391  * @brief Sets the sound type for the notification.
 392  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 393  * @param[in] noti The notification handle
 394  * @param[in] type The notification sound type
 395  * @param[in] path The user sound file path
 396  * @return #NOTIFICATION_ERROR_NONE on success,
 397  *         otherwise any other value on failure
 398  * @retval #NOTIFICATION_ERROR_NONE         Success
 399  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 400  * @par Sample code:
 401  * @code
 402 #include <notification.h>
 403 ...
 404 {
 405         notification_h noti = NULL;
 406         int noti_err = NOTIFICATION_ERROR_NONE;
 407
 408         noti_err  = notification_set_sound(noti, NOTIFICATION_SOUND_TYPE_DEFAULT, NULL);
 409         if(noti_err != NOTIFICATION_ERROR_NONE) {
 410                 return;
 411         }
 412 }
 413  * @endcode
 414  */
 415 int notification_set_sound(notification_h noti,
 416                                             notification_sound_type_e type,
 417                                             const char *path);
 418
 419 /**
 420  * @brief Gets the sound type from the notification handle.
 421  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 422  * @param[in]  noti  The notification handle
 423  * @param[out] type  The notification sound type
 424  * @param[out] path  The user sound file path
 425  * @return #NOTIFICATION_ERROR_NONE on success,
 426  *         otherwise any other value on failure
 427  * @retval #NOTIFICATION_ERROR_NONE Success
 428  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 429  * @par Sample code:
 430  * @code
 431 #include <notification.h>
 432 ...
 433 {
 434         notification_h noti = NULL;
 435         int noti_err = NOTIFICATION_ERROR_NONE;
 436         notification_sound_type_e type = NOTIFICATION_SOUND_TYPE_NONE;
 437
 438         noti_err  = notification_get_sound(noti, &type, NULL);
 439         if(noti_err != NOTIFICATION_ERROR_NONE) {
 440                 return;
 441         }
 442 }
 443  * @endcode
 444  */
 445 int notification_get_sound(notification_h noti,
 446                                             notification_sound_type_e *type,
 447                                             const char **path);
 448
 449 /**
 450  * @brief Sets the vibration type for the notification.
 451  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 452  * @param[in] noti The notification handle
 453  * @param[in] type The notification vibration type
 454  * @param[in] path The user vibration file path
 455  * @return #NOTIFICATION_ERROR_NONE on success,
 456  *         otherwise any other value on failure
 457  * @retval #NOTIFICATION_ERROR_NONE         Success
 458  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 459  * @par Sample code:
 460  * @code
 461 #include <notification.h>
 462 ...
 463 {
 464         notification_h noti = NULL;
 465         int noti_err = NOTIFICATION_ERROR_NONE;
 466
 467         noti_err  = notification_set_vibration(noti, NOTIFICATION_VIBRATION_TYPE_DEFAULT, NULL);
 468         if(noti_err != NOTIFICATION_ERROR_NONE) {
 469                 return;
 470         }
 471 }
 472  * @endcode
 473  */
 474 int notification_set_vibration(notification_h noti,
 475                                                 notification_vibration_type_e type,
 476                                                 const char *path);
 477
 478 /**
 479  * @brief Gets the vibrate type from the notification handle.
 480  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 481  * @param[in]  noti The notification handle
 482  * @param[out] type The notification sound type
 483  * @param[out] path The user vibration file path
 484  * @return #NOTIFICATION_ERROR_NONE on success,
 485  *         otherwise other value on failure
 486  * @retval #NOTIFICATION_ERROR_NONE         Success
 487  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 488  * @par Sample code:
 489  * @code
 490 #include <notification.h>
 491 ...
 492  {
 493         notification_h noti = NULL;
 494         int noti_err = NOTIFICATION_ERROR_NONE;
 495         notification_vibration_type_e type = NOTIFICATION_VIBRATION_TYPE_NONE;
 496
 497         noti_err  = notification_get_vibration(noti, &type, NULL);
 498         if(noti_err != NOTIFICATION_ERROR_NONE) {
 499                 return;
 500         }
 501 }
 502   * @endcode
 503   */
 504 int notification_get_vibration(notification_h noti,
 505                                                 notification_vibration_type_e *type,
 506                                                 const char **path);
 507
 508 /**
 509  * @brief Sets the LED displaying option.
 510  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 511  * @param[in] noti      The notification handle
 512  * @param[in] operation The LED notification operation
 513  * @param[in] led_argb  The notification led color
 514  * @return #NOTIFICATION_ERROR_NONE on success,
 515  *         otherwise other value on failure
 516  * @retval #NOTIFICATION_ERROR_NONE         Success
 517  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 518  * @par Sample code:
 519  * @code
 520 #include <notification.h>
 521 ...
 522 {
 523         notification_h noti = NULL;
 524         int noti_err = NOTIFICATION_ERROR_NONE;
 525
 526         noti_err  = notification_set_led(noti, NOTIFICATION_LED_TYPE_DEFAULT, NULL);
 527         if(noti_err != NOTIFICATION_ERROR_NONE) {
 528                 return;
 529         }
 530 }
 531  * @endcode
 532  */
 533 int notification_set_led(notification_h noti,
 534                                                 notification_led_op_e operation,
 535                                                 int led_argb);
 536
 537 /**
 538  * @brief Gets the LED displaying option from the notification handle.
 539  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 540  * @param[in]  noti      The notification handle
 541  * @param[out] operation The LED notification operation
 542  * @param[out] led_argb  The notification LED color
 543  * @return #NOTIFICATION_ERROR_NONE on success,
 544  *         otherwise any other value on failure
 545  * @retval #NOTIFICATION_ERROR_NONE         Success
 546  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 547  * @par Sample code:
 548  * @code
 549 #include <notification.h>
 550 ...
 551  {
 552         notification_h noti = NULL;
 553         int noti_err = NOTIFICATION_ERROR_NONE;
 554         notification_led_type_e type = NOTIFICATION_LED_TYPE_NONE;
 555
 556         noti_err  = notification_get_led(noti, &type, NULL);
 557         if(noti_err != NOTIFICATION_ERROR_NONE) {
 558                 return;
 559         }
 560 }
 561   * @endcode
 562   */
 563 int notification_get_led(notification_h noti,
 564                                                 notification_led_op_e *operation,
 565                                                 int *led_argb);
 566
 567 /**
 568  * @brief Sets the time period of flashing the LED.
 569  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 570  * @param[in] noti   The notification handle
 571  * @param[in] on_ms  The time for turning on the LED
 572  * @param[in] off_ms The time for turning off the LED
 573  * @return #NOTIFICATION_ERROR_NONE on success,
 574  *         otherwise any other value on failure
 575  * @retval #NOTIFICATION_ERROR_NONE         Success
 576  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 577  * @par Sample code:
 578  * @code
 579 #include <notification.h>
 580 ...
 581 {
 582         notification_h noti = NULL;
 583         int noti_err = NOTIFICATION_ERROR_NONE;
 584
 585         noti_err  = notification_set_led_time_period(noti, 100, 100);
 586         if(noti_err != NOTIFICATION_ERROR_NONE) {
 587                 return;
 588         }
 589 }
 590  * @endcode
 591  */
 592 int notification_set_led_time_period(notification_h noti,
 593                                                 int on_ms, int off_ms);
 594
 595 /**
 596  * @brief Gets the time period of flashing the LED from the notification handle.
 597  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 598  * @param[in]  noti   The notification handle
 599  * @param[out] on_ms  The time for turning on the LED
 600  * @param[out] off_ms The time for turning on the LED
 601  * @return #NOTIFICATION_ERROR_NONE on success,
 602  *         otherwise any other value on failure
 603  * @retval #NOTIFICATION_ERROR_NONE         Success
 604  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 605  * @par Sample code:
 606  * @code
 607 #include <notification.h>
 608 ...
 609  {
 610         notification_h noti = NULL;
 611         int noti_err = NOTIFICATION_ERROR_NONE;
 612         int led_on_ms = 0;
 613         int led_off_ms = 0;
 614
 615         noti_err  = notification_get_led_time_period(noti, &led_on_ms, &led_off_ms);
 616         if(noti_err != NOTIFICATION_ERROR_NONE) {
 617                 return;
 618         }
 619 }
 620   * @endcode
 621   */
 622 int notification_get_led_time_period(notification_h noti,
 623                                                 int *on_ms, int *off_ms);
 624
 625 /**
 626  * @brief Sets the launch option for a notification.
 627  * @details When notification data selected in display application, application launched by app_control_send_launch_request with app_control handle.
 628  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 629  * @param[in] noti The notification handle
 630  * @param[in] type Launching option type
 631  * @param[in] option App Control handler
 632  * @return #NOTIFICATION_ERROR_NONE on success,
 633  *         otherwise any other value on failure
 634  * @retval #NOTIFICATION_ERROR_NONE         Success
 635  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 636  * @par Sample code:
 637  * @code
 638 #include <notification.h>
 639 ...
 640 {
 641         notification_h noti = NULL;
 642         app_control_h app_control = NULL;
 643         int noti_err = NOTIFICATION_ERROR_NONE;
 644
 645         ...
 646
 647         app_control_create(&app_control);
 648         app_control_set_app_id(app_control, "org.tizen.app");
 649
 650         ...
 651
 652         noti_err  = notification_set_launch_option(noti, NOTIFICATION_LAUNCH_OPTION_APP_CONTROL, (void *)app_control);
 653         if(noti_err != NOTIFICATION_ERROR_NONE) {
 654                 notification_free(noti);
 655                 return;
 656         }
 657
 658         app_control_destroy(app_control);
 659 }
 660  * @endcode
 661  */
 662 int notification_set_launch_option(notification_h noti,
 663                                                                 notification_launch_option_type type, void *option);
 664
 665 /**
 666  * @brief Gets the launch option from the notification handle.
 667  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 668  * @remarks You must release @a app_control using app_control_destroy().
 669  * @param[in]  noti        The notification handle
 670  * @param[in] type Launching option type
 671  * @param[out] option The pointer of App Control handler
 672  * @return #NOTIFICATION_ERROR_NONE on success,
 673  *         otherwise any other value on failure
 674  * @retval #NOTIFICATION_ERROR_NONE         Success
 675  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 676  * @par Sample code:
 677  * @code
 678 #include <notification.h>
 679 ...
 680 {
 681         app_control_h app_control = NULL;
 682         app_control_create(&app_control);
 683
 684         ...
 685
 686         noti_err = notification_get_launch_option(noti, NOTIFICATION_LAUNCH_OPTION_APP_CONTROL, (void *)&app_control);
 687         if(noti_err != NOTIFICATION_ERROR_NONE) {
 688                 notification_free(noti);
 689                 return;
 690         }
 691 }
 692  * @endcode
 693  */
 694 int notification_get_launch_option(notification_h noti,
 695                                                                 notification_launch_option_type type, void *option);
 696
 697 /**
 698  * @brief Sets the property of the notification.
 699  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 700  * @param[in] noti  The notification handle
 701  * @param[in] flags The property with | operation
 702  * @return #NOTIFICATION_ERROR_NONE on success,
 703  *         otherwise any other value on failure
 704  * @retval #NOTIFICATION_ERROR_NONE         Success
 705  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 706  * @par Sample code:
 707  * @code
 708 #include <notification.h>
 709 ...
 710 {
 711         notification_h noti = NULL;
 712         int noti_err = NOTIFICATION_ERROR_NONE;
 713         bundle *b = NULL;
 714
 715         noti = notification_create(NOTIFICATION_TYPE_NOTI);
 716         if(noti == NULL) {
 717                 return;
 718         }
 719
 720         noti_err  = notification_set_property(noti, NOTIFICATION_PROP_DISPLAY_ONLY_SIMMODE | NOTIFICATION_PROP_DISABLE_APP_LAUNCH);
 721         if(noti_err != NOTIFICATION_ERROR_NONE) {
 722                 notification_free(noti);
 723                 return;
 724         }
 725 }
 726  * @endcode
 727  */
 728 int notification_set_property(notification_h noti,
 729                                                int flags);
 730
 731 /**
 732  * @brief Gets the property of the notification from the notification handle.
 733  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 734  * @param[in]  noti  The notification handle
 735  * @param[out] flags The notification property
 736  * @return #NOTIFICATION_ERROR_NONE on success,
 737  *         otherwise any other value on failure
 738  * @retval #NOTIFICATION_ERROR_NONE         Success
 739  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 740  * @par Sample code:
 741  * @code
 742 #include <notification.h>
 743 ...
 744 {
 745         notification_h noti = NULL;
 746         int noti_err = NOTIFICATION_ERROR_NONE;
 747         int flags = 0;
 748
 749         noti_err  = notification_get_property(noti, &flags);
 750         if(noti_err != NOTIFICATION_ERROR_NONE) {
 751                 return;
 752         }
 753 }
 754  * @endcode
 755  */
 756 int notification_get_property(notification_h noti,
 757                                                int *flags);
 758
 759 /**
 760  * @brief Sets applications to display the notification.
 761  * @details All display application is enable(NOTIFICATION_DISPLAY_APP_ALL) if you are not call this API.
 762  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 763  * @param[in] noti    The notification handle
 764  * @param[in] applist The with | operation
 765  * @return #NOTIFICATION_ERROR_NONE on success,
 766  *         otherwise any other value on failure
 767  * @retval #NOTIFICATION_ERROR_NONE         Success
 768  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 769  * @par Sample code:
 770  * @code
 771 #include <notification.h>
 772 ...
 773 {
 774         notification_h noti = NULL;
 775         int noti_err = NOTIFICATION_ERROR_NONE;
 776         bundle *b = NULL;
 777
 778         noti = notification_create(NOTIFICATION_TYPE_NOTI);
 779         if(noti == NULL) {
 780                 return;
 781         }
 782
 783         noti_err  = notification_set_display_applist(noti, NOTIFICATION_DISPLAY_APP_NOTIFICATION_TRAY | NOTIFICATION_DISPLAY_APP_TICKER);
 784         if(noti_err != NOTIFICATION_ERROR_NONE) {
 785                 notification_free(noti);
 786                 return;
 787         }
 788 }
 789 }
 790  * @endcode
 791  */
 792 int notification_set_display_applist(notification_h noti,
 793                                                       int applist);
 794
 795 /**
 796  * @brief Gets the application list displaying the notification from the notification handle.
 797  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 798  * @param[in]  noti    The notification handle
 799  * @param[out] applist The display application list
 800  * @return #NOTIFICATION_ERROR_NONE on success,
 801  *         otherwise any other value on failure
 802  * @retval #NOTIFICATION_ERROR_NONE         Success
 803  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 804  * @par Sample code:
 805  * @code
 806 #include <notification.h>
 807 ...
 808 {
 809         notification_h noti = NULL;
 810         int noti_err = NOTIFICATION_ERROR_NONE;
 811         int applist = 0;
 812
 813         noti_err  = notification_get_display_applist(noti, &applist);
 814         if(noti_err != NOTIFICATION_ERROR_NONE) {
 815                 return;
 816         }
 817 }
 818  * @endcode
 819  */
 820 int notification_get_display_applist(notification_h noti,
 821                                                       int *applist);
 822
 823 /**
 824  * @brief Sets the initial size for the ongoing type.
 825  * @details After notification_post() call, the size is not updated.
 826  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 827  * @param[in] noti The notification handle
 828  * @param[in] size The double type size
 829  * @return #NOTIFICATION_ERROR_NONE on success,
 830  *         otherwise any other value on failure
 831  * @retval #NOTIFICATION_ERROR_NONE         Success
 832  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 833  * @par Sample code:
 834  * @code
 835 #include <notification.h>
 836 ...
 837 {
 838         notification_h noti = NULL;
 839         int noti_err = NOTIFICATION_ERROR_NONE;
 840
 841         noti = notification_create(NOTIFICATION_TYPE_NOTI);
 842         if(noti == NULL) {
 843                 return;
 844         }
 845
 846         noti_err  = notification_set_size(noti, 0.0);
 847         if(noti_err != NOTIFICATION_ERROR_NONE) {
 848                 notification_free(noti);
 849                 return;
 850         }
 851 }
 852  * @endcode
 853  */
 854 int notification_set_size(notification_h noti,
 855                                            double size);
 856
 857 /**
 858  * @brief Gets the progress size.
 859  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 860  * @param[in]  noti The notification handle
 861  * @param[out] size The progress size
 862  * @return #NOTIFICATION_ERROR_NONE on success,
 863  *         otherwise any other value on failure
 864  * @retval #NOTIFICATION_ERROR_NONE         Success
 865  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 866  * @par Sample code:
 867  * @code
 868 #include <notification.h>
 869 ...
 870 {
 871         notification_h noti = NULL;
 872         int noti_err = NOTIFICATION_ERROR_NONE;
 873         double size = 0.0;
 874
 875         noti_err  = notification_get_size(noti, &size);
 876         if(noti_err != NOTIFICATION_ERROR_NONE) {
 877                 return;
 878         }
 879 }
 880  * @endcode
 881  */
 882 int notification_get_size(notification_h noti,
 883                                            double *size);
 884
 885 /**
 886  * @brief Sets the initial progress for the ongoing type.
 887  * @details After the notification_post() call, the progress is not updated.
 888  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 889  * @param[in] noti       The notification handle
 890  * @param[in] percentage The progress percentage
 891  * @return #NOTIFICATION_ERROR_NONE on success,
 892  *         otherwise any other value on failure
 893  * @retval #NOTIFICATION_ERROR_NONE         Success
 894  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 895  * @par Sample code:
 896  * @code
 897 #include <notification.h>
 898 ...
 899 {
 900         notification_h noti = NULL;
 901         int noti_err = NOTIFICATION_ERROR_NONE;
 902
 903         noti = notification_create(NOTIFICATION_TYPE_NOTI);
 904         if(noti == NULL) {
 905                 return;
 906         }
 907
 908         noti_err  = notification_set_progress(noti, 0.0);
 909         if(noti_err != NOTIFICATION_ERROR_NONE) {
 910                 notification_free(noti);
 911                 return;
 912         }
 913 }
 914  * @endcode
 915  */
 916 int notification_set_progress(notification_h noti,
 917                                                double percentage);
 918
 919 /**
 920  * @brief Gets the progress from the notification handle.
 921  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 922  * @remarks At the end of the operation, the progress should be @c 1.0.
 923  * @param[in]  noti       The notification handle
 924  * @param[out] percentage The progress percentage
 925  * @return #NOTIFICATION_ERROR_NONE on success,
 926  *         otherwise any other value on failure
 927  * @retval #NOTIFICATION_ERROR_NONE         Success
 928  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 929  * @par Sample code:
 930  * @code
 931 #include <notification.h>
 932 ...
 933 {
 934         notification_h noti = NULL;
 935         int noti_err = NOTIFICATION_ERROR_NONE;
 936         double percentage = 0.0;
 937
 938         noti_err  = notification_get_progress(noti, &percentage);
 939         if(noti_err != NOTIFICATION_ERROR_NONE) {
 940                 return;
 941         }
 942 }
 943  * @endcode
 944  */
 945 int notification_get_progress(notification_h noti,
 946                                                double *percentage);
 947
 948 /**
 949  * @brief Sets the layout of the notification view.
 950  * @details Caller can set displaying layout of notification.
 951  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 952  * @param[in] noti The notification handle
 953  * @param[in] layout The type of layout
 954  * @return #NOTIFICATION_ERROR_NONE on success,
 955  *         otherwise any other value on failure
 956  * @retval #NOTIFICATION_ERROR_NONE         Success
 957  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 958  * @see #notification_ly_type_e
 959  */
 960 int notification_set_layout(notification_h noti,
 961                 notification_ly_type_e layout);
 962
 963 /**
 964  * @brief Gets the layout of the notification view from the notification handle.
 965  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 966  * @param[in]  noti The notification handle
 967  * @param[out] layout The type of layout
 968  * @return #NOTIFICATION_ERROR_NONE on success,
 969  *         otherwise any other value on failure
 970  * @retval #NOTIFICATION_ERROR_NONE         Success
 971  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 972  * @see #notification_ly_type_e
 973  */
 974 int notification_get_layout(notification_h noti,
 975                 notification_ly_type_e *layout);
 976
 977 /**
 978  * @brief Gets the type of a notification.
 979  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
 980  * @param[in]  noti The notification handle
 981  * @param[out] type The notification type
 982  * @return #NOTIFICATION_ERROR_NONE on success,
 983  *         otherwise any other value on failure
 984  * @retval #NOTIFICATION_ERROR_NONE         Success
 985  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 986  * @par Sample code:
 987  * @code
 988 #include <notification.h>
 989 ...
 990  {
 991         int noti_err = NOTIFICATION_ERROR_NONE;
 992         notification_type_e type;
 993
 994         noti_err  = notification_get_type(noti, &type);
 995         if(noti_err != NOTIFICATION_ERROR_NONE) {
 996                 return;
 997         }
 998 }
 999  * @endcode
1000  */
1001 int notification_get_type(notification_h noti,
1002                                            notification_type_e * type);
1003
1004 /**
1005  * @internal
1006  * @brief Inserts a notification.
1007  * @details The notification will be inserted to the database and then it will appear in the notification area.
1008  *          When notification_create() is called, if priv_id is #NOTIFICATION_PRIV_ID_NONE, priv_id returns the internally set priv_id.
1009  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1010  * @privlevel public
1011  * @privilege %http://tizen.org/privilege/notification
1012  * @param[in]  noti    The notification handle
1013  * @param[out] priv_id The private ID
1014  * @return #NOTIFICATION_ERROR_NONE on success,
1015  *         otherwise any other value on failure
1016  * @retval #NOTIFICATION_ERROR_NONE         Success
1017  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1018  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1019  * @pre Notification handle should be created by notification_create().
1020  * @post notification_free().
1021  * @par Sample code:
1022  * @code
1023 #include <notification.h>
1024 ...
1025  {
1026         int noti_err = NOTIFICATION_ERROR_NONE;
1027
1028         noti_err  = notification_insert(noti, NULL);
1029         if(noti_err != NOTIFICATION_ERROR_NONE) {
1030                 return;
1031         }
1032 }
1033  * @endcode
1034  */
1035 int notification_insert(notification_h noti,
1036                                          int *priv_id);
1037
1038 /**
1039  * @brief Updates notification data.
1040  * @details The updated notification will appear in the notification area.
1041  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1042  * @privlevel public
1043  * @privilege %http://tizen.org/privilege/notification
1044  * @param[in] noti The notification handle that is created by notification_create()
1045  * @return #NOTIFICATION_ERROR_NONE on success,
1046  *         otherwise any other value on failure
1047  * @retval #NOTIFICATION_ERROR_NONE         Success
1048  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1049  * @retval #NOTIFICATION_ERROR_NOT_EXIST_ID Priv ID does not exist
1050  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1051  * @par Sample code:
1052  * @code
1053 #include <notification.h>
1054 ...
1055  {
1056         int noti_err = NOTIFICATION_ERROR_NONE;
1057
1058         noti_err  = notification_update(NULL);
1059         if(noti_err != NOTIFICATION_ERROR_NONE) {
1060                 return;
1061         }
1062 }
1063  * @endcode
1064  */
1065 int notification_update(notification_h noti);
1066
1067 /**
1068  * @internal
1069  * @brief Updates a notification, asynchronously.
1070  * @details The updated notification will appear in the notification area.
1071  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1072  * @privlevel public
1073  * @privilege %http://tizen.org/privilege/notification
1074  * @remarks This function updates the notification asynchronously.
1075  * @param[in] noti      The notification handle that is created by notification_create()
1076  * @param[in] result_cb The callback called when an update completed
1077  * @param[in] user_data The user data which you want to use in callback
1078  * @return #NOTIFICATION_ERROR_NONE on success,
1079  *         otherwise any other value on failure
1080  * @retval #NOTIFICATION_ERROR_NONE         Success
1081  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1082  * @retval #NOTIFICATION_ERROR_NOT_EXIST_ID Priv ID does not exist
1083  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1084  * @par Sample code:
1085  * @code
1086 #include <notification.h>
1087 ...
1088  {
1089         int noti_err = NOTIFICATION_ERROR_NONE;
1090
1091         noti_err  = notification_update_async(NULL, result_cb, data);
1092         if(noti_err != NOTIFICATION_ERROR_NONE) {
1093                 return;
1094         }
1095 }
1096  * @endcode
1097  */
1098 int notification_update_async(notification_h noti,
1099                 void (*result_cb)(int priv_id, int result, void *data), void *user_data);
1100
1101 /**
1102  * @brief Deletes a notification with the given handle.
1103  * @details notification_delete() removes notification data from database and notification_free() releases memory of notification data.
1104  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1105  * @privlevel public
1106  * @privilege %http://tizen.org/privilege/notification
1107  * @param[in] noti The notification handle
1108  * @return #NOTIFICATION_ERROR_NONE on success,
1109  *         otherwise any other value on failure
1110  * @retval #NOTIFICATION_ERROR_NONE         Success
1111  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1112  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1113  * @par Sample code:
1114  * @code
1115 #include <notification.h>
1116 ...
1117  {
1118         notificaton_h noti = NULL;
1119         int noti_err = NOTIFICATION_ERROR_NONE;
1120
1121         ...
1122
1123         noti_err  = notification_delete(noti);
1124         if(noti_err != NOTIFICATION_ERROR_NONE) {
1125                 return;
1126         }
1127
1128 }
1129  * @endcode
1130  */
1131 int notification_delete(notification_h noti);
1132
1133 /**
1134  * @brief Creates internal structure data and returns a notification handle.
1135  * @details Available type is #NOTIFICATION_TYPE_NOTI and #NOTIFICATION_TYPE_ONGOING.
1136  * #NOTIFICATION_TYPE_NOTI is remaining notification data even if device is restarted.
1137  * #NOTIFICATION_TYPE_ONGOING can display progressive feather, but notification data is removed after device is restarted.
1138  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1139  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
1140  * @param[in] type The notification type
1141  * @return Notification handle(notification_h) on success,
1142  *         otherwise @c NULL on failure
1143  * @retval notification_h Success
1144  * @retval NULL Failure
1145  * @exception #NOTIFICATION_ERROR_NONE Success
1146  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1147  * @exception #NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory
1148  * @see #notification_type_e
1149  * @par Sample code:
1150  * @code
1151 #include <notification.h>
1152 ...
1153 {
1154         notification_h noti = NULL;
1155
1156         noti = notification_create(NOTIFICATION_TYPE_NOTI);
1157         if(noti == NULL) {
1158                 return;
1159         }
1160         ...
1161 }
1162  * @endcode
1163  */
1164 notification_h notification_create(notification_type_e type);
1165
1166 /**
1167  * @brief Creates a notification clone.
1168  * @details Newly created notification handle is returned.
1169  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1170  * @remarks This cloned notification handle should be freed using notification_free().
1171  * @param[in]  noti  The notification handle
1172  * @param[out] clone The newly created notification handle that has same with input @a noti
1173  * @return #NOTIFICATION_ERROR_NONE if success,
1174  *         otherwise any other value if failure
1175  * @retval #NOTIFICATION_ERROR_NONE         Success
1176  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1177  * @see #notification_type_e
1178  * @par Sample code:
1179  * @code
1180 #include <notification.h>
1181 ...
1182 {
1183         notification_h noti = notification_create(NOTIFICATION_TYPE_NOTI);
1184         notification_h clone = NULL;
1185
1186         notification_clone(noti, &clone);
1187         ...
1188 }
1189  * @endcode
1190  */
1191 int notification_clone(notification_h noti, notification_h *clone);
1192
1193 /**
1194  * @brief Frees the internal structure data of a notification handle.
1195  * @details Internal data of a notification handle is released. Data of the inserted notification is not deleted.
1196  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1197  * @param[in] noti The notification handle
1198  * @return #NOTIFICATION_ERROR_NONE on success,
1199  *         otherwise any other value on failure
1200  * @retval #NOTIFICATION_ERROR_NONE         Success
1201  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1202  * @pre Notification handle should be created by notification_create().
1203  * @par Sample code:
1204  * @code
1205 #include <notification.h>
1206 ...
1207 {
1208         notification_h noti = NULL;
1209         int noti_err = NOTIFICATION_ERROR_NONE;
1210
1211         noti = notification_create(NOTIFICATION_TYPE_NOTI);
1212         if(noti == NULL) {
1213                 return;
1214         }
1215         ...
1216
1217         noti_err = notification_free(noti);
1218         if(noti_err != NOTIFICATION_ERROR_NONE) {
1219                 return;
1220         }
1221 }
1222  * @endcode
1223  */
1224 int notification_free(notification_h noti);
1225
1226 /**
1227  * @}
1228  */
1229
1230 /**
1231  * @internal
1232  * @addtogroup NOTIFICATION_LIST
1233  * @{
1234  */
1235
1236 /**
1237  * @internal
1238  * @brief Returns the notification list handle.
1239  * @details If count is equal to @c -1, all notifications are returned.
1240  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1241  * @privlevel public
1242  * @privilege %http://tizen.org/privilege/notification
1243  * @param[in]  type  The notification type
1244  * @param[in]  count The returned notification data number
1245  * @param[out] #NOTIFICATION_ERROR_NONE on success, other value on failure
1246  * @return #NOTIFICATION_ERROR_NONE on success,
1247  *         otherwise any other value on failure
1248  * @retval #NOTIFICATION_ERROR_NONE         Success
1249  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1250  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1251  * @see #notification_list_h
1252  * @par Sample code:
1253  * @code
1254 #include <notification.h>
1255 ...
1256 {
1257         notification_list_h noti_list = NULL;
1258         int noti_err = NOTIFICATION_ERROR_NONE;
1259
1260         noti_err = notification_get_list(NOTIFICATION_TYPE_NONE, -1, &noti_list);
1261         if(noti_err != NOTIFICATION_ERROR_NONE) {
1262                 return;
1263         }
1264 }
1265  * @endcode
1266  */
1267 int notification_get_list(notification_type_e type,
1268                                            int count,
1269                                            notification_list_h * list);
1270
1271 /**
1272  * @internal
1273  * @brief Returns the notification detail list handle of grouping data.
1274  * @details If count is equal to c -1, all notifications are returned.
1275  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1276  * @privlevel public
1277  * @privilege %http://tizen.org/privilege/notification
1278  * @param[in]  pkgname  The caller application package name
1279  * @param[in]  group_id The group ID
1280  * @param[in]  priv_id  The private ID
1281  * @param[in]  count    The returned notification data number
1282  * @param[out] list     The notification list handle
1283  * @return #NOTIFICATION_ERROR_NONE if success,
1284  *         other value if failure
1285  * @retval #NOTIFICATION_ERROR_NONE Success
1286  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1287  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1288  * @see #notification_list_h
1289  * @par Sample code:
1290  * @code
1291 #include <notification.h>
1292 ...
1293 {
1294         notification_list_h noti_list = NULL;
1295         int noti_err = NOTIFICATION_ERROR_NONE;
1296
1297         noti_err = notification_get_detail_list(pkgname, group_id, priv_id, -1, &noti_list);
1298         if(noti_err != NOTIFICATION_ERROR_NONE) {
1299                 return;
1300         }
1301 }
1302  * @endcode
1303  */
1304 int notification_get_detail_list(const char *pkgname,
1305                                                   int group_id,
1306                                                   int priv_id,
1307                                                   int count,
1308                                                   notification_list_h *list);
1309
1310 /**
1311  * @internal
1312  * @brief Frees a notification list.
1313  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1314  * @privlevel public
1315  * @privilege %http://tizen.org/privilege/notification
1316  * @param[in] list The notification list handle
1317  * @return #NOTIFICATION_ERROR_NONE on success,
1318  *         otherwise any other value on failure
1319  * @retval #NOTIFICATION_ERROR_NONE         Success
1320  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1321  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1322  * @pre notification_get_grouping_list() or notification_get_detail_list().
1323  * @see #notification_list_h
1324  * @par Sample code:
1325  * @code
1326 #include <notification.h>
1327 ...
1328 {
1329         notification_list_h noti_list = NULL;
1330         int noti_err = NOTIFICATION_ERROR_NONE;
1331
1332         ...
1333
1334         noti_err = notification_free_list(noti_list);
1335         if(noti_err != NOTIFICATION_ERROR_NONE) {
1336                 return;
1337         }
1338 }
1339  * @endcode
1340  */
1341 int notification_free_list(notification_list_h list);
1342
1343 /**
1344  * @}
1345  */
1346
1347 /**
1348  * @addtogroup NOTIFICATION_MODULE
1349  * @{
1350  */
1351
1352 /**
1353  * @internal
1354  * @brief Registers a callback for all notification events.
1355  * @details The registered callback could be called for all notification events.
1356  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1357  * @privlevel public
1358  * @privilege %http://tizen.org/privilege/notification
1359  * @param[in] changed_cb The callback function
1360  * @param[in] user_data  The user data
1361  * @return #NOTIFICATION_ERROR_NONE on success,
1362  *         otherwise any other value on failure
1363  * @retval #NOTIFICATION_ERROR_NONE         Success
1364  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1365  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1366  * @see notification_unregister_detailed_changed_cb()
1367  * @par Sample code:
1368  * @code
1369 #include <notification.h>
1370 ...
1371 {
1372         noti_err = notification_register_detailed_changed_cb(app_changed_cb, user_data);
1373         if(noti_err != NOTIFICATION_ERROR_NONE) {
1374                 return;
1375         }
1376 }
1377  * @endcode
1378  */
1379 int notification_register_detailed_changed_cb(
1380                 void (*detailed_changed_cb)(void *data, notification_type_e type, notification_op *op_list, int num_op),
1381                 void *user_data);
1382
1383 /**
1384  * @internal
1385  * @brief Unregisters a callback for all notification events.
1386  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1387  * @privlevel public
1388  * @privilege %http://tizen.org/privilege/notification
1389  * @param[in] changed_cb The callback function
1390  * @return #NOTIFICATION_ERROR_NONE on success,
1391  *         otherwise any other value on failure
1392  * @retval #NOTIFICATION_ERROR_NONE         Success
1393  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1394  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1395  * @see notification_register_detailed_changed_cb()
1396  * @par Sample code:
1397  * @code
1398 #include <notification.h>
1399 ...
1400 {
1401         noti_err = notification_register_detailed_changed_cb(app_changed_cb, user_data);
1402         if(noti_err != NOTIFICATION_ERROR_NONE) {
1403                 return;
1404         }
1405 }
1406  * @endcode
1407  */
1408 int notification_unregister_detailed_changed_cb(
1409                 void (*detailed_changed_cb)(void *data, notification_type_e type, notification_op *op_list, int num_op),
1410                 void *user_data);
1411
1412 /**
1413  * @brief Sets the tag of the notification handle.
1414  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1415  * @param[in] noti Notification handle
1416  * @param[in] tag tag for loading notification handle
1417  * @return #NOTIFICATION_ERROR_NONE on success, other value on failure
1418  * @retval #NOTIFICATION_ERROR_NONE Success
1419  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1420  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1421  * @see notification_get_tag()
1422  * @par Sample code:
1423  * @code
1424 #include <notification.h>
1425 ...
1426 {
1427         notification_h noti = NULL;
1428         int noti_err = NOTIFICATION_ERROR_NONE;
1429
1430         noti = notification_create(NOTIFICATION_TYPE_NOTI);
1431         if(noti == NULL) {
1432                 return;
1433         }
1434         ...
1435
1436         noti_err = notification_set_tag(noti, tag);
1437         if(noti_err != NOTIFICATION_ERROR_NONE) {
1438                 return;
1439         }
1440 }
1441  * @endcode
1442  */
1443 int notification_set_tag(notification_h noti, const char *tag);
1444
1445 /**
1446  * @brief Gets the tag of the notification handle.
1447  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1448  * @param[in] noti Notification handle
1449  * @param[out] tag tag for loading notification handle
1450  * @return #NOTIFICATION_ERROR_NONE on success, other value on failure
1451  * @retval #NOTIFICATION_ERROR_NONE Success
1452  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1453  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1454  * @see notification_set_tag()
1455  * @par Sample code:
1456  * @code
1457 #include <notification.h>
1458 ...
1459 {
1460         int noti_err = NOTIFICATION_ERROR_NONE;
1461         const char *tag = NULL;
1462
1463         ...
1464
1465         noti_err = notification_get_tag(noti, &tag);
1466         if(noti_err != NOTIFICATION_ERROR_NONE) {
1467                 return;
1468         }
1469 }
1470  * @endcode
1471  */
1472 int notification_get_tag(notification_h noti, const char **tag);
1473
1474 /**
1475  * @brief Loads a notification from the notification's database with the tag.
1476  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1477  * @privlevel public
1478  * @privilege %http://tizen.org/privilege/notification
1479  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
1480  * @param[in] tag tag for loading notification handle
1481  * @return Notification handle(notification_h) on success, NULL on failure
1482  * @retval notification_h Success
1483  * @retval NULL Failure
1484  * @exception #NOTIFICATION_ERROR_NONE Success
1485  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1486  * @exception #NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory
1487  * @exception #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1488  * @see #notification_type_e
1489  * @par Sample code:
1490  * @code
1491 #include <notification.h>
1492 ...
1493 {
1494         notification_h noti = NULL;
1495
1496         noti = notification_load_by_tag(tag);
1497         if(noti == NULL) {
1498                 return;
1499         }
1500         ...
1501 }
1502  * @endcode
1503  */
1504 notification_h notification_load_by_tag(const char *tag);
1505
1506 /**
1507  * @brief Deletes all notifications of the given type.
1508  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1509  * @privlevel public
1510  * @privilege %http://tizen.org/privilege/notification
1511  * @param[in] type Notification type
1512  * @return #NOTIFICATION_ERROR_NONE if success, other value if failure
1513  * @retval #NOTIFICATION_ERROR_NONE Success
1514  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1515  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1516  * @par Sample code:
1517  * @code
1518 #include <notification.h>
1519 ...
1520  {
1521         int noti_err = NOTIFICATION_ERROR_NONE;
1522
1523         noti_err  = notification_delete_all(NOTIFICATION_TYPE_NOTI);
1524         if(noti_err != NOTIFICATION_ERROR_NONE) {
1525                 return;
1526         }
1527 }
1528  * @endcode
1529  */
1530 int notification_delete_all(notification_type_e type);
1531
1532 /**
1533  * @brief Posts a notification.
1534  * @since_tizen @if WEARABLE 2.3.1 @elseif MOBILE 2.3 @endif
1535  * @privlevel public
1536  * @privilege %http://tizen.org/privilege/notification
1537  * @param[in] noti Notification handle
1538  * @return #NOTIFICATION_ERROR_NONE if success, other value if failure
1539  * @retval #NOTIFICATION_ERROR_NONE Success
1540  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1541  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1542  * @pre Notification handle should be created by notification_create().
1543  * @post notification_free().
1544  * @par Sample code:
1545  * @code
1546 #include <notification.h>
1547 ...
1548  {
1549         int noti_err = NOTIFICATION_ERROR_NONE;
1550
1551         noti_err  = notification_post(noti);
1552         if(noti_err != NOTIFICATION_ERROR_NONE) {
1553                 return;
1554         }
1555 }
1556  * @endcode
1557  */
1558 int notification_post(notification_h noti);
1559
1560 /**
1561  * @}
1562  */
1563
1564 #ifdef __cplusplus
1565 }
1566 #endif
1567 #endif                          /* __NOTIFICATION_H__ */