[EFL][WK2] Rename async APIs for better consistency with EFL
[WebKit-https.git] / Source / WebKit2 / UIProcess / API / efl / ewk_cookie_manager.h
1 /*
2  * Copyright (C) 2012 Intel Corporation. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  * 1. Redistributions of source code must retain the above copyright
8  *    notice, this list of conditions and the following disclaimer.
9  * 2. Redistributions in binary form must reproduce the above copyright
10  *    notice, this list of conditions and the following disclaimer in the
11  *    documentation and/or other materials provided with the distribution.
12  *
13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
14  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
15  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
17  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
19  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
20  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
21  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
22  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
23  * THE POSSIBILITY OF SUCH DAMAGE.
24  */
25
26 /**
27  * @file    ewk_cookie_manager.h
28  * @brief   Describes the Ewk Cookie Manager API.
29  */
30
31 #ifndef ewk_cookie_manager_h
32 #define ewk_cookie_manager_h
33
34 #include "ewk_error.h"
35 #include <Eina.h>
36
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40
41 /** Creates a type name for Ewk_Cookie_Manager */
42 typedef struct EwkCookieManager Ewk_Cookie_Manager;
43
44 /**
45  * \enum    Ewk_Cookie_Accept_Policy
46  *
47  * @brief   Contains accept policies for the cookies.
48  */
49 enum Ewk_Cookie_Accept_Policy {
50     /// Accepts every cookie sent from any page.
51     EWK_COOKIE_ACCEPT_POLICY_ALWAYS,
52     /// Rejects all cookies.
53     EWK_COOKIE_ACCEPT_POLICY_NEVER,
54     /// Accepts only cookies set by the main document loaded.
55     EWK_COOKIE_ACCEPT_POLICY_NO_THIRD_PARTY
56 };
57
58 /// Creates a type name for the Ewk_Cookie_Accept_Policy.
59 typedef enum Ewk_Cookie_Accept_Policy Ewk_Cookie_Accept_Policy;
60
61 /**
62  * \enum    Ewk_Cookie_Persistent_Storage
63  *
64  * @brief   Enum values to denote cookies persistent storage type.
65  */
66 enum Ewk_Cookie_Persistent_Storage {
67     /// Cookies are stored in a text file in the Mozilla "cookies.txt" format.
68     EWK_COOKIE_PERSISTENT_STORAGE_TEXT,
69     /// Cookies are stored in a SQLite file in the current Mozilla format.
70     EWK_COOKIE_PERSISTENT_STORAGE_SQLITE
71 };
72
73 /// Creates a type name for the Ewk_Cookie_Persistent_Storage.
74 typedef enum Ewk_Cookie_Persistent_Storage Ewk_Cookie_Persistent_Storage;
75
76 /**
77  * @typedef Ewk_Cookie_Manager_Policy_Async_Get_Cb Ewk_Cookie_Manager_Policy_Async_Get_Cb
78  * @brief Callback type for use with ewk_cookie_manager_accept_policy_async_get
79  */
80 typedef void (*Ewk_Cookie_Manager_Policy_Async_Get_Cb)(Ewk_Cookie_Accept_Policy policy, Ewk_Error *error, void *event_info);
81
82 /**
83  * @typedef Ewk_Cookie_Manager_Hostnames_Async_Get_Cb Ewk_Cookie_Manager_Hostnames_Async_Get_Cb
84  * @brief Callback type for use with ewk_cookie_manager_hostnames_with_cookies_async_get
85  *
86  * @note The @a hostnames list items are guaranteed to be eina_stringshare. Whenever possible
87  * save yourself some cpu cycles and use eina_stringshare_ref() instead of eina_stringshare_add()
88  * or strdup().
89  */
90 typedef void (*Ewk_Cookie_Manager_Hostnames_Async_Get_Cb)(Eina_List *hostnames, Ewk_Error *error, void *event_info);
91
92 /**
93  * @typedef Ewk_Cookie_Manager_Changes_Watch_Cb Ewk_Cookie_Manager_Changes_Watch_Cb
94  * @brief Callback type for use with ewk_cookie_manager_changes_watch()
95  */
96 typedef void (*Ewk_Cookie_Manager_Changes_Watch_Cb)(void *event_info);
97
98 /**
99  * Set the @a filename where non-session cookies are stored persistently using @a storage as the format to read/write the cookies.
100  *
101  * Cookies are initially read from @filename to create an initial set of cookies.
102  * Then, non-session cookies will be written to @filename.
103  *
104  * By default, @a manager doesn't store the cookies persistenly, so you need to call this
105  * method to keep cookies saved across sessions.
106  *
107  * @param cookie_manager The cookie manager to update.
108  * @param filename the filename to read to/write from.
109  * @param storage the type of storage.
110  */
111 EAPI void ewk_cookie_manager_persistent_storage_set(Ewk_Cookie_Manager *manager, const char *filename, Ewk_Cookie_Persistent_Storage storage);
112
113 /**
114  * Set @a policy as the cookie acceptance policy for @a manager.
115  *
116  * By default, only cookies set by the main document loaded are accepted.
117  *
118  * @param manager The cookie manager to update.
119  * @param policy a #Ewk_Cookie_Accept_Policy
120  */
121
122 EAPI void ewk_cookie_manager_accept_policy_set(Ewk_Cookie_Manager *manager, Ewk_Cookie_Accept_Policy policy);
123
124 /**
125  * Asynchronously get the cookie acceptance policy of @a manager.
126  *
127  * By default, only cookies set by the main document loaded are accepted.
128  *
129  * @param manager The cookie manager to query.
130  * @param callback The function to call when the policy is received or an error occured.
131  * @param data User data (may be @c NULL).
132  */
133 EAPI void ewk_cookie_manager_accept_policy_async_get(const Ewk_Cookie_Manager *manager, Ewk_Cookie_Manager_Policy_Async_Get_Cb callback, void *data);
134
135 /**
136  * Asynchronously get the list of host names for which @a manager contains cookies.
137  *
138  * @param manager The cookie manager to query.
139  * @param callback The function to call when the host names have been received.
140  * @param data User data (may be @c NULL).
141  */
142 EAPI void ewk_cookie_manager_hostnames_with_cookies_async_get(const Ewk_Cookie_Manager *manager, Ewk_Cookie_Manager_Hostnames_Async_Get_Cb callback, void *data);
143
144 /**
145  * Remove all cookies of @a manager for the given @a hostname.
146  *
147  * @param manager The cookie manager to update.
148  * @param hostname A host name.
149  */
150 EAPI void ewk_cookie_manager_hostname_cookies_clear(Ewk_Cookie_Manager *manager, const char *hostname);
151
152 /**
153  * Watch for cookies changes in @a manager.
154  *
155  * Pass @c NULL as value for @a callback to stop watching for changes.
156  *
157  * @param manager The cookie manager to watch.
158  * @param callback function that will be called every time cookies are added, removed or modified.
159  * @param data User data (may be @c NULL).
160  */
161 EAPI void ewk_cookie_manager_changes_watch(Ewk_Cookie_Manager *manager, Ewk_Cookie_Manager_Changes_Watch_Cb callback, void *data);
162
163 /**
164  * Delete all cookies of @a manager.
165  *
166  * @param manager The cookie manager to update.
167  */
168 EAPI void ewk_cookie_manager_cookies_clear(Ewk_Cookie_Manager *manager);
169
170 #ifdef __cplusplus
171 }
172 #endif
173
174 #endif // ewk_cookie_manager_h