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  * @details If @a pkgname is NULL, caller_pkgname is set internally.
 360  * @param[in] pkgname Caller application package name or NULL
 361  * @param[in] type Notification type
 362  * @return NOTIFICATION_ERROR_NONE if success, other value if failure
 363  * @retval NOTIFICATION_ERROR_NONE Success
 364  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid input value
 365  * @par Sample code:
 366  * @code
 367 #include <notification.h>
 368 ...
 369  {
 370         int noti_err = NOTIFICATION_ERROR_NONE;
 371
 372         noti_err  = notification_delete_all_by_type(NULL, NOTIFICATION_TYPE_NOTI);
 373         if(noti_err != NOTIFICATION_ERROR_NONE) {
 374                 return;
 375         }
 376 }
 377  * @endcode
 378  */
 379 NOTIFICATION_DEPRECATED_API int notification_delete_all_by_type(const char *pkgname,
 380                                                      notification_type_e type);
 381
 382 /**
 383  * @internal
 384  * @brief This function will be deprecated.
 385  * @details If @a pkgname is NULL, caller_pkgname is set internally.
 386  * @param[in] pkgname Caller application package name or NULL
 387  * @param[in] type Notification type
 388  * @param[in] priv_id Priv ID
 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_by_priv_id(NULL, NOTIFICATION_TYPE_NOTI, APP_PRIV_ID);
 400         if(noti_err != NOTIFICATION_ERROR_NONE) {
 401                 return;
 402         }
 403 }
 404  * @endcode
 405  */
 406 NOTIFICATION_DEPRECATED_API int notification_delete_by_priv_id(const char *pkgname,
 407                                                     notification_type_e type,
 408                                                     int priv_id);
 409
 410 /**
 411  * @internal
 412  * @brief This function will be deprecated.
 413  * @details When notification data selected in display application, application launched by appsvc_run_service with service_handle.
 414  * @param[in] noti Notification handle
 415  * @param[in] type Notification execute type
 416  * @param[in] text Basic text for button
 417  * @param[in] key Value for localized text
 418  * @param[in] service_handle Appsvc bundle data
 419  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
 420  * @retval NOTIFICATION_ERROR_NONE Success
 421  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 422  * @par Sample code:
 423  * @code
 424 #include <notification.h>
 425 ...
 426 {
 427         notification_h noti = NULL;
 428         int noti_err = NOTIFICATION_ERROR_NONE;
 429         bundle *b = NULL;
 430
 431         ...
 432
 433         b = bundle_create();
 434         appsvc_set_operation(b, APPSVC_OPERATION_VIEW);
 435         appsvc_set_uri(b,"http://www.samsung.com");
 436
 437         noti_err  = notification_set_execute_option(noti, NOTIFICATION_EXECUTE_TYPE_SINGLE_LAUNCH, NULL, NULL, b);
 438         if(noti_err != NOTIFICATION_ERROR_NONE) {
 439                 notification_free(noti);
 440                 return;
 441         }
 442
 443         bundle_free(b);
 444 }
 445  * @endcode
 446  */
 447 NOTIFICATION_DEPRECATED_API int notification_set_execute_option(notification_h noti,
 448                                                      notification_execute_type_e type,
 449                                                      const char *text,
 450                                                      const char *key,
 451                                                      bundle *service_handle);
 452
 453 /**
 454  * @internal
 455  * @brief This function will be deprecated.
 456  * @remarks ID is valid only after inserting the notification.
 457  * @param[in] noti Notification handle
 458  * @param[out] group_id Group ID
 459  * @param[out] priv_id Private ID
 460  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
 461  * @retval NOTIFICATION_ERROR_NONE Success
 462  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 463  * @par Sample code:
 464  * @code
 465 #include <notification.h>
 466  ...
 467   {
 468          int noti_err = NOTIFICATION_ERROR_NONE;
 469          int group_id, priv_id;
 470
 471          noti_err  = notification_get_id(noti, &group_id, &priv_id);
 472          if(noti_err != NOTIFICATION_ERROR_NONE) {
 473                  return;
 474          }
 475  }
 476  * @endcode
 477  */
 478 NOTIFICATION_DEPRECATED_API int notification_get_id(notification_h noti,
 479                                          int *group_id, int *priv_id);
 480
 481 /**
 482  * @internal
 483  * @brief This function will be deprecated.
 484  * @param[in] type Notification type
 485  * @param[in] group_id Group ID
 486  * @param[in] priv_id Priv ID
 487  * @return Notification handle(#notification_h) on success, NULL on failure
 488  * @retval #notification_h Success
 489  * @retval NULL Failure
 490  * @see #notification_type_e
 491  * @see #notification_h
 492  * @par Sample code:
 493  * @code
 494 #include <notification.h>
 495 ...
 496 {
 497         notification_h noti = NULL;
 498
 499         noti = notification_load("org.tizen.app", priv_id);
 500         if(noti == NULL) {
 501                 return;
 502         }
 503         ...
 504 }
 505  * @endcode
 506  */
 507 NOTIFICATION_DEPRECATED_API notification_h notification_load(char *pkgname,
 508                                 int priv_id);
 509
 510 /**
 511  * @internal
 512  * @brief This function will be deprecated.
 513  * @details Available types are #NOTIFICATION_TYPE_NOTI and #NOTIFICATION_TYPE_ONGOING.
 514  * #NOTIFICATION_TYPE_NOTI is remaining notification data even if device is restarted.
 515  * #NOTIFICATION_TYPE_ONGOING can display progressive feather, but notification data is removed after device is restarted.
 516  * If group_id is #NOTIFICATION_GROUP_ID_NONE, notification data is not grouped. #NOTIFICATION_GROUP_ID_DEFAULT,
 517  * notification data is grouped with same title. Positive number ( > 0 ) is grouped with same number.
 518  * If priv_id is #NOTIFICATION_PRIV_ID_NONE, priv_id is set internally and return it when notification_insert() call.
 519  * Positive number and zero ( >= 0 ) is application set private ID. These ID should have be unique each application package.
 520  * @param[in] type Notification type
 521  * @param[in] group_id Group ID
 522  * @param[in] priv_id Priv ID
 523  * @return Notification handle(#notification_h) on success, NULL on failure
 524  * @retval #notification_h Success
 525  * @retval NULL Failure
 526  * @see #notification_type_e
 527  * @see #notification_h
 528  * @par Sample code:
 529  * @code
 530 #include <notification.h>
 531 ...
 532 {
 533         notification_h noti = NULL;
 534
 535         noti = notification_new(NOTIFICATION_TYPE_NOTI, APP_GROUP_ID, NOTIFICATION_PRIV_ID_NONE);
 536         if(noti == NULL) {
 537                 return;
 538         }
 539         ...
 540 }
 541  * @endcode
 542  */
 543 NOTIFICATION_DEPRECATED_API notification_h notification_new(notification_type_e type, int group_id,
 544                                 int priv_id);
 545
 546 /**
 547  * @internal
 548  * @brief This function will be deprecated.
 549  * @param[in] noti Notification handle
 550  * @param[in] type Notification execute type
 551  * @param[out] text Text for button
 552  * @param[out] service_handle Appsvc bundle data
 553  * @return NOTIFICATION_ERROR_NONE on success, other value on failure
 554  * @retval NOTIFICATION_ERROR_NONE Success
 555  * @retval NOTIFICATION_ERROR_INVALID_PARAMETER Invalid parameter
 556  * @par Sample code:
 557  * @code
 558 #include <notification.h>
 559 ...
 560 {
 561         notification_h noti = NULL;
 562         int noti_err = NOTIFICATION_ERROR_NONE;
 563         bundle *b = NULL;
 564
 565         ...
 566
 567         noti_err  = notification_get_execute_option(noti, NOTIFICATION_EXECUTE_TYPE_SINGLE_LAUNCH, NULL, NULL, &b);
 568         if(noti_err != NOTIFICATION_ERROR_NONE) {
 569                 notification_free(noti);
 570                 return;
 571         }
 572 }
 573  * @endcode
 574  */
 575 NOTIFICATION_DEPRECATED_API int notification_get_execute_option(notification_h noti,
 576                                                      notification_execute_type_e type,
 577                                                      const char **text,
 578                                                      bundle **service_handle);
 579
 580 int notification_set_ongoing_flag(notification_h noti, bool ongoing_flag);
 581
 582 int notification_get_ongoing_flag(notification_h noti, bool *ongoing_flag);
 583
 584 /**
 585  * @}
 586  */
 587
 588 #ifdef __cplusplus
 589 }
 590 #endif
 591 #endif