Opera Software

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:

Function Categories

Messages


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:

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:
  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:

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:

Enumerated Types

EmLoadStatus: Browser loading status flags.

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

EmBrowserStatus: Return status for API functions.

EmJavascriptStatus: JavaScript function return status closely corresponding to EmBrowserStatus.

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

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

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

EmBrowserWindowOptions:

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

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.)

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


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

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.


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

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.

EmBrowserInitLibraryProc: Initialize and start the embedded browser.

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.

EmBrowserGetPortLocationProc: Getting where Opera can draw in the window.

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.

EmGetVisibilityProc: Query Opera as to visibility status.

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

Properties

EmBrowserGetDLProgressNumsProc: Get download progress numbers.

EmBrowserGetPageBusyProc: Returns the current load status.

EmBrowserGetSecurityDescProc: Returns the current security level on the page.

EmBrowserGetTextProc: Get various text strings from the browser.

Command Messages

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

EmBrowserDoHandleMessageProc: Send a command message to Opera.

Miscellaneous

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

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

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

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

EmBrowserSetFallbackEncodingProc: Set default encoding, will be used if document doesn't supply an 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.

*** 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

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

EmBrowserSetSoundProc: Enable or disable sounds in browser and page.

EmBrowserGetZoomProc: Get zoom factor for EmBrowser, in per cent

EmBrowserSetBrowserStylesheetProc: Set the browser stylesheet.


EmBrowserGetAltStylesheetCountProc: Get number of alternate stylesheets.

EmBrowserGetAltStylesheetTitleProc: Get alternate stylesheet title.

EmBrowserEnableAltStylesheetProc: Get alternate stylesheet title.


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

EmBrowserGetScrollPosition: Get the the scroll position of the document

EmBrowserSetScrollPosition: Scroll document to given position.

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.

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

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

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

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

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.

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

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

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

 

*** APIs below added in EmBrowser 3.0

EmBrowserGetDocumentTitleProc: Get title of document.

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.

EmBrowserAppRequestNewBrowserProc: Ask host to create a new browser.

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.

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.

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

 

*** APIs below added in EmBrowser 3.0


EmBrowserAppJavascriptNotificationProc: Hook for before executing Javascript.


EmBrowserAppAfterNavigationProc: Hook for after navigation.

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

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.

 

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.


AppFreeProc: Opera frees memory via the host application.

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

Miscellaneous APIs - Added in EmBrowser 3.0

Cookies

EmBrowserGetCookieListProc: Return list of cookies in the document.

EmBrowserGetCookieCountProc: Return the number of cookies registered for the document

EmBrowserGetCookieNameProc: Get the name of the cookie.

EmBrowserGetCookieValueProc: Get the value of the cookie.

EmBrowserGetCookieExpiryProc: Get the expiry time of the cookie.

EmBrowserGetCookieDomainProc: Get the domain of the cookie.

EmBrowserGetCookiePathProc: Get the path of the cookie.

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

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

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

History

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

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

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

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

EmBrowserRemoveHistoryItemProc: Remove an item from the history list.

EmBrowserInsertHistoryItemProc: Insert an item in the history list.

EmBrowserAppendHistoryItemProc: Append an item to the history list.

EmBrowserAppendHistoryItemProc: Get title of the history item.

EmBrowserGetHistoryItemURLProc: Get url of the history item.

EmBrowserRemoveAllHistoryItemsProc: Remove all items from the history list.

Javascript


EmBrowserJSResultProc: Notification of the result of a javascript operation.

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


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.

EmBrowserJSCallMethodProc: Call a method on an object.

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

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

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

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.

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

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

Plugin

EmBrowserUsePluginPathProc: Use plugin path

Properties

EmBrowserGetULProgressProc: Get upload progress numbers.

EmBrowserGetDLProgressProc: Get download progress numbers. Modified interface.

Image Display

EmBrowserSetImageDisplay: Set the image display mode.

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.

Visibility of visited links

EmBrowserSetVisLinksProc: Disable or enable the visibility of visited links

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