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