[EFL][CustomProtocol] Do not add duplicated custom scheme
[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_download_job.h"
44 #include "ewk_error.h"
45 #include "ewk_favicon_database.h"
46 #include "ewk_navigation_data.h"
47 #include "ewk_storage_manager.h"
48 #include "ewk_url_scheme_request.h"
49 #include <Evas.h>
50
51 #ifdef __cplusplus
52 extern "C" {
53 #endif
54
55 /// Creates a type name for Ewk_Download_Job_Error.
56 typedef struct Ewk_Download_Job_Error Ewk_Download_Job_Error;
57
58 /**
59  * @brief Structure containing details about a download failure.
60  */
61 struct Ewk_Download_Job_Error {
62     Ewk_Download_Job *download_job; /**< download that failed */
63     Ewk_Error *error; /**< download error */
64 };
65
66 /**
67  * Declare Ewk_Context as Ewk_Object.
68  *
69  * @see Ewk_Object
70  */
71 #ifdef __cplusplus
72 typedef class EwkObject Ewk_Context;
73 #else
74 typedef struct EwkObject Ewk_Context;
75 #endif
76
77 /**
78  * \enum    Ewk_Cache_Model
79  *
80  * @brief   Contains option for cache model
81  */
82 enum Ewk_Cache_Model {
83     /// Use the smallest cache capacity.
84     EWK_CACHE_MODEL_DOCUMENT_VIEWER,
85     /// Use bigger cache capacity than EWK_CACHE_MODEL_DOCUMENT_VIEWER.
86     EWK_CACHE_MODEL_DOCUMENT_BROWSER,
87     /// Use the biggest cache capacity.
88     EWK_CACHE_MODEL_PRIMARY_WEBBROWSER
89 };
90
91 /// Creates a type name for the Ewk_Cache_Model.
92 typedef enum Ewk_Cache_Model Ewk_Cache_Model;
93
94 /**
95  * \enum    Ewk_Process_Model
96  *
97  * @brief   Contains option for process model
98  */
99 enum Ewk_Process_Model {
100     EWK_PROCESS_MODEL_SHARED_SECONDARY,
101     EWK_PROCESS_MODEL_MULTIPLE_SECONDARY
102 };
103
104 /// Creates a type name for the Ewk_Process_Model.
105 typedef enum Ewk_Process_Model Ewk_Process_Model;
106
107 /**
108  * \enum    Ewk_TLS_Error_Policy
109  *
110  * @brief   Contains option for TLS error policy
111  */
112 enum Ewk_TLS_Error_Policy {
113     EWK_TLS_ERROR_POLICY_FAIL, // Fail on TLS errors.
114     EWK_TLS_ERROR_POLICY_IGNORE // Ignore TLS errors.
115 };
116
117 // Creates a type name for the Ewk_TLS_Error_Policy.
118 typedef enum Ewk_TLS_Error_Policy Ewk_TLS_Error_Policy;
119
120 /**
121  * @typedef Ewk_Url_Scheme_Request_Cb Ewk_Url_Scheme_Request_Cb
122  * @brief Callback type for use with ewk_context_url_scheme_register().
123  */
124 typedef void (*Ewk_Url_Scheme_Request_Cb) (Ewk_Url_Scheme_Request *request, void *user_data);
125
126 /**
127  * @typedef Ewk_History_Navigation_Cb Ewk_History_Navigation_Cb
128  * @brief Type definition for a function that will be called back when @a view did navigation (loaded new URL).
129  */
130 typedef void (*Ewk_History_Navigation_Cb)(const Evas_Object *view, Ewk_Navigation_Data *navigation_data, void *user_data);
131
132 /**
133  * @typedef Ewk_History_Client_Redirection_Cb Ewk_History_Client_Redirection_Cb
134  * @brief Type definition for a function that will be called back when @a view performed a client redirect.
135  */
136 typedef void (*Ewk_History_Client_Redirection_Cb)(const Evas_Object *view, const char *source_url, const char *destination_url, void *user_data);
137
138 /**
139  * @typedef Ewk_History_Server_Redirection_Cb Ewk_History_Server_Redirection_Cb
140  * @brief Type definition for a function that will be called back when @a view performed a server redirect.
141  */
142 typedef void (*Ewk_History_Server_Redirection_Cb)(const Evas_Object *view, const char *source_url, const char *destination_url, void *user_data);
143
144 /**
145  * @typedef Ewk_History_Title_Update_Cb Ewk_History_Title_Update_Cb
146  * @brief Type definition for a function that will be called back when history title is updated.
147  */
148 typedef void (*Ewk_History_Title_Update_Cb)(const Evas_Object *view, const char *title, const char *url, void *user_data);
149
150 /**
151  * @typedef Ewk_Download_Requested_Cb Ewk_Download_Requested_Cb
152  * @brief Type definition for a function that will be called back when new download job is requested.
153  */
154 typedef void (*Ewk_Download_Requested_Cb)(Ewk_Download_Job *download, void *user_data);
155
156 /**
157  * @typedef Ewk_Download_Failed_Cb Ewk_Download_Failed_Cb
158  * @brief Type definition for a function that will be called back when a download job has failed.
159  */
160 typedef void (*Ewk_Download_Failed_Cb)(Ewk_Download_Job_Error *error, void *user_data);
161
162 /**
163  * @typedef Ewk_Download_Cancelled_Cb Ewk_Download_Cancelled_Cb
164  * @brief Type definition for a function that will be called back when a download job is cancelled.
165  */
166 typedef void (*Ewk_Download_Cancelled_Cb)(Ewk_Download_Job *download, void *user_data);
167
168 /**
169  * @typedef Ewk_Download_Finished_Cb Ewk_Download_Finished_Cb
170  * @brief Type definition for a function that will be called back when a download job is finished.
171  */
172 typedef void (*Ewk_Download_Finished_Cb)(Ewk_Download_Job *download, void *user_data);
173
174 /**
175  * @typedef Ewk_Context_History_Client_Visited_Links_Populate_Cb Ewk_Context_History_Client_Visited_Links_Populate_Cb
176  * @brief Type definition for a function that will be called back when client is asked to provide visited links from a client-managed storage.
177  *
178  * @see ewk_context_visited_link_add
179  */
180 typedef void (*Ewk_History_Populate_Visited_Links_Cb)(void *user_data);
181
182 /**
183  * Callback to receive message from extension.
184  *
185  * @param name name of message from extension
186  * @param body body of message from extendion
187  * @param user_data user_data will be passsed when receiving message from extension
188  *
189  * @see ewk_context_message_from_extensions_callback_set
190  * @see ewk_extension_message_post
191  */
192 typedef void (*Ewk_Context_Message_From_Extension_Cb)(const char *name, const Eina_Value *body, void *user_data);
193
194 /**
195  * Gets default Ewk_Context instance.
196  *
197  * The returned Ewk_Context object @b should not be unref'ed if application
198  * does not call ewk_context_ref() for that.
199  *
200  * @return Ewk_Context object.
201  */
202 EAPI Ewk_Context *ewk_context_default_get(void);
203
204 /**
205  * Creates a new Ewk_Context.
206  *
207  * The returned Ewk_Context object @b should be unref'ed after use.
208  *
209  * @return Ewk_Context object on success or @c NULL on failure
210  *
211  * @see ewk_object_unref
212  * @see ewk_context_new_with_extensions_path
213  */
214 EAPI Ewk_Context *ewk_context_new(void);
215
216 /**
217  * Creates a new Ewk_Context.
218  *
219  * The returned Ewk_Context object @b should be unref'ed after use.
220  *
221  * @param path directory path of extensions
222  *
223  * @return Ewk_Context object on success or @c NULL on failure
224  *
225  * @note All shared objects which have ewk_extension_init() in the given @a path will be loaded.
226  *
227  * @see ewk_object_unref
228  * @see ewk_context_new
229  * @see Ewk_Extension_Initialize_Function
230  */
231 EAPI Ewk_Context *ewk_context_new_with_extensions_path(const char *path);
232
233 /**
234  * Gets the application cache manager instance for this @a context.
235  *
236  * @param context context object to query.
237  *
238  * @return Ewk_Cookie_Manager object instance or @c NULL in case of failure.
239  */
240 EAPI Ewk_Application_Cache_Manager *ewk_context_application_cache_manager_get(const Ewk_Context *context);
241
242 /**
243  * Gets the cookie manager instance for this @a context.
244  *
245  * @param context context object to query.
246  *
247  * @return Ewk_Cookie_Manager object instance or @c NULL in case of failure.
248  */
249 EAPI Ewk_Cookie_Manager *ewk_context_cookie_manager_get(const Ewk_Context *context);
250
251 /**
252  * Gets the database manager instance for this @a context.
253  *
254  * @param context context object to query
255  *
256  * @return Ewk_Database_Manager object instance or @c NULL in case of failure
257  */
258 EAPI Ewk_Database_Manager *ewk_context_database_manager_get(const Ewk_Context *context);
259
260 /**
261  * Sets the favicon database directory for this @a context.
262  *
263  * Sets the directory path to be used to store the favicons database
264  * for @a context on disk. Passing @c NULL as @a directory_path will
265  * result in using the default directory for the platform.
266  *
267  * Calling this method also means enabling the favicons database for
268  * its use from the applications, it is therefore expected to be
269  * called only once. Further calls for the same instance of
270  * @a context will not have any effect.
271  *
272  * @param context context object to update
273  * @param directory_path database directory path to set
274  *
275  * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise
276  */
277 EAPI Eina_Bool ewk_context_favicon_database_directory_set(Ewk_Context *context, const char *directory_path);
278
279 /**
280  * Gets the favicon database instance for this @a context.
281  *
282  * @param context context object to query.
283  *
284  * @return Ewk_Favicon_Database object instance or @c NULL in case of failure.
285  */
286 EAPI Ewk_Favicon_Database *ewk_context_favicon_database_get(const Ewk_Context *context);
287
288 /**
289  * Gets the storage manager instance for this @a context.
290  *
291  * @param context context object to query.
292  *
293  * @return Ewk_Storage_Manager object instance or @c NULL in case of failure.
294  */
295 EAPI Ewk_Storage_Manager *ewk_context_storage_manager_get(const Ewk_Context *context);
296
297 /**
298  * Register @a scheme in @a context.
299  *
300  * When an URL request with @a scheme is made in the #Ewk_Context, the callback
301  * function provided will be called with a #Ewk_Url_Scheme_Request.
302  *
303  * It is possible to handle URL scheme requests asynchronously, by calling ewk_object_ref() on the
304  * #Ewk_Url_Scheme_Request and calling ewk_url_scheme_request_finish() later when the data of
305  * the request is available.
306  *
307  * To replace registered callback with new callback, calls ewk_context_url_scheme_register()
308  * with new callback again.
309  *
310  * @param context a #Ewk_Context object.
311  * @param scheme the network scheme to register
312  * @param callback the function to be called when an URL request with @a scheme is made.
313  * @param user_data data to pass to callback function
314  *
315  * @code
316  * static void custom_url_scheme_request_cb(Ewk_Url_Scheme_Request *request, void *user_data)
317  * {
318  *     const char *scheme;
319  *     char *contents_data = NULL;
320  *     unsigned contents_length = 0;
321  *
322  *     scheme = ewk_url_scheme_request_scheme_get(request);
323  *     if (!strcmp(scheme, "myapp")) {
324  *         // Initialize contents_data with a welcome page, and set its length to contents_length
325  *     } else {
326  *         Eina_Strbuf *buf = eina_strbuf_new();
327  *         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);
328  *         contents_data = eina_strbuf_string_steal(buf);
329  *         contents_length = strlen(contents_data);
330  *         eina_strbuf_free(buf);
331  *     }
332  *     ewk_url_scheme_request_finish(request, contents_data, contents_length, "text/html");
333  *     free(contents_data);
334  * }
335  * @endcode
336  */
337 EAPI Eina_Bool ewk_context_url_scheme_register(Ewk_Context *context, const char *scheme, Ewk_Url_Scheme_Request_Cb callback, void *user_data);
338
339 /**
340  * Sets history callbacks for the given @a context.
341  *
342  * To stop listening for history events, you may call this function with @c
343  * NULL for the callbacks.
344  *
345  * @param context context object to set history callbacks
346  * @param navigate_func The function to call when @c ewk_view did navigation (may be @c NULL).
347  * @param client_redirect_func The function to call when @c ewk_view performed a client redirect (may be @c NULL).
348  * @param server_redirect_func The function to call when @c ewk_view performed a server redirect (may be @c NULL).
349  * @param title_update_func The function to call when history title is updated (may be @c NULL).
350  * @param populate_visited_links_func The function is called when client is asked to provide visited links from a
351  *        client-managed storage (may be @c NULL).
352  * @param data User data (may be @c NULL).
353  */
354 EAPI void ewk_context_history_callbacks_set(Ewk_Context *context,
355                                             Ewk_History_Navigation_Cb navigate_func,
356                                             Ewk_History_Client_Redirection_Cb client_redirect_func,
357                                             Ewk_History_Server_Redirection_Cb server_redirect_func,
358                                             Ewk_History_Title_Update_Cb title_update_func,
359                                             Ewk_History_Populate_Visited_Links_Cb populate_visited_links_func,
360                                             void *data);
361
362 /**
363  * Sets download callbacks for the given @a context.
364  *
365  * To stop listening for download events, you may call this function with @c
366  * NULL for the callbacks.
367  *
368  * @param context context object to set download callbacks
369  * @param download_requested_func the function to call when new download is requested (may be @c NULL).
370  * @param download_failed_func the function to call when a download job has failed (may be @c NULL).
371  * @param download_cancelled_func the function to call when a download job is cancelled (may be @c NULL).
372  * @param download_finished_func the function to call when a download job is finished (may be @c NULL).
373  * @param data User data (may be @c NULL).
374  */
375 EAPI void ewk_context_download_callbacks_set(Ewk_Context *context,
376                                              Ewk_Download_Requested_Cb download_requested_func,
377                                              Ewk_Download_Failed_Cb download_failed_func,
378                                              Ewk_Download_Cancelled_Cb download_cancelled_func,
379                                              Ewk_Download_Finished_Cb download_finished_func,
380                                              void* data);
381
382 /**
383  * Registers the given @a visited_url as visited link in @a context visited link cache.
384  *
385  * This function shall be invoked as a response to @c populateVisitedLinks callback of the history cient.
386  *
387  * @param context context object to add visited link data
388  * @param visited_url visited url
389  *
390  * @see Ewk_Context_History_Client
391  */
392 EAPI void ewk_context_visited_link_add(Ewk_Context *context, const char *visited_url);
393
394 /**
395  * Set @a cache_model as the cache model for @a context.
396  *
397  * By default, it is EWK_CACHE_MODEL_DOCUMENT_VIEWER.
398  *
399  * @param context context object to update.
400  * @param cache_model a #Ewk_Cache_Model.
401  *
402  * @return @c EINA_TRUE on success or @c EINA_FALSE on failure
403  */
404 EAPI Eina_Bool ewk_context_cache_model_set(Ewk_Context *context, Ewk_Cache_Model cache_model);
405
406 /**
407  * Gets the cache model for @a context.
408  *
409  * @param context context object to query.
410  *
411  * @return the cache model for the @a context.
412  */
413 EAPI Ewk_Cache_Model ewk_context_cache_model_get(const Ewk_Context *context);
414
415 /**
416  * Sets additional plugin path for @a context.
417  *
418  * @param context context object to set additional plugin path
419  * @param path the path to be used for plugins
420  *
421  * @return @c EINA_TRUE on success or @c EINA_FALSE on failure
422  */
423 EAPI Eina_Bool ewk_context_additional_plugin_path_set(Ewk_Context *context, const char *path);
424
425 /**
426  * Clears HTTP caches in local storage and all resources cached in memory 
427  * such as images, CSS, JavaScript, XSL, and fonts for @a context.
428  *
429  * @param context context object to clear all resource caches
430  */
431 EAPI void ewk_context_resource_cache_clear(Ewk_Context *context);
432
433 /**
434  * Posts message to extensions asynchronously.
435  *
436  * @note body only supports @c EINA_VALUE_TYPE_STRINGSHARE or @c EINA_VALUE_TYPE_STRING,
437  * now.
438  *
439  * @param context context object to post message to extensions
440  * @param name message name
441  * @param body message body
442  *
443  * @return @c EINA_TRUE on success of @c EINA_FALSE on failure or when the type
444  * of @p body is not supported.
445  */
446 EAPI Eina_Bool ewk_context_message_post_to_extensions(Ewk_Context *context, const char *name, const Eina_Value *body);
447
448 /**
449  * Sets callback for received extension message.
450  *
451  * Client can pass @c NULL for callback to stop listening for messages.
452  *
453  * @param context context object
454  * @param callback callback for received injected bundle message or @c NULL
455  * @param user_data user data
456  */
457 EAPI void ewk_context_message_from_extensions_callback_set(Ewk_Context *context, Ewk_Context_Message_From_Extension_Cb callback, void *user_data);
458
459 /**
460  * Sets a process model for @a context.
461  *
462  * Sets a process model for web views, which will be used to decide how
463  * processes should be handled. Default value is
464  * EWK_PROCESS_MODEL_SHARED_SECONDARY which means that there is only one
465  * web process. When EWK_PROCESS_MODEL_MULTIPLE_SECONDARY is set a
466  * network process is introduced and every web view starts new web process.
467  * This function should be used before first web process is spawned.
468  *
469  * @param context context object to set process model
470  * @param process_model a #Ewk_Process_Model
471  */
472 EAPI Eina_Bool ewk_context_process_model_set(Ewk_Context *context, Ewk_Process_Model process_model);
473
474 /**
475  * Gets the process model for @a context.
476  *
477  * @param context context object to query
478  *
479  * @return the process model for the @a context
480  */
481 EAPI Ewk_Process_Model ewk_context_process_model_get(const Ewk_Context *context);
482
483 /**
484  * Gets TLS error policy for @a context.
485  *
486  * @param context context object to get TLS error policy
487  *
488  * @return The TLS errors policy for the context
489  */
490 EAPI Ewk_TLS_Error_Policy ewk_context_tls_error_policy_get(const Ewk_Context *context);
491
492 /**
493  * Sets TLS error policy for @a context.
494  *
495  * Sets how TLS certificate errors should be handled. The available policies are listed in #Ewk_TLS_Error_Policy enumeration.
496  *
497  * @param context context object to set TLS error policy
498  * @param tls_error_policy a #Ewk_TLS_Error_Policy
499  */
500 EAPI void ewk_context_tls_error_policy_set(Ewk_Context *context, Ewk_TLS_Error_Policy tls_error_policy);
501
502 /**
503  * Sets the list of preferred languages.
504  *
505  * Sets the list of preferred langages. This list will be used to build the "Accept-Language"
506  * header that will be included in the network requests.
507  * Client can pass @c NULL for languages to clear what is set before.
508  *
509  * @param languages the list of preferred languages (char* as data) or @c NULL
510  *
511  * @note all contexts will be affected.
512  */
513 EAPI void ewk_context_preferred_languages_set(Eina_List *languages);
514
515
516 /**
517  * Allows accepting the specified TLS certificate for the speficied host.
518  *
519  * @param context context object to allow accepting a specific certificate for a specific host
520  * @param pem the certificate to be accepted in PEM format
521  * @param host the host for which the certificate is to be accepted
522  */
523 EAPI void ewk_context_tls_certificate_for_host_allow(Ewk_Context *context, const char *pem, const char *host);
524
525 #ifdef __cplusplus
526 }
527 #endif
528
529 #endif // ewk_context_h