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