# EmBrowser 3.0

# Embedding the Opera Rendering Engine in Desktop Applications

## Table of Contents

1. Table of Contents
2. The Browser Component
   - Control
   - Focus
3. The EmBrowser API
   - General
   - Backwards Compatibility
   - Specifications
   - Thread Safety
   - Reentrancy
   - Function Categories
   - Messages
4. Special Issues for Embedding Opera 7.5 on the Windows Platform
   - Operating System Support
   - Functions
   - Structure Alignment
   - Distribution
   - Java
5. Special Issues for Embedding Opera 7.5 on the Macintosh Platform
   - Operating System Support
   - Executable Format
   - Event Handlers
   - Java Support and Thread Issues
   - Backwards Compatibility Exceptions
   - Structure Alignment
   - Distribution
   - Plug-Ins
   - Local File Browsing
6. Data Types
   - String Formats
   - Opaque Browser Types
   - Opaque Browser Types - Added in EmBrowser 3.0
   - Browser Structs
   - Browser Structs - Added in EmBrowser 3.0
7. Enumerated Types
8. Browser Instance APIs
   - Creation and Deletion
   - Screen Port Management
   - Basic Navigation
   - Properties
   - Command Messages
   - Miscellaneous
9. Document Instance APIs
10. Notifications
11. Miscellaneous APIs
    - Memory Allocation
12. Miscellaneous APIs - Added in EmBrowser 3.0
    - Cookies
    - History
    - JavaScript
    - Thumbnail
    - Plug-in
    - Properties
    - Image Display
    - Visibility of Visited Links
13. Miscellaneous
    - Proxy servers
    - Cache
    - Adding plugins
    - Local file URLs and security policy

## The Browser Component

The Opera Rendering Engine Library is the Opera 7.5 (or 9.0) browser embeddable in third party desktop applications (referred to has "host" applications) by using the EmBrowser 3.0 API. Ideally third party host applications make use of the installed Opera 7.5 desktop application. This is done by simply using a discovery process to find a copy of Opera on the local computer with a compatible API version from which to create embedded browser instances. This avoids the issue of having unnecessary multiple copies of Opera for each host application that embeds Opera.
An instance of the embedded browser consists of the rectangle containing the browser content area, optionally with scrollbars. All other Opera UI elements that exist outside of the rendering rectangle in the desktop browser such as menus, m2 mailer, hotlist, etc. are absent. Only UI elements that actually belong to the rendering area, such as dialogs, simplified contextual menus, and mouse gestures can be included in instances of the embedded browser.

### Control

The browser component is designed to be a control. Opera subscribes to its own operating system events, accesses the network, and draws itself automatically, without any intervention needed from the host application. This makes the job of embedding Opera as easy as possible because the host application does not have to dedicate a lot of coding effort into controlling Opera on behalf of the operating system by trapping and dispatching events. That said, it should be emphasized that the host application still has complete control over Opera, this is just accomplished in an easier way via the EmBrowser API.

### Focus

The concept of focus between the host application and embedded browser is very central to embedding Opera. When Opera has focus, it receives and processes keyboard and mouse events, and when the host application has focus, it receives mouse and keyboard events. When Opera detects a mouse click in the browser content area when the host application has focus, Opera requests the host application to be given focus. If the host application grants focus, Opera will then automatically handle subsequent keyboard events and mouse events that relate to the browser.

In general:

To allow Opera to receive mouse events: EmBrowserSetVisibilityProc(TRUE), EmBrowserSetActiveProc(TRUE).

To allow Opera to receive keyboard events: EmBrowserSetVisibilityProc(TRUE), EmBrowserSetActiveProc(TRUE), and EmBrowserSetFocusProc(TRUE).

## The EmBrowser API

### General

The EmBrowser API is a platform-independent, C API used to create browser instances, interact with and control Opera. Platform-specific data types have been purposely kept out of the header file to facilitate the easiest possible cross-platform integration of the browser component.

### Backwards Compatibility

The API is designed to have binary backwards compatibility with the use of padded structures containing the browser functions. This makes it possible for older programs to embed newer versions of Opera without encountering difficulty. The EmBrowser.h header file specifies which values are part of the EmBrowser version 2.0, and which were introduced as part of EmBrowser version 3.0. In this document all functions, enums, and data structures can be assumed to be EmBrowser 2.0 compatible unless otherwise it is specifically noted in various sections as EmBrowser 3.0.

The full-featured Opera 7.5 desktop browsers for Windows and Macintosh were released with the EmBrowser 3.0 API. This API is backwards compatible with EmBrowser 2.0 which was released with the Opera 6.03 on Macintosh. Host applications that use the same codebase for their The goal has been that Macintosh and Windows applications should be able to embed Opera 7.5 using the EmBrowser 3.0 API with as few platform specific considerations in the code as possible.

### Specifications

The web technology specifications of the embedded browser are identical to those of the Opera browser being embedded by the host application. This information can be found on Opera's web site here.

### Thread Safety

Opera is not a thread safe application as it runs on many platforms that do not support threads.

### Reentrancy

Opera is not re-entrant, which means that special care should be taken to avoid calling back into Opera from an Opera callback. Doing so can cause unexpected behavior. This is because when Opera calls back into the host application during a notification or notification message there can already be a command sequence executing on the stack.

Exceptions to this rule:

- "Get" functions are the only functions that can be guaranteed to work from a callback.
- JavaScript functions can be called from JavaScript callbacks.

### Function Categories

- Browser Instance: Functions that operate on the browser instance (EmBrowserRef) level.
- Browser Document: Functions that operate on a specific browser document (EmDocumentRef). There can be many browser documents per browser instance.
- Notifications: Function callbacks from Opera into the host application which modification parameters, or halt the browser during various operations.
- Miscellaneous: Functions which do not call for an EmBrowserRef or EmDocumentRef. These break the original design concept, but have nonetheless crept in. These APIs can cause unexpected results if Opera has not been properly initialized.

### Messages

- Notification Messages: Messages used by the browser to communicate with the host application via a callback. See EmBrowserAppSimpleNotificationProc.
- Command Messages: Messages used by the host application to control Opera. See EmBrowserDoHandleMessageProc.

## Special Issues for Embedding Opera 7.5 on the Windows Platform

### Operating System Support

Opera 7.5 works with Windows 95SE, 98, ME, NT4, 2000, XP.

### Functions

EmBrowserProcessOperaMessageProc: Message hook for mouse and keyboard handling
Exported by Opera.dll as TranslateOperaMessage
EmBrowserSetFocusProc ensures that most messages from Windows are correctly sent to the browser window proc. However, Opera needs to process virtual-key messages and this must be done before a call to TranslateMessage, just like when using TranslateAccelerator. See test application for example.

### Structure Alignment

Opera uses struct member alignment set to 4, four, bytes throughout all modules on Win32. For applications passing structures back and forth this has to be the same. Otherwise data corruption will occur.

To facilitate the use of EmBrowser for applications with a different alignment, EmBrowser.h starts with

# pragma pack( push, before_embrowser_pack ) # pragma pack(4)
and ends with
# pragma pack( pop, before_embrowser_pack )

### Distribution

Create a directory for your instance of Opera, %OPERADIR%. Add an operadef6.ini file that contain the section and entry :
[System]
Multi user=0
this will make Opera create a profile directory within the %OPERADIR% directory. Otherwise a profile directory will be created with files in the current users application data area (I.e. "C:\Documents and Settings\%USERNAME%\Application Data\Opera\Opera\profile" where the logic is %APPLICATIONDATA%\Opera\%{foldername of directory with Opera.exe}%\profile)

In your %OPERADIR% you need to create two directories:

-defaults
-skin
that contain the following files
defaults/
embedded_mouse.ini - define mouse actions
embedded_menu.ini - define all menus, also context
embedded_keyboard.ini - define keyboard input
standard_toolbar.ini - define toolbars in Opera-drawn ui

