PlugIn Protocol Technical Details (changes)
Showing changes from revision #2 to #3:
Added | Removed | Changed
WindowManager
» Messages
» Message Codes
» PlugIn Protocol Technical Details
PlugIn Protocol Technical Details
PlugIn Protocol Data Formats
The Message_PlugIn_Open contains a filename that refers to a file of parameters and attributes. This plugin uses this information to locate the correct data, classes, implementation, etc.
The file contains the concatenation of one or more binary records of the form:
| Bytes | Purpose |
|---|---|
| 4 | Type of data |
| 4 | Size of record (without header): |
| (4+n+p) + (4+s+q) + (4+t+r) bytes | |
| 4 | Size of name (unpadded) |
| n | Name, padded to word boundary |
| 4 | Size of data (unpadded) |
| s | Data, padded to word boundary |
| 4 | Size of MIME type (unpadded) |
| t | MIME type, padded to word boundary |
Integers are stored in little-endian order. Flags (parameters with void value whose presence or absence only is significant) are represented by a parameter of type DATA with zero length.
The parameters include:
- All the attributes of the OBJECT (or other) element that references this plugin
- All the PARAM elements enclosed within it
- Special parameters created by the browser (rather than being part of the object element)
These parameters are passed exactly as seen in the HTML without any conversions. The data/URL/ref distinction is as given in the DTD (or OBJECT attributes) or in the VALUETYPE attribute of the PARAM element.
The plugin may implement its own URL fetching code, or it may have the browser fetch URLs on its behalf by issuing a Message_PlugIn_URLAccess message to the browser.
Plugin Data Types
The following tables details the data types:
| Value | Meaning |
|---|---|
| 0 | Terminator (this is the last word in the file) |
| 1 | Data from PARAM |
| 2 | URL from PARAM |
| 3 | Object ref from PARAM |
| 4 | Special parameter from browser |
Plugin Special Parameters
| Bytes | Purpose |
|---|---|
| BASEHREF | The full URL of the document containing this object |
| USERAGENT | The name of the browser |
| UAVERSION | Version number of the browser (user agent) in format ‘x.y’. If the plugin needs a specific browser feature, it may refuse to initialise if this version is not high enough |
| APIVERSION | Version number if the API in format ‘x.y’. Changes in x mean a major incompatible change in formats. If the plugin doesn’t understand this version it should refuse to initialise. Changes in y mean some new functionality introduced in a backwards compatible way |
| BGCOLOR | The background colour of the page, which can be used by the plug-in as the default background colour. The colour is passed in as a string in the format ‘BBGGRR00’ |
String_Value
Many of the strings passed around in this protocol are of unspecified size and may, especially in the case of URLs, be larger than could fit within the body of a Wimp message. Therefore, they are defined in this spec as string_values.
These are also used in the Browser spec and are defined as being either:
- if < 256, offsets from the start of the message body (+20 in messages)
- if > 256, pointers to data held in shared memory (e.g. the RMA or a dynamic area).
It is always the responsibility of the sender to free the memory used for any pointers after they are no longer required.
The protocol is defined in such a way that there should always be a reply received or the message will be bounced by the Wimp. In either case it is then safe for the sender to free the memory allocated.
See also
Social
and
ROOL Store
Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.