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