include/notification_internal.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_INTERNAL_H__
  23 #define __NOTIFICATION_INTERNAL_H__
  24
  25 #include <notification_error.h>
  26 #include <notification_type.h>
  27 #include <notification_list.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34  * @addtogroup NOTIFICATION_INTERNAL
  35  * @{
  36  */
  37
  38 /**
  39  * @brief This function add deferred task. the registered task will be executed when notification service become ready
  40  * @param[in] deferred_task_cb The callback function
  41  * @param[in] user_data The user data to be passed to the callback function
  42  * @return #NOTIFICATION_ERROR_NONE if success, other value if failure
  43  * @see #notification_error_e
  44  * @see notification_is_service_ready()
  45  */
  46 int notification_add_deferred_task(
  47                 void (*deferred_task_cb)(void *data), void *user_data);
  48
  49 /**
  50  * @brief This function remove deferred task.
  51  * @param[in] deferred_task_cb The callback function
  52  * @return #NOTIFICATION_ERROR_NONE if success, other value if failure
  53  * @see #notification_error_e
  54  * @see notification_is_service_ready()
  55  */
  56 int notification_del_deferred_task(
  57                 void (*deferred_task_cb)(void *data));
  58
  59 /**
  60  * @brief This function will be removed.
  61  * @see notification_unresister_changed_cb()
  62  */
  63 int
  64 notification_resister_changed_cb(
  65         void (*changed_cb)(void *data, notification_type_e type),
  66         void *user_data);
  67
  68 /**
  69  * @brief This function will be removed.
  70  * @see notification_resister_changed_cb()
  71  */
  72 int
  73 notification_unresister_changed_cb(
  74         void (*changed_cb)(void *data, notification_type_e type));
  75
  76 /**
  77  * @brief Updates the progress of the inserted notification. This only works for the ongoing notification (NOTIFICATION_TYPE_ONGOING).
  78  * @details The Notification view on the notification area could be updated.
  79  * @param[in] noti Notification handle or NULL if priv_id is valid
  80  * @param[in] priv_id Private ID
  81  * @param[in] progress Percentage value of progressive data
  82  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
  83  * @retval NOTIFICATION_ERROR_NONE Success
  84  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
  85  * @par Sample code:
  86  * @code
  87 #include <notification.h>
  88 ...
  89  {
  90         int noti_err = NOTIFICATION_ERROR_NONE;
  91
  92         noti_err  = notification_update_progress(NULL, APP_NOTI_PRIV_ID, 0.6);
  93         if(noti_err != NOTIFICATION_ERROR_NONE) {
  94                 return;
  95         }
  96 }
  97  * @endcode
  98  */
  99 int notification_update_progress(notification_h noti,
 100                                                   int priv_id,
 101                                                   double progress);
 102
 103 /**
 104  * @brief Updates the size of inserted notification data. This only works for the ongoing notification (NOTIFICATION_TYPE_ONGOING).
 105  * @details Notification view on notification area could be updated.
 106  * @param[in] noti Notification handle or NULL if priv_id is valid
 107  * @param[in] priv_id Private ID
 108  * @param[in] size Bytes of progressive data
 109  * @return NOTIFICATION_ERROR_NONE if success, other value if failure
 110  * @retval NOTIFICATION_ERROR_NONE Success
 111  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 112  * @par Sample code:
 113  * @code
 114 #include <notification.h>
 115 ...
 116  {
 117         int noti_err = NOTIFICATION_ERROR_NONE;
 118
 119         noti_err  = notification_update_size(NULL, APP_NOTI_PRIV_ID, 3000000);
 120         if(noti_err != NOTIFICATION_ERROR_NONE) {
 121                 return;
 122         }
 123 }
 124  * @endcode
 125  */
 126 int notification_update_size(notification_h noti,
 127                                               int priv_id, double size);
 128
 129 /**
 130  * @brief Updates the content of the inserted notification data. This is only for the ongoing notification (NOTIFICATION_TYPE_ONGOING).
 131  * @details Notification view on notification area could be updated.
 132  * @param[in] noti Notification handle or NULL if priv_id is valid
 133  * @param[in] priv_id Private ID
 134  * @param[in] content Text to update
 135  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
 136  * @retval NOTIFICATION_ERROR_NONE Success
 137  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 138  * @par Sample code:
 139  * @code
 140 #include <notification.h>
 141 ...
 142  {
 143         int noti_err = NOTIFICATION_ERROR_NONE;
 144
 145         noti_err  = notification_update_content(NULL, APP_NOTI_PRIV_ID, "updated string");
 146         if(noti_err != NOTIFICATION_ERROR_NONE) {
 147                 return;
 148         }
 149 }
 150  * @endcode
 151  */
 152 int notification_update_content(notification_h noti,
 153                                                          int priv_id,
 154                                                          const char *content);
 155
 156 /**
 157  * @brief This function will be deprecated.
 158  * @see notification_set_image()
 159  *
 160  */
 161 NOTIFICATION_DEPRECATED_API int notification_set_icon(notification_h noti,
 162                                            const char *icon_path);
 163
 164 /**
 165  * @brief This function will be deprecated.
 166  * @see notification_get_image()
 167  *
 168  */
 169 NOTIFICATION_DEPRECATED_API int notification_get_icon(notification_h noti,
 170                                            char **icon_path);
 171
 172 /**
 173  * @brief This function will be deprecated.
 174  * @see notification_set_text()
 175  *
 176  */
 177 NOTIFICATION_DEPRECATED_API int notification_set_title(notification_h noti,
 178                                             const char *title,
 179                                             const char *loc_title);
 180
 181 /**
 182  * @brief This function will be deprecated.
 183  * @see notification_get_text()
 184  *
 185  */
 186 NOTIFICATION_DEPRECATED_API int notification_get_title(notification_h noti,
 187                                             char **title,
 188                                             char **loc_title);
 189
 190 /**
 191  * @brief This function will be deprecated.
 192  * @see notification_set_text()
 193  *
 194  */
 195 NOTIFICATION_DEPRECATED_API int notification_set_content(notification_h noti,
 196                                               const char *content,
 197                                               const char *loc_content);
 198
 199 /**
 200  * @brief This function will be deprecated.
 201  * @see notification_get_text()
 202  *
 203  */
 204 NOTIFICATION_DEPRECATED_API int notification_get_content(notification_h noti,
 205                                               char **content,
 206                                               char **loc_content);
 207
 208 /**
 209  * @brief This function will be removed.
 210  * @see notification_set_execute_option()
 211  *
 212  */
 213 NOTIFICATION_DEPRECATED_API int notification_set_application(notification_h noti, const char *pkgname); /* Do not use this */
 214
 215 /**
 216  * @brief This function will be removed.
 217  * @see notification_get_execute_option()
 218  *
 219  */
 220 NOTIFICATION_DEPRECATED_API int notification_get_application(notification_h noti, char **pkgname);      /* Do not use this */
 221
 222 /**
 223  * @brief This function will be deprecated.
 224  * @see notification_set_execute_option()
 225  *
 226  */
 227 NOTIFICATION_DEPRECATED_API int notification_set_args(notification_h noti, bundle * args, bundle * group_args); /* Do not use this */
 228
 229 /**
 230  * @brief This function will be deprecated.
 231  * @see notification_get_execute_option()
 232  *
 233  */
 234 NOTIFICATION_DEPRECATED_API int notification_get_args(notification_h noti, bundle ** args, bundle ** group_args);       /* Do not use this */
 235
 236 /**
 237  * @brief This function is deprecated.
 238  * @see notification_get_grouping_list()
 239  *
 240  */
 241 NOTIFICATION_DEPRECATED_API int notification_get_grouping_list(notification_type_e type,
 242                                                     int count,
 243                                                     notification_list_h *list);
 244
 245 /**
 246  * @brief This function will be deprecated.
 247  * @see notification_delete_by_priv_id()
 248  *
 249  */
 250 NOTIFICATION_DEPRECATED_API int notification_delete_group_by_group_id(const char *pkgname,
 251                                                            notification_type_e type,
 252                                                            int group_id);
 253
 254 /**
 255  * @brief This function will be deprecated.
 256  * @see notification_delete_by_priv_id()
 257  *
 258  */
 259 NOTIFICATION_DEPRECATED_API int notification_delete_group_by_priv_id(const char *pkgname,
 260                                                           notification_type_e type,
 261                                                           int priv_id);
 262 /**
 263  * @brief This function will be deprecated.
 264  *
 265  */
 266 NOTIFICATION_DEPRECATED_API int notification_get_count(notification_type_e type,
 267                                             const char *pkgname,
 268                                             int group_id, int priv_id,
 269                                             int *count);
 270
 271 /**
 272  * @brief This function will be deprecated.
 273  *
 274  */
 275 NOTIFICATION_DEPRECATED_API int notifiation_clear(notification_type_e type);
 276
 277 /**
 278  * @internal
 279  * @brief This function will be deprecated.
 280  * @details Use only for the notification tray's clear button operation.
 281  * @param[in] type Notification type
 282  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
 283  * @retval NOTIFICATION_ERROR_NONE Success
 284  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 285  * @see #notification_type_e
 286  * @par Sample code:
 287  * @code
 288 #include <notification.h>
 289 ...
 290  {
 291         int noti_err = NOTIFICATION_ERROR_NONE;
 292
 293         noti_err  = notification_clear(NOTIFICATION_TYPE_NOTI);
 294         if(noti_err != NOTIFICATION_ERROR_NONE) {
 295                 return;
 296         }
 297 }
 298  * @endcode
 299  */
 300 NOTIFICATION_DEPRECATED_API int notification_clear(notification_type_e type);
 301
 302 /**
 303  * @internal
 304  * @brief This function will be deprecated.
 305  * @return 1 on ready, other value on not ready
 306  */
 307 NOTIFICATION_DEPRECATED_API int notification_is_service_ready(void);
 308
 309 /**
 310  * @internal
 311  * @brief This function will be deprecated.
 312  * @param[in] list Notification list handle
 313  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
 314  * @retval NOTIFICATION_ERROR_NONE Success
 315  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 316  * @pre notification_get_grouping_list() or notification_get_detail_list().
 317  * @see #notification_op
 318  */
 319 NOTIFICATION_DEPRECATED_API int notification_op_get_data(notification_op *noti_op,
 320                                                        notification_op_data_type_e type,
 321                                                        void *data);
 322
 323 /**
 324  * @internal
 325  * @brief This function will be deprecated.
 326  * @details Caller_pkgname is set automatically when notification_new() is called. We do not recommend to use this API.
 327  * @param[in] noti Notification handle
 328  * @param[in] pkgname Caller package name
 329  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
 330  * @retval NOTIFICATION_ERROR_NONE Success
 331  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 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 = notification_new(NOTIFICATION_TYPE_NOTI, APP_GROUP_ID, NOTIFICATION_PRIV_ID_NONE);
 341         if(noti == NULL) {
 342                 return;
 343         }
 344
 345         noti_err  = notification_set_pkgname(noti, "com.samsung.phone");
 346         if(noti_err != NOTIFICATION_ERROR_NONE) {
 347                 notification_free(noti);
 348                 return;
 349         }
 350 }
 351  * @endcode
 352  */
 353 NOTIFICATION_DEPRECATED_API int notification_set_pkgname(notification_h noti,
 354                                               const char *pkgname);
 355
 356 /**
 357  * @internal
 358  * @brief This function will be deprecated.
 359  * @param[in] noti Notification handle
 360  * @param[out] pkgname Caller package name
 361  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
 362  * @retval NOTIFICATION_ERROR_NONE Success
 363  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 364  * @par Sample code:
 365  * @code
 366 #include <notification.h>
 367 ...
 368 {
 369         notification_h noti = NULL;
 370         int noti_err = NOTIFICATION_ERROR_NONE;
 371         char *pkgname = NULL;
 372
 373         noti_err  = notification_get_pkgname(noti, &pkgname);
 374         if(noti_err != NOTIFICATION_ERROR_NONE) {
 375                 return;
 376         }
 377 }
 378  * @endcode
 379  */
 380 NOTIFICATION_DEPRECATED_API int notification_get_pkgname(notification_h noti,
 381                                               char **pkgname);
 382
 383 /**
 384  * @internal
 385  * @brief This function will be deprecated.
 386  * @details If @a pkgname is NULL, caller_pkgname is set internally.
 387  * @param[in] pkgname Caller application package name or NULL
 388  * @param[in] type Notification type
 389  * @return NOTIFICATION_ERROR_NONE if success, other value if failure
 390  * @retval NOTIFICATION_ERROR_NONE Success
 391  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 392  * @par Sample code:
 393  * @code
 394 #include <notification.h>
 395 ...
 396  {
 397         int noti_err = NOTIFICATION_ERROR_NONE;
 398
 399         noti_err  = notification_delete_all_by_type(NULL, NOTIFICATION_TYPE_NOTI);
 400         if(noti_err != NOTIFICATION_ERROR_NONE) {
 401                 return;
 402         }
 403 }
 404  * @endcode
 405  */
 406 NOTIFICATION_DEPRECATED_API int notification_delete_all_by_type(const char *pkgname,
 407                                                      notification_type_e type);
 408
 409 /**
 410  * @internal
 411  * @brief This function will be deprecated.
 412  * @details If @a pkgname is NULL, caller_pkgname is set internally.
 413  * @param[in] pkgname Caller application package name or NULL
 414  * @param[in] type Notification type
 415  * @param[in] priv_id Priv ID
 416  * @return NOTIFICATION_ERROR_NONE if success, other value if failure
 417  * @retval NOTIFICATION_ERROR_NONE Success
 418  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 419  * @par Sample code:
 420  * @code
 421 #include <notification.h>
 422 ...
 423  {
 424         int noti_err = NOTIFICATION_ERROR_NONE;
 425
 426         noti_err  = notification_delete_by_priv_id(NULL, NOTIFICATION_TYPE_NOTI, APP_PRIV_ID);
 427         if(noti_err != NOTIFICATION_ERROR_NONE) {
 428                 return;
 429         }
 430 }
 431  * @endcode
 432  */
 433 NOTIFICATION_DEPRECATED_API int notification_delete_by_priv_id(const char *pkgname,
 434                                                     notification_type_e type,
 435                                                     int priv_id);
 436
 437 /**
 438  * @internal
 439  * @brief This function will be deprecated.
 440  * @details When notification data selected in display application, application launched by appsvc_run_service with service_handle.
 441  * @param[in] noti Notification handle
 442  * @param[in] type Notification execute type
 443  * @param[in] text Basic text for button
 444  * @param[in] key Value for localized text
 445  * @param[in] service_handle Appsvc bundle data
 446  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
 447  * @retval NOTIFICATION_ERROR_NONE Success
 448  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 449  * @par Sample code:
 450  * @code
 451 #include <notification.h>
 452 ...
 453 {
 454         notification_h noti = NULL;
 455         int noti_err = NOTIFICATION_ERROR_NONE;
 456         bundle *b = NULL;
 457
 458         ...
 459
 460         b = bundle_create();
 461         appsvc_set_operation(b, APPSVC_OPERATION_VIEW);
 462         appsvc_set_uri(b,"http://www.samsung.com");
 463
 464         noti_err  = notification_set_execute_option(noti, NOTIFICATION_EXECUTE_TYPE_SINGLE_LAUNCH, NULL, NULL, b);
 465         if(noti_err != NOTIFICATION_ERROR_NONE) {
 466                 notification_free(noti);
 467                 return;
 468         }
 469
 470         bundle_free(b);
 471 }
 472  * @endcode
 473  */
 474 NOTIFICATION_DEPRECATED_API int notification_set_execute_option(notification_h noti,
 475                                                      notification_execute_type_e type,
 476                                                      const char *text,
 477                                                      const char *key,
 478                                                      bundle *service_handle);
 479
 480 /**
 481  * @internal
 482  * @brief This function will be deprecated.
 483  * @remarks ID is valid only after inserting the notification.
 484  * @param[in] noti Notification handle
 485  * @param[out] group_id Group ID
 486  * @param[out] priv_id Private ID
 487  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
 488  * @retval NOTIFICATION_ERROR_NONE Success
 489  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 490  * @par Sample code:
 491  * @code
 492 #include <notification.h>
 493  ...
 494   {
 495          int noti_err = NOTIFICATION_ERROR_NONE;
 496          int group_id, priv_id;
 497
 498          noti_err  = notification_get_id(noti, &group_id, &priv_id);
 499          if(noti_err != NOTIFICATION_ERROR_NONE) {
 500                  return;
 501          }
 502  }
 503  * @endcode
 504  */
 505 NOTIFICATION_DEPRECATED_API int notification_get_id(notification_h noti,
 506                                          int *group_id, int *priv_id);
 507
 508 /**
 509  * @internal
 510  * @brief This function will be deprecated.
 511  * @param[in] type Notification type
 512  * @param[in] group_id Group ID
 513  * @param[in] priv_id Priv ID
 514  * @return Notification handle(#notification_h) on success, NULL on failure
 515  * @retval #notification_h Success
 516  * @retval NULL Failure
 517  * @see #notification_type_e
 518  * @see #notification_h
 519  * @par Sample code:
 520  * @code
 521 #include <notification.h>
 522 ...
 523 {
 524         notification_h noti = NULL;
 525
 526         noti = notification_load("org.tizen.app", priv_id);
 527         if(noti == NULL) {
 528                 return;
 529         }
 530         ...
 531 }
 532  * @endcode
 533  */
 534 NOTIFICATION_DEPRECATED_API notification_h notification_load(char *pkgname,
 535                                 int priv_id);
 536
 537 /**
 538  * @internal
 539  * @brief This function will be deprecated.
 540  * @details Available types are #NOTIFICATION_TYPE_NOTI and #NOTIFICATION_TYPE_ONGOING.
 541  * #NOTIFICATION_TYPE_NOTI is remaining notification data even if device is restarted.
 542  * #NOTIFICATION_TYPE_ONGOING can display progressive feather, but notification data is removed after device is restarted.
 543  * If group_id is #NOTIFICATION_GROUP_ID_NONE, notification data is not grouped. #NOTIFICATION_GROUP_ID_DEFAULT,
 544  * notification data is grouped with same title. Positive number ( > 0 ) is grouped with same number.
 545  * If priv_id is #NOTIFICATION_PRIV_ID_NONE, priv_id is set internally and return it when notification_insert() call.
 546  * Positive number and zero ( >= 0 ) is application set private ID. These ID should have be unique each application package.
 547  * @param[in] type Notification type
 548  * @param[in] group_id Group ID
 549  * @param[in] priv_id Priv ID
 550  * @return Notification handle(#notification_h) on success, NULL on failure
 551  * @retval #notification_h Success
 552  * @retval NULL Failure
 553  * @see #notification_type_e
 554  * @see #notification_h
 555  * @par Sample code:
 556  * @code
 557 #include <notification.h>
 558 ...
 559 {
 560         notification_h noti = NULL;
 561
 562         noti = notification_new(NOTIFICATION_TYPE_NOTI, APP_GROUP_ID, NOTIFICATION_PRIV_ID_NONE);
 563         if(noti == NULL) {
 564                 return;
 565         }
 566         ...
 567 }
 568  * @endcode
 569  */
 570 NOTIFICATION_DEPRECATED_API notification_h notification_new(notification_type_e type, int group_id,
 571                                 int priv_id);
 572
 573 /**
 574  * @internal
 575  * @brief This function will be deprecated.
 576  * @param[in] noti Notification handle
 577  * @param[in] type Notification execute type
 578  * @param[out] text Text for button
 579  * @param[out] service_handle Appsvc bundle data
 580  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
 581  * @retval NOTIFICATION_ERROR_NONE Success
 582  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 583  * @par Sample code:
 584  * @code
 585 #include <notification.h>
 586 ...
 587 {
 588         notification_h noti = NULL;
 589         int noti_err = NOTIFICATION_ERROR_NONE;
 590         bundle *b = NULL;
 591
 592         ...
 593
 594         noti_err  = notification_get_execute_option(noti, NOTIFICATION_EXECUTE_TYPE_SINGLE_LAUNCH, NULL, NULL, &b);
 595         if(noti_err != NOTIFICATION_ERROR_NONE) {
 596                 notification_free(noti);
 597                 return;
 598         }
 599 }
 600  * @endcode
 601  */
 602 NOTIFICATION_DEPRECATED_API int notification_get_execute_option(notification_h noti,
 603                                                      notification_execute_type_e type,
 604                                                      const char **text,
 605                                                      bundle **service_handle);
 606
 607 /**
 608  * @internal
 609  * @brief This function sets notification property for designated package.
 610  * @since_tizen 2.3
 611  * @privlevel public
 612  * @privilege http://tizen.org/privilege/core/notification
 613  * @param[in] pkgname The name of designated package
 614  * @param[in] property name
 615  * @param[in] property value
 616  * @return #NOTIFICATION_ERROR_NONE if success, other value if failure
 617  * @see #notification_error_e
 618  */
 619 int notification_setting_property_set(const char *pkgname, const char *property, const char *value);
 620
 621 /**
 622  * @internal
 623  * @brief This function gets notification property for designated package.
 624  * @since_tizen 2.3
 625  * @privlevel public
 626  * @privilege http://tizen.org/privilege/core/notification
 627  * @param[in] pkgname The name of designated package
 628  * @param[in] property name
 629  * @param[in] pointer which can save the getting value
 630  * @return #NOTIFICATION_ERROR_NONE if success, other value if failure
 631  * @see #notification
 632  */
 633 int notification_setting_property_get(const char *pkgname, const char *property, char **value);
 634
 635 /**
 636  * @}
 637  */
 638
 639 #ifdef __cplusplus
 640 }
 641 #endif
 642 #endif