include/notification.h

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