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
 324 /**
 325  * @brief Sets the sound type for the notification.
 326  * @since_tizen 2.3
 327  * @param[in] noti The notification handle
 328  * @param[in] type The notification sound type
 329  * @param[in] path The user sound file path
 330  * @return #NOTIFICATION_ERROR_NONE on success,
 331  *         otherwise any other value on failure
 332  * @retval #NOTIFICATION_ERROR_NONE         Success
 333  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 334  * @par Sample code:
 335  * @code
 336 #include <notification.h>
 337 ...
 338 {
 339         notification_h noti = NULL;
 340         int noti_err = NOTIFICATION_ERROR_NONE;
 341
 342         noti_err  = notification_set_sound(noti, NOTIFICATION_SOUND_TYPE_DEFAULT, NULL);
 343         if(noti_err != NOTIFICATION_ERROR_NONE) {
 344                 return;
 345         }
 346 }
 347  * @endcode
 348  */
 349 int notification_set_sound(notification_h noti,
 350                                             notification_sound_type_e type,
 351                                             const char *path);
 352
 353 /**
 354  * @brief Gets the sound type from the notification handle.
 355  * @since_tizen 2.3
 356  * @param[in]  noti  The notification handle
 357  * @param[out] type  The notification sound type
 358  * @param[out] path  The user sound file path
 359  * @return #NOTIFICATION_ERROR_NONE on success,
 360  *         otherwise any other value on failure
 361  * @retval #NOTIFICATION_ERROR_NONE Success
 362  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 363  * @par Sample code:
 364  * @code
 365 #include <notification.h>
 366 ...
 367 {
 368         notification_h noti = NULL;
 369         int noti_err = NOTIFICATION_ERROR_NONE;
 370         notification_sound_type_e type = NOTIFICATION_SOUND_TYPE_NONE;
 371
 372         noti_err  = notification_get_sound(noti, &type, NULL);
 373         if(noti_err != NOTIFICATION_ERROR_NONE) {
 374                 return;
 375         }
 376 }
 377  * @endcode
 378  */
 379 int notification_get_sound(notification_h noti,
 380                                             notification_sound_type_e *type,
 381                                             const char **path);
 382
 383 /**
 384  * @brief Sets the vibration type for the notification.
 385  * @since_tizen 2.3
 386  * @param[in] noti The notification handle
 387  * @param[in] type The notification vibration type
 388  * @param[in] path The user vibration file path
 389  * @return #NOTIFICATION_ERROR_NONE on success,
 390  *         otherwise any other value on failure
 391  * @retval #NOTIFICATION_ERROR_NONE         Success
 392  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 393  * @par Sample code:
 394  * @code
 395 #include <notification.h>
 396 ...
 397 {
 398         notification_h noti = NULL;
 399         int noti_err = NOTIFICATION_ERROR_NONE;
 400
 401         noti_err  = notification_set_vibration(noti, NOTIFICATION_VIBRATION_TYPE_DEFAULT, NULL);
 402         if(noti_err != NOTIFICATION_ERROR_NONE) {
 403                 return;
 404         }
 405 }
 406  * @endcode
 407  */
 408 int notification_set_vibration(notification_h noti,
 409                                                 notification_vibration_type_e type,
 410                                                 const char *path);
 411
 412 /**
 413  * @brief Gets the vibrate type from the notification handle.
 414  * @since_tizen 2.3
 415  * @param[in]  noti The notification handle
 416  * @param[out] type The notification sound type
 417  * @param[out] path The user vibration file path
 418  * @return #NOTIFICATION_ERROR_NONE on success,
 419  *         otherwise other value on failure
 420  * @retval #NOTIFICATION_ERROR_NONE         Success
 421  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 422  * @par Sample code:
 423  * @code
 424 #include <notification.h>
 425 ...
 426  {
 427         notification_h noti = NULL;
 428         int noti_err = NOTIFICATION_ERROR_NONE;
 429         notification_vibration_type_e type = NOTIFICATION_VIBRATION_TYPE_NONE;
 430
 431         noti_err  = notification_get_vibration(noti, &type, NULL);
 432         if(noti_err != NOTIFICATION_ERROR_NONE) {
 433                 return;
 434         }
 435 }
 436   * @endcode
 437   */
 438 int notification_get_vibration(notification_h noti,
 439                                                 notification_vibration_type_e *type,
 440                                                 const char **path);
 441
 442 /**
 443  * @brief Sets the LED displaying option.
 444  * @since_tizen 2.3
 445  * @param[in] noti      The notification handle
 446  * @param[in] operation The LED notification operation
 447  * @param[in] led_argb  The notification led color
 448  * @return #NOTIFICATION_ERROR_NONE on success,
 449  *         otherwise other value on failure
 450  * @retval #NOTIFICATION_ERROR_NONE         Success
 451  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 452  * @par Sample code:
 453  * @code
 454 #include <notification.h>
 455 ...
 456 {
 457         notification_h noti = NULL;
 458         int noti_err = NOTIFICATION_ERROR_NONE;
 459
 460         noti_err  = notification_set_led(noti, NOTIFICATION_LED_TYPE_DEFAULT, NULL);
 461         if(noti_err != NOTIFICATION_ERROR_NONE) {
 462                 return;
 463         }
 464 }
 465  * @endcode
 466  */
 467 int notification_set_led(notification_h noti,
 468                                                 notification_led_op_e operation,
 469                                                 int led_argb);
 470
 471 /**
 472  * @brief Gets the LED displaying option from the notification handle.
 473  * @since_tizen 2.3
 474  * @param[in]  noti      The notification handle
 475  * @param[out] operation The LED notification operation
 476  * @param[out] led_argb  The notification LED color
 477  * @return #NOTIFICATION_ERROR_NONE on success,
 478  *         otherwise any other value on failure
 479  * @retval #NOTIFICATION_ERROR_NONE         Success
 480  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 481  * @par Sample code:
 482  * @code
 483 #include <notification.h>
 484 ...
 485  {
 486         notification_h noti = NULL;
 487         int noti_err = NOTIFICATION_ERROR_NONE;
 488         notification_led_type_e type = NOTIFICATION_LED_TYPE_NONE;
 489
 490         noti_err  = notification_get_led(noti, &type, NULL);
 491         if(noti_err != NOTIFICATION_ERROR_NONE) {
 492                 return;
 493         }
 494 }
 495   * @endcode
 496   */
 497 int notification_get_led(notification_h noti,
 498                                                 notification_led_op_e *operation,
 499                                                 int *led_argb);
 500
 501 /**
 502  * @brief Sets the time period of flashing the LED.
 503  * @since_tizen 2.3
 504  * @param[in] noti   The notification handle
 505  * @param[in] on_ms  The time for turning on the LED
 506  * @param[in] off_ms The time for turning off the LED
 507  * @return #NOTIFICATION_ERROR_NONE on success,
 508  *         otherwise any other value on failure
 509  * @retval #NOTIFICATION_ERROR_NONE         Success
 510  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 511  * @par Sample code:
 512  * @code
 513 #include <notification.h>
 514 ...
 515 {
 516         notification_h noti = NULL;
 517         int noti_err = NOTIFICATION_ERROR_NONE;
 518
 519         noti_err  = notification_set_led_time_period(noti, 100, 100);
 520         if(noti_err != NOTIFICATION_ERROR_NONE) {
 521                 return;
 522         }
 523 }
 524  * @endcode
 525  */
 526 int notification_set_led_time_period(notification_h noti,
 527                                                 int on_ms, int off_ms);
 528
 529 /**
 530  * @brief Gets the time period of flashing the LED from the notification handle.
 531  * @since_tizen 2.3
 532  * @param[in]  noti   The notification handle
 533  * @param[out] on_ms  The time for turning on the LED
 534  * @param[out] off_ms The time for turning on the LED
 535  * @return #NOTIFICATION_ERROR_NONE on success,
 536  *         otherwise any other value on failure
 537  * @retval #NOTIFICATION_ERROR_NONE         Success
 538  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 539  * @par Sample code:
 540  * @code
 541 #include <notification.h>
 542 ...
 543  {
 544         notification_h noti = NULL;
 545         int noti_err = NOTIFICATION_ERROR_NONE;
 546         int led_on_ms = 0;
 547         int led_off_ms = 0;
 548
 549         noti_err  = notification_get_led_time_period(noti, &led_on_ms, &led_off_ms);
 550         if(noti_err != NOTIFICATION_ERROR_NONE) {
 551                 return;
 552         }
 553 }
 554   * @endcode
 555   */
 556 int notification_get_led_time_period(notification_h noti,
 557                                                 int *on_ms, int *off_ms);
 558
 559 /**
 560  * @brief Sets the launch option for a notification.
 561  * @details When notification data selected in display application, application launched by app_control_send_launch_request with app_control handle.
 562  * @since_tizen 2.3
 563  * @param[in] noti The notification handle
 564  * @param[in] type Launching option type
 565  * @param[in] option App Control handler
 566  * @return #NOTIFICATION_ERROR_NONE on success,
 567  *         otherwise any other value on failure
 568  * @retval #NOTIFICATION_ERROR_NONE         Success
 569  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 570  * @par Sample code:
 571  * @code
 572 #include <notification.h>
 573 ...
 574 {
 575         notification_h noti = NULL;
 576         app_control_h app_control = NULL;
 577         int noti_err = NOTIFICATION_ERROR_NONE;
 578
 579         ...
 580
 581         app_control_create(&app_control);
 582         app_control_set_app_id(app_control, "org.tizen.app");
 583
 584         ...
 585
 586         noti_err  = notification_set_launch_option(noti, NOTIFICATION_LAUNCH_OPTION_APP_CONTROL, (void *)app_control);
 587         if(noti_err != NOTIFICATION_ERROR_NONE) {
 588                 notification_free(noti);
 589                 return;
 590         }
 591
 592         app_control_destroy(app_control);
 593 }
 594  * @endcode
 595  */
 596 int notification_set_launch_option(notification_h noti,
 597                                                                 notification_launch_option_type type, void *option);
 598
 599 /**
 600  * @brief Gets the launch option from the notification handle.
 601  * @since_tizen 2.3
 602  * @remarks You must release @a app_control using app_control_destroy().
 603  * @param[in]  noti        The notification handle
 604  * @param[in] type Launching option type
 605  * @param[out] option The pointer of App Control handler
 606  * @return #NOTIFICATION_ERROR_NONE on success,
 607  *         otherwise any other value on failure
 608  * @retval #NOTIFICATION_ERROR_NONE         Success
 609  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 610  * @par Sample code:
 611  * @code
 612 #include <notification.h>
 613 ...
 614 {
 615         app_control_h app_control = NULL;
 616         app_control_create(&app_control);
 617
 618         ...
 619
 620         noti_err = notification_get_launch_option(noti, NOTIFICATION_LAUNCH_OPTION_APP_CONTROL, (void *)&app_control);
 621         if(noti_err != NOTIFICATION_ERROR_NONE) {
 622                 notification_free(noti);
 623                 return;
 624         }
 625 }
 626  * @endcode
 627  */
 628 int notification_get_launch_option(notification_h noti,
 629                                                                 notification_launch_option_type type, void *option);
 630
 631 /**
 632  * @brief Sets the handler for a specific event.
 633  * @details When some event occurs on notification, application launched by app_control_send_launch_request with app_control handle.\n
 634  *          Setting event handler of a button means that the notification will show the button.
 635  * @since_tizen 2.4
 636  * @param[in] noti The notification handle
 637  * @param[in] event_type event type
 638  * @param[in] event_handler app control handle
 639  * @return #NOTIFICATION_ERROR_NONE on success,
 640  *         otherwise any other value on failure
 641  * @retval #NOTIFICATION_ERROR_NONE         Success
 642  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 643  * @see #notification_event_type_e
 644  * @par Sample code:
 645  * @code
 646 #include <notification.h>
 647 ...
 648 {
 649         notification_h noti = NULL;
 650         app_control_h app_control = NULL;
 651         int noti_err = NOTIFICATION_ERROR_NONE;
 652
 653         ...
 654
 655         app_control_create(&app_control);
 656         app_control_set_app_id(app_control, "org.tizen.app");
 657
 658         ...
 659
 660         noti_err  = notification_set_event_handler(noti, NOTIFICATION_EVENT_TYPE_CLICK_ON_BUTTON_1, app_control);
 661         if(noti_err != NOTIFICATION_ERROR_NONE) {
 662                 notification_free(noti);
 663                 return;
 664         }
 665
 666         app_control_destroy(app_control);
 667 }
 668  * @endcode
 669  */
 670 int notification_set_event_handler(notification_h noti, notification_event_type_e event_type, app_control_h event_handler);
 671
 672 /**
 673  * @brief Gets the event handler of a specific event.
 674  * @remarks You must release @a app_control using app_control_destroy().
 675  * @since_tizen 2.4
 676  * @param[in]  noti        The notification handle
 677  * @param[in] event_type Launching option type
 678  * @param[out] option The pointer of App Control handler
 679  * @return #NOTIFICATION_ERROR_NONE on success,
 680  *         otherwise any other value on failure
 681  * @retval #NOTIFICATION_ERROR_NONE         Success
 682  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 683  * @see #notification_event_type_e
 684  * @par Sample code:
 685  * @code
 686 #include <notification.h>
 687 ...
 688 {
 689         app_control_h app_control = NULL;
 690         app_control_create(&app_control);
 691
 692         ...
 693
 694         noti_err = notification_get_event_handler(noti, NOTIFICATION_EVENT_TYPE_CLICK_ON_BUTTON_1, &app_control);
 695         if(noti_err != NOTIFICATION_ERROR_NONE) {
 696                 notification_free(noti);
 697                 return;
 698         }
 699 }
 700  * @endcode
 701  */
 702 int notification_get_event_handler(notification_h noti, notification_event_type_e event_type, app_control_h *event_handler);
 703
 704 /**
 705  * @brief Sets the property of the notification.
 706  * @since_tizen 2.3
 707  * @param[in] noti  The notification handle
 708  * @param[in] flags The property with | operation
 709  * @return #NOTIFICATION_ERROR_NONE on success,
 710  *         otherwise any other value on failure
 711  * @retval #NOTIFICATION_ERROR_NONE         Success
 712  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 713  * @par Sample code:
 714  * @code
 715 #include <notification.h>
 716 ...
 717 {
 718         notification_h noti = NULL;
 719         int noti_err = NOTIFICATION_ERROR_NONE;
 720         bundle *b = NULL;
 721
 722         noti = notification_create(NOTIFICATION_TYPE_NOTI);
 723         if(noti == NULL) {
 724                 return;
 725         }
 726
 727         noti_err  = notification_set_property(noti, NOTIFICATION_PROP_DISPLAY_ONLY_SIMMODE | NOTIFICATION_PROP_DISABLE_APP_LAUNCH);
 728         if(noti_err != NOTIFICATION_ERROR_NONE) {
 729                 notification_free(noti);
 730                 return;
 731         }
 732 }
 733  * @endcode
 734  */
 735 int notification_set_property(notification_h noti,
 736                                                int flags);
 737
 738 /**
 739  * @brief Gets the property of the notification from the notification handle.
 740  * @since_tizen 2.3
 741  * @param[in]  noti  The notification handle
 742  * @param[out] flags The notification property
 743  * @return #NOTIFICATION_ERROR_NONE on success,
 744  *         otherwise any other value on failure
 745  * @retval #NOTIFICATION_ERROR_NONE         Success
 746  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 747  * @par Sample code:
 748  * @code
 749 #include <notification.h>
 750 ...
 751 {
 752         notification_h noti = NULL;
 753         int noti_err = NOTIFICATION_ERROR_NONE;
 754         int flags = 0;
 755
 756         noti_err  = notification_get_property(noti, &flags);
 757         if(noti_err != NOTIFICATION_ERROR_NONE) {
 758                 return;
 759         }
 760 }
 761  * @endcode
 762  */
 763 int notification_get_property(notification_h noti,
 764                                                int *flags);
 765
 766 /**
 767  * @brief Sets applications to display the notification.
 768  * @details All display application is enable(NOTIFICATION_DISPLAY_APP_ALL) if you are not call this API.
 769  * @since_tizen 2.3
 770  * @param[in] noti    The notification handle
 771  * @param[in] applist The with | operation
 772  * @return #NOTIFICATION_ERROR_NONE on success,
 773  *         otherwise any other value on failure
 774  * @retval #NOTIFICATION_ERROR_NONE         Success
 775  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 776  * @par Sample code:
 777  * @code
 778 #include <notification.h>
 779 ...
 780 {
 781         notification_h noti = NULL;
 782         int noti_err = NOTIFICATION_ERROR_NONE;
 783         bundle *b = NULL;
 784
 785         noti = notification_create(NOTIFICATION_TYPE_NOTI);
 786         if(noti == NULL) {
 787                 return;
 788         }
 789
 790         noti_err  = notification_set_display_applist(noti, NOTIFICATION_DISPLAY_APP_NOTIFICATION_TRAY | NOTIFICATION_DISPLAY_APP_TICKER | NOTIFICATION_DISPLAY_APP_INDICATOR);
 791         if(noti_err != NOTIFICATION_ERROR_NONE) {
 792                 notification_free(noti);
 793                 return;
 794         }
 795 }
 796 }
 797  * @endcode
 798  */
 799 int notification_set_display_applist(notification_h noti,
 800                                                       int applist);
 801
 802 /**
 803  * @brief Gets the application list displaying the notification from the notification handle.
 804  * @since_tizen 2.3
 805  * @param[in]  noti    The notification handle
 806  * @param[out] applist The display application list
 807  * @return #NOTIFICATION_ERROR_NONE on success,
 808  *         otherwise any other value on failure
 809  * @retval #NOTIFICATION_ERROR_NONE         Success
 810  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 811  * @par Sample code:
 812  * @code
 813 #include <notification.h>
 814 ...
 815 {
 816         notification_h noti = NULL;
 817         int noti_err = NOTIFICATION_ERROR_NONE;
 818         int applist = 0;
 819
 820         noti_err  = notification_get_display_applist(noti, &applist);
 821         if(noti_err != NOTIFICATION_ERROR_NONE) {
 822                 return;
 823         }
 824 }
 825  * @endcode
 826  */
 827 int notification_get_display_applist(notification_h noti,
 828                                                       int *applist);
 829
 830 /**
 831  * @brief Sets the initial size for the ongoing type.
 832  * @details After notification_post() call, the size is not updated.
 833  * @since_tizen 2.3
 834  * @param[in] noti The notification handle
 835  * @param[in] size The double type size
 836  * @return #NOTIFICATION_ERROR_NONE on success,
 837  *         otherwise any other value on failure
 838  * @retval #NOTIFICATION_ERROR_NONE         Success
 839  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 840  * @par Sample code:
 841  * @code
 842 #include <notification.h>
 843 ...
 844 {
 845         notification_h noti = NULL;
 846         int noti_err = NOTIFICATION_ERROR_NONE;
 847
 848         noti = notification_create(NOTIFICATION_TYPE_NOTI);
 849         if(noti == NULL) {
 850                 return;
 851         }
 852
 853         noti_err  = notification_set_size(noti, 0.0);
 854         if(noti_err != NOTIFICATION_ERROR_NONE) {
 855                 notification_free(noti);
 856                 return;
 857         }
 858 }
 859  * @endcode
 860  */
 861 int notification_set_size(notification_h noti,
 862                                            double size);
 863
 864 /**
 865  * @brief Gets the progress size.
 866  * @since_tizen 2.3
 867  * @param[in]  noti The notification handle
 868  * @param[out] size The progress size
 869  * @return #NOTIFICATION_ERROR_NONE on success,
 870  *         otherwise any other value on failure
 871  * @retval #NOTIFICATION_ERROR_NONE         Success
 872  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 873  * @par Sample code:
 874  * @code
 875 #include <notification.h>
 876 ...
 877 {
 878         notification_h noti = NULL;
 879         int noti_err = NOTIFICATION_ERROR_NONE;
 880         double size = 0.0;
 881
 882         noti_err  = notification_get_size(noti, &size);
 883         if(noti_err != NOTIFICATION_ERROR_NONE) {
 884                 return;
 885         }
 886 }
 887  * @endcode
 888  */
 889 int notification_get_size(notification_h noti,
 890                                            double *size);
 891
 892 /**
 893  * @brief Sets the initial progress for the ongoing type.
 894  * @details After the notification_post() call, the progress is not updated.
 895  * @since_tizen 2.3
 896  * @param[in] noti       The notification handle
 897  * @param[in] percentage The progress percentage
 898  * @return #NOTIFICATION_ERROR_NONE on success,
 899  *         otherwise any other value on failure
 900  * @retval #NOTIFICATION_ERROR_NONE         Success
 901  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 902  * @par Sample code:
 903  * @code
 904 #include <notification.h>
 905 ...
 906 {
 907         notification_h noti = NULL;
 908         int noti_err = NOTIFICATION_ERROR_NONE;
 909
 910         noti = notification_create(NOTIFICATION_TYPE_NOTI);
 911         if(noti == NULL) {
 912                 return;
 913         }
 914
 915         noti_err  = notification_set_progress(noti, 0.0);
 916         if(noti_err != NOTIFICATION_ERROR_NONE) {
 917                 notification_free(noti);
 918                 return;
 919         }
 920 }
 921  * @endcode
 922  */
 923 int notification_set_progress(notification_h noti,
 924                                                double percentage);
 925
 926 /**
 927  * @brief Gets the progress from the notification handle.
 928  * @since_tizen 2.3
 929  * @remarks At the end of the operation, the progress should be @c 1.0.
 930  * @param[in]  noti       The notification handle
 931  * @param[out] percentage The progress percentage
 932  * @return #NOTIFICATION_ERROR_NONE on success,
 933  *         otherwise any other value on failure
 934  * @retval #NOTIFICATION_ERROR_NONE         Success
 935  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 936  * @par Sample code:
 937  * @code
 938 #include <notification.h>
 939 ...
 940 {
 941         notification_h noti = NULL;
 942         int noti_err = NOTIFICATION_ERROR_NONE;
 943         double percentage = 0.0;
 944
 945         noti_err  = notification_get_progress(noti, &percentage);
 946         if(noti_err != NOTIFICATION_ERROR_NONE) {
 947                 return;
 948         }
 949 }
 950  * @endcode
 951  */
 952 int notification_get_progress(notification_h noti,
 953                                                double *percentage);
 954
 955 /**
 956  * @brief Sets the layout of the notification view.
 957  * @details Caller can set displaying layout of notification.
 958  * @since_tizen 2.3
 959  * @param[in] noti The notification handle
 960  * @param[in] layout The type of layout
 961  * @return #NOTIFICATION_ERROR_NONE on success,
 962  *         otherwise any other value on failure
 963  * @retval #NOTIFICATION_ERROR_NONE         Success
 964  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 965  * @see #notification_ly_type_e
 966  */
 967 int notification_set_layout(notification_h noti,
 968                 notification_ly_type_e layout);
 969
 970 /**
 971  * @brief Gets the layout of the notification view from the notification handle.
 972  * @since_tizen 2.3
 973  * @param[in]  noti The notification handle
 974  * @param[out] layout The type of layout
 975  * @return #NOTIFICATION_ERROR_NONE on success,
 976  *         otherwise any other value on failure
 977  * @retval #NOTIFICATION_ERROR_NONE         Success
 978  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 979  * @see #notification_ly_type_e
 980  */
 981 int notification_get_layout(notification_h noti,
 982                 notification_ly_type_e *layout);
 983
 984 /**
 985  * @brief Gets the type of a notification.
 986  * @since_tizen 2.3
 987  * @param[in]  noti The notification handle
 988  * @param[out] type The notification type
 989  * @return #NOTIFICATION_ERROR_NONE on success,
 990  *         otherwise any other value on failure
 991  * @retval #NOTIFICATION_ERROR_NONE         Success
 992  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 993  * @par Sample code:
 994  * @code
 995 #include <notification.h>
 996 ...
 997  {
 998         int noti_err = NOTIFICATION_ERROR_NONE;
 999         notification_type_e type;
1000
1001         noti_err  = notification_get_type(noti, &type);
1002         if(noti_err != NOTIFICATION_ERROR_NONE) {
1003                 return;
1004         }
1005 }
1006  * @endcode
1007  */
1008 int notification_get_type(notification_h noti,
1009                                            notification_type_e * type);
1010
1011 /**
1012  * @internal
1013  * @brief Inserts a notification.
1014  * @details The notification will be inserted to the database and then it will appear in the notification area.
1015  *          When notification_create() is called, if priv_id is #NOTIFICATION_PRIV_ID_NONE, priv_id returns the internally set priv_id.
1016  * @since_tizen 2.3
1017  * @privlevel public
1018  * @privilege %http://tizen.org/privilege/notification
1019  * @param[in]  noti    The notification handle
1020  * @param[out] priv_id The private ID
1021  * @return #NOTIFICATION_ERROR_NONE on success,
1022  *         otherwise any other value on failure
1023  * @retval #NOTIFICATION_ERROR_NONE         Success
1024  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1025  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1026  * @pre Notification handle should be created by notification_create().
1027  * @post notification_free().
1028  * @par Sample code:
1029  * @code
1030 #include <notification.h>
1031 ...
1032  {
1033         int noti_err = NOTIFICATION_ERROR_NONE;
1034
1035         noti_err  = notification_insert(noti, NULL);
1036         if(noti_err != NOTIFICATION_ERROR_NONE) {
1037                 return;
1038         }
1039 }
1040  * @endcode
1041  */
1042 int notification_insert(notification_h noti,
1043                                          int *priv_id);
1044
1045 /**
1046  * @brief Updates notification data.
1047  * @details The updated notification will appear in the notification area.
1048  * @since_tizen 2.3
1049  * @privlevel public
1050  * @privilege %http://tizen.org/privilege/notification
1051  * @param[in] noti The notification handle that is created by notification_create()
1052  * @return #NOTIFICATION_ERROR_NONE on success,
1053  *         otherwise any other value on failure
1054  * @retval #NOTIFICATION_ERROR_NONE         Success
1055  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1056  * @retval #NOTIFICATION_ERROR_NOT_EXIST_ID Priv ID does not exist
1057  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1058  * @par Sample code:
1059  * @code
1060 #include <notification.h>
1061 ...
1062  {
1063         int noti_err = NOTIFICATION_ERROR_NONE;
1064
1065         noti_err  = notification_update(NULL);
1066         if(noti_err != NOTIFICATION_ERROR_NONE) {
1067                 return;
1068         }
1069 }
1070  * @endcode
1071  */
1072 int notification_update(notification_h noti);
1073
1074 /**
1075  * @internal
1076  * @brief Updates a notification, asynchronously.
1077  * @details The updated notification will appear in the notification area.
1078  * @since_tizen 2.3
1079  * @privlevel public
1080  * @privilege %http://tizen.org/privilege/notification
1081  * @remarks This function updates the notification asynchronously.
1082  * @param[in] noti      The notification handle that is created by notification_create()
1083  * @param[in] result_cb The callback called when an update completed
1084  * @param[in] user_data The user data which you want to use in callback
1085  * @return #NOTIFICATION_ERROR_NONE on success,
1086  *         otherwise any other value on failure
1087  * @retval #NOTIFICATION_ERROR_NONE         Success
1088  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1089  * @retval #NOTIFICATION_ERROR_NOT_EXIST_ID Priv ID does not exist
1090  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1091  * @par Sample code:
1092  * @code
1093 #include <notification.h>
1094 ...
1095  {
1096         int noti_err = NOTIFICATION_ERROR_NONE;
1097
1098         noti_err  = notification_update_async(NULL, result_cb, data);
1099         if(noti_err != NOTIFICATION_ERROR_NONE) {
1100                 return;
1101         }
1102 }
1103  * @endcode
1104  */
1105 int notification_update_async(notification_h noti,
1106                 void (*result_cb)(int priv_id, int result, void *data), void *user_data);
1107
1108 /**
1109  * @brief Deletes a notification with the given handle.
1110  * @details notification_delete() removes notification data from database and notification_free() releases memory of notification data.
1111  * @since_tizen 2.3
1112  * @privlevel public
1113  * @privilege %http://tizen.org/privilege/notification
1114  * @param[in] noti The notification handle
1115  * @return #NOTIFICATION_ERROR_NONE on success,
1116  *         otherwise any other value on failure
1117  * @retval #NOTIFICATION_ERROR_NONE         Success
1118  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1119  * @retval NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1120  * @par Sample code:
1121  * @code
1122 #include <notification.h>
1123 ...
1124  {
1125         notificaton_h noti = NULL;
1126         int noti_err = NOTIFICATION_ERROR_NONE;
1127
1128         ...
1129
1130         noti_err  = notification_delete(noti);
1131         if(noti_err != NOTIFICATION_ERROR_NONE) {
1132                 return;
1133         }
1134
1135 }
1136  * @endcode
1137  */
1138 int notification_delete(notification_h noti);
1139
1140 /**
1141  * @brief Creates internal structure data and returns a notification handle.
1142  * @details Available type is #NOTIFICATION_TYPE_NOTI and #NOTIFICATION_TYPE_ONGOING.
1143  * #NOTIFICATION_TYPE_NOTI is remaining notification data even if device is restarted.
1144  * #NOTIFICATION_TYPE_ONGOING can display progressive feather, but notification data is removed after device is restarted.
1145  * @since_tizen 2.3
1146  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
1147  * @param[in] type The notification type
1148  * @return Notification handle(notification_h) on success,
1149  *         otherwise @c NULL on failure
1150  * @retval notification_h Success
1151  * @retval NULL Failure
1152  * @exception #NOTIFICATION_ERROR_NONE Success
1153  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1154  * @exception #NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory
1155  * @see #notification_type_e
1156  * @par Sample code:
1157  * @code
1158 #include <notification.h>
1159 ...
1160 {
1161         notification_h noti = NULL;
1162
1163         noti = notification_create(NOTIFICATION_TYPE_NOTI);
1164         if(noti == NULL) {
1165                 return;
1166         }
1167         ...
1168 }
1169  * @endcode
1170  */
1171 notification_h notification_create(notification_type_e type);
1172
1173 /**
1174  * @brief Creates a notification clone.
1175  * @details Newly created notification handle is returned.
1176  * @since_tizen 2.3
1177  * @remarks This cloned notification handle should be freed using notification_free().
1178  * @param[in]  noti  The notification handle
1179  * @param[out] clone The newly created notification handle that has same with input @a noti
1180  * @return #NOTIFICATION_ERROR_NONE if success,
1181  *         otherwise any other value if failure
1182  * @retval #NOTIFICATION_ERROR_NONE         Success
1183  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1184  * @see #notification_type_e
1185  * @par Sample code:
1186  * @code
1187 #include <notification.h>
1188 ...
1189 {
1190         notification_h noti = notification_create(NOTIFICATION_TYPE_NOTI);
1191         notification_h clone = NULL;
1192
1193         notification_clone(noti, &clone);
1194         ...
1195 }
1196  * @endcode
1197  */
1198 int notification_clone(notification_h noti, notification_h *clone);
1199
1200 /**
1201  * @brief Frees the internal structure data of a notification handle.
1202  * @details Internal data of a notification handle is released. Data of the inserted notification is not deleted.
1203  * @since_tizen 2.3
1204  * @param[in] noti The notification handle
1205  * @return #NOTIFICATION_ERROR_NONE on success,
1206  *         otherwise any other value on failure
1207  * @retval #NOTIFICATION_ERROR_NONE         Success
1208  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1209  * @pre Notification handle should be created by notification_create().
1210  * @par Sample code:
1211  * @code
1212 #include <notification.h>
1213 ...
1214 {
1215         notification_h noti = NULL;
1216         int noti_err = NOTIFICATION_ERROR_NONE;
1217
1218         noti = notification_create(NOTIFICATION_TYPE_NOTI);
1219         if(noti == NULL) {
1220                 return;
1221         }
1222         ...
1223
1224         noti_err = notification_free(noti);
1225         if(noti_err != NOTIFICATION_ERROR_NONE) {
1226                 return;
1227         }
1228 }
1229  * @endcode
1230  */
1231 int notification_free(notification_h noti);
1232
1233 /**
1234  * @}
1235  */
1236
1237 /**
1238  * @addtogroup NOTIFICATION_MODULE
1239  * @{
1240  */
1241
1242 /**
1243  * @internal
1244  * @brief Registers a callback for all notification events.
1245  * @details The registered callback could be called for all notification events.
1246  * @since_tizen 2.3
1247  * @privlevel public
1248  * @privilege %http://tizen.org/privilege/notification
1249  * @param[in] changed_cb The callback function
1250  * @param[in] user_data  The user data
1251  * @return #NOTIFICATION_ERROR_NONE on success,
1252  *         otherwise any other value on failure
1253  * @retval #NOTIFICATION_ERROR_NONE         Success
1254  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1255  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1256  * @see notification_unregister_detailed_changed_cb()
1257  * @par Sample code:
1258  * @code
1259 #include <notification.h>
1260 ...
1261 {
1262         noti_err = notification_register_detailed_changed_cb(app_changed_cb, user_data);
1263         if(noti_err != NOTIFICATION_ERROR_NONE) {
1264                 return;
1265         }
1266 }
1267  * @endcode
1268  */
1269 int notification_register_detailed_changed_cb(
1270                 void (*detailed_changed_cb)(void *data, notification_type_e type, notification_op *op_list, int num_op),
1271                 void *user_data);
1272
1273 /**
1274  * @internal
1275  * @brief Unregisters a callback for all notification events.
1276  * @since_tizen 2.3
1277  * @privlevel public
1278  * @privilege %http://tizen.org/privilege/notification
1279  * @param[in] changed_cb The callback function
1280  * @return #NOTIFICATION_ERROR_NONE on success,
1281  *         otherwise any other value on failure
1282  * @retval #NOTIFICATION_ERROR_NONE         Success
1283  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1284  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1285  * @see notification_register_detailed_changed_cb()
1286  * @par Sample code:
1287  * @code
1288 #include <notification.h>
1289 ...
1290 {
1291         noti_err = notification_register_detailed_changed_cb(app_changed_cb, user_data);
1292         if(noti_err != NOTIFICATION_ERROR_NONE) {
1293                 return;
1294         }
1295 }
1296  * @endcode
1297  */
1298 int notification_unregister_detailed_changed_cb(
1299                 void (*detailed_changed_cb)(void *data, notification_type_e type, notification_op *op_list, int num_op),
1300                 void *user_data);
1301
1302 /**
1303  * @brief Sets the tag of the notification handle.
1304  * @since_tizen 2.3
1305  * @param[in] noti Notification handle
1306  * @param[in] tag tag for loading notification handle
1307  * @return #NOTIFICATION_ERROR_NONE on success, other value on failure
1308  * @retval #NOTIFICATION_ERROR_NONE Success
1309  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1310  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1311  * @see notification_get_tag()
1312  * @par Sample code:
1313  * @code
1314 #include <notification.h>
1315 ...
1316 {
1317         notification_h noti = NULL;
1318         int noti_err = NOTIFICATION_ERROR_NONE;
1319
1320         noti = notification_create(NOTIFICATION_TYPE_NOTI);
1321         if(noti == NULL) {
1322                 return;
1323         }
1324         ...
1325
1326         noti_err = notification_set_tag(noti, tag);
1327         if(noti_err != NOTIFICATION_ERROR_NONE) {
1328                 return;
1329         }
1330 }
1331  * @endcode
1332  */
1333 int notification_set_tag(notification_h noti, const char *tag);
1334
1335 /**
1336  * @brief Gets the tag of the notification handle.
1337  * @since_tizen 2.3
1338  * @param[in] noti Notification handle
1339  * @param[out] tag tag for loading notification handle
1340  * @return #NOTIFICATION_ERROR_NONE on success, other value on failure
1341  * @retval #NOTIFICATION_ERROR_NONE Success
1342  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1343  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1344  * @see notification_set_tag()
1345  * @par Sample code:
1346  * @code
1347 #include <notification.h>
1348 ...
1349 {
1350         int noti_err = NOTIFICATION_ERROR_NONE;
1351         const char *tag = NULL;
1352
1353         ...
1354
1355         noti_err = notification_get_tag(noti, &tag);
1356         if(noti_err != NOTIFICATION_ERROR_NONE) {
1357                 return;
1358         }
1359 }
1360  * @endcode
1361  */
1362 int notification_get_tag(notification_h noti, const char **tag);
1363
1364 /**
1365  * @internal
1366  * @brief Gets the package name of the notification
1367  * @remarks The pkgname must be released using free()
1368  * @since_tizen 2.4
1369  * @privlevel NP
1370  * @param[in] noti Notification handle
1371  * @param[out] pkgname package name of the notification
1372  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
1373  * @retval NOTIFICATION_ERROR_NONE Success
1374  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1375  * @par Sample code:
1376  * @code
1377 #include <notification.h>
1378 ...
1379 {
1380         notification_h noti = NULL;
1381         int noti_err = NOTIFICATION_ERROR_NONE;
1382         char *pkgname = NULL;
1383
1384         noti_err  = notification_get_pkgname(noti, &pkgname);
1385         if(noti_err != NOTIFICATION_ERROR_NONE) {
1386                 return;
1387         }
1388 }
1389  * @endcode
1390  */
1391 int notification_get_pkgname(notification_h noti, char **pkgname);
1392
1393 /**
1394  * @brief Loads a notification from the notification's database with the tag.
1395  * @since_tizen 2.3
1396  * @privlevel public
1397  * @privilege %http://tizen.org/privilege/notification
1398  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
1399  * @param[in] tag tag for loading notification handle
1400  * @return Notification handle(notification_h) on success, NULL on failure
1401  * @retval notification_h Success
1402  * @retval NULL Failure
1403  * @exception #NOTIFICATION_ERROR_NONE Success
1404  * @exception #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1405  * @exception #NOTIFICATION_ERROR_OUT_OF_MEMORY Out of memory
1406  * @exception #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1407  * @see #notification_type_e
1408  * @par Sample code:
1409  * @code
1410 #include <notification.h>
1411 ...
1412 {
1413         notification_h noti = NULL;
1414
1415         noti = notification_load_by_tag(tag);
1416         if(noti == NULL) {
1417                 return;
1418         }
1419         ...
1420 }
1421  * @endcode
1422  */
1423 notification_h notification_load_by_tag(const char *tag);
1424
1425 /**
1426  * @brief Deletes all notifications of the given type.
1427  * @since_tizen 2.3
1428  * @privlevel public
1429  * @privilege %http://tizen.org/privilege/notification
1430  * @param[in] type Notification type
1431  * @return #NOTIFICATION_ERROR_NONE if success, other value if failure
1432  * @retval #NOTIFICATION_ERROR_NONE Success
1433  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
1434  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1435  * @par Sample code:
1436  * @code
1437 #include <notification.h>
1438 ...
1439  {
1440         int noti_err = NOTIFICATION_ERROR_NONE;
1441
1442         noti_err  = notification_delete_all(NOTIFICATION_TYPE_NOTI);
1443         if(noti_err != NOTIFICATION_ERROR_NONE) {
1444                 return;
1445         }
1446 }
1447  * @endcode
1448  */
1449 int notification_delete_all(notification_type_e type);
1450
1451 /**
1452  * @brief Posts a notification.
1453  * @since_tizen 2.3
1454  * @privlevel public
1455  * @privilege %http://tizen.org/privilege/notification
1456  * @param[in] noti Notification handle
1457  * @return #NOTIFICATION_ERROR_NONE if success, other value if failure
1458  * @retval #NOTIFICATION_ERROR_NONE Success
1459  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1460  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1461  * @pre Notification handle should be created by notification_create().
1462  * @post notification_free().
1463  * @par Sample code:
1464  * @code
1465 #include <notification.h>
1466 ...
1467  {
1468         int noti_err = NOTIFICATION_ERROR_NONE;
1469
1470         noti_err  = notification_post(noti);
1471         if(noti_err != NOTIFICATION_ERROR_NONE) {
1472                 return;
1473         }
1474 }
1475  * @endcode
1476  */
1477 int notification_post(notification_h noti);
1478
1479 /**
1480  * @brief Sets permissions to application for updating or deletin the notification
1481  * @since_tizen 2.4
1482  * @privlevel public
1483  * @privilege %http://tizen.org/privilege/notification
1484  * @param[in] noti Notification handle
1485  * @param[in] permission_type permission type
1486  * @param[in] app_id target application id
1487  * @return #NOTIFICATION_ERROR_NONE if success, other value if failure
1488  * @retval #NOTIFICATION_ERROR_NONE Success
1489  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1490  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1491  * @see #notification_get_permission
1492  * @see #notification_permission_type_e
1493  * @see #notification_h
1494  * @par Sample code:
1495  * @code
1496 #include <notification.h>
1497 ...
1498 {
1499         notification_h noti = NULL;
1500         int noti_err = NOTIFICATION_ERROR_NONE;
1501
1502         noti = notification_create(NOTIFICATION_TYPE_NOTI);
1503         if(noti == NULL) {
1504                 return;
1505         }
1506         ...
1507
1508         noti_err = notification_set_permission(noti, NOTIFICATION_PERMISSION_TYPE_DELETE, "org.tizen.xxx");
1509         if(noti_err != NOTIFICATION_ERROR_NONE) {
1510                 return;
1511         }
1512 }
1513  * @endcode
1514  */
1515 int notification_set_permission(notification_h handle, notification_permission_type_e permission_type, const char *app_id);
1516
1517 /**
1518  * @brief Gets permissions of the notification
1519  * @remarks app_id must not be freed. This will be free with notification_free.
1520  * @since_tizen 2.4
1521  * @privlevel public
1522  * @privilege %http://tizen.org/privilege/notification
1523  * @param[in] noti Notification handle
1524  * @param[out] permission_type permission type
1525  * @param[out] app_id target application id
1526  * @return #NOTIFICATION_ERROR_NONE if success, other value if failure
1527  * @retval #NOTIFICATION_ERROR_NONE Success
1528  * @retval #NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
1529  * @retval #NOTIFICATION_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
1530  * @see #notification_set_permission
1531  * @see #notification_permission_type_e
1532  * @see #notification_h
1533  * @par Sample code:
1534  * @code
1535 #include <notification.h>
1536 ...
1537 {
1538         int noti_err = NOTIFICATION_ERROR_NONE;
1539         notification_permission_type_e permission_type;
1540         const char *app_id = NULL;
1541
1542         ...
1543
1544         noti_err = notification_get_permission(noti, &permission_type, &app_id);
1545         if(noti_err != NOTIFICATION_ERROR_NONE) {
1546                 return;
1547         }
1548 }
1549  * @endcode
1550  */
1551 int notification_get_permission(notification_h handle, notification_permission_type_e *permission_type, const char **app_id);
1552
1553
1554 /**
1555  * @}
1556  */
1557
1558 #ifdef __cplusplus
1559 }
1560 #endif
1561 #endif                          /* __NOTIFICATION_H__ */