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