skin/
windows_skin.zip - the default skin set if no other is specified in operadef6.ini. Most widgets are platform native. (Scrollbars, comboboxes, radiobuttons, checkboxes.)
standard_skin.zip - includes a superset of all graphics used. If an image is missing from the specified skin the image is gotten from this file.

This gives you a standard working setup.

All ini files is in human readable form, text, and can be modified with a text editor. An example from embedded_menu.ini:
[Link Popup Menu] Item, 67389 = Open link Item, 50216 = Copy link --------------------1 Submenu, 157500, Encoding Menu = Submenu, 162000, Quick Preferences Menu = Show popup menu, "Quick Preferences Menu"
This is the context menu when right clicking on a link. The section name [Link Popup Menu] is fixed for Opera lookup. The first "Item" is just a type id, item is a standard menu item. The number following, here ie. 67389, is a lookup number from our stringtable in the language file. You can also use "hardcoded" strings here, but that is not recommended. Following the "item" description is an action.
If this section is removed from embedded_menu.ini there is no context menu shown when right clicking links.
The above mentioned configuration files can be stored anywhere on the system if pointed to in operadef6.ini:
[User Prefs] Mouse Configuration=defaults/embedded_mouse.ini Keyboard Configuration=defaults/embedded_keyboard.ini Toolbar Configuration=defaults/standard_toolbar.ini Menu Configuration=defaults/embedded_menu.ini

#### Main Opera directory contents

This is the directory mentioned above as %OPERADIR%

Program modules
Filename | Use | Format | Overwritten on install | Additional info
--- | --- | --- | --- | ---
chartables.bin | Contains tables for Unicode support | binary | yes | -
es262-32.dll | ECMAScript (JavaScript) module. | binary | yes | -
opera.dll | Main library including HTML renderer, mailer, UI, image decoders | binary | yes | -
OUniAnsi.dll | Unicode to Ansi conversion library for Win9x | binary | yes | -
xmlparse.dll | XML parser module. | binary | yes | -
zip.dll | Zip module. | binary | yes | Not required in 9.0
dialog.ini | Dialog definitions | text/plain | yes | -
english.lng | Language strings | text/plain | yes | This is a fallback if no other is specified in the operadef6.ini or opera6.ini
xmlentities.ini | XML doc type map | text/plain | yes | Says which XML document types to map to which local DTD-replacement files
html40_entities.dtd | XHTML DTD replacement | text/plain | yes | Minimal XHTML DTD replacement that declares character entities that authors seem to assume are declared

Profile

The following four directories will be created in the profile root: acpo, cache4, images and sessions.

##### acpo directory contents

Acpo files
Filename | Use | Format | Overwritten on install | Additional info
--- | --- | --- | --- | ---
acpoxxxxxx.bin | These files contain info about the ads shown in the ad window. See www.opera.com/docs/ads/ for a detailed explanation. | binary | no | -

##### Cache4

Cache files
Filename | Use | Format | Overwritten on install | Additional info
--- | --- | --- | --- | ---
dcache4.url | Index of the cached files; without index the files are useless. dcache4.url is updated on closing Opera. | binary | no | Cache settings can be found at "File > Preferences > History and Cache". These files are removable, but to empty the cache, you can also use 'Delete private data' from the File menu in Opera. Editable with Joe Segur's Opera File Explorer, a third party helper app.
oprxxxxx.xxx | These are the cached files. | Same as the original files | no

##### Sessions

Window setups
Filename | Use | Format | Overwritten on install | Additional info

##### Images

Images
Filename | Use | Format | Overwritten on install | Additional info
--- | --- | --- | --- | ---
*.* | User stored images and favicons | image/png (image/jpeg, image/gif or image/x-windows-bmp are also possible | no | -

#### Profile directory contents

Stored usage data
Filename | Use | Format | Overwritten on install | Additional info
--- | --- | --- | --- | ---
adprefs.ini | Configurations for banner. | text/plain | no |
cookies4.dat | Stores cookies. | binary (see description) | no | File is removable, but to delete all cookies at once, you can also use 'Delete private data' from the File menu in Opera.
download.dat | Stores information about recent downloads, as seen in the Transfer window. Useful to keep track of downloaded files and enable the 'Resume download' function. | binary | no | File is removable, but to delete all download data, you can also use 'Delete private data' from the File menu in Opera. There's an opera.ini-only setting for the number of days to keep download data available: `LogEntryDaysToLive=` under [User Prefs].
global.dat | Stores the global history. Properties for the Global history are set from "File > Preferences > History and cache". URLs stored in the Global history are used for the auto complete function, and can be checked from "Window > Special > History". | text/plain | no | File is removable, but to clear the global history, you can also use 'Delete private data' from the File menu in Opera. Easy to edit with Joe Segur's Opera File Explorer, a third party helper app.
opcacrt6.dat | Stores CA Certificates | binary | no | More info about certificates.
opcert6.dat | Stores Personal Certificates and private keys | binary | no | More info about certificates.
opera.dir | Stores 'Go to page' dialog history. This can be accessed from the Go To dialog, and clicking on the arrow to the right of the input field. | text/plain | no | File is removable, but to clear the 'Go To' dialog history, you can also use 'Delete private data' from the File menu in Opera.
oprand.dat | Random seed file, used for generating keys | binary | no | -
opssl6.dat | Stores SSL preferences | binary | no | -
jswarn.dir | Not used and will be phased out. | text/plain | no | -
vlink4.dat | Stores visited links. | binary | no | File is removable, but to clear all visited links at once, you can also use 'Delete private data' from the File menu in Opera. Editable with Joe Segur's Opera File Explorer, a third party helper app.

#### Skin directory

This directory contains the default skin and fallback skin

Filename | Use | Format | Overwritten on install | Additional info
standard_skin.zip | Fallback skin, all images missing in other skins are fetched from this skinfile. | application/zip | yes |
windows_skin.zip | Default skin, uses system native widgets. | application/zip | yes |

Note: Edit the setting files externally only while EmBrowser is not running. All settings are flushed back to disk when EmBrowser exits.

### Java on Windows

Opera for Windows is using a Java runtime environment installed on your computer to run Java applets and to implement Netscape4 LiveConnect technology. Opera does not use the plug-in software that comes with the JRE installation, but loads the Java VM in its own fashion and uses JNI to communicate with the VM. Opera for Windows is able to use the runtime environments from Sun and IBM version 1.2 and upwards.

#### Finding the JRE

On Windows, Opera finds the JRE to use by searching through the registry entries that the JRE and JDK installations write to the registry. The search procedure described here is based on how it works in Opera 7.0 build 2312. This is the first build which search the Sun JDK registry entries. In general, Opera relies on the registry settings being correct. Typically, if the registry contains entries for a runtime that has been deleted, and Opera decides that this is the version it decides to use, Opera will not detect this and will try to load the VM from the path given in the registry. Starting the VM will then fail and Opera will not try to load the VM from another runtime.

Opera is able to detect and use the following runtimes:

- Sun JRE 1.2 and newer
- IBM JRE 1.2 and newer
- Sun JRE installed as a part of the Sun J2SDK 1.2 and newer

If there are more than one runtime environments detected by Opera, the following algorithm is used to decide which runtime to use:

1. First read in the CurrentVersion entry for:
   - HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime Environment (Sun JRE)
   - HKEY_LOCAL_MACHINE\SOFTWARE\IBM\Java2 Runtime Environment (IBM JRE)
   - HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit (Sun JDK)
2. Iterate through the registry subfolders for the Sun JRE. If the CurrentVersion for it is supported, and matches one of them, and that subfolder has a RuntimeLib value, that one is selected as the runtime to use.
3. Iterate through the registry subfolders for the IBM JRE. If the CurrentVersion for it is supported, and matches one of them, and that subfolder has a RuntimeLib value, that one is selected as the runtime to use.
4. Iterate through the registry subfolders for the Sun JDK. If the CurrentVersion for it is supported, and matches one of them, and that subfolder has a JavaHome value, jre\bin\client\jvm.dll or jre\bin\hotspot\jvm.dll (depending on the JDK version) is appended to the JavaHome to create the VM path and selected as the runtime to use.
5. If none of the above selected a runtime, then one of the runtimes that where iterated through with the newest version number is selected (If it's a supported version).

There is a [Java] section of the ini file to be used when using the native interface solution for applet loading. There are three settings:

- Opera ClassPath
- Security Policy
- Enabled

The "Opera ClassPath" is the path of the opera.jar file to be used. The "Security Policy" is the path to the opera.policy file that defines permissions for the opera.jar file. If these entries are omitted, Opera will use the following logic to search for opera.jar and opera.policy
%OPERADIR%\Classes\opera.jar
%OPERADIR%\Classes\opera.policy
Where %OPERADIR% is the directory where opera.dll is installed.
"Enabled" is a setting for turning Java on and off. Default is on.
Hence if the whole section is removed, Opera will try to find a compatible Java runtime and use it.

Example with absolute paths for opera.jar and opera.policy:

[Java] Opera ClassPath=D:/Program Files/Opera/Classes/opera.jar Security Policy=D:/Program Files/Opera/Classes/opera.policy Enabled=1
opera.policy grant example:
grant codeBase "file:/${browser.opera.classpath}" { permission java.security.AllPermission; };

## Special Issues for Embedding Opera 7.5 on the Macintosh Platform

### Operating System Support

Opera 7.5 works with Mac OS X 10.1 - 10.3 at the time this document was written. It is intended to work with later versions of Mac OS X, but various issues can occur with later versions due to Apple APIs changing. Contact your support representative or check on www.opera .com for information as newer Mac OS versions are released.

### Executable Format

Opera 7.5 uses the Mach-O executable format however, the EmBrowser API has been made such that CFM applications can embed Opera 7.5. This is facilitated with the use of a CFM shared library containing glue code which resides in the application bundle Opera.app/Contents/Mac OS. This facilitates backward compatibility for applications which embedded Opera 6.0x EmBrowser 2.0.

### Event Handlers

Opera registers Carbon Event handlers onto the window level. The host application should always register their own Carbon Event handlers before initializing Opera. This insures correct event propagation between the host application and Opera. The window has to be properly activated before the Carbon Event Dispatcher will dispatch events to the window. Improper window activation on the side of the host application can result in Opera not getting events.

### Java Support and Thread Issues

Java on Mac uses the JavaVM.framework (installed by default on all OSX versions) to get a VM capable of Java version 1.2 or newer. We use the JavaEmbedding API to embed Java applets in carbon controls and we're currently limited to Java version 1.3.1. This may change in the future.

LiveConnect is not working.

The opera.jar and opera.policy files are kept inside the application package and they need to be there in order for java to work properly. Both files are inside Opera.app/Contents/Resources/.

Apple's JavaEmbedding framework used by Opera for Java Applet support spawns many operating system threads. This is poor design on Apple's part, but unfortunately beyond Opera's control. It requires that the host application take certain precautions in making sure that if Java threads call back into event handlers that the event is captured and re-posted onto the main thread. Sample code for this can be found in WidgetApp.

### Backwards Compatibility Exceptions

One Macintosh specific data type was erroneously overlooked in the EmBrowser 2.0/Opera 6.03 distribution. There was a Rect as a parameter to the EmBrowserAppRequestNewBrowserProc. This has now been changed to an EmBrowserRect.

### Structure Alignment

Default Codewarrior. Standard PPC Struct alignment. Longs are 4 byte aligned and that is the reason this type has been used throughout the EmBrowser API. (No chars or shorts, which would be 2 byte aligned have been used in the API.)

### Distribution

Opera is a self-contained application bundle which is a drag-and-drop install not requiring any installation program. Application bundle technology is used by Opera in localized language support and selection among other things. Opera on the Macintosh is designed to be embedded in third party applications from the fully-installed application bundle. If a host application vendor wishes to pull Opera components apart and place them otherwise, special care must be taken to prevent unexpected side-effects or a partially disabled browser component.

Opera normally registers itself for some Mac OS X Services. If Opera is to be distributed inside another application bundle, make sure to remove the NSServices record from Opera.app/Contents/info.plist. Otherwise Mac OS will add items and keyboard shortcuts to the Services menu.

Opera Bundle Contents
Location | Filename(s) | Optional for Embedded | Additional info
--- | --- | --- | ---
Opera.app/Contents/Frameworks | * | No | No optional components in this folder.
Opera.app/Contents/MacOS | * | No | No optional components in this folder.
Opera.app/Contents/PlugIns | * | No | No optional components in this folder. Note: This is an extension to the print dialog and has nothing to do with Internet Plug-Ins.
Opera.app/Contents/Resources | chartables.bin | No | Conversiont o UTF-16. Without this file, even English pages will not be correct
Opera.app/Contents/Resources | default.adr | Yes | Default bookmarks
Opera.app/Contents/Resources/defaults | embedded_*.ini | No | Embedded keyboard, menu and mouse configuration files.
Opera.app/Contents/Resources/defaults | standard_*.ini | Yes | Desktop keyboard, menu and mouse configuration files.
Opera.app/Contents/Resources/defaults | mac_keyboard.ini | Yes | Keyboard input specification file
Opera.app/Contents/Resources | dialog.ini | No | Authentication dialogs, etc.
Opera.app/Contents/Resources/en.lproj | default.adr | Yes | Localized default bookmarks
Opera.app/Contents/Resources/en.lproj | en.lng | No | Contains English localized JavaScript, authentication dialogs, and load status strings for embedded instances of Opera.
Opera.app/Contents/Resources/en.lproj | search.ini | Yes |
Opera.app/Contents/Resources/en.lproj/Help | * | Yes | Browser help files
Opera.app/Contents/Resources | fastforward.ini | Yes | Mouse gestures will not work if this file is removed.
Opera.app/Contents/Resources | hhd.ssr | No* | Not required in 9.0
Opera.app/Contents/Resources/Images | operabanner.png | Yes |
Opera.app/Contents/Resources | *.icns | Yes |
Opera.app/Contents/Resources | opera.jar, opera.policy | Yes | Only optional if you do not plan on using Java in the browser component.
Opera.app/Contents/Resources/Skin | mac_skin.zip standard_skin.zip | No |
Opera.app/Contents/Resources/Styles | browser.css | No | (CSS files in the "Styles" directory not specifically listed in this table are optional.)
Opera.app/Contents/Resources/Styles | dir.css drives.css | No | Optional if local file browser is not to be used in the browser component.
Opera.app/Contents/Resources/Styles | user.css | No |
Opera.app/Contents/Resources/Styles | wml.css | No |

Files Created when Running Opera
Location | Description | Filename(s) | Additional info
--- | --- | --- | ---
~/Library/Preferences/Opera Preferences | Cookies | cookies4.dat vlink.dat |
~/Library/Preferences/Opera Preferences | Preferences | Opera 7 Preferences |
~/Library/Preferences/Opera Preferences | Bookmarks | Bookmarks |
~/Library/Preferences/Opera Preferences | Contacts | Contacts |
~/Library/Caches/Opera Cache/Cache ƒ | Opera Desktop Browser Cache | * |
~/Library/Preferences/Opera Preferences/<creator ID or PID > | Browser cache for host apps using EmBrowser API | * | Uses vendorDataID, 4 digit code, if specified (example for WidgetApp: params->vendorDataID = 'wApp'), otherwise PID of host application.

### Plug-ins

To add plug-ins to be used in Opera, simply add them to the Mac OS plug-in folder and re-start Opera. The folder is "/Library/Internet Plug-Ins" at the system-level or on a per-user basis in "~/Library/Internet Plug-Ins.

### Local File Browsing

Browsing local files has changed slightly between Opera 6 to Opera 7.5. In Opera 6 the volumename is part of the path, and with Opera 7.5, the root volume can be assumed.

Example in Opera 7.5:
file://localhost/Users/<username>/Desktop/Release%20Archive/EmBrowser%20Docs/EmBrowserDoc.html

Same Example In Opera 6:
file://localhost/<volumename>/Users/<username>/Desktop/Release Archive/EmBrowser Docs/EmBrowserDoc.html

## Data Types

The data types in EmBrowser API were chosen for as much consistency across platforms as possible. For simplicity and alignment, longs were chosen for most numeric and boolean values.

### String Formats:

Opera is a full UTF-16 enabled program, the string formats used in Opera are made up of null terminated strings of unsigned short values as specified in the UTF-16 spec. The types are EmBrowserChar and EmBrowserString for characters and strings respectively.

### Opaque Browser Types

EmBrowserRef: Represents a browser instance. This is a rectangular area of rendered content which will be placed in a platform window by the host application.
EmDocumentRef: Represents a browser document or frame/frameset. One EmBrowser can contain many documents.

### Opaque Browser Types - Added in EmBrowser version 3.0

EmCookieRef: A browser cookie.
EmHistoryRef: A browser history item representing previously visited pages.
EmThumbnailRef: A thumbnail image of a page of browser content. Thumbnails are native and temporary.
EmJavascriptObjectRef: A JavaScript object.

### Browser Structs

EmBrowserRect: A platform-independent rectangle.

EmBrowserInitParameterBlock: Initialization parameter block. Set of parameters and pointers which control how the embedded browser starts up.

### Browser Structs - Added in EmBrowser 3.0

EmJavascriptValue: Javascript value. Consists of a type (see EmJavascriptType) and a specific value depending on the type.

EmJavaScriptType: A JavaScript type.

> Possible values:

- emJavascriptNull: null
- emJavascriptUndefined: undefined
- emJavascriptBoolean: a truth value
- emJavascriptNumber: a floating point number
- emJavascriptString: a string (EmBrowserString)
- emJavascriptObject: an object (EmJavascriptObjectRef).

## Enumerated Types

EmLoadStatus: Browser loading status flags.

- emLoadStatusLoading: Page is busy loading.
- emLoadStatusLoaded: Not Busy. Load succeded.
- emLoadStatusFailed: Not Busy. Load failed.
- emLoadStatusStopped: Not Busy. Load stopped by request from user/host app.
- emLoadStatusEmpty: Not Busy. Nothing loaded (for instance a newly created widget).
- emLoadStatusUnknown: Unknown/other. Do not test on this, test on the values which have specific meanings.

  *** Added in EmBrowser 3.0

- emLoadStatusUploading: Busy performing upload.
- emLoadStatusCreated: Page is still busy loading. Document has been created and is available through a call on EmBrowserGetRootDocProc(). The JavaScript environment has been created. The normal status sequence is Loading, Created and finally Loaded.

EmThumbnailStatus: These represents return values from thumbnail API functions. Is a subset of values corresponding directly to EmBrowserStatus.

- emThumbnailNoErr: Same as emBrowserNoErr.
- emThumbnailOutOfMemoryErr: Same as emBrowserOutOfMemoryErr.
- emThumbnailGenericErr: Same as emBrowserGenericErr.

EmBrowserStatus: Return status for API functions.

- emBrowserNoErr: No error.
- emBrowserOutOfMemoryErr: Out of Memory.
- emBrowserGenericErr: Generic Error.
- emBrowserParameterErr: Invalid parameter specified.

EmJavascriptStatus: JavaScript function return status closely corresponding to EmBrowserStatus.

- emJavascriptNoErr: Same as emBrowserNoErr.
- emJavascriptOutOfMemoryErr: Same as emBrowserOutOfMemoryErr.
- emJavascriptGenericErr: Same as emBrowserGenericErr.
- emJavascriptParameterErr: Same as emBrowserParameterErr.
- emJavascriptCompilationErr: JavaScript would not compile.
- emJavascriptExecutionErr: JavaScript would not execute.

EmMouseCursor: Self explanatory values corresponding to standard mouse cursor shapes.

EmBrowserImageDisplayMode: Mode indicating the level of image display in the browser.

- emBrowserImageDisplayNone: Image display turned off.
- emBrowserImageDisplayAll: All cached images displayed.
- emBrowserImageDisplayLoaded: Display both cached and non-cached images.

EmBrowserOptions: Browser startup options. Controls whether certain facilities are turned on or off during browser start-up.

- emBrowserOptionUseDefaults: Default behavior.
- emBrowserOptionSilent: Inhibit dialogs from coming up on URL load. This prevents sheets and dialogs from coming up for cases in which the host application has placed a browser window in an offscreen location.
- emBrowserOptionNoContextMenu: Disables context menus.
- emBrowserOptionDisableAppkeys: Disables application keys. (On Windows this will mean that Opera will not process WM_APPCOMMAND messages.)

EmBrowserWindowOptions:

- emBrowserWindowOptionUseDefaults: Make and activate the window.
- emBrowserWindowOptionBackground: Make the window behind the current window.

EmBrowserURLOptions: Used to determine whether a page is fetched or the browser cache can be used (default).

- emBrowserURLOptionDefault: Default behavior.
- emBrowserURLOptionNoCache: Bypass the browser cache and fetch the entire page.

EmBrowserInitParams: Control whether or not font enumeration for all installed fonts is performed when Opera is started. (Introduced as a result of very slow start-up discovered on certain computers with hundreds of fonts installed.)

- emBrowserInitDefault: Enumerate fonts.
- emBrowserInitNoFontEnumeration: Do not enumerate fonts.

EmOperaSearchOptions: Options for searching a browser page. Mostly self-explanatory and correspond to typical options in a search dialog.

- emOperaSearchOptionUseDefaults
- emOperaSearchOptionCaseSensitive
- emOperaSearchOptionEntireWord
- emOperaSearchOptionFindNext
- emOperaSearchOptionUpwards: Only used with find next.

  *** Added in EmBrowser 3.0

- emOperaSearchOptionWrapSearch: Wrap around.

EmBrowserTextOptions: Used in the EmBrowserGetTextProc to determine which text to retrieve for a given EmBrowserRef.

- emBrowserURLText: Text of currently loaded/loading URL.
- emBrowserLoadStatusText: Load status text.
- emBrowserTitleText: Page title text.
- emBrowserMouseContextText: If the mouse is over a hyperlink, the text of that URL.
- emBrowserCombinedStatusText: If the user is over hypertext then show URL mouse context, if page is loading and the user in not over hypertext show page loading status. (This imitates IE browser control behavior.)

EmBrowserAppMessage: Notification messages informing the host application what is taking place inside the browser component. These are sent to the host application via the EmBrowserAppSimpleNotificationProc. All notifications are on a EmBrowserRef basis (as opposed to the higher granularity of having them on a per EmBrowserDoc basis.) This means that,

> Required: Host application must respond to the following messages in order for Opera to behave properly.

- emBrowser_app_msg_edit_commands_changed: This indicates that EmBrowserCanHandleMessageProc should be run and menu items on the edit menu in the host application should be updated accordingly.
- emBrowser_app_msg_request_focus: Opera requesting keyboard focus as a result of detected user action or user action required (such as an authentication dialog appearing during a page load.) Host application responds by sending TRUE to EmBrowserSetFocusProc or knowingly disables it by doing nothing.
- emBrowser_app_msg_going_away: Please remove all refs to the widget, it is going away.

  Optional: Host application can ignore these messages while still maintaining a reasonable level of browser function.

- emBrowser_app_msg_status_text_changed: Fired when mouse is moved over a link.
- emBrowser_app_msg_page_busy_changed: Fired when EmLoadStatus changed and can be retrieved using EmBrowserGetPageBusyProc.
- emBrowser_app_msg_progress_changed: Fired when load progress text has been changed and can be retrieved using EmBrowserGetTextProc.
- emBrowser_app_msg_url_changed: Fired when the URL has changed.
- emBrowser_app_msg_title_changed: Fired when the page title has changed.
- emBrowser_app_msg_security_changed: Fired when entering/exiting secure mode.
- emBrowser_app_msg_page_undisplay: Fired just before a page is unloaded.
- emBrowser_app_msg_phase_changed: Application has gone from uploading straight to downloading or vice versa (less likely) without any "loading stopped"
- emBrowser_app_msg_request_close: For example a JavaScript Window close
- emBrowser_app_msg_request_activation: JavaScript initiated.
- emBrowser_app_msg_request_raise = 1302: JavaScript initiated. Move higher in z-order.
- emBrowser_app_msg_request_lower = 1303: JavaScript initiated.Move lower in z-order.
- emBrowser_app_msg_request_show = 1304: JavaScript initiated.
- emBrowser_app_msg_request_hide = 1305: JavaScript initiated.
- emBrowser_app_msg_content_type_unknown: Obsloete.
- emBrowser_app_msg_content_type_unsupported: Obsolete.
- emBrowser_app_msg_protocol_unsupported: Content unsupported and host application can get the URL, and send it off to give another application or the OS a chance at opening the content.

EmBrowserMessage: Messages that the host application sends to the browser.

- emBrowser_msg_copy_cmd: Edit menu copy command, sent to the browser as it currently has focus.
- emBrowser_msg_paste_cmd: Edit menu paste command, sent to the browser as it currently has focus
- emBrowser_msg_cut_cmd: Edit menu cut command, sent to the browser as it currently has focus.
- emBrowser_msg_clear_cmd: Edit menu clear command, sent to the browser as it currently has focus.
- emBrowser_msg_select_all_cmd: Edit menu select all command, sent to the browser as it currently has focus.
- emBrowser_msg_undo_cmd: Edit menu undo command, sent to the browser as it currently has focus.
- emBrowser_msg_redo_cmd: Edit menu redo command, sent to the browser as it currently has focus.
- emBrowser_msg_quit_cmd: This is used to find out if currently present modal dialogs hinder the host application's ability to close the widget. It does not perform an actual "quit" of the browser component.
- emBrowser_msg_back: Standard browser "back" command.
- emBrowser_msg_forward: Standard browser "forward" command.
- emBrowser_msg_reload: Standard browser "reload" command.
- emBrowser_msg_stop_loading: Standard browser "stop" command.
- emBrowser_msg_homepage: Standard browser "back" command.
- emBrowser_msg_searchpage: Internet search page defined by the operating system. Not search in page.
- emBrowser_msg_has_document: Now a valid EmBrowserDoc has been associated with an EmBrowserRef
- emBrowser_msg_clone_window
- emBrowser_msg_print: Print the browser page. Should bring up approprite OS specific print dialog with options.

## Browser Instance APIs

All browser instance APIs take EmBrowserRef as the first input paramter, and return EmBrowserStatus, unless otherwise specified. All APIs are EmBrowser 2.0 unless otherwise specified.

### Creation and Deletion

EmBrowserCreateProc: Creates an instance of the embedded browser.

- Input: void pointer to screen port, EmBrowserOptions
- Output parameter: The newly created EmBrowserRef

EmBrowserInitLibraryProc: Initialize and start the embedded browser.

- Input: EmBrowserInitParameterBlock

EmBrowserShutdown: Releases all global structures, stops network activity and unregisters system callbacks.

EmBrowserDestroyProc: Destroys an instance of the embedded browser.

### Screen Port Management

EmBrowserSetPortLocationProc: Setting where Opera can draw in the window.

- Input: EmBrowserRect, void pointer to platform-specific window type.

EmBrowserGetPortLocationProc: Getting where Opera can draw in the window.

- Input/Output: Pointer to EmBrowserRect.

EmSetVisibilityProc: Setting whether Opera is visible or not. Opera should be set to invisible when it is not needed and/or when the host application is placed in the background.

- Input: Boolean for visible.

EmGetVisibilityProc: Query Opera as to visibility status.

- Output: Boolean for current visibility state.

EmBrowserScrollToSelectionProc: Scroll the browser to currently selected text. Has no effect if no text is selected.

### Basic Navigation

EmBrowserOpenURLProc: Open URL in browser. Note: EmBrowserURLOptions parameter added in API version 2.0

- Input: EmBrowserString containing the URL, and EmBrowserURLOptions.

### Properties

EmBrowserGetDLProgressNumsProc: Get download progress numbers.

- Output: Long size of the page remaining to be downloaded. -1 if the total size is unknown at the current stage. Long size of the page being downloaded. -1 if the size is unknown at the current stage.

EmBrowserGetPageBusyProc: Returns the current load status.

- Output: EmLoadStatus

EmBrowserGetSecurityDescProc: Returns the current security level on the page.

- Output: Boolean indicating if security is on or off, a long buffersize, and an EmBrowserString containing the description of active security.

EmBrowserGetTextProc: Get various text strings from the browser.

- Input: EmBrowserTextOptions, long buffer size.
- Output: EmBrowserString and long text length.

### Command Messages

EmBrowserCanHandleMessageProc: Query Opera to see if a message is currently available.

- Input: EmBrowserMessage

EmBrowserDoHandleMessageProc: Send a command message to Opera.

- Input: EmBrowserMessage.

### Miscellaneous

EmBrowserDrawProc: Force the Widget to draw itself. Only needed in special circumstances, as the widget is a self-drawing.

- Input: EmBrowserRect containing the region to update.

EmBrowserSetActiveProc: Inform the EmBrowser that it has become active, to activate forms controls, scrollbars or inactive to deactivate.

- Input: Boolean indicating active/inactive.

EmBrowserSetFocusProc: Inform the EmBrowser that it has received or lost keyboard focus.

- Input: Boolean indicating focus lost/gained.

EmBrowserSetZoomProc: Set zoom factor for EmBrowser, in per cent.

- Input: long zoom factor.

EmBrowserSetFallbackEncodingProc: Set default encoding, will be used if document doesn't supply an encoding.

- Input: EmBrowserString containing encoding.

EmBrowserSetUserStylesheetProc: Set the user stylesheet. Pass NULL to stop using custom stylesheet. Note: This API should take an EmBrowserRef as a first parameter, but it does not.

- Input: EmBrowserString containing the path to the file containing the stylesheet. This path is specified in platform specific manner.

*** APIs below added in EmBrowser 3.0

EmBrowserSetUILanguage: Set user interface language, otherwise it will default to the english.lng in the directory in which opera is located

- Input: EmBrowserString containing the full path to the language file.
- Remark: The language files can be placed anywhere on the system, including inside a bundle on Mac OS.
- Fallback: To return to the default English language you need to specify the full path to that file as well.

EmBrowserForceEncodingProc: Force encoding. This encoding _will_ be used in subsequent loads in the window.

- Input: EmBrowserString containing encoding.

EmBrowserSetSoundProc: Enable or disable sounds in browser and page.

- Input: Boolean to enable/disable sound on web pages.

EmBrowserGetZoomProc: Get zoom factor for EmBrowser, in per cent

- Output: Long containing zoom factor.

EmBrowserSetBrowserStylesheetProc: Set the browser stylesheet.

- Input: EmBrowserString containint style sheet path in platform format.

EmBrowserGetAltStylesheetCountProc: Get number of alternate stylesheets.

EmBrowserGetAltStylesheetTitleProc: Get alternate stylesheet title.

- Input: Long containing index, and long containing buffersize.
- Output: EmBrowserString containing at text buffer.

EmBrowserEnableAltStylesheetProc: Get alternate stylesheet title.

- Input: EmBrowserString containing title.

EmBrowserGetContentSizeProc: Get the width & height of the document (not the view).

- Input: Longs containing width and height.

EmBrowserGetScrollPosition: Get the the scroll position of the document

- Input: Longs containing x and y coordinates.

EmBrowserSetScrollPosition: Scroll document to given position.

- Input: Longs containing x and y coordinates.

## Document Instance APIs

All document instance APIs take EmDocumentRef as the first input paramter, and return EmBrowserStatus, unless otherwise specified. All APIs are EmBrowser 2.0 unless otherwise specified.

EmBrowserOpenURLinDocProc: Opens a URL in the given document on a page, essentially re-targeting a frameset.

- Input: EmBrowserString containing the URL and EmBrowserURLOptions.

EmBrowserGetSourceSizeProc: Get the size that will need to be allocated by the host for HTML source. Used in conjunction with EmBrowserGetSourceProc.

- Output: A long containing buffer size to allocate.

EmBrowserGetSourceProc: Get the HTML source for the page. Only works after the page is finished loading.

- Input: long containing buffer size, and an EmBrowserString containing the text buffer.

EmBrowserGetRootDocProc: Get root document for a given EmBrowserRef. Used in frameset traversal.

- Output: EmDocumentRef of the root document object.

EmBrowserGetURLProc: Get URL for a given document. Note: textLength parameter added in API version 2.0

- Input: Long containing buffer size allocated.
- Output: EmBrowserString containing the URL, and a long containing the actual buffersize.

EmBrowserGetNumberOfSubDocumentsProc: Get Number of sub-documents for a given document. Zero means document is not a frameset. Used in conjunction with EmBrowserGetSubDocuments for finding out how large of an array to allocate.

- Return value: Long containing number of sub-documents.

EmBrowserGetParentDocumentProc: Get parent for a given document. Null means this document is at the top of the structure.

- Output: EmDocumentRef containing the parent document object if one exists.

EmBrowserGetBrowserProc: Get EmBrowserRef in which a given document is contained.

- Output: EmBrowserRef.

EmBrowserGetSubDocumentsProc: Get all sub-documents and coordinates for a given document. Zero means document is not a frameset.

- Input: Long containing the number of documents.
- Output: A pointer to an array of EmDocumentRefs and a pointer to an array of EmBrowserRects.

*** APIs below added in EmBrowser 3.0

EmBrowserGetDocumentTitleProc: Get title of document.

- Input: Long containing buffer size.
- Output: EmBrowserString conaining the text buffer and a long containing the buffer size.

## Notifications

These methods are callbacks from Opera into the host application. All have EmBrowserRef as the first parameter. In the case of callbacks, "input" parameters are going to the host application and "output" parameters are manipulated by the host application before returning and allowing Opera to continue executing. Function pointers to the desired callbacks must be defined by the host application and placed in the EmBrowserAppNotification structure.

NOTE: During a callback, never call back into Opera unless it is a "get" function. Get functions are the only functions that can be guaranteed to work from a callback. All others should be avoided.

EmBrowserAppSimpleNotificationProc: General purpose Opera notifying the host application using messages.
Input: EmBrowserAppMessage.
EmBrowserAppBeforeNavigationProc: Hook for before loading the URL.

- Input: EmBrowserString containing the original destination URL.
- Output: EmBrowserString containing the new URL overridden by the host application. Note: The size of this set to be EmBrowserChar[4096], or 8k. (Adding an additional size parameter was not done to preserve backwards compatibility.)
- Return: True if host application wants the URL to load, false if host application wants to stop the URL load.

EmBrowserAppRequestNewBrowserProc: Ask host to create a new browser.

- Input: EmBrowserOptions,EmBrowserWindowOptions,EmBrowserRect containing location and bounds(width and height is size, top and left is window position), EmBrowserString containing destination URL.
- Output: EmBrowserRef newly created by the host application.

EmBrowserAppHandleUnknownProtocolProc: Handle protocols not supported by Opera such as news and mail. Optional, if not implemented, the browser will send an message to the Operating system to attempt to open an appropriate application.

- Input: EmBrowserString containng the URL.

EmBrowserAppRequestSetPositionProc: Asks the host application to move the window to the given coords. Return non-zero if successful. JavaScript is allowed to re-size browser windows. This gives the host application the opportunity to decide whether or not to allow this to take place. Return non-zero if successful.

- Input: Longs containing x and y coordinates.

EmBrowserAppRequestSetSizeProc: Asks the host application to resize the widget to the given size. Return non-zero if successful.

- Input: Longs containing width and height.

*** APIs below added in EmBrowser 3.0

EmBrowserAppJavascriptNotificationProc: Hook for before executing Javascript.

- Input: EmDocumentRef .

EmBrowserAppAfterNavigationProc: Hook for after navigation.

- Input: EmDocumentRef .

EmBrowserAppRequestSetCursorProc: Hook for setting the mouse cursor. Optional, if not implemented the widget will set all cursors.

- Input: EmDocumentRef .

EmBrowserAppAllowLocalFileURLProc: Hook for allowing the loading of a local file URL referred from within a document fetched from a server. Loading of local files referred from within a server document is normally not allowed because of security reasons.

- Input: EmBrowserString parameters containing the document URL and the local file url referred from within the document.
- Return: True if host application wants the local file URL to load, false if host application wants to avoid the local file URL load.

## Miscellaneous APIs

EmBrowserSearchInActiveDocumentProc: Search in document
typedef EmBrowserStatus (*EmBrowserSearchInActiveDocumentProc)(IN EmBrowserRef inst, IN const EmBrowserString pattern, EmOperaSearchOptions options);
EmBrowserSetFallbackEncodingProc: Set default encoding, will be used if document doesn't supply an encoding.
typedef EmBrowserStatus (*EmBrowserSetFallbackEncodingProc)(IN const EmBrowserString encoding);

### Memory Allocation

These functions were introduced for the primitive memory handling on MacOS 9 and are only present for backwards compatibility only. The function pointers are defined by the host application in the InitParamaterBlock, otherwise, Opera uses standard OS memory allocation.

AppMallocProc: Opera allocates memory via the host application.

- Input: Size of block to be allocated
- Output: Void pointer to allocated block.

AppFreeProc: Opera frees memory via the host application.

- Input: Void pointer to block to be de-allocated.
- Output: void.

AppReallocProc: Opera re-allocates memory via the host application.

- Input: Void pointer of block to be re-allocated, long containing new size.
- Output: void.

## Miscellaneous APIs - Added in EmBrowser 3.0

### Cookies

EmBrowserGetCookieListProc: Return list of cookies in the document.

- Output: EmCookieRef

EmBrowserGetCookieCountProc: Return the number of cookies registered for the document

- Input: EmBrowserString containing domain and an EmBrowserString conaining the path.

EmBrowserGetCookieNameProc: Get the name of the cookie.

- Input: EmCookieRef ref and a long containing the allocated buffer size.
- Output: An EmBrowserString containing the text buffer and a long containing actual buffer size.

EmBrowserGetCookieValueProc: Get the value of the cookie.

- Input: EmCookieRef ref and a long containing the allocated buffer size.
- Output: An EmBrowserString containing the text buffer and a long containing actual buffer size.

EmBrowserGetCookieExpiryProc: Get the expiry time of the cookie.

- Input: EmCookieRef ref.
- Returns: A long containing the expiry time.

EmBrowserGetCookieDomainProc: Get the domain of the cookie.

- Input: EmCookieRef ref and a long containing the allocated buffer size.
- Output: An EmBrowserString containing the text buffer and a long containing actual buffer size.

EmBrowserGetCookiePathProc: Get the path of the cookie.

- Input: EmCookieRef ref and a long containing the allocated buffer size.
- Output: An EmBrowserString containing the text buffer and a long containing actual buffer size.

EmBrowserGetCookieSecurityProc: Get the security state of the cookie. Return nonzero if cookie is secure.

- Input: EmCookieRef ref .
- Returns: A long containing the expiry time.

EmBrowserSetCookieRequestProc: Set a cookie. Fill in entire request: name, value and attributes.

- Input: EmDocumentRef , an EmBrowserString containing path and an EmBrowserString.

EmBrowserSetCookieValueProc: Set a cookie value. The request: name and attributes are subtracted from existing cookie.

- Input: An EmDocumentRef , an EmCookieRef ref and an EmBrowserString containing the value.

### History

EmBrowserGetHistoryListProc: Return the list of items in the current session's history.

- Input: EmBrowserRef
- Output: EmHistoryRef array

EmBrowserGetHistorySizeProc: Return the number of items in the current session's history.

- Input: EmBrowserRef.
- Output: Long number of items.

EmBrowserGetHistoryIndexProc: Return the index of the current position in the history list.

- Input: EmBrowserRef.
- Output: Long index number.

EmBrowserSetHistoryIndexProc: Set the index of the current position in the history list.

- Input: EmBrowserRef, long index number.

EmBrowserRemoveH istoryItemProc: Remove an item from the history list.

- Input: EmBrowserRef, long containing an index.

EmBrowserInsertHistoryItemProc: Insert an item in the history list.

- Input: EmBrowserRef, long containing an index, and EmHistoryRef.

EmBrowserAppendHistoryItemProc: Append an item to the history list.

- Input: EmBrowserRef and an EmHistoryRef.

EmBrowserAppendHistoryItemProc: Get title of the history item.

- Input: EmHistoryRef, a long containing buffer size.
- Output: An EmBrowserString containing a text buffer, and a long containing the length.

EmBrowserGetHistoryItemURLProc: Get url of the history item.

- Input: EmHistoryRef, a long containing buffer size.
- Output: An EmBrowserString containing a text buffer, and a long containing the length.

EmBrowserRemoveAllHistoryItemsProc: Remove all items from the history list.

- Input: An EmBrowserRef.

### Javascript

EmBrowserJSResultProc: Notification of the result of a javascript operation.

- Input: Void pointer containing clientData an EmJavascriptStatus status and an EmJavaScriptValue.

EmBrowserJSEvaluateCodeProc: Evaluate a string of JavaScript code in a document.

- Input: An EmDocumentRef doc, EmBrowserString containing code, an EmBrowserJSResultProc callback, and a void pointer to client data.

EmBrowserJSGetPropertyProc: Read the value of a property of an object.
typedef EmJavascriptStatus (*EmBrowserJSGetPropertyProc)(IN EmDocumentRef doc, IN EmJavascriptObjectRef object, IN EmBrowserString propertyName,
IN EmBrowserJSResultProc callback /* can be NULL */, IN void *callbackClientData /* can be NULL */);
EmBrowserJSSetPropertyProc: Write a value to a property of an object.

- Input: An EmDocumentRef, EmJavascriptObjectRef , EmBrowserString containing a property name, an EmJavascriptValue *value, an EmBrowserJSResultProc callback and a void pointer to callback client data.

EmBrowserJSCallMethodProc: Call a method on an object.

- Input: An EmDocumentRef, EmJavascriptObjectRef, an EmBrowserString containing the method name, an unsigned containing a count of arguments, an EmJavaScriptValue array containg the arguments, an EmBrowserJSResultProc callback, and a void pointer to callback client data.

EmBrowserJSProtectObjectProc: Protect a javascript object (increasing its reference count by one).

- Input: An EmJavascriptObjectRef object

EmBrowserJSUnprotectObjectProc: Unprotect a javascript object (decreasing its reference count by one).

- Input: An EmJavascriptObjectRef object

EmBrowserJSMethodCallProc: Hook for function call to functions created with EmBrowserJSCreateMethodProc.

- Input:Void pointer to client data, an EmDocumentRef, an EmJavascriptObjectRef, an unsigned containing an arguments count, and an EmJavascriptValue array containing arguments.
- Output: EmJavascriptValue *returnValue);

EmBrowserJSCreateMethodProc: Create a method.
Input: An EmDocumentRef an EmJavascriptObjectRef, an EmBrowserJSMethodCallProc, and a void pointer to callback client data

### Thumbnail

EmBrowserThumbnailResultProc: Notification of the result of a thumbnail operation.

- Input: A void pointer to the image data, an EmThumbnailStatus status, and an EmThumbnailRef.

EmBrowserThumbnailRequestProc: Request creation of a thumbnail of a web page.

- Input: An EmBrowserString containing the URL, longs containing width, height and scale, and an EmBrowserThumbnailResultProc callback.
- Output: An EmThumbnailRef.

EmBrowserThumbnailKillProc: Kill a thumbnail request (when you do not want more updates).

- Input: EmThumbnailRef.

### Plugin

EmBrowserUsePluginPathProc: Use plugin path

- Input: An EmBrowserRef and an EmBrowserString containing the plug-in path.

### Properties

EmBrowserGetULProgressProc: Get upload progress numbers.

- Input: EmBrowserRef inst,
- Output: Longs containing the number of bytes that has been uploaded, and the size of the page being uploaded. -1 if the size is unknown at the current stage

EmBrowserGetDLProgressProc: Get download progress numbers. Modified interface.

- Input: EmBrowserRef inst
- Output: Longs containing he number of bytes that has been downloaded, and the size of the page being downloaded. -1 if the size is unknown at the current stage

### Image Display

EmBrowserSetImageDisplay: Set the image display mode.

- Input: EmBrowserRef and an EmBrowserImageDisplayMode.

enum { emBrowserImageDisplayNone = 0, emBrowserImageDisplayAll = 1, emBrowserImageDisplayLoaded = 2 }; typedef long EmBrowserImageDisplayMode;

Where emBrowserImageDisplayNone will supress all images, emBrowserImageDisplayAll will show all images and emBrowserImageDisplayLoaded will only show images that is in cache.

EmBrowserGetImageDisplay: Get the image display mode.

- Input: EmBrowserRef.
- Output: EmBrowserImageDisplayMode.

### Visibility of visited links

EmBrowserSetVisLinksProc: Disable or enable the visibility of visited links

- Input: A boolean flag for turning visibility on or off.

## Miscellaneous

### Proxy servers

Proxy servers are configured in the settings file, operadef6.ini (for more information look at profiles), like this:

[Proxy] Use HTTP=1 Use HTTPS=1 Use FTP=1 Use GOPHER=0 Use WAIS=0 Use Automatic Proxy Configuration=0 HTTPS Server=https.proxy.server:1080 FTP Server=ftp.proxy.server:1080 Gopher Server=gopher.proxy.server:1080 WAIS Server=wais.proxy.server:1080 Automatic Proxy Configuration URL=automatic.proxy.configuration.url Enable HTTP 1.1 for proxy=0 No Proxy Servers=*.opera.com,*.support.opera.com No Proxy Servers Check=1 HTTP Server=http.proxy.server:1080

[Proxy]
Entry: | Description:
--- | ---
Use HTTP=1 | Flag for using HTTP-proxy. Is integer with default TRUE
Use HTTPS=0 | Flag for setting HTTPS-proxy active. Is write only integer
Use FTP=1 | Is integer with default TRUE
Use Gopher=1 | Flag for using Gopher-proxy. Is integer with default ""
Use WAIS=1 | Flag for setting WAIS-proxy active. Is integer with default TRUE
HTTP Server= | Is string with default "" port number is after : ie. proxy.com:1081
HTTPS Server= | Is string with default "" port number is after : ie. proxy.com:1081
FTP Server= | FTP proxy server. Is string with default "" port number is after : ie. proxy.com:1081
Gopher Server= | Gopher server. String with default "" port number set after : ie. proxy.com:1081
WAIS Server= | Address of WAIS server. Is string with default ""
No PROXY Servers= | List of server to not go through server, comma separated. Is string with default ""
No PROXY Servers Check=1 | Enable list of no proxy list. Is integer with default TRUE
Proxy Complete Failure Retry Time | Dependant on unimplemented code, auto proxy configuration. Is integer with default 0.
Proxy FallBackPolicy | Dependant on unimplemented code, auto proxy configuration. Is integer with default 0
Proxy Single Failure Retry Time | Dependant on unimplemented code, auto proxy configuration. Is integer with default 0
Proxy TimeOut | Dependant on unimplemented code, auto proxy configuration. Is integer with default 0
Use FTP | Flag for using FTP-proxy. Is write only integer.
Use Proxy On Local Names Check | Flag for accessing local machines through proxy. Is integer with default FALSE

If proxy configuration is omitted from the settings file the system settings are used as fallback proxy configuration.

For more details on proxy server settings read this page on Opera's support pages.

### Cache

As with proxy servers the cache directory and settings will follow the embrowser component, and is configurable via the settings file operadef6.ini.

[User Prefs] Turbo Mode=1 Max Direct History Lines=200 Max Global History Lines=500 Automatic RAM Cache=1 Cache Directory4=%ProfileDir%\Cache4 [Cache] Document=2000 Figure=2000 Cache Docs=1 Cache Figs=1 Always Check Redirect Images=0 Always Check Redirect=0 [Disk Cache] Size=10000 Docs Exp Days=0 Docs Exp Hours=0 Docs Exp Minutes=5 Figs Exp Days=0 Figs Exp Hours=5 Figs Exp Minutes=0 Other Exp Days=0 Other Exp Hours=5 Other Exp Minutes=0 Docs Modification=2 Figs Modification=2 Other Modification=2

[Cache]
Entry: | Description: | configure from UI:
--- | --- | ---
Document=2000 | Size of document cache, in kB. Is integer with default 500 | Preferences > History and Cache
Figure=2000 | Size of image cache. Is integer with default 500 | Preferences > History and Cache
Cache Docs=1 | Cache flag for documents. (Is documented in detail, standard Help). Is integer with default TRUE | Preferences > History and Cache
Cache Figs=1 | Cache flag for images. (Is documented in detail, standard help). Is integer with default TRUE | Preferences > History and Cache
Always Check Redirect=0 | Always check redirect on documents. (Is documented in standard Help). Is integer with default TRUE | Preferences > History and Cache
Always Check Redirect Images=0 | Always check redirect on images. (Is documented in standard Help.) Is integer with default TRUE | Preferences > History and Cache

[Disk Cache]
Entry: | Description: | configure from UI:
--- | --- | ---
Size H=0 | Used for calculating the size of disk cache larger than 64k. (size h*64k). Is integer with default 0 | no
Cache Docs=1 | Flag for disk cache, documents. Is integer with default TRUE | All entries: Preferences > History and Cache
Cache Figs=1 | Flag for disk image caching. Is integer with default TRUE
Cache Other=1 | Flag for disk cache for other content. Is integer with default TRUE
Empty On Exit=0 | Flag for empty cache on exit. Is integer with default FALSE
Docs Exp Days=0 | Cache expire time for documents. Is integer with default 0
Docs Exp Hours=5 | Cache expire time for documents. Is integer with default 5
Docs Exp Minutes=0 | Cache expire time for documents. Is integer with default 0
Figs Exp Days=1 | Expire images in cache, day value. Is integer with default 0
Figs Exp Hours=0 | Expire images in cache, hour value. Is integer with default 5
Figs Exp Minutes=0 | Expire images in cache, minutes value. Is integer with default 0
Other Exp Days=5 | Expire other in cache, days value. Is integer with default 0
Other Exp Hours=5 | Expire other in cache, hour value. Is integer with default 5
Other Exp Minutes=0 | Expire other in cache, minutes value. Is integer with default 0
Size=6000 | is integer with default 2000. Disk cache size in kilobytes.
Docs Modification=0 | Check for modication flag. Is integer with default TIME. ALWAYS 0 NEVER 1 TIME 2
Figs Modification=0 | Check for modication flag. Is integer with default TIME. ALWAYS 0 NEVER 1 TIME 2
Other Modification=0 | Check for modication flag. Is integer with default TIME. ALWAYS 0 NEVER 1 TIME 2

Automatic Ram Cache will use 10% of the physical memory size for ram cache.

For more details on cache settings see Opera's support pages

### Adding plug-ins

Opera scans the plugin directories specified in the opera.ini file on startup and registers new ones, if any:

    [User Prefs]
    Plugin Path=Plugins;Program\Plugins

Plugin Path can contain absolute or relative, to the location of Opera.dll, directories.

To use plugins in the Embrowser component you can also supply the library with a plugin path via EmBrowserUsePluginPathProc that contain the plugin(s) you want to use. For example if Flash is to be used on Windows, you need to supply a directory with the npswf32.dll file via EmBrowserUsePluginPathProc.

The following plugin files that are distributed with Opera on Win32 are:

    plugdef.dll (Opera Default Plugin, shows a push button on EMBED content without a known plugin)
    npswf32.dll (Macromedia Shockwave Flash)

### Local file URLs and security policy

EmBrowserAppAllowLocalFileURLProc() can be used by the host application to allow the loading of a local file URL referred from within a document fetched from a server.

A local file URL will get loaded for HTML elements with attributes like SRC and HREF set to for instance file://C:/foo.bar

Examples are:

    <BGSOUND src="file://C:/test.wav">

    <DIV id='b' style='color: #008000; background-image: url(file://C:/test.gif); text-align: justify'>
    Text inside div b
    </DIV>

    <EMBED name="FlashPlayer" width="400" height="300" type="application/x-shockwave-flash"
    pluginspage="http://www.macromedia.com/go/getflashplayer" src="file://C:/foo.swf" quality="high">
    </EMBED>

    <OBJECT data="file://C:/foo.swf" type="application/x-shockwave-flash">
    </OBJECT>

    <FRAME name="fixed" src="file://C:/test.jpg">

    <IFRAME id="myIFrame" src="file://C:/test-iframe.html"
    align="right" frameborder="1" height="500" width="500" marginHeight="5" marginWidth="5">
    </IFRAME>

    <IMG src="file://C:/test.jpg">

    <HEAD>
    <LINK id="myLinkStylesheet" title="myTitle" rel="stylesheet" type="text/css" href="file://C:/test.css">
    </HEAD>

    <SCRIPT type="text/javascript" src="file://C:/Source/jstest/regression-lib/testbase.js">
    </SCRIPT>

Loading of local files like .exe and .bat will not result in automatically execution. If such files are referred from within the FRAME or the IFRAME element, the download dialogue is activated. If such files are referred from within the EMBED or the OBJECT element, and the mime type is associated with an existing plugin, the file content is streamed to the plugin. If such files are referred from within the IMG element, a broken image logo is shown. For IMG, BGSOUND, LINK and SCRIPT, the file is loaded, but the file type cannot be handled, and the file is ignored.

User/application defined protocols like "photoshop://" or "sam://" can only be handled if the protocol is defined in the Preferences setting as a trusted protocol.

## Last Updated

2006-05-04 / Johan Borg