tizen_src/ewk/efl_integration/public/ewk_notification.h

   1 // Copyright 2013 Samsung Electronics. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef ewk_notification_h
   6 #define ewk_notification_h
   7
   8 #include <Eina.h>
   9 #include <Evas.h>
  10 #include "ewk_export.h"
  11 #include "ewk_security_origin.h"
  12
  13 #ifdef __cplusplus
  14 extern "C" {
  15 #endif
  16
  17 struct _Ewk_Notification_Permission {
  18     const char* origin;
  19     Eina_Bool allowed;
  20 };
  21
  22 typedef struct Ewk_Notification Ewk_Notification;
  23 typedef struct _Ewk_Notification_Permission Ewk_Notification_Permission;
  24 typedef struct Ewk_Notification_Permission_Request Ewk_Notification_Permission_Request;
  25 typedef void (*Ewk_Notification_Show_Callback)(Ewk_Notification*, void*);
  26 typedef void (*Ewk_Notification_Cancel_Callback)(uint64_t, void*);
  27
  28 /**
  29  * Sets callbacks for notifications handling.
  30  *
  31  * These callbacks will receive all notifications from all webview instances.
  32  * @e show_callback is used to display notification UI. Embeder should call
  33  * ewk_notification_showed after it displays notification UI. @e cancel_callback
  34  * will be called after notification is closed by engine. It's used to notify
  35  * embeder that related notification UI should be destroyed.
  36  *
  37  * @param show_callback notification show callback. Can't be NULL
  38  * @param cancel_callback notification close callback. Can't be NULL
  39  * @param user_data extra data for callback
  40  *
  41  * @return EINA_TRUE on success, EINA_FALSE on failure (i.e. when ewk_init was not called)
  42  */
  43 EXPORT_API Eina_Bool ewk_notification_callbacks_set(Ewk_Notification_Show_Callback show_callback, Ewk_Notification_Cancel_Callback cancel_callback, void* user_data);
  44
  45 /**
  46  * Resets notification callbacks to NULL
  47  *
  48  * @return EINA_TRUE on success, EINA_FALSE on failure (i.e. when ewk_init was not called)
  49  */
  50 EXPORT_API Eina_Bool ewk_notification_callbacks_reset();
  51
  52 /**
  53  * Get notification icon as Evas_Object
  54  *
  55  * @param ewk_notification pointer to notification data
  56  * @param evas canvas where icon object will be added
  57  *
  58  * @return Evas_Object containing icon if successful, @c NULL otherwise.
  59  *         Caller takes ownership of returned Evas_Object.
  60  */
  61 EXPORT_API Evas_Object* ewk_notification_icon_get(const Ewk_Notification* ewk_notification, Evas* evas);
  62
  63 /**
  64  * Save notification icon as PNG image
  65  *
  66  * @param ewk_notification notification data pointer
  67  * @param path path where file will be saved
  68  *
  69  * @return EINA_TRUE on success
  70  */
  71 EXPORT_API Eina_Bool ewk_notification_icon_save_as_png(
  72     const Ewk_Notification* ewk_notification, const char* path);
  73
  74 /**
  75  * Requests for getting body of notification.
  76  *
  77  * @param ewk_notification pointer of notificaion data
  78  *
  79  * @return body of notification
  80  *         Lifetime only valid as long as @a ewk_notification is valid.
  81  */
  82 EXPORT_API const char* ewk_notification_body_get(const Ewk_Notification* ewk_notification);
  83
  84 /**
  85  * Notify that notification is clicked.
  86  *
  87  * @param notification_id identifier of notification
  88  *
  89  * @return EINA_TRUE on success, EINA_FALSE if notification id is invalid
  90  */
  91 EXPORT_API Eina_Bool ewk_notification_clicked(uint64_t notification_id);
  92
  93 /**
  94  * Requests for getting icon url of notification.
  95  *
  96  * @param ewk_notification pointer of notification data
  97  *
  98  * @return Always returns NULL - this API is deprecated.
  99  *
 100  * @deprecated
 101  */
 102 EINA_DEPRECATED EXPORT_API const char* ewk_notification_icon_url_get(const Ewk_Notification* ewk_notification);
 103
 104 /**
 105  * Requests for getting id of notification.
 106  *
 107  * @param ewk_notification pointer of notification data
 108  *
 109  * @return id of notification
 110  */
 111 EXPORT_API uint64_t ewk_notification_id_get(const Ewk_Notification* ewk_notification);
 112
 113 /**
 114  * Requests for setting cached notification permissions.
 115  *
 116  * By calling this notification permission is replaced as passed ewk_notification_permissions.
 117  *
 118  * @param context context object
 119  * @param ewk_notification_permissions list of cached permissions(Ewk_Notification_Permission)
 120  *
 121  * @return EINA_TRUE if successful, EINA_FALSE if ewk_init was not called
 122  */
 123 EXPORT_API Eina_Bool ewk_notification_cached_permissions_set(Eina_List *ewk_notification_permissions);
 124
 125 /**
 126  * Requests for getting origin of notification permission request.
 127  *
 128  * @param request Ewk_Notification_Permission_Request object to get origin for notification permission request
 129  *
 130  * @return security origin of notification permission request
 131  *         Lifetime only valid as long as @a ewk_notification is valid.
 132  */
 133 EXPORT_API const Ewk_Security_Origin* ewk_notification_permission_request_origin_get(const Ewk_Notification_Permission_Request* request);
 134
 135 /**
 136  * Reply the result about notification permission.
 137  *
 138  * @param request Ewk_Notification_Permission_Request object to get the
 139  *                infomation about notification permission request.
 140  * @param allow result about notification permission
 141  *
 142  * @return EINA_TRUE is successful. EINA_FALSE if reply was already called for
 143  *         this request or if request is NULL
 144  */
 145 EXPORT_API Eina_Bool ewk_notification_permission_reply(Ewk_Notification_Permission_Request *request, Eina_Bool allow);
 146
 147 /**
 148  * Deprecated, use ewk_notification_permission_reply instead.
 149  * Sets permission of notification.
 150  *
 151  * @param request Ewk_Notification_Permission_Request object to allow/deny notification permission
 152  *        request is freed in this function.
 153  * @param allowed @c EINA_TRUE if permission is allowed, @c EINA_FALSE if permission is denied
 154  *
 155  * @return EINA_TRUE is successful. EINA_FALSE if reply was already called for
 156  *         this request or if request is NULL
 157  *
 158  * @deprecated
 159  * @see ewk_notification_permission_reply
 160  */
 161 EINA_DEPRECATED EXPORT_API Eina_Bool ewk_notification_permission_request_set(Ewk_Notification_Permission_Request* request, Eina_Bool allowed);
 162
 163 /**
 164  * Suspend the operation for permission request.
 165  *
 166  * This suspends the operation for permission request.
 167  * This is very useful to decide the policy from the additional UI operation like the popup.
 168  *
 169  * @param request Ewk_Notification_Permission_Request object to suspend notification permission request
 170  */
 171 EXPORT_API Eina_Bool ewk_notification_permission_request_suspend(Ewk_Notification_Permission_Request* request);
 172
 173 /**
 174  * Notify that notification policies are removed.
 175  *
 176  * @param context context object
 177  * @param origins list of security origins(made by UAs)
 178  */
 179 EXPORT_API Eina_Bool ewk_notification_policies_removed(Eina_List* origins);
 180
 181 /**
 182  * Requests for getting security origin of notification.
 183  *
 184  * @param ewk_notification pointer of notification data
 185  *
 186  * @return security origin of notification
 187  *         Lifetime only valid as long as @a ewk_notification is valid.
 188  */
 189 EXPORT_API const Ewk_Security_Origin* ewk_notification_security_origin_get(const Ewk_Notification* ewk_notification);
 190
 191 /**
 192  * Notify that notification is showed.
 193  *
 194  * @param notification_id identifier of notification
 195  */
 196 EXPORT_API Eina_Bool ewk_notification_showed(uint64_t notification_id);
 197
 198 /**
 199  * Notify that notification was closed.
 200  *
 201  * @param notification_id identifier of notification
 202  * @param by_user         informs whether notification was closed by user
 203  *                        action or by some other application logic
 204  */
 205 EXPORT_API Eina_Bool ewk_notification_closed(uint64_t notification_id, Eina_Bool by_user);
 206
 207 /**
 208  * Requests for getting title of notification.
 209  *
 210  * @param ewk_notification pointer of notification data
 211  *
 212  * @return title of notification
 213  *         Lifetime only valid as long as @a ewk_notification is valid.
 214  */
 215 EXPORT_API const char* ewk_notification_title_get(const Ewk_Notification* ewk_notification);
 216
 217 /**
 218  * Query if the notification is silent
 219  *
 220  * @param ewk_notification pointer of notification data
 221  *
 222  * @return @c EINA_TRUE if the notification must be silent, @c EINA_FALSE
 223  *         otherwise
 224  */
 225 EXPORT_API Eina_Bool ewk_notification_silent_get(const Ewk_Notification* ewk_notification);
 226
 227 #ifdef __cplusplus
 228 }
 229 #endif
 230 #endif // ewk_notification_h