dd91b686961a3d14050fd93fa71ce93919a31efd
[WebKit-https.git] / Source / WebKit2 / UIProcess / API / efl / ewk_context.h
1 /*
2  * Copyright (C) 2012 Samsung Electronics
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Library General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Library General Public License for more details.
13  *
14  * You should have received a copy of the GNU Library General Public License
15  * along with this program; see the file COPYING.LIB.  If not, write to
16  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17  * Boston, MA 02110-1301, USA.
18  */
19
20 /**
21  * @file    ewk_context.h
22  * @brief   Describes the context API.
23  *
24  * @note ewk_context encapsulates all pages related to specific use of WebKit.
25  *
26  * Applications have the option of creating a context different than the default one
27  * and use it for a group of pages. All pages in the same context share the same
28  * preferences, visited link set, local storage, etc.
29  *
30  * A process model can be specified per context. The default one is the shared model
31  * where the web-engine process is shared among the pages in the context. The second
32  * model allows each page to use a separate web-engine process. This latter model is
33  * currently not supported by WebKit2/EFL.
34  *
35  */
36
37 #ifndef ewk_context_h
38 #define ewk_context_h
39
40 #include "ewk_application_cache_manager.h"
41 #include "ewk_cookie_manager.h"
42 #include "ewk_database_manager.h"
43 #include "ewk_favicon_database.h"
44 #include "ewk_navigation_data.h"
45 #include "ewk_storage_manager.h"
46 #include "ewk_url_scheme_request.h"
47 #include <Evas.h>
48
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
52
53 /**
54  * Declare Ewk_Context as Ewk_Object.
55  *
56  * @see Ewk_Object
57  */
58 typedef struct EwkObject Ewk_Context;
59
60 /**
61  * \enum    Ewk_Cache_Model
62  *
63  * @brief   Contains option for cache model
64  */
65 enum Ewk_Cache_Model {
66     /// Use the smallest cache capacity.
67     EWK_CACHE_MODEL_DOCUMENT_VIEWER,
68     /// Use bigger cache capacity than EWK_CACHE_MODEL_DOCUMENT_VIEWER.
69     EWK_CACHE_MODEL_DOCUMENT_BROWSER,
70     /// Use the biggest cache capacity.
71     EWK_CACHE_MODEL_PRIMARY_WEBBROWSER
72 };
73
74 /// Creates a type name for the Ewk_Cache_Model.
75 typedef enum Ewk_Cache_Model Ewk_Cache_Model;
76
77 /**
78  * \enum    Ewk_Process_Model
79  *
80  * @brief   Contains option for process model
81  */
82 enum Ewk_Process_Model {
83     EWK_PROCESS_MODEL_SHARED_SECONDARY,
84     EWK_PROCESS_MODEL_MULTIPLE_SECONDARY
85 };
86
87 /// Creates a type name for the Ewk_Process_Model.
88 typedef enum Ewk_Process_Model Ewk_Process_Model;
89
90 /**
91  * \enum    Ewk_TLS_Error_Policy
92  *
93  * @brief   Contains option for TLS error policy
94  */
95 enum Ewk_TLS_Error_Policy {
96     EWK_TLS_ERROR_POLICY_FAIL, // Fail on TLS errors.
97     EWK_TLS_ERROR_POLICY_IGNORE // Ignore TLS errors.
98 };
99
100 // Creates a type name for the Ewk_TLS_Error_Policy.
101 typedef enum Ewk_TLS_Error_Policy Ewk_TLS_Error_Policy;
102
103 /**
104  * @typedef Ewk_Url_Scheme_Request_Cb Ewk_Url_Scheme_Request_Cb
105  * @brief Callback type for use with ewk_context_url_scheme_register().
106  */
107 typedef void (*Ewk_Url_Scheme_Request_Cb) (Ewk_Url_Scheme_Request *request, void *user_data);
108
109 /**
110  * @typedef Ewk_History_Navigation_Cb Ewk_History_Navigation_Cb
111  * @brief Type definition for a function that will be called back when @a view did navigation (loaded new URL).
112  */
113 typedef void (*Ewk_History_Navigation_Cb)(const Evas_Object *view, Ewk_Navigation_Data *navigation_data, void *user_data);
114
115 /**
116  * @typedef Ewk_History_Client_Redirection_Cb Ewk_History_Client_Redirection_Cb
117  * @brief Type definition for a function that will be called back when @a view performed a client redirect.
118  */
119 typedef void (*Ewk_History_Client_Redirection_Cb)(const Evas_Object *view, const char *source_url, const char *destination_url, void *user_data);
120
121 /**
122  * @typedef Ewk_History_Server_Redirection_Cb Ewk_History_Server_Redirection_Cb
123  * @brief Type definition for a function that will be called back when @a view performed a server redirect.
124  */
125 typedef void (*Ewk_History_Server_Redirection_Cb)(const Evas_Object *view, const char *source_url, const char *destination_url, void *user_data);
126
127 /**
128  * @typedef Ewk_History_Title_Update_Cb Ewk_History_Title_Update_Cb
129  * @brief Type definition for a function that will be called back when history title is updated.
130  */
131 typedef void (*Ewk_History_Title_Update_Cb)(const Evas_Object *view, const char *title, const char *url, void *user_data);
132
133 /**
134  * @typedef Ewk_Context_History_Client_Visited_Links_Populate_Cb Ewk_Context_History_Client_Visited_Links_Populate_Cb
135  * @brief Type definition for a function that will be called back when client is asked to provide visited links from a client-managed storage.
136  *
137  * @see ewk_context_visited_link_add
138  */
139 typedef void (*Ewk_History_Populate_Visited_Links_Cb)(void *user_data);
140
141 /**
142  * Callback for didReceiveMessageFromInjectedBundle and didReceiveSynchronousMessageFromInjectedBundle
143  *
144  * User should allocate new string for return_data before setting it.
145  * The return_data string will be freed on WebKit side.
146  *
147  * @param name name of message from injected bundle
148  * @param body body of message from injected bundle
149  * @param return_data return_data string from application
150  * @param user_data user_data will be passsed when receiving message from injected bundle
151  */
152 typedef void (*Ewk_Context_Message_From_Injected_Bundle_Cb)(const char *name, const char *body, char **return_data, void *user_data);
153
154 /**
155  * Gets default Ewk_Context instance.
156  *
157  * The returned Ewk_Context object @b should not be unref'ed if application
158  * does not call ewk_context_ref() for that.
159  *
160  * @return Ewk_Context object.
161  */
162 EAPI Ewk_Context *ewk_context_default_get(void);
163
164 /**
165  * Creates a new Ewk_Context.
166  *
167  * The returned Ewk_Context object @b should be unref'ed after use.
168  *
169  * @return Ewk_Context object on success or @c NULL on failure
170  *
171  * @see ewk_object_unref
172  * @see ewk_context_new_with_extensions_path
173  */
174 EAPI Ewk_Context *ewk_context_new(void);
175
176 /**
177  * Creates a new Ewk_Context.
178  *
179  * The returned Ewk_Context object @b should be unref'ed after use.
180  *
181  * @param path directory path of extensions
182  *
183  * @return Ewk_Context object on success or @c NULL on failure
184  *
185  * @note All shared objects which have ewk_extension_init() in the given @a path will be loaded.
186  *
187  * @see ewk_object_unref
188  * @see ewk_context_new
189  * @see Ewk_Extension_Initialize_Function
190  */
191 EAPI Ewk_Context *ewk_context_new_with_extensions_path(const char *path);
192
193 /**
194  * Gets the application cache manager instance for this @a context.
195  *
196  * @param context context object to query.
197  *
198  * @return Ewk_Cookie_Manager object instance or @c NULL in case of failure.
199  */
200 EAPI Ewk_Application_Cache_Manager *ewk_context_application_cache_manager_get(const Ewk_Context *context);
201
202 /**
203  * Gets the cookie manager instance for this @a context.
204  *
205  * @param context context object to query.
206  *
207  * @return Ewk_Cookie_Manager object instance or @c NULL in case of failure.
208  */
209 EAPI Ewk_Cookie_Manager *ewk_context_cookie_manager_get(const Ewk_Context *context);
210
211 /**
212  * Gets the database manager instance for this @a context.
213  *
214  * @param context context object to query
215  *
216  * @return Ewk_Database_Manager object instance or @c NULL in case of failure
217  */
218 EAPI Ewk_Database_Manager *ewk_context_database_manager_get(const Ewk_Context *context);
219
220 /**
221  * Sets the favicon database directory for this @a context.
222  *
223  * Sets the directory path to be used to store the favicons database
224  * for @a context on disk. Passing @c NULL as @a directory_path will
225  * result in using the default directory for the platform.
226  *
227  * Calling this method also means enabling the favicons database for
228  * its use from the applications, it is therefore expected to be
229  * called only once. Further calls for the same instance of
230  * @a context will not have any effect.
231  *
232  * @param context context object to update
233  * @param directory_path database directory path to set
234  *
235  * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise
236  */
237 EAPI Eina_Bool ewk_context_favicon_database_directory_set(Ewk_Context *context, const char *directory_path);
238
239 /**
240  * Gets the favicon database instance for this @a context.
241  *
242  * @param context context object to query.
243  *
244  * @return Ewk_Favicon_Database object instance or @c NULL in case of failure.
245  */
246 EAPI Ewk_Favicon_Database *ewk_context_favicon_database_get(const Ewk_Context *context);
247
248 /**
249  * Gets the storage manager instance for this @a context.
250  *
251  * @param context context object to query.
252  *
253  * @return Ewk_Storage_Manager object instance or @c NULL in case of failure.
254  */
255 EAPI Ewk_Storage_Manager *ewk_context_storage_manager_get(const Ewk_Context *context);
256
257 /**
258  * Register @a scheme in @a context.
259  *
260  * When an URL request with @a scheme is made in the #Ewk_Context, the callback
261  * function provided will be called with a #Ewk_Url_Scheme_Request.
262  *
263  * It is possible to handle URL scheme requests asynchronously, by calling ewk_object_ref() on the
264  * #Ewk_Url_Scheme_Request and calling ewk_url_scheme_request_finish() later when the data of
265  * the request is available.
266  *
267  * @param context a #Ewk_Context object.
268  * @param scheme the network scheme to register
269  * @param callback the function to be called when an URL request with @a scheme is made.
270  * @param user_data data to pass to callback function
271  *
272  * @code
273  * static void custom_url_scheme_request_cb(Ewk_Url_Scheme_Request *request, void *user_data)
274  * {
275  *     const char *scheme;
276  *     char *contents_data = NULL;
277  *     unsigned contents_length = 0;
278  *
279  *     scheme = ewk_url_scheme_request_scheme_get(request);
280  *     if (!strcmp(scheme, "myapp")) {
281  *         // Initialize contents_data with a welcome page, and set its length to contents_length
282  *     } else {
283  *         Eina_Strbuf *buf = eina_strbuf_new();
284  *         eina_strbuf_append_printf(buf, "&lt;html&gt;&lt;body&gt;&lt;p&gt;Invalid application: %s&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;", scheme);
285  *         contents_data = eina_strbuf_string_steal(buf);
286  *         contents_length = strlen(contents_data);
287  *         eina_strbuf_free(buf);
288  *     }
289  *     ewk_url_scheme_request_finish(request, contents_data, contents_length, "text/html");
290  *     free(contents_data);
291  * }
292  * @endcode
293  */
294 EAPI Eina_Bool ewk_context_url_scheme_register(Ewk_Context *context, const char *scheme, Ewk_Url_Scheme_Request_Cb callback, void *user_data);
295
296 /**
297  * Sets history callbacks for the given @a context.
298  *
299  * To stop listening for history events, you may call this function with @c
300  * NULL for the callbacks.
301  *
302  * @param context context object to set history callbacks
303  * @param navigate_func The function to call when @c ewk_view did navigation (may be @c NULL).
304  * @param client_redirect_func The function to call when @c ewk_view performed a client redirect (may be @c NULL).
305  * @param server_redirect_func The function to call when @c ewk_view performed a server redirect (may be @c NULL).
306  * @param title_update_func The function to call when history title is updated (may be @c NULL).
307  * @param populate_visited_links_func The function is called when client is asked to provide visited links from a
308  *        client-managed storage (may be @c NULL).
309  * @param data User data (may be @c NULL).
310  */
311 EAPI void ewk_context_history_callbacks_set(Ewk_Context *context,
312                                             Ewk_History_Navigation_Cb navigate_func,
313                                             Ewk_History_Client_Redirection_Cb client_redirect_func,
314                                             Ewk_History_Server_Redirection_Cb server_redirect_func,
315                                             Ewk_History_Title_Update_Cb title_update_func,
316                                             Ewk_History_Populate_Visited_Links_Cb populate_visited_links_func,
317                                             void *data);
318
319 /**
320  * Registers the given @a visited_url as visited link in @a context visited link cache.
321  *
322  * This function shall be invoked as a response to @c populateVisitedLinks callback of the history cient.
323  *
324  * @param context context object to add visited link data
325  * @param visited_url visited url
326  *
327  * @see Ewk_Context_History_Client
328  */
329 EAPI void ewk_context_visited_link_add(Ewk_Context *context, const char *visited_url);
330
331 /**
332  * Set @a cache_model as the cache model for @a context.
333  *
334  * By default, it is EWK_CACHE_MODEL_DOCUMENT_VIEWER.
335  *
336  * @param context context object to update.
337  * @param cache_model a #Ewk_Cache_Model.
338  *
339  * @return @c EINA_TRUE on success or @c EINA_FALSE on failure
340  */
341 EAPI Eina_Bool ewk_context_cache_model_set(Ewk_Context *context, Ewk_Cache_Model cache_model);
342
343 /**
344  * Gets the cache model for @a context.
345  *
346  * @param context context object to query.
347  *
348  * @return the cache model for the @a context.
349  */
350 EAPI Ewk_Cache_Model ewk_context_cache_model_get(const Ewk_Context *context);
351
352 /**
353  * Sets additional plugin path for @a context.
354  *
355  * @param context context object to set additional plugin path
356  * @param path the path to be used for plugins
357  *
358  * @return @c EINA_TRUE on success or @c EINA_FALSE on failure
359  */
360 EAPI Eina_Bool ewk_context_additional_plugin_path_set(Ewk_Context *context, const char *path);
361
362 /**
363  * Clears HTTP caches in local storage and all resources cached in memory 
364  * such as images, CSS, JavaScript, XSL, and fonts for @a context.
365  *
366  * @param context context object to clear all resource caches
367  */
368 EAPI void ewk_context_resource_cache_clear(Ewk_Context *context);
369
370 /**
371  * Posts message to injected bundle.
372  *
373  * @param context context object to post message to injected bundle
374  * @param name message name
375  * @param body message body
376  */
377 EAPI void ewk_context_message_post_to_injected_bundle(Ewk_Context *context, const char *name, const char *body);
378
379 /**
380  * Sets callback for received injected bundle message.
381  *
382  * Client can pass @c NULL for callback to stop listening for messages.
383  *
384  * @param context context object
385  * @param callback callback for received injected bundle message or @c NULL
386  * @param user_data user data
387  */
388 EAPI void ewk_context_message_from_injected_bundle_callback_set(Ewk_Context *context, Ewk_Context_Message_From_Injected_Bundle_Cb callback, void *user_data);
389
390 /**
391  * Sets a process model for @a context.
392  *
393  * Sets a process model for web views, which will be used to decide how
394  * processes should be handled. Default value is
395  * EWK_PROCESS_MODEL_SHARED_SECONDARY which means that there is only one
396  * web process. When EWK_PROCESS_MODEL_MULTIPLE_SECONDARY is set a
397  * network process is introduced and every web view starts new web process.
398  * This function should be used before first web process is spawned.
399  *
400  * @param context context object to set process model
401  * @param process_model a #Ewk_Process_Model
402  */
403 EAPI Eina_Bool ewk_context_process_model_set(Ewk_Context *context, Ewk_Process_Model process_model);
404
405 /**
406  * Gets the process model for @a context.
407  *
408  * @param context context object to query
409  *
410  * @return the process model for the @a context
411  */
412 EAPI Ewk_Process_Model ewk_context_process_model_get(const Ewk_Context *context);
413
414 /**
415  * Gets TLS error policy for @a context.
416  *
417  * @param context context object to get TLS error policy
418  *
419  * @return The TLS errors policy for the context
420  */
421 EAPI Ewk_TLS_Error_Policy ewk_context_tls_error_policy_get(const Ewk_Context *context);
422
423 /**
424  * Sets TLS error policy for @a context.
425  *
426  * Sets how TLS certificate errors should be handled. The available policies are listed in #Ewk_TLS_Error_Policy enumeration.
427  *
428  * @param context context object to set TLS error policy
429  * @param tls_error_policy a #Ewk_TLS_Error_Policy
430  */
431 EAPI void ewk_context_tls_error_policy_set(Ewk_Context *context, Ewk_TLS_Error_Policy tls_error_policy);
432
433 /**
434  * Sets the list of preferred languages.
435  *
436  * Sets the list of preferred langages. This list will be used to build the "Accept-Language"
437  * header that will be included in the network requests.
438  * Client can pass @c NULL for languages to clear what is set before.
439  *
440  * @param languages the list of preferred languages (char* as data) or @c NULL
441  *
442  * @note all contexts will be affected.
443  */
444 EAPI void ewk_context_preferred_languages_set(Eina_List *languages);
445
446 #ifdef __cplusplus
447 }
448 #endif
449
450 #endif // ewk_context_h