/* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is the EAL package. * * The Initial Developer of the Original Code is Nokia Corporation. * Portions created by the Initial Developer are Copyright (C) 2005 * the Initial Developer. All Rights Reserved. * * Contact: Leonid Zolotarev * * ***** END LICENSE BLOCK ***** */ #ifndef __NETEAL_H #define __NETEAL_H #include #include G_BEGIN_DECLS /** @mainpage NETEAL - an EAL library which manipulates Browser Engines on a remote server. * * @section intro_sec Introduction * * @par * * NETEAL pushes EAL (Engine Abstraction Layer) idea a bit further by allowing * manipulation of a Browser Engine created in a separate server process in its own address * space. The primary goal of this approach is to allow decoupling of UI (EAL client) code * from Browser Engine code not only logically but also functionally. This, in turn, * allows creation of more robust and reliable ultra-low-weight UI applications which * merely act as a tiny shell to heavy Browser Engines. * * @par * * This particular version of NETEAL library uses dbus-glib bindings to talk to * corresponding server. * * @section diff_sec Differences between EAL and NETEAL * * From point of view, the biggest difference is that applications using NETEAL do not need to link to both the EAL library * and the implementation library (for ex. microb-eal). As result, web_set_env() is removed entirely and g_web_new() * is replaced with g_web_new_neteal() * * In additional, there are certain differences in functions provided. Ideally, NETEAL tries to implement as many functions * as EAL does, but on top of that, NETEAL also: * -# provides a set of special neteal_* helper functions which allow connecting/disconnecting * from different servers, creating and killing web engines, etc. * -# provides *_net counterpart to every regular EAL function. These *_net functions have exactly the same * signature, except first argument is a server connection id, normally obtained with * neteal_server_connect(). * -# does not implement g_web_engine_get_engine_widget() function but instead provides a replacement function g_web_engine_embed_engine_widget(), * and g_web_engine_embed_engine_widget_xid() * * @par * * Note: Since NETEAL library operates over the network, it does not work with real GWeb* and GWebEngine*. Instead, corresponding functions * take and give generic GObjects which do not implement any interfaces. Do not try to dereference these pointers. * * @section usage_sec Using NETEAL * * -# initialize library with neteal_init() * -# use neteal_servers_list() to list if there are EAL servers already created * -# if there aren't any, create your own with neteal_server_create_fork() * -# connect to a server with neteal_server_connect() * -# call neteal_set_current() and continue with normal EAL functions * -# (optional) see if there are any Web objects already created with neteal_list_webs(), and use one if you decide to * * @par * The following illustrates the algorithm outlined above: * @code * GArray *g; * guint32 server; * guint32 connection; * * neteal_init(); * * g = neteal_servers_list(); * * if (!g->len) * { * ULOG_DEBUG_F("no servers around, creating our own"); * server = neteal_server_create_fork("myserver"); * } * else * { * server = g_array_index(g, guint32, 0); * ULOG_DEBUG_F("there are %d servers, using first [%d]", g->len, server); * } * * g_array_free(g, TRUE); * * ULOG_DEBUG_F("using server %d", server); * * connection = neteal_server_connect(server); * * neteal_set_current(connection); * @endcode * * @section usage_errors Error Handling * NETEAL distinguishes three kind of errors: * -# Errors occuring during neteal_* family functions execution * -# Errors occuring during standard EAL functions execution * -# Internal Browser Engine's errors * @par * These errors are handled differently. Failing neteal_* functions typically * return 0 or NULL, and have error parameter set, which normally should be investigated. * Ordinary failing EAL functions call user provided handler, which is installed * connection-wide by neteal_set_eal_errorhandler(). Internal Browser Engine's errors * are not handled in any specific fashion. * * @section add_notes Additional Notes * * The library is not thread-safe. Just do not try it. If you want asynchronus functions * calls, implement your own in form of extensions. */ /** NETEALCallNotify * The callback type, * handle - the actual related object * user_data - original user data supplied * @note IMPORTANT, don't make any neteal calls in callback handler, relay it to next main loop iteration */ typedef void (* NETEALCallNotify) (GObject *handle, void *user_data); /** NETEALCallNotifyRet * The callback type, * handle - the actual related object * user_data - original user data supplied * ret_val - function specific return value which is owned internally by the caller. Do not assume the pointer to be valid after the callback has finished. * @note IMPORTANT, don't make any neteal calls in callback handler, relay it to next main loop iteration */ typedef void (* NETEALCallNotifyRet) (GObject *handle, void *user_data, void *ret_val); /** NETEALErrorHandlerEAL * The callback type, * handle - handle of the entity involved * user_data - original user data supplied */ typedef void (* NETEALErrorHandlerEAL) (const gchar *function_name, GError *error, gpointer user_data); /** NETEALConnectionErrorHandler * The callback type for network connection problems * handle - handle of the entity involved * is_expected - tells if connection termination was expected (e.g server shutdown) * user_data - supplied user_data */ typedef void (* NETEALConnectionErrorHandler) (guint32 connectionid, gboolean is_expected, gpointer user_data); /** Initialize the neteal library. * @return nothing * @note This function must be called first. It does not really do * anything useful and is here to prevent misuses. Should only be * called once. */ void neteal_init(); /** Polls for Discovery server avaliability. * @return If server NOT found or timeout expired then FALSE, otherwise TRUE * @param freq - Frequency in milliseconds of DBUS connection check * @param timeout - Searching timeout in seconds. * note it is a good idea to call this function to make sure discovery server * is up and running before you call neteal_servers_list(); */ gboolean neteal_glookup_discovery_server(guint32 freq, guint32 timeout); /** Get list of EAL servers currently running. * @return GArray list of server ids, NULL on failure * @note This function makes a connection to DISCOVERY server, * asks for the list of EAL servers currently created, then disconnects. * Use it to locate EAL servers you can use. */ GArray *neteal_servers_list(); /** Create an EAL server * @return id of the new server, 0 on failure * @note This function creates an EAL server by "fork" mechanism. */ guint32 neteal_server_create_fork(gchar *name); /** Connects to a EAL server * @return connid - handle of server connection, 0 on failure * @param server_id - ID of the EAL server to connect * @note Use returned serverid for all the *_net functions counterparts of * ordinary browser-eal functions. * @seealso neteal_set_current() */ guint32 neteal_server_connect(guint32 server_id); /** Makes specified server connection "current". * @return nothing * @param connid handle of server connection * @note This function sets current EAL server connection as "current". * This causes ordinary browser-eal functions to operate over it, so * using of *_net() functions is no longer requiered. */ void neteal_set_current(guint32 connid); /** Gets current connection id, previously set by neteal_set_current() * @return connection id * @param nothing * @note */ guint32 neteal_get_current(); /** Disconnects the connection and frees all allocated resources * @param connid - server connection id * @return nothing * @note After the connection is destroyed, "current" connection also * becomes invalid, so it is generally a bad idea to continnue using * regular EAL functions without re-establishing a new one. */ void neteal_server_conn_destroy (guint32 connid); /** Lists ids of web objects created on the server * @return GArray of guint - current web objects, NULL on failure * @note */ GArray *neteal_list_webs(); GArray *neteal_list_webs_with_timeout(int timeout); /** Cancels a pending asynchronous request * @param id Identifier returned by asynchronous call * @return TRUE if the call was canceled, or FALSE if no such call was found. */ gboolean neteal_cancel_async(guint call_id); /** Creates an Web object on the remote server * @param name - name of the engine * @return id of the new Web object * @note */ GWeb* g_web_new_neteal(gchar *name); /** Creates an Web object on the remote server, async version * @param name - name of the engine * @param callback - executed on request completion * @param user_data - user data passed to the callback * @return id of the new Web object * @note */ void g_web_new_neteal_async(gchar *name, NETEALCallNotify notify, gpointer user_data); /** Embeds provided GtkSocket's xid into servers GtkPlug, containging engine widget * @param xid - id of GtkSocket normally obtained with gtk_socket_get_id () * @return id of the widget on the server, 0 on failure * @note as of the time of writing, there is an issue, possible in gtk+ preventing * using it properly. Using this function is disencouraged. Consider using * g_web_engine_embed_engine_widget_xid() instead. */ guint32 g_web_engine_embed_engine_widget(GWebEngine *handle, guint32 xid); /** Asks server for xid of its GtkPlug containing engine widget and parent's window xid * @param xid - id of GtkPlug created on the server * @param xid of parent window * @param transparency * @return id of the widget on the server, 0 on failure * @note */ guint32 g_web_engine_embed_engine_widget_xid(GWebEngine *handle, gboolean transparency, guint32 parentxid, guint32 *xid); /** Return error occured during neteal_* function call * @return GError * @note */ GError *neteal_get_last_error(); /** Sets handler for errors occuring during EAL functions execution * @param connection - connection * @param errorhandler - user-provided function * @param user_data user provided data * @return nothing * @note It generally makes sense to write your own errorhandler, because library-provided * handler does nothing but just prints out the error. */ void neteal_set_eal_errorhandler(guint32 connection, NETEALErrorHandlerEAL errorhandler, gpointer user_data); /** Sets error handler for the connection id * @param connection - connection * @param errorhandler - user-provided function * @param user_data - user provided data * @return nothing * @note This handler is invoked if connection to the server breaks. You do not need to call * neteal_server_conn_destroy(). If connection is zero, current connection is used. If both provided * and current connection are zero, function does nothing. */ void neteal_set_connection_errorhandler(guint32 connection, NETEALConnectionErrorHandler errorhandler, gpointer user_data); /** Tells server to initiate shutdown. * @param connection - connection * @return nothing * @note When function returns, the server is not guaranteed to be fully shutdown. Invokation of this function causes * complete destruction of all web and webengine objects associated to it. * When the server has fully terminated, connection error is invoked with is_expected value set to TRUE */ void neteal_connection_terminate(guint32 connection); /** Sets enviroument variable for the server process * @param name - variable name * @param value - variable value * @param overwrite indicades if the variable should be rewritten if its already set * @return setenv()'s return value * @note see setenv (3) manual page for more information * @note IMPORTANT, it works only if neteal connection is available, after neteal_server_connect * @note IMPORTANT, it use neteal_get_current connection, neteal_set_current must be setted up before */ gint neteal_set_env(gchar *name, gchar *value, gboolean overwrite); /** Gets EAL library this web has been created with * @return string with the engine name */ gchar* g_web_getname(GWeb *self); /** Async addition for g_web_engine_load_url * @param notify - executed on request completion * @param user_data - user data passed to the callback * @return nothing */ void g_web_engine_load_url_async(GWebEngine *self, const gchar *url, NETEALCallNotify notify, gpointer user_data); /** Async addition for g_web_engine_evaluate_js * @param notify - executed on request completion * @param user_data - user data passed to the callback * @return nothing */ void g_web_engine_evaluate_js_async(GWebEngine *self, const gchar *js, NETEALCallNotify notify, gpointer user_data); /** Async addition for g_web_engine_realize_window * @param notify - executed on request completion * @param user_data - user data passed to the callback * @return nothing */ void g_web_engine_realize_window_async(GWebEngine *self, NETEALCallNotify notify, gpointer user_data); /** Async addition for g_web_new_web_engine_window_with_context * @param notify - executed on request completion, first param of notify is user_data, second is pointer to GWebEngine * @param user_data - user data passed to the callback * @return 0 if success, -1 otherwise */ gint g_web_new_web_engine_window_with_context_async(GWeb* gweb, gpointer context, gboolean leave_tracks, gboolean without_history, NETEALCallNotify notify, gpointer user_data); /** Async addition for g_web_engine_embed_engine_widget_xid * @param notify - executed on request completion, first param of notify is user_data, second is pointer * to array of two elements of guint32: first is xid, second is widget, this values must be copied * @param user_data - user data passed to the callback * @return 0 if success, -1 otherwise */ gint g_web_engine_embed_engine_widget_xid_async(GWebEngine *self, gboolean transparency, guint32 parentxid, NETEALCallNotify notify, gpointer user_data); /** Async addition for neteal_server_create_fork * @param notify - executed on request completion, first param of notify is user_data, second is pid (guint32) * @param user_data - user data passed to the callback * @return 0 if success, -1 otherwise */ gint neteal_server_create_fork_async(gchar *name, NETEALCallNotify notify, gpointer user_data); /** Async addition for neteal_list_webs * @param notify - executed on request completion, first param of notify is user_data, second is GArray of guint - current web objects, NULL on failure * @param user_data - user data passed to the callback * @return 0 if success, -1 otherwise */ gint neteal_list_webs_async(NETEALCallNotify notify, gpointer user_data); /** Async addition for g_web_get_global * @param notify - executed on request completion, first param of notify is pointer to notifier object, second is user_data * @param user_data - user data passed to the callback * @return 0 if success, -1 otherwise */ guint32 g_web_get_global_async(GWeb* self, NETEALCallNotify notify, gpointer user_data); /** Async addition for g_web_engine_get_engine_notifier * @param notify - executed on request completion, first param of notify is pointer to notifier object, second is user_data * @param user_data - user data passed to the callback * @return 0 if success, -1 otherwise */ guint32 g_web_engine_get_engine_notifier_async(GWebEngine *self, NETEALCallNotify notify, gpointer user_data); /** Async addition for g_web_transfer_item_get_web_item * @param notify - executed on request completion, first param of notify is pointer to notifier object, second is user_data * @param user_data - user data passed to the callback * @return 0 if success, -1 otherwise */ guint32 g_web_transfer_item_get_web_item_async(GWebTransferItem *self, NETEALCallNotify notify, gpointer user_data); /** Creates web buses on engine side with specific names @param ui_to_eal_name - name of bus that sends messages from ui side to engine @param eal_to_ui_name - name of bus that sends messages from engine side to ui */ void g_web_create_web_buses(GWeb* self, const char* ui_to_eal_name, const char* eal_to_ui_name); /** Async version of g_web_suspend Note: Return value of the call is given to notify callback but owned internally. Return value type is gint32. @param self - GWeb instance @param notify - User callback executed on completion. See NETEALCallNotifyRet for details @param user_data - User data passed to the callback */ void g_web_suspend_async(GWeb *self, NETEALCallNotifyRet notify, gpointer user_data); /** Async addition for g_web_engine_stop_load * @param notify - executed on request completion * @param user_data - user data passed to the callback */ void g_web_engine_stop_load_async(GWebEngine *self, NETEALCallNotify notify, gpointer user_data); /** Async version of g_web_engine_go_back. After call has completed * function given in notify is called with given user_data in parameters. * @param self GWebEngine * @param steps number of steps to go forward * @param notify callback function of type NETEALCallNotify * @param user_data data passed to function given in notify */ void g_web_engine_go_back_async(GWebEngine *self, guint nsteps, NETEALCallNotify notify, gpointer user_data); /** Async version of g_web_engine_go_forward. After call has completed * function given in notify is called with given user_data in parameters. * @param self GWebEngine * @param steps number of steps to go forward * @param notify callback function of type NETEALCallNotify * @param user_data data passed to function given in notify */ void g_web_engine_go_forward_async(GWebEngine *self, guint nsteps, NETEALCallNotify notify, gpointer user_data); /** * Starts an asynchronous query for page unload permission * @param self GWebEngine * @param notify callback function of type NETEALCallNotify2 * @param user_data Result of the unload permission query, will be given as * the user_data parameter for notify function * @return Identifier for the asynchronous call, nonzero if request was sceduled successfully */ guint g_web_engine_permit_page_unload_async(GWebEngine *self, NETEALCallNotifyRet notify, gpointer user_data); G_END_DECLS #endif