awesomium-raw-0.1.0.0: include/awesomium_capi.h
/**
* @file awesomium_capi.h
*
* The main header for the Awesomium C API.
*
* @author
*
* This file is a part of Awesomium, a library that makes it easy for
* developers to embed the web in their applications.
*
* Website: <http://www.awesomium.com>
*
* Copyright (C) 2011 Khrona. All rights reserved. Awesomium is a
* trademark of Khrona.
*/
#ifndef __AWESOMIUM_CAPI_H__
#define __AWESOMIUM_CAPI_H__
#include <Awesomium/PlatformUtils.h>
#include <stdlib.h>
#ifdef _WIN32
#include <windows.h>
#endif
#ifdef __cplusplus
extern "C" {
#endif
#ifdef _WIN32
typedef wchar_t wchar16;
#else
typedef unsigned short wchar16;
#endif
#if __LP64__
typedef long int64;
#else
typedef long long int64;
#endif
/// WebView instance
typedef struct _awe_webview awe_webview;
/// JSValue instance
typedef struct _awe_jsvalue awe_jsvalue;
/// JSArray instance
typedef struct _awe_jsarray awe_jsarray;
/// JSObject instance
typedef struct _awe_jsobject awe_jsobject;
/// RenderBuffer instance, owned by the WebView
typedef struct _awe_renderbuffer awe_renderbuffer;
/// HeaderDefinition instance
typedef struct _awe_header_definition awe_header_definition;
/// ResourceResponse instance
typedef struct _awe_resource_response awe_resource_response;
/// ResourceRequest instance
typedef struct _awe_resource_request awe_resource_request;
/// UploadElement instance
typedef struct _awe_upload_element awe_upload_element;
/// String instance
typedef struct _awe_string awe_string;
/// HistoryQueryResult instance
typedef struct _awe_history_query_result awe_history_query_result;
/// HistoryEntry instance
typedef struct _awe_history_entry awe_history_entry;
typedef enum _awe_loglevel
{
AWE_LL_NONE,
AWE_LL_NORMAL,
AWE_LL_VERBOSE
} awe_loglevel;
typedef enum _awe_mousebutton
{
AWE_MB_LEFT,
AWE_MB_MIDDLE,
AWE_MB_RIGHT
} awe_mousebutton;
typedef enum _awe_url_filtering_mode
{
AWE_UFM_NONE,
AWE_UFM_BLACKLIST,
AWE_UFM_WHITELIST
} awe_url_filtering_mode;
typedef enum _awe_webkey_type
{
AWE_WKT_KEYDOWN,
AWE_WKT_KEYUP,
AWE_WKT_CHAR
} awe_webkey_type;
typedef enum _awe_webkey_modifiers
{
/// Whether or not a Shift key is down
AWE_WKM_SHIFT_KEY = 1 << 0,
/// Whether or not a Control key is down
AWE_WKM_CONTROL_KEY = 1 << 1,
/// Whether or not an ALT key is down
AWE_WKM_ALT_KEY = 1 << 2,
/// Whether or not a meta key (Command-key on Mac, Windows-key on Windows) is down
AWE_WKM_META_KEY = 1 << 3,
/// Whether or not the key pressed is on the keypad
AWE_WKM_IS_KEYPAD = 1 << 4,
/// Whether or not the character input is the result of an auto-repeat timer.
AWE_WKM_IS_AUTOREPEAT = 1 << 5,
} awe_webkey_modifiers;
typedef enum _awe_cursor_type
{
AWE_CUR_POINTER,
AWE_CUR_CROSS,
AWE_CUR_HAND,
AWE_CUR_IBEAM,
AWE_CUR_WAIT,
AWE_CUR_HELP,
AWE_CUR_EAST_RESIZE,
AWE_CUR_NORTH_RESIZE,
AWE_CUR_NORTHEAST_RESIZE,
AWE_CUR_NORTHWEST_RESIZE,
AWE_CUR_SOUTH_RESIZE,
AWE_CUR_SOUTHEAST_RESIZE,
AWE_CUR_SOUTHWEST_RESIZE,
AWE_CUR_WEST_RESIZE,
AWE_CUR_NORTHSOUTH_RESIZE,
AWE_CUR_EASTWEST_RESIZE,
AWE_CUR_NORTHEAST_SOUTHWEST_RESIZE,
AWE_CUR_NORTHWEST_SOUTHEAST_RESIZE,
AWE_CUR_COLUMN_RESIZE,
AWE_CUR_ROW_RESIZE,
AWE_CUR_MIDDLE_PANNING,
AWE_CUR_EAST_PANNING,
AWE_CUR_NORTH_PANNING,
AWE_CUR_NORTHEAST_PANNING,
AWE_CUR_NORTHWEST_PANNING,
AWE_CUR_SOUTH_PANNING,
AWE_CUR_SOUTHEAST_PANNING,
AWE_CUR_SOUTHWEST_PANNING,
AWE_CUR_WEST_PANNING,
AWE_CUR_MOVE,
AWE_CUR_VERTICAL_TEXT,
AWE_CUR_CELL,
AWE_CUR_CONTEXT_MENU,
AWE_CUR_ALIAS,
AWE_CUR_PROGRESS,
AWE_CUR_NO_DROP,
AWE_CUR_COPY,
AWE_CUR_NONE,
AWE_CUR_NOT_ALLOWED,
AWE_CUR_ZOOM_IN,
AWE_CUR_ZOOM_OUT,
AWE_CUR_CUSTOM
} awe_cursor_type;
typedef enum _awe_ime_state
{
AWE_IME_DISABLE = 0,
AWE_IME_MOVE_WINDOW = 1,
AWE_IME_COMPLETE_COMPOSITION = 2
} awe_ime_state;
typedef enum _awe_media_type
{
AWE_MEDIA_TYPE_NONE,
AWE_MEDIA_TYPE_IMAGE,
AWE_MEDIA_TYPE_VIDEO,
AWE_MEDIA_TYPE_AUDIO
} awe_media_type;
typedef enum _awe_media_state
{
AWE_MEDIA_STATE_NONE = 0x0,
AWE_MEDIA_STATE_ERROR = 0x1,
AWE_MEDIA_STATE_PAUSED = 0x2,
AWE_MEDIA_STATE_MUTED = 0x4,
AWE_MEDIA_STATE_LOOP = 0x8,
AWE_MEDIA_STATE_CAN_SAVE = 0x10,
AWE_MEDIA_STATE_HAS_AUDIO = 0x20
};
enum _awe_can_edit_flags
{
AWE_CAN_EDIT_NOTHING = 0x0,
AWE_CAN_UNDO = 0x1,
AWE_CAN_REDO = 0x2,
AWE_CAN_CUT = 0x4,
AWE_CAN_COPY = 0x8,
AWE_CAN_PASTE = 0x10,
AWE_CAN_DELETE = 0x20,
AWE_CAN_SELECT_ALL = 0x40
};
enum _awe_dialog_flags
{
AWE_DIALOG_HAS_OK_BUTTON = 0x1,
AWE_DIALOG_HAS_CANCEL_BUTTON = 0x2,
AWE_DIALOG_HAS_PROMPT_FIELD = 0x4,
AWE_DIALOG_HAS_MESSAGE = 0x8
};
typedef struct _awe_webkeyboardevent
{
awe_webkey_type type;
int modifiers;
int virtual_key_code;
int native_key_code;
wchar16 text[4];
wchar16 unmodified_text[4];
bool is_system_key;
} awe_webkeyboardevent;
typedef struct _awe_rect
{
int x, y, width, height;
} awe_rect;
#ifdef _WIN32
_OSMExport bool awe_is_child_process(HINSTANCE hInstance);
_OSMExport int awe_child_process_main(HINSTANCE hInstance);
#else
_OSMExport bool awe_is_child_process(int argc, char** argv);
_OSMExport int awe_child_process_main(int argc, char** argv);
#endif
/*****************************
* UTF-16 String Definitions *
*****************************/
/**
* Get an instance of an empty string. This is a convenience method to
* quickly pass an empty string to the C API-- you should not destroy
* this string yourself.
*/
_OSMExport const awe_string* awe_string_empty();
/**
* Create a string from an ASCII string. You must call awe_string_destroy
* with the returned instance once you're done using it.
*
* @param str An ASCII string to be copied from.
*
* @param len The length of the string
*/
_OSMExport awe_string* awe_string_create_from_ascii(const char* str,
size_t len);
/**
* Create a string from a Wide string. You must call awe_string_destroy
* with the returned instance once you're done using it.
*
* @param str A Wide string to be copied from.
*
* @param len The length of the string
*/
_OSMExport awe_string* awe_string_create_from_wide(const wchar_t* str,
size_t len);
/**
* Create a string from a UTF-8 string. You must call awe_string_destroy
* with the returned instance once you're done using it.
*
* @param str A UTF-8 string to be copied from.
*
* @param len The length of the string.
*/
_OSMExport awe_string* awe_string_create_from_utf8(const char* str,
size_t len);
/**
* Create a string from a UTF-16 string. You must call awe_string_destroy
* with the returned instance once you're done using it.
*
* @param str A UTF-16 string to be copied from.
*
* @param len The length of the string.
*/
_OSMExport awe_string* awe_string_create_from_utf16(const wchar16* str,
size_t len);
/**
* Destroys a string instance created with one of the above functions.
*
* @param str The instance to destroy.
*/
_OSMExport void awe_string_destroy(awe_string* str);
/**
* Gets the length of a string.
*
* @param str The string to get the length of.
*
* @return The length of the string.
*/
_OSMExport size_t awe_string_get_length(const awe_string* str);
/**
* Get a pointer to the actual internal UTF-16 bytes of a string.
*
* @param str The string to get the UTF-16 bytes of.
*
* @return A constant pointer to the UTF-16 buffer of the string.
*/
_OSMExport const wchar16* awe_string_get_utf16(const awe_string* str);
/**
* Converts a string to a wide string by copying to the destination buffer.
*
* @param str The source string instance
*
* @param dest The destination buffer to copy to.
*
* @param len The size of the destination buffer.
*
* @return Returns the full size of the string-- you can use this for
* pre-allocation purposes: call this method once with a NULL
* destination and 0 length to get the size to allocate your
* destination buffer, and then call it again to actually
* convert the string.
*/
_OSMExport int awe_string_to_wide(const awe_string* str,
wchar_t* dest,
size_t len);
/**
* Converts a string to a UTF-8 string by copying to the destination buffer.
*
* @param str The source string instance
*
* @param dest The destination buffer to copy to.
*
* @param len The size of the destination buffer.
*
* @return Returns the full size of the string-- you can use this for
* pre-allocation purposes: call this method once with a NULL
* destination and 0 length to get the size to allocate your
* destination buffer, and then call it again to actually
* convert the string.
*/
_OSMExport int awe_string_to_utf8(const awe_string* str,
char* dest,
size_t len);
/***********************
* Web Core Functions *
***********************/
/**
* Instantiates the WebCore singleton with a set of configuration
* parameters.
*
* Here are recommendations for the default parameters:
* <pre>
* enable_plugins = false
* enable_javascript = true
* enable_databases = false
* package_path = awe_string_empty()
* locale_path = awe_string_empty()
* user_data_path = awe_string_empty()
* plugin_path = awe_string_empty()
* log_path = awe_string_empty()
* log_level = AWE_LL_NORMAL
* forceSingleProcess = false
* childProcessPath = (empty)
* enable_auto_detect_encoding = true
* accept_language_override = awe_string_empty()
* default_charset_override = awe_string_empty()
* user_agent_override = awe_string_empty()
* proxy_server = awe_string_empty()
* proxy_config_script = awe_string_empty()
* save_cache_and_cookies = true
* max_cache_size = 0
* disable_same_origin_policy = false
* disable_win_message_pump = false
* custom_css = awe_string_empty()
* </pre>
*/
_OSMExport void awe_webcore_initialize(bool enable_plugins,
bool enable_javascript,
bool enable_databases,
const awe_string* package_path,
const awe_string* locale_path,
const awe_string* user_data_path,
const awe_string* plugin_path,
const awe_string* log_path,
awe_loglevel log_level,
bool force_single_process,
const awe_string* child_process_path,
bool enable_auto_detect_encoding,
const awe_string* accept_language_override,
const awe_string* default_charset_override,
const awe_string* user_agent_override,
const awe_string* proxy_server,
const awe_string* proxy_config_script,
const awe_string* auth_server_whitelist,
bool save_cache_and_cookies,
int max_cache_size,
bool disable_same_origin_policy,
bool disable_win_message_pump,
const awe_string* custom_css);
/**
* Instantiates the WebCore singleton with the default parameters
* specified in the method above.
*/
_OSMExport void awe_webcore_initialize_default();
/**
* Destroys the WebCore singleton and destroys any remaining WebViews.
*/
_OSMExport void awe_webcore_shutdown();
/**
* Sets the base directory.
*
* @param base_dir_path The absolute path to your base directory.
* The base directory is a location that holds
* all of your local assets. It will be used
* for WebView::loadFile and WebView::loadHTML
* (to resolve relative URLs).
*/
_OSMExport void awe_webcore_set_base_directory(const awe_string* base_dir_path);
/**
* Creates a new WebView.
*
* @param width The width of the WebView in pixels.
* @param height The height of the WebView in pixels.
* @param viewSource Enable this to view the HTML source of any web-page
* loaded into this WebView. Default is false.
*
* @return Returns a pointer to the created WebView instance. To call methods
* on the WebView, see awe_webview_load_url() and related functions.
*/
_OSMExport awe_webview* awe_webcore_create_webview(int width, int height,
bool view_source);
/**
* Sets a custom response page to use when a WebView encounters a
* certain HTML status code from the server (like '404 - File not found').
*
* @param status_code The status code this response page should be
* associated with.
* See <http://en.wikipedia.org/wiki/List_of_HTTP_status_codes>
*
* @param file_path The local page to load as a response, should be
* a path relative to the base directory.
*/
_OSMExport void awe_webcore_set_custom_response_page(int status_code,
const awe_string* file_path);
/**
* Updates the WebCore and allows it to conduct various operations such
* as updating the render buffer of each WebView, destroying any
* WebViews that are queued for destruction, and invoking any queued
* callback events.
*/
_OSMExport void awe_webcore_update();
/**
* Retrieves the base directory.
*
* @return Returns a string instance representing the current
* base directory. (You do not need to destroy this instance)
*/
_OSMExport const awe_string* awe_webcore_get_base_directory();
/**
* Returns whether or not plugins are enabled.
*/
_OSMExport bool awe_webcore_are_plugins_enabled();
/**
* Clear the disk cache and media cache.
*/
_OSMExport void awe_webcore_clear_cache();
/**
* Clear all cookies.
*/
_OSMExport void awe_webcore_clear_cookies();
/**
* Sets a cookie for a certain URL.
*
* @param url The URL to set the cookie on.
*
* @param cookie_string The cookie string, for example:
* <pre> "key1=value1; key2=value2" </pre>
*
* @param is_http_only Whether or not this cookie is HTTP-only.
*
* @param force_session_cookie Whether or not to force this as a
* session cookie.
*
*/
_OSMExport void awe_webcore_set_cookie(const awe_string* url,
const awe_string* cookie_string,
bool is_http_only,
bool force_session_cookie);
/**
* Gets all cookies for a certain URL.
*
* @param url The URL whose cookies will be retrieved.
*
* @param exclude_http_only Whether or not to exclude HTTP-only
* cookies from the result.
*
* @return Returns the cookie string. (You do not need to destroy this string)
*/
_OSMExport const awe_string* awe_webcore_get_cookies(const awe_string* url,
bool exclude_http_only);
/**
* Deletes a certain cookie on a certain URL.
*
* @param url The URL that we will be deleting cookies on.
*
* @param cookie_name The name of the cookie that will be deleted.
*/
_OSMExport void awe_webcore_delete_cookie(const awe_string* url,
const awe_string* cookie_name);
/**
* Set whether or not the printer dialog should be suppressed or not.
* Set this to "true" to hide printer dialogs and print immediately
* using the OS's default printer when WebView::print is called.
* Default is "false" if you never call this.
*
* @param suppress Whether or not the printer dialog should be
* suppressed.
*/
_OSMExport void awe_webcore_set_suppress_printer_dialog(bool suppress);
/**
* Query the on-disk history database.
*
* @param full_text_query All results returned should match the
* specified text (either in the page title or
* in the actual text of the page itself).
* Specify an empty string to match anything.
*
* @param num_days_ago Limit results to a specified number of days ago.
*
* @param max_count Limit results to a maximum count. Specify 0 to
* use no limit.
*
* @note You must enable "SaveCacheAndCookies" (see awe_webcore_initialize) for
* this method to work (otherwise no results will be returned).
*
* @return Returns an instance of awe_history_query_result containing the results
* of the query. You must call awe_history_query_result_destroy once
* you are finished using the instance.
*/
_OSMExport awe_history_query_result* awe_webcore_query_history(const awe_string* full_text_query,
int num_days_ago, int max_count);
/***********************
* Web View Functions *
***********************/
/**
* Queue a WebView for destruction by the WebCore.
*
* @param webview The WebView instance.
*
*/
_OSMExport void awe_webview_destroy(awe_webview* webview);
/**
* Loads a URL into the WebView asynchronously.
*
* @param webview The WebView instance.
*
* @param url The URL to load.
*
* @param frame_name The name of the frame to load the URL
* in; leave this blank to load in the main frame.
*
* @param username If the URL requires authentication, the username
* to authorize as, otherwise just pass an empty string.
*
* @param password If the URL requires authentication, the password
* to use, otherwise just pass an empty string.
*/
_OSMExport void awe_webview_load_url(awe_webview* webview,
const awe_string* url,
const awe_string* frame_name,
const awe_string* username,
const awe_string* password);
/**
* Loads a string of HTML into the WebView asynchronously.
*
* @param webview The WebView instance.
*
* @param html The HTML string (ASCII) to load.
*
* @param frame_name The name of the frame to load the HTML
* in; leave this blank to load in the main frame.
*/
_OSMExport void awe_webview_load_html(awe_webview* webview,
const awe_string* html,
const awe_string* frame_name);
/**
* Loads a local file into the WebView asynchronously.
*
* @param webview The WebView instance.
*
* @param file The file to load.
*
* @param frame_name The name of the frame to load the file
* in; leave this blank to load in the main frame.
*
* @note The file should exist within the base directory.
*/
_OSMExport void awe_webview_load_file(awe_webview* webview,
const awe_string* file,
const awe_string* frame_name);
_OSMExport awe_string* awe_webview_get_url(awe_webview* webview);
/**
* Navigates back/forward in history via a relative offset.
*
* @param webview The WebView instance.
*
* @param offset The relative offset in history to navigate to.
*/
_OSMExport void awe_webview_go_to_history_offset(awe_webview* webview,
int offset);
/// Get the number of steps back in history we can go.
_OSMExport int awe_webview_get_history_back_count(awe_webview* webview);
/// Get the number of steps forward in history we can go.
_OSMExport int awe_webview_get_history_forward_count(awe_webview* webview);
/**
* Stops the current navigation.
*/
_OSMExport void awe_webview_stop(awe_webview* webview);
/**
* Reloads the current page.
*/
_OSMExport void awe_webview_reload(awe_webview* webview);
/**
* Executes a string of Javascript in the context of the current page
* asynchronously.
*
* @param javascript The string of Javascript to execute.
*
* @param frame_name The name of the frame to execute in;
* pass an empty string to execute in the main frame.
*/
_OSMExport void awe_webview_execute_javascript(awe_webview* webview,
const awe_string* javascript,
const awe_string* frame_name);
/**
* Executes a string of Javascript in the context of the current page
* asynchronously with a result.
*
* @param javascript The string of Javascript to execute.
*
* @param frame_name The name of the frame to execute in;
* pass an empty string to execute in the main frame.
*
* @param timeout_ms The maximum amount of time (in milliseconds) to wait
* for a result. Pass 0 to use no timeout. (If no result
* is obtained, or the timeout is reached, this function
* will return a jsvalue with type "null")
*
* @return Returns an awe_jsvalue instance. You must call awe_jsvalue_destroy
* on this instance when you're done using it.
*/
_OSMExport awe_jsvalue* awe_webview_execute_javascript_with_result(
awe_webview* webview,
const awe_string* javascript,
const awe_string* frame_name,
int timeout_ms);
/**
* Call a certain function defined in Javascript directly.
*
* @param object The name of the object that contains the function,
* pass an empty string if the function is defined in
* the global scope.
*
* @param function The name of the function.
*
* @param args The arguments to pass to the function.
*
* @param frame_name The name of the frame to execute in;
* leave this blank to execute in the main frame.
*/
_OSMExport void awe_webview_call_javascript_function(awe_webview* webview,
const awe_string* object,
const awe_string* function,
const awe_jsarray* arguments,
const awe_string* frame_name);
/**
* Creates a new global Javascript object that will persist throughout
* the lifetime of this WebView. This object is managed directly by
* Awesomium and so you can modify its properties and bind callback
* functions via awe_webview_set_object_property() and
* awe_webview_set_object_callback(), respectively.
*
* @param objectName The name of the object.
*/
_OSMExport void awe_webview_create_object(awe_webview* webview,
const awe_string* object_name);
/**
* Destroys a Javascript object previously created by
* awe_webview_create_object
*
* @param object_name The name of the object to destroy.
*/
_OSMExport void awe_webview_destroy_object(awe_webview* webview,
const awe_string* object_name);
/**
* Sets a property of a Javascript object previously created by
* awe_webview_create_object().
*
* @param object_name The name of the Javascript object.
*
* @param property_name The name of the property.
*
* @param value The javascript-value of the property.
*/
_OSMExport void awe_webview_set_object_property(awe_webview* webview,
const awe_string* object_name,
const awe_string* property_name,
const awe_jsvalue* value);
/**
* Sets a callback function of a Javascript object previously created
* by awe_webview_create_object(). This is very useful for passing events
* from Javascript to C. To receive notification of the callback, please
* see awe_webview_set_callback_js_callback().
*
* @param object_name The name of the Javascript object.
*
* @param callback_name The name of the callback function.
*/
_OSMExport void awe_webview_set_object_callback(awe_webview* webview,
const awe_string* object_name,
const awe_string* callback_name);
/**
* Returns whether or not a page is currently loading in the WebView.
*
* @return If a page is loading, returns true, otherwise returns false.
*/
_OSMExport bool awe_webview_is_loading_page(awe_webview* webview);
/**
* Returns whether or not the WebView is dirty and needs to be
* re-rendered via awe_webview_render.
*
* @return If the WebView is dirty, returns true, otherwise returns
* false.
*/
_OSMExport bool awe_webview_is_dirty(awe_webview* webview);
/**
* Returns the bounds of the area that has changed since the last call
* to awe_webview_render.
*
* @return The bounds of the dirty area.
*/
_OSMExport awe_rect awe_webview_get_dirty_bounds(awe_webview* webview);
/**
* Renders this WebView into an offscreen render buffer and clears the
* dirty state.
*
* @return A pointer to the internal render buffer instance that was used to
* render this WebView. This value may change between renders and
* may return NULL if the WebView has crashed.
*/
_OSMExport const awe_renderbuffer* awe_webview_render(awe_webview* webview);
/**
* All rendering is actually done asynchronously in a separate process
* and so the page is usually continuously rendering even if you never
* call awe_webview_render. Call this to temporarily pause rendering.
*/
_OSMExport void awe_webview_pause_rendering(awe_webview* webview);
/**
* Resume rendering after all call to awe_webview_pause_rendering.
*/
_OSMExport void awe_webview_resume_rendering(awe_webview* webview);
/**
* Injects a mouse-move event in local coordinates.
*
* @param x The absolute x-coordinate of the mouse (localized to
* the WebView).
*
* @param y The absolute y-coordinate of the mouse (localized to
* the WebView).
*/
_OSMExport void awe_webview_inject_mouse_move(awe_webview* webview,
int x,
int y);
/**
* Injects a mouse-down event.
*
* @param button The button that was pressed.
*/
_OSMExport void awe_webview_inject_mouse_down(awe_webview* webview,
awe_mousebutton button);
/**
* Injects a mouse-up event.
*
* @param button The button that was released.
*/
_OSMExport void awe_webview_inject_mouse_up(awe_webview* webview,
awe_mousebutton button);
/**
* Injects a mouse-wheel event.
*
* @param scrollAmountVert The relative amount of pixels to scroll vertically.
*
* @param scrollAmountHorz The relative amount of pixels to scroll horizontally.
*/
_OSMExport void awe_webview_inject_mouse_wheel(awe_webview* webview,
int scroll_amount_vert,
int scroll_amount_horz);
/**
* Injects a keyboard event. You'll need to initialize the members of
* awe_webkeyboardevent yourself.
*
* @param keyboardEvent The keyboard event to inject.
*/
_OSMExport void awe_webview_inject_keyboard_event(awe_webview* webview,
awe_webkeyboardevent key_event);
#ifdef _WIN32
/**
* Injects a native Windows keyboard event.
*
* @param msg The msg parameter.
* @param wparam The wparam parameter.
* @param lparam The lparam parameter.
*/
_OSMExport void awe_webview_inject_keyboard_event_win(awe_webview* webview,
UINT msg,
WPARAM wparam,
LPARAM lparam);
#endif
/**
* Invokes a 'cut' action using the system clipboard.
*/
_OSMExport void awe_webview_cut(awe_webview* webview);
/**
* Invokes a 'copy' action using the system clipboard.
*/
_OSMExport void awe_webview_copy(awe_webview* webview);
/**
* Invokes a 'paste' action using the system clipboard.
*/
_OSMExport void awe_webview_paste(awe_webview* webview);
/**
* Selects all items on the current page.
*/
_OSMExport void awe_webview_select_all(awe_webview* webview);
/// Copies an image on the page to the system clipboard.
_OSMExport void awe_webview_copy_image_at(awe_webview* webview,
int x,
int y);
/**
* Zooms the page a specified percent.
*
* @param zoom_percent The percent of the page to zoom to. Valid range
* is from 10% to 500%.
*/
_OSMExport void awe_webview_set_zoom(awe_webview* webview,
int zoom_percent);
/**
* Resets the zoom level.
*/
_OSMExport void awe_webview_reset_zoom(awe_webview* webview);
/// Gets the current zoom level.
_OSMExport int awe_webview_get_zoom(awe_webview* webview);
/// Gets the zoom level for a specific hostname.
_OSMExport int awe_webview_get_zoom_for_host(awe_webview* webview,
const awe_string* host);
/**
* Resizes this WebView to certain dimensions.
*
* @param width The width in pixels to resize to.
*
* @param height The height in pixels to resize to.
*
* @param wait_for_repaint Whether or not to wait for the WebView
* to finish repainting.
*
* @param repaint_timeout_ms The maximum amount of time to wait
* for a repaint, in milliseconds.
*
* @return Returns true if the resize was successful. This operation
* can fail if there is another resize already pending (see
* awe_webview_is_resizing) or if the repaint timeout was exceeded.
*/
_OSMExport bool awe_webview_resize(awe_webview* webview,
int width,
int height,
bool wait_for_repaint,
int repaint_timeout_ms);
/**
* Checks whether or not there is a resize operation pending.
*
* @return Returns true if we are waiting for the WebView process to
* return acknowledgement of a pending resize operation.
*/
_OSMExport bool awe_webview_is_resizing(awe_webview* webview);
/**
* Notifies the current page that it has lost focus.
*/
_OSMExport void awe_webview_unfocus(awe_webview* webview);
/**
* Notifies the current page that is has gained focus. You will need
* to call this to gain textbox focus, among other things. (If you
* fail to ever see a blinking caret when typing text, this is why).
*/
_OSMExport void awe_webview_focus(awe_webview* webview);
/**
* Sets whether or not pages should be rendered with transparency
* preserved. (ex, for pages with style="background-color:transparent")
*
* @param is_transparent Whether or not this WebView is transparent.
*/
_OSMExport void awe_webview_set_transparent(awe_webview* webview,
bool is_transparent);
_OSMExport bool awe_webview_is_transparent(awe_webview* webview);
/**
* Sets the current URL Filtering Mode (default is AWE_UFM_NONE).
* See awe_url_filtering_mode for more information on the modes.
*
* @param mode The URL filtering mode to use.
*/
_OSMExport void awe_webview_set_url_filtering_mode(awe_webview* webview,
awe_url_filtering_mode mode);
/**
* Adds a new URL Filter rule.
*
* @param filter A string with optional wildcards that describes a
* certain URL.
*
* @note For example, to match all URLs from the domain
* "google.com", your filter string might be:
* http://google.com/*
*
* @note You may also use the "local://" scheme prefix to
* describe the URL to the base directory (set via
* awe_webcore_set_base_directory).
*/
_OSMExport void awe_webview_add_url_filter(awe_webview* webview,
const awe_string* filter);
/**
* Clears all URL Filter rules.
*/
_OSMExport void awe_webview_clear_all_url_filters(awe_webview* webview);
/**
* Defines a new Header Definition or updates it if it already exists.
*
* @param name The unique name of the Header Definition; this is
* used to refer to it later in
* awe_webview_add_header_rewrite_rule and
* related methods.
*
* @param num_fields The number of fields in the header.
*
* @param field_names An array of strings representing the field names
*
* @param field_vales An array of strings representing the field values
*/
_OSMExport void awe_webview_set_header_definition(awe_webview* webview,
const awe_string* name,
size_t num_fields,
const awe_string** field_names,
const awe_string** field_values);
/**
* Adds a new a header re-write rule. All requests whose URL matches the
* specified rule will have its HTTP headers re-written with the
* specified header definition before sending it to the server.
*
* @param rule A string with optional wildcards (*, ?) that
* matches the URL(s) that will have its headers
* re-written with the specified header definition.
*
* @param name The name of the header definition (specified in
* awe_webview_set_header_definition).
*
* @note The case where a URL is matched by multiple rules is
* unsupported, only the first match will be used.
*/
_OSMExport void awe_webview_add_header_rewrite_rule(awe_webview* webview,
const awe_string* rule,
const awe_string* name);
/**
* Removes a header re-write rule from this WebView.
*
* @param rule The rule to remove (should match the string
* specified in awe_webview_add_header_rewrite_rule exactly).
*/
_OSMExport void awe_webview_remove_header_rewrite_rule(awe_webview* webview,
const awe_string* rule);
/**
* Removes all header re-write rules that are using a certain header
* definition.
*
* @param name The name of the header definition (specified in
* awe_webview_set_header_definition). If you specify an
* empty string, this will remove ALL header re-write rules.
*/
_OSMExport void awe_webview_remove_header_rewrite_rules_by_definition_name(
awe_webview* webview,
const awe_string* name);
/**
* This should be called as a response to the request file chooser callback.
*
* @param file_path The full path to the file that was chosen.
*/
_OSMExport void awe_webview_choose_file(awe_webview* webview,
const awe_string* file_path);
/**
* Print the current page. To suppress the printer selection dialog and
* print immediately using the operating system's defaults, see
* awe_webcore_set_suppress_printer_dialog.
*/
_OSMExport void awe_webview_print(awe_webview* webview);
/**
* Request the page dimensions and scroll position of the page. You can
* retrieve the response via the get scroll data callback.
*
* @param frame_name The frame's scroll data to retrieve. Leave blank
* to get the main frame's scroll data.
*/
_OSMExport void awe_webview_request_scroll_data(awe_webview* webview,
const awe_string* frame_name);
/**
* Start finding a certain string on the current web-page. All matches
* of the string will be highlighted on the page and you can jump
* to different instances of the string by using the 'findNext'
* parameter. To get actual stats about a certain query, please see
* awe_webview_set_callback_get_find_results.
*
* @param request_id A unique numeric ID for each search. You will
* need to generate one yourself for each unique
* search-- please note that you should use the
* same request_id if you wish to iterate through
* all the search results using the 'findNext'
* parameter.
*
* @param search_string The string to search for.
*
* @param forward Whether or not we should search forward, down
* the page.
*
* @param case_sensitive Whether or not this search is case-sensitive.
*
* @param find_next Whether or not we should jump to the next
* instance of a search string (you should use
* the same request_id as a previously-successful
* search).
*/
_OSMExport void awe_webview_find(awe_webview* webview,
int request_id,
const awe_string* search_string,
bool forward,
bool case_sensitive,
bool find_next);
/**
* Stop finding. This will un-highlight all matches of a previous
* call to awe_webview_find.
*
* @param clear_selection Whether or not we should also deselect
* the currently-selected string instance.
*/
_OSMExport void awe_webview_stop_find(awe_webview* webview,
bool clear_selection);
/**
* Attempt automatic translation of the current page via Google
* Translate. All language codes are ISO 639-2.
*
* @param source_language The language to translate from
* (for ex. "en" for English)
*
* @param target_language The language to translate to
* (for ex. "fr" for French)
*/
_OSMExport void awe_webview_translate_page(awe_webview* webview,
const awe_string* source_language,
const awe_string* target_language);
/**
* Call this method to let the WebView know you will be passing
* text input via IME and will need to be notified of any
* IME-related events (caret position, user unfocusing textbox, etc.)
* Please see awe_webview_set_callback_update_ime
*/
_OSMExport void awe_webview_activate_ime(awe_webview* webview,
bool activate);
/**
* Update the current IME text composition.
*
* @param inputString The string generated by your IME.
* @param cursorPos The current cursor position in your IME composition.
* @param targetStart The position of the beginning of the selection.
* @param targetEnd The position of the end of the selection.
*/
_OSMExport void awe_webview_set_ime_composition(awe_webview* webview,
const awe_string* input_string,
int cursor_pos,
int target_start,
int target_end);
/**
* Confirm a current IME text composition.
*
* @param inputString The string generated by your IME.
*/
_OSMExport void awe_webview_confirm_ime_composition(awe_webview* webview,
const awe_string* input_string);
/**
* Cancel a current IME text composition.
*/
_OSMExport void awe_webview_cancel_ime_composition(awe_webview* webview);
/**
* Respond to the "request login" callback with some user-supplied
* credentials.
*
* @param request_id The unique ID of the request.
*
* @param username The username supplied by the user.
*
* @param password The password supplied by the user.
*/
_OSMExport void awe_webview_login(awe_webview* webview,
int request_id,
const awe_string* username,
const awe_string* password);
/**
* Respond to the "request login" callback by telling the
* server that the user cancelled the authentication request.
*
* @param request_id The unique ID of the request.
*/
_OSMExport void awe_webview_cancel_login(awe_webview* webview,
int request_id);
/**
* Respond to the "show javascript dialog" callback.
*
* @param request_id The unique ID of the dialog request.
*
* @param was_cancelled Whether or not the dialog was cancelled/ignored.
*
* @param prompt_text If the dialog had a prompt, you should pass whatever
* text the user entered into the textbox via this parameter.
*/
_OSMExport void awe_webview_close_javascript_dialog(awe_webview* webview,
int request_id,
bool was_cancelled,
const awe_string* prompt_text);
/**
* Assign a callback function to be notified when a WebView begins navigation
* to a certain URL.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_begin_navigation(
awe_webview* webview,
void (*callback)(awe_webview* caller,
const awe_string* url,
const awe_string* frame_name));
/**
* Assign a callback function to be notified when a WebView begins to actually
* receive data from a server.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_begin_loading(
awe_webview* webview,
void (*callback)(awe_webview* caller,
const awe_string* url,
const awe_string* frame_name,
int status_code,
const awe_string* mime_type));
/**
* Assign a callback function to be notified when a WebView has finished
* all loads.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_finish_loading(
awe_webview* webview,
void (*callback)(awe_webview* caller));
/**
* Assign a callback function to be notified when a Javascript object callback
* has been invoked on a page.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_js_callback(
awe_webview* webview,
void (*callback)(awe_webview* caller,
const awe_string* object_name,
const awe_string* callback_name,
const awe_jsarray* arguments));
/**
* Assign a callback function to be notified when a page title is received.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_receive_title(
awe_webview* webview,
void (*callback)(awe_webview* caller,
const awe_string* title,
const awe_string* frame_name));
/**
* Assign a callback function to be notified when a tooltip has changed state.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_change_tooltip(
awe_webview* webview,
void (*callback)(awe_webview* caller,
const awe_string* tooltip));
/**
* Assign a callback function to be notified when a cursor has changed state.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_change_cursor(
awe_webview* webview,
void (*callback)(awe_webview* caller,
awe_cursor_type cursor));
/**
* Assign a callback function to be notified when keyboard focus has changed.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_change_keyboard_focus(
awe_webview* webview,
void (*callback)(awe_webview* caller,
bool is_focused));
/**
* Assign a callback function to be notified when the target URL has changed.
* This is usually the result of hovering over a link on the page.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_change_target_url(
awe_webview* webview,
void (*callback)(awe_webview* caller,
const awe_string* url));
/**
* Assign a callback function to be notified when an external link is attempted
* to be opened. An external link is any link that normally opens in a new
* window in a standard browser (for example, links with target="_blank",
* calls to window.open(url), and URL open events from Flash plugins).
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_open_external_link(
awe_webview* webview,
void (*callback)(awe_webview* caller,
const awe_string* url,
const awe_string* source));
/**
* Assign a callback function to be notified when a page requests for a certain
* URL to be downloaded by the user.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_request_download(
awe_webview* webview,
void (*callback)(awe_webview* caller,
const awe_string* download));
/**
* Assign a callback function to be notified when the renderer for a certain
* WebView (which is isolated in a separate process) crashes unexpectedly.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_web_view_crashed(
awe_webview* webview,
void (*callback)(awe_webview* caller));
/**
* Assign a callback function to be notified when when the renderer for a
* certain plugin (usually Flash, which is isolated in a separate process)
* crashes unexpectedly.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_plugin_crashed(
awe_webview* webview,
void (*callback)(awe_webview* caller,
const awe_string* plugin_name));
/**
* Assign a callback function to be notified when the page requests for the
* containing window to be moved to a certain location on the screen.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_request_move(
awe_webview* webview,
void (*callback)(awe_webview* caller,
int x,
int y));
/**
* Assign a callback function to be notified when the contents of the page has finished
* loading. This occurs at the end of most page loads.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_get_page_contents(
awe_webview* webview,
void (*callback)(awe_webview* caller,
const awe_string* url,
const awe_string* contents));
/**
* Assign a callback function to be notified once the DOM (Document Object
* Model) for a page is ready. This is very useful for executing Javascript
* on a page before its content has finished loading.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_dom_ready(
awe_webview* webview,
void (*callback)(awe_webview* caller));
/**
* Assign a callback function to be notified whenever a page requests a file
* chooser dialog to be displayed (usually the result of an "input" element
* with type "file" being clicked by a user). You will need to display your
* own dialog (it does not have to be modal, this request does not block).
* Once a file has been chosen by the user, awe_webview_choose_file or
* awe_webview_choose_multiple_files should be called.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_request_file_chooser(
awe_webview* webview,
void (*callback)(awe_webview* caller,
bool select_multiple_files,
const awe_string* title,
const awe_string* default_path));
/**
* Assign a callback function to be notified of a response to
* awe_webview_request_scroll_data.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_get_scroll_data(
awe_webview* webview,
void (*callback)(awe_webview* caller,
int contentWidth,
int contentHeight,
int preferredWidth,
int scrollX,
int scrollY));
/**
* Assign a callback function to be notified of any Javascript
* console messages. (Usually Javascript errors encountered in scripts)
*
* @param webview The WebView instance
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_js_console_message(
awe_webview* webview,
void (*callback)(awe_webview* caller,
const awe_string* message,
int line_number,
const awe_string* source));
/**
* Assign a callback function to be notified whenever we receive
* results back from an in-page find operation (awe_webview_find).
*
* @param webview The WebView instance
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_get_find_results(
awe_webview* webview,
void (*callback)(awe_webview* caller,
int request_id,
int num_matches,
awe_rect selection,
int cur_match,
bool finalUpdate));
/**
* Assign a callback function to be notified whenever the user does
* something that may change the position or visiblity of the IME Widget.
* This callback is only active when IME is activated (please
* see awe_webview_activate_ime).
*
* @param webview The WebView instance
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_update_ime(
awe_webview* webview,
void (*callback)(awe_webview* caller,
awe_ime_state state,
awe_rect caret_rect));
/**
* Assign a callback function to be notified whenever the page requests
* a context menu to be shown (usually the result of a user right-clicking
* somewhere on the page). It is your responsiblity to display a menu for
* the user to select an appropriate action.
*
* @param webview The WebView instance
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_show_context_menu(
awe_webview* webview,
void (*callback)(awe_webview* caller,
int mouse_x,
int mouse_y,
awe_media_type type,
int media_state,
const awe_string* link_url,
const awe_string* src_url,
const awe_string* page_url,
const awe_string* frame_url,
const awe_string* selection_text,
bool is_editable,
int edit_flags));
/**
* Assign a callback function to be notified whenever a page requests
* authentication from the user (ex, Basic HTTP Auth, NTLM Auth, etc.).
* See awe_webview_login and awe_webview_cancel_login
*
* @param webview The WebView instance
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_request_login(
awe_webview* webview,
void (*callback)(awe_webview* caller,
int request_id,
const awe_string* request_url,
bool is_proxy,
const awe_string* host_and_port,
const awe_string* scheme,
const awe_string* realm));
/**
* Assign a callback function to be notified whenever the history state
* has changed. (eg, the state of thie back/forward buttons should be
* updated)
*
* @param webview The WebView instance
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_change_history(
awe_webview* webview,
void (*callback)(awe_webview* caller,
int back_count,
int forward_count));
/**
* Assign a callback function to be notified whenever a WebView has
* finished resizing to a certain size (and has finished repainting
* the RenderBuffer).
*
* @param webview The WebView instance
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_finish_resize(
awe_webview* webview,
void (*callback)(awe_webview* caller,
int width,
int height));
/**
* Assign a callback function to be notified whenever a WebView
* requests that a certain Javascript dialog be shown (eg, alert,
* confirm, prompt). See awe_webview_close_javascript_dialog for
* more information.
*
* @param webview The WebView instance
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_show_javascript_dialog(
awe_webview* webview,
void (*callback)(awe_webview* caller,
int request_id,
int dialog_flags,
const awe_string* message,
const awe_string* default_prompt,
const awe_string* frame_url));
/***********************
* JS Value Functions *
***********************/
typedef enum _awe_jsvalue_type
{
JSVALUE_TYPE_NULL,
JSVALUE_TYPE_BOOLEAN,
JSVALUE_TYPE_INTEGER,
JSVALUE_TYPE_DOUBLE,
JSVALUE_TYPE_STRING,
JSVALUE_TYPE_OBJECT,
JSVALUE_TYPE_ARRAY
} awe_jsvalue_type;
/**
* Create a JSValue instance initialized as a null type. You must call
* awe_jsvalue_destroy with the returned instance once you're done using it.
*/
_OSMExport awe_jsvalue* awe_jsvalue_create_null_value();
/**
* Create a JSValue instance initialized with a boolean type. You must call
* awe_jsvalue_destroy with the returned instance once you're done using it.
*
* @param value The initial value
*/
_OSMExport awe_jsvalue* awe_jsvalue_create_bool_value(bool value);
/**
* Create a JSValue instance initialized with an integer type. You must call
* awe_jsvalue_destroy with the returned instance once you're done using it.
*
* @param value The initial value
*/
_OSMExport awe_jsvalue* awe_jsvalue_create_integer_value(int value);
/**
* Create a JSValue instance initialized with a double type. You must call
* awe_jsvalue_destroy with the returned instance once you're done using it.
*
* @param value The initial value
*/
_OSMExport awe_jsvalue* awe_jsvalue_create_double_value(double value);
/**
* Create a JSValue instance initialized with a string type. You must call
* awe_jsvalue_destroy with the returned instance once you're done using it.
*
* @param value The initial value
*/
_OSMExport awe_jsvalue* awe_jsvalue_create_string_value(const awe_string* value);
/**
* Create a JSValue instance initialized with an object type. You must call
* awe_jsvalue_destroy with the returned instance once you're done using it.
*
* @param value The initial value
*/
_OSMExport awe_jsvalue* awe_jsvalue_create_object_value(const awe_jsobject* value);
/**
* Create a JSValue instance initialized with an array type. You must call
* awe_jsvalue_destroy with the returned instance once you're done using it.
*
* @param value The initial value
*/
_OSMExport awe_jsvalue* awe_jsvalue_create_array_value(const awe_jsarray* value);
/**
* Destroys a JSValue instance.
*
* @param jsvalue The JSValue instance.
*/
_OSMExport void awe_jsvalue_destroy(awe_jsvalue* jsvalue);
/**
* Get the type of a JSValue.
*
* @param jsvalue The JSValue instance.
*
* @return Returns the type of the JSValue (see enum awe_jsvalue_type)
*/
_OSMExport awe_jsvalue_type awe_jsvalue_get_type(const awe_jsvalue* jsvalue);
/**
* Get the value as a string.
*
* @param jsvalue The JSValue instance.
*
* @return Returns a string instance. You'll need to call awe_string_destroy
* with this instance when you're done using it.
*/
_OSMExport awe_string* awe_jsvalue_to_string(const awe_jsvalue* jsvalue);
/// Returns this value as an integer.
_OSMExport int awe_jsvalue_to_integer(const awe_jsvalue* jsvalue);
/// Returns this value as an double.
_OSMExport double awe_jsvalue_to_double(const awe_jsvalue* jsvalue);
/// Returns this value as an boolean.
_OSMExport bool awe_jsvalue_to_boolean(const awe_jsvalue* jsvalue);
/// Returns this value as an array. Will throw an exception if not an array.
_OSMExport const awe_jsarray* awe_jsvalue_get_array(const awe_jsvalue* jsvalue);
/// Returns this value as an object. Will throw an exception if not an object.
_OSMExport const awe_jsobject* awe_jsvalue_get_object(const awe_jsvalue* jsvalue);
/****************************
* JS Value Array Functions *
****************************/
/**
* Create a JSValue Array.
*
* @param jsvalue_array An array of JSValue instances to be copied from.
* @param length Length of the array.
*/
_OSMExport awe_jsarray* awe_jsarray_create(const awe_jsvalue** jsvalue_array,
size_t length);
/**
* Destroys a JSValue Array created with awe_jsarray_create.
*/
_OSMExport void awe_jsarray_destroy(awe_jsarray* jsarray);
/**
* Get the size of a JSValue Array.
*/
_OSMExport size_t awe_jsarray_get_size(const awe_jsarray* jsarray);
/**
* Get a specific element of a JSValue Array. The Array retains ownership
* of the returned JSValue instance (you do not need to destroy it).
*/
_OSMExport const awe_jsvalue* awe_jsarray_get_element(const awe_jsarray* jsarray,
size_t index);
/*****************************
* JS Value Object Functions *
*****************************/
/**
* Creates a JSValue Object.
*/
_OSMExport awe_jsobject* awe_jsobject_create();
/**
* Destroys a JSValue Object created with awe_jsobject_create
*/
_OSMExport void awe_jsobject_destroy(awe_jsobject* jsobject);
/**
* Returns whether or not a JSValue Object has a certained named property.
*/
_OSMExport bool awe_jsobject_has_property(const awe_jsobject* jsobject,
const awe_string* property_name);
/**
* Gets the value of a certain named property of a JSValue Object. You do not
* need to destroy the returned jsvalue instance, it is owned by the object.
*/
_OSMExport const awe_jsvalue* awe_jsobject_get_property(const awe_jsobject* jsobject,
const awe_string* property_name);
/**
* Sets the value of a certained named property of a JSValue Object.
*/
_OSMExport void awe_jsobject_set_property(awe_jsobject* jsobject,
const awe_string* property_name,
const awe_jsvalue* value);
/**
* Get the number of key/value pairs in a JSValue object.
*/
_OSMExport size_t awe_jsobject_get_size(awe_jsobject* jsobject);
/**
* Get a list of all key names as a JSValue Array, you need to call
* awe_jsarray_destroy on the returned value after you're done using it.
*/
_OSMExport awe_jsarray* awe_jsobject_get_keys(awe_jsobject* jsobject);
/***************************
* Render Buffer Functions *
***************************/
/**
* Get the width (in pixels) of a RenderBuffer.
*/
_OSMExport int awe_renderbuffer_get_width(const awe_renderbuffer* renderbuffer);
/**
* Get the height (in pixels) of a RenderBuffer.
*/
_OSMExport int awe_renderbuffer_get_height(const awe_renderbuffer* renderbuffer);
/**
* Get the rowspan (number of bytes per row) of a RenderBuffer.
*/
_OSMExport int awe_renderbuffer_get_rowspan(const awe_renderbuffer* renderbuffer);
/**
* Get a pointer to the actual pixel buffer within a RenderBuffer.
*/
_OSMExport const unsigned char* awe_renderbuffer_get_buffer(
const awe_renderbuffer* renderbuffer);
/**
* Copy a RenderBuffer to a specific destination with the same dimensions.
*/
_OSMExport void awe_renderbuffer_copy_to(const awe_renderbuffer* renderbuffer,
unsigned char* dest_buffer,
int dest_rowspan,
int dest_depth,
bool convert_to_rgba,
bool flip_y);
/**
* Copy a RenderBuffer to a pixel buffer with a floating-point pixel format
* for use with game engines like Unity3D.
*/
_OSMExport void awe_renderbuffer_copy_to_float(const awe_renderbuffer* renderbuffer,
float* dest_buffer);
/**
* Save a copy of this RenderBuffer to a PNG image file.
*/
_OSMExport bool awe_renderbuffer_save_to_png(const awe_renderbuffer* renderbuffer,
const awe_string* file_path,
bool preserve_transparency);
/**
* Save a copy of this RenderBuffer to a JPEG image file with quality 1 to 100.
*/
_OSMExport bool awe_renderbuffer_save_to_jpeg(const awe_renderbuffer* renderbuffer,
const awe_string* file_path,
int quality);
/**
* Get the alpha value at a certain point (origin is top-left). This is
* useful for alpha-picking.
*
* @param x The x-value of the point.
* @param y The y-value of the point.
*
* @return Returns the alpha value at a certain point (255 is comppletely
* opaque, 0 is completely transparent).
*/
_OSMExport unsigned char awe_renderbuffer_get_alpha_at_point(const awe_renderbuffer* renderbuffer,
int x,
int y);
/**
* Sets the alpha channel to completely opaque values.
*/
_OSMExport void awe_renderbuffer_flush_alpha(const awe_renderbuffer* renderbuffer);
/************************
* Resource Interceptor *
************************/
/**
* Assign a callback function to intercept requests for resources. You can use
* this to modify requests before they are sent, respond to requests using
* your own custom resource-loading back-end, or to monitor requests for
* tracking purposes.
*
* @param webview The WebView instance.
*
* @param callback A function pointer to the callback.
*/
_OSMExport void awe_webview_set_callback_resource_request(
awe_webview* webview,
awe_resource_response* (*callback)(
awe_webview* caller,
awe_resource_request* request));
/**
* Assign a callback function to intercept responses to requests. You can use
* this for tracking/statistic purposes.
*/
_OSMExport void awe_webview_set_callback_resource_response(
awe_webview* webview,
void (*callback)(
awe_webview* caller,
const awe_string* url,
int status_code,
bool was_cached,
int64 request_time_ms,
int64 response_time_ms,
int64 expected_content_size,
const awe_string* mime_type));
/**
* Create a ResourceResponse from a raw block of data. (Buffer is copied)
*/
_OSMExport awe_resource_response* awe_resource_response_create(
size_t num_bytes,
unsigned char* buffer,
const awe_string* mime_type);
/**
* Create a ResourceResponse from a file on disk.
*/
_OSMExport awe_resource_response* awe_resource_response_create_from_file(
const awe_string* file_path);
/************************
* Resource Request *
************************/
/// Cancel the request (this is useful for blocking a resource load).
_OSMExport void awe_resource_request_cancel(awe_resource_request* request);
/// Get the URL associated with this request. (You must destroy returned string)
_OSMExport awe_string* awe_resource_request_get_url(awe_resource_request* request);
/// Get the HTTP method (usually "GET" or "POST") (You must destroy returned string)
_OSMExport awe_string* awe_resource_request_get_method(awe_resource_request* request);
/// Set the HTTP method
_OSMExport void awe_resource_request_set_method(awe_resource_request* request,
const awe_string* method);
/// Get the referrer (You must destroy returned string)
_OSMExport awe_string* awe_resource_request_get_referrer(awe_resource_request* request);
/// Set the referrer
_OSMExport void awe_resource_request_set_referrer(awe_resource_request* request,
const awe_string* referrer);
/// Get extra headers for the request (You must destroy returned string)
_OSMExport awe_string* awe_resource_request_get_extra_headers(awe_resource_request* request);
/**
* Override extra headers for the request, delimited by /r/n (CRLF).
*
* Format should be:
* Name: Value/r/nName: Value/r/nName: Value
*
* Headers should NOT end in /r/n (CRLF)
*/
_OSMExport void awe_resource_request_set_extra_headers(awe_resource_request* request,
const awe_string* headers);
/**
* Append an extra header to the request.
*
* @param name Name of the header
* @param value Value of the header
*/
_OSMExport void awe_resource_request_append_extra_header(awe_resource_request* request,
const awe_string* name,
const awe_string* value);
/// Get the number of upload elements (essentially, batches of POST data).
_OSMExport size_t awe_resource_request_get_num_upload_elements(awe_resource_request* request);
/// Get a certain upload element (returned instance is owned by this class)
_OSMExport const awe_upload_element* awe_resource_request_get_upload_element(awe_resource_request* request,
size_t idx);
/// Clear all upload elements
_OSMExport void awe_resource_request_clear_upload_elements(awe_resource_request* request);
/// Append a file for POST data (adds a new UploadElement)
_OSMExport void awe_resource_request_append_upload_file_path(awe_resource_request* request,
const awe_string* file_path);
/// Append a string of bytes for POST data (adds a new UploadElement)
_OSMExport void awe_resource_request_append_upload_bytes(awe_resource_request* request,
const awe_string* bytes);
/************************
* Upload Element *
************************/
/// Whether or not this UploadElement is a file
_OSMExport bool awe_upload_element_is_file_path(const awe_upload_element* ele);
/// Whether or not this UploadElement is a string of bytes
_OSMExport bool awe_upload_element_is_bytes(const awe_upload_element* ele);
/// Get the string of bytes associated with this UploadElement (You must destroy returned string)
_OSMExport awe_string* awe_upload_element_get_bytes(const awe_upload_element* ele);
/// Get the file path associated with this UploadElement (You must destroy returned string)
_OSMExport awe_string* awe_upload_element_get_file_path(const awe_upload_element* ele);
/************************
* History Query Result *
************************/
/// Destroy the instance (you must call this once you're done using the instance)
_OSMExport void awe_history_query_result_destroy(awe_history_query_result* res);
/// Get the total number of entries
_OSMExport size_t awe_history_query_result_get_size(awe_history_query_result* res);
/// Get a certain entry (you must destroy any returned entry using awe_history_entry_destroy).
/// May return NULL if the index is out of bounds.
_OSMExport awe_history_entry* awe_history_query_result_get_entry_at_index(awe_history_query_result* res,
size_t idx);
/************************
* History Entry *
************************/
/// Destroy the instance
_OSMExport void awe_history_entry_destroy(awe_history_entry* entry);
/// Get the URL of the page
_OSMExport awe_string* awe_history_entry_get_url(awe_history_entry* entry);
/// Get the title of the page
_OSMExport awe_string* awe_history_entry_get_title(awe_history_entry* entry);
/// Get the last time this page was visited (in seconds since epoch)
_OSMExport double awe_history_entry_get_visit_time(awe_history_entry* entry);
/// Get the number of times this page was visited.
_OSMExport int awe_history_entry_get_visit_count(awe_history_entry* entry);
#ifdef __cplusplus
}
#endif
/**
* @mainpage Awesomium C API
*
* @section intro_sec Introduction
*
* Hi there, welcome to the Awesomium C API docs! Awesomium is a software
* library that makes it easy to put the web in your applications. Whether
* that means embedded web browsing, rendering pages as images, streaming
* pages over the net, or manipulating web content live for some other
* purpose, Awesomium does it all.
*
* Our C API provides much more compatibility than our C++ API at the cost
* of some extra convenience.
*
* To start off, we'd recommend looking at some of the following functions:
* <pre>
* awe_webcore_initialize()
* awe_webcore_initialize_default()
* awe_webcore_shutdown()
* awe_webcore_create_webview()
* awe_webview_load_url()
* awe_webview_render()
* awe_webview_destroy()
* </pre>
*
* To avoid memory leaks, there is one major rule that you must follow in
* our C API regarding ownership of returned objects: if a function returns
* a regular pointer to an instance, you must destroy the instance using the
* relevant method. Otherwise, if a function returns a const pointer to an
* instance, you should not destroy it (ownership is retained by Awesomium).
*
* For example, you must destroy all strings you create in Awesomium:
*
* <pre>
* awe_string* str = awe_string_create_from_ascii("Hello", strlen("Hello"));
*
* // Use the string somewhere... then destroy it when we are done:
*
* awe_string_destroy(str);
* </pre>
*
* But you should not destroy certain strings returned from certain methods:
*
* <pre>
* const awe_string* str = awe_webcore_get_base_directory();
*
* // We do not need to destroy this string: when a function returns
* // a const pointer in Awesomium, it means ownership is retained by
* // Awesomium and the instance will be destroyed automatically later.
* </pre>
*
* For more help and tips with the API, please visit our Knowledge Base
* <http://support.awesomium.com/faqs>
*
* @section usefullinks_sec Useful Links
* - Awesomium Main: <http://www.awesomium.com>
* - Support Home: <http://support.awesomium.com>
*
* @section copyright_sec Copyright
* This documentation is copyright (C) 2011 Khrona. All rights reserved.
* Awesomium is a trademark of Khrona.
*/
#endif