Acorn Plug-In Protocol Functional Specification

1. Document Status
2. Issue / revision History

3. Overview
4. Outstanding issues
5. Technical Background
6. User Interface
7. Programmer's Interface
   1. Invocation
   2. Shutdown
   3. Plug-in death
   4. Browser death
   5. Window events
   6. Data pointers
   7. Stream protocol
   8. System variables
   9. The OBJECT tag
   10. Helper applications
   11. Help protocol
   12. About plug-in
8. Data interchange
   1. Message_PlugIn_Open (&4D540)
   2. Message_PlugIn_Opening (&4D541)
   3. Message_PlugIn_Close (&4D542)
   4. Message_PlugIn_Closed (&4D543)
   5. Message_PlugIn_Reshape (&4D544)
   6. Message_PlugIn_Reshape_Request (&4D545)
   7. Message_PlugIn_Focus (&4D546)
   8. Message_PlugIn_Unlock (&4D547)
   9. Message_PlugIn_Stream_New (&4D548)
   10. Message_PlugIn_Stream_Destroy (&4D549)
   11. Message_PlugIn_Stream_Write (&4D54A)
   12. Message_PlugIn_Stream_Written (&4D54B)
   13. Message_PlugIn_Stream_As_File (&4D54C)
   14. Message_PlugIn_URL_Access (&4D54D)
   15. Message_PlugIn_Notify (&4D54E)
   16. Message_PlugIn_Status (&4D54F)
   17. Message_PlugIn_Busy (&4D550)
   18. Message_PlugIn_Action (&4D551)
   19. Message_PlugIn_Abort (&4D552)
9. Data formats
   1. API versions
10. External dependencies
11. Acceptance test
12. Non compliances
13. Development test strategy

14. Glossary
15. References
    1. Director Player Software Functional Specification
    2. Java Software Functional Specification
    3. [NC] Browser Software Functional Specification
    4. Acorn Nested Window Manager Functional Specification
    5. Wimp message protocol
    6. Wimp Help protocol

The World Wide Web is gradually being extended to offer better support for embedding multimedia data inside Web pages. A well-established mechanism known as "helpers" allows a browser to delegate the display of unsupported data types to other applications. However, the helper application displays this data independently, usually in its own window.

The idea of a "plug-in" is to integrate the display of such data into the WWW browser's own window. A number of proposed HTML extensions are being promoted, such as <APPLET> (by Sun for Java), <EMBED> (by Netscape) and <OBJECT> (by W3C).

This protocol is described from the point of view of a web browser and plug-in however it is applicable to any application that needs to embed another application's windows within its own.

There are no outstanding issues.

This model does not fit well with RISC OS practices. It does not have a standard scheme for DLLs, and the alternative - using relocatable modules - is not practical for very large playback engines for systems like Java and Director. Therefore plug-ins are implemented as separate tasks, with a special message protocol between the browser and the plug-in to permit communication and control.

In order to display the data inside the browser's own window, the plug-in needs to be made responsible for updating a certain portion of the browser's work area. This could be done by the browser instructing the plug-in to redraw parts of the window. However, this approach is rejected because it introduces significant differences between a plug-in and a normal application. Instead, we utilise a new facility added to the Window Manager, whereby windows can be created "inside" a parent window. The Window Manager takes care of event distribution to the plug-in, and also ensures that the "child" window is in a fixed position relative to the work-area of the parent - so the plug-in's display area will be scrolled within the browser window if the user manipulates the browser window's scrollbars.

There is no user interface component to this specification.

A plug-in accepts one or more types of data, specified using normal RISC OS filetypes. It is the responsibility of the browser to map MIME types to RISC OS filetypes.

Just as other RISC OS applications may be "single document" or "multiple document", a plug-in implementor may choose whether to handle multiple items at once or not. Ideally, plug-ins should be able to cope with multiple pieces of data, potentially owned by multiple client applications. However, for ease of implementation it may sometimes be preferred to restrict each instance of a plug-in to displaying one piece of data. In this case, were two such pieces of data to be displayed at once, it would be necessary to invoke the plug-in twice.

Invocation

1. Broadcast Message_PlugIn_Open, passing the filename and filetype of the data, and the parent window information. This message also contains an opaque 32 bit value known as the "browser instance handle". This is a word of significance to the browser, and might be different for each instance of a plug-in. The plug-in must always quote the correct browser instance handle to the browser in subsequent messages.

2. If a Message_PlugIn_Opening is received in reply, an existing invocation of a suitable plug-in has agreed to handle the data. The Message_PlugIn_Opening contains an opaque word value, known as the "plug-in instance handle", which together with the task handle of the plug-in task uniquely identifies the piece of data. The browser remembers both of these values for use in future messages.

3. If no task responds to Message_PlugIn_Opening, the browser attempts to launch the appropriate plug-in. This is done by looking for an environment variable called Alias$@PlugInType_xxx where xxx is the hexadecimal type value. If this variable is not found, no suitable plug-in is available, and the browser regards the attempt to display the data as unsuccessful. If the variable is found, then the browser launches it by calling Wimp_StartTask.

4. The result of Wimp_StartTask is the task handle of the new invocation of the plug-in. As soon as Wimp_StartTask returns, the browser re-broadcasts the Message_PlugIn_Open message.

5. Normally, the plug-in accepts this message and replies with Message_PlugIn_Opening, containing a plug-in instance handle as described above.

6. If no reply was forthcoming, the browser assumes that for some reason the plug-in was unable to load the data, and it regards the attempt to display this data as unsuccessful. This might be because the data is malformed, erroneous or of an incompatible version to that expected by the plug-in, or it might be because of some unexpected eventuality (out of memory, etc). If a detailed failure message is to be issued to the user, it is the responsibility of the plug-in to do this.

   If further data of the same type needs to be displayed, either simultaneously or sequentially, then the browser should repeat the whole process starting with the broadcast.

7. If the plug-in replies and so requests then the browser opens a data stream for the initial object being embedded and sends this data to the plug-in according to the plug-in stream protocol.

8. The plug-in examines the contents of the file that was named in the Message_PlugIn_Open message. This file contains all of the information from the OBJECT, EMBED or APPLET tag, and is used by the plug-in to initialise itself. The plug-in may have to fetch the contents of more URLs in order to do this; it may get the browser to do this on its behalf by using Message_PlugIn_URL_Access.

9. If during startup the plug-in encounters an unrecoverable error it tidies up after itself and sends a Message_PlugIn_Closed to the browser, setting a flag in the message to indicate that this is due to an error. The message may optionally include an error message for the browser to display.

Shutdown

1. Browser sends Message_PlugIn_Close directly to the plug-in task, passing the plug-in instance handle associated with the data.

2. Plug-in closes and deletes its window, cleans up state and data, etc.

3. Plug-in replies with Message_PlugIn_Closed.

4. Plug-in decrements its count of active objects. If the count is zero, it is free to exit if it wishes. A flag in the Message_PlugIn_Close acts as a hint to the plug-in as to whether the browser would like the plug-in to remain running or not, but the plug-in does not have to honour this if it does not want to.

Plug-in death

Browser death

Window events

The Window Manager's nested window mechanism handles all subwindow positioning issues automatically. If a browser window is closed, then the subwindow is removed from view, and is reinstated when the parent window is reopened. If the browser window is scrolled, the Window Manager ensures that the plug-in window stays at the same position relative to the browser's work area, if necessary it repositions the subwindow and clips it if it has scrolled partiallly or entirely out of view. Repositioning is done by the Window Manager without sending Open_Window_Request events to the plug-in.

If the plug-in receives a keypress or mouse button click that it does not want to handle, it must pass it on to the browser by means of Wimp_SendMessage. It must set the window handle field of the message to the handle of its parent window. Note that this should be used instead of Wimp_ProcessKey.

If the browser wishes to forcibly resize or reposition the subwindow, it sends a Message_PlugIn_Reshape to the plug-in, quoting the plug-in instance handle. The plug-in must honour this request by re-opening itself at the new position. The coordinates in this request are work-area coordinates of the parent window. The parent window handle in this message may be different to the original one. The plug-in should be prepared to check for this, and re-create its window as a child of the new parent if necessary.

If the plug-in wishes to alter its size, it cannot simply resize its window. Instead it must send a Message_PlugIn_Reshape_Request to the browser. The browser responds by reformatting the page (if necessary) and then replying with a suitable Message_PlugIn_Reshape. The plug-in must act on this in the normal way.

Data pointers

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 defined as being either offsets from the start of the message body (if less than 256) or as pointers to data held in shared memory (i.e. the RMA or a dynamic area). It is always the responsibility of the sender to free the memory used for any such pointers. The protocol is defined in such a way that there should always be a reply received or the message will be bounced by the Window Manager. In either case it is then safe for the sender to free the memory allocated.

However to avoid memory leaks it is recommended that careful track is kept of such pointers so that they can be freed when a plug-in instance is closed.

All strings must be null terminated but need not start at a word-aligned address.

Stream protocol

Some plug-ins may wish the browser to fetch data from the net for them rather than having to implement their own fetching code. A flexible interface is provided for this based, in part, on the API used in the de facto standard plug-in API created by Netscape, in order to facilitate porting plug-ins to RISC OS.

N.B. Take note of the non-compliances section.

There are several ways a stream can be instigated, as follows

1. The browser wishes to transfer the initial data which launched the plug-in
2. The plug-in requests some data be fetched for it with Message_PlugIn_URL_Access
3. The plug-in requests some data be posted for it with Message_PlugIn_URL_Access
4. The plug-in wishes to write directly to a browser window

Initial transfer

1. Browser fills in flags, mime type, stream data and sends Message_PlugIn_StreamNew.

2. The plug-in returns the same message

   • quoting the reference
   • filling in the plug-in stream instance handle
   • updating the stream mode (if necessary).

3. If mode is applicable

   1. Browser sends Message_PlugIn_Stream_Write
   2. Plug-in replies with Message_PlugIn_Stream_Written giving the number of bytes that is could process.
   This is repeated until all data is transferred or an error occurs.

4. Browser sends Message_PlugIn_Stream_Destroy with appropriate reason code.

Plug-in requests data be fetched or posted

1. Plug-in sends the Message_PlugIn_URL_Access message.
2. When data starts arriving we continue as initial transfer.

Plug-in write to browser

1. Plug-in fills in MIME type, target, plug-in stream instance and sends Message_PlugIn_Stream_New.

2. The browser returns the same message

   • quoting the reference
   • filling in the stream fields.

3. The plug-in writes data;

   • Plug-in sends Message_PlugIn_Stream_Write
   • Browser replies with Message_PlugIn_Stream_Written giving the number of bytes that it could process.

   This is repeated until all data is transferred or an error occurs.

4. Plug-in sends Message_PlugIn_Stream_Destroy with appropriate reason code.

System variables

For a plug-in yyyy whose file type is xxx the variables which the plug-in must set are:

yyyy$Dir

The application directory containing !Boot, !Run etc. files

PlugIn$Type_xxx

Name of plug-in for browser menu

Alias$@PlugInType_xxx

Command to run plug-in as a stand-alone application, no arguments

The plug-in can optionally set these variables:

PlugIn$About_xxx

The directory containing plug-in copyright details

If the plug-in is capable of being launched as a stand-alone application without the browser involvement it must define these variables:

File$Type_xxx

Up to 8 character name describing file format

Alias$@RunType_xxx

Command to run plug-in as a standalone application, takes filename as an argument

If the plug-in can also be used as a helper application then this variable must also be set:

Alias$@HelperType_xxx

Command to run plug-in as a helper application

For example a sample !Boot file might contain the following:

  Set Java$Dir         <Obey$Dir>
  Set File$Type_AE4    Java
  Set PlugIn$Type_AE4  Java
  Set PlugIn$About_AE4 <Java$Dir>.About

  SetMacro Alias$@RunType_AE4    /<Java$Dir>.!RunImage -standalone %%*0
  SetMacro Alias$@PlugInType_AE4 /<Java$Dir>.!RunImage -plug-in %%*0

If a file is embedded with APPLET, EMBED or OBJECT then the Alias$@PlugInType_xxx variable is used to start the application.

If a file is pointed to with an anchor (eg <A HREF="applets/myapplet.class">) then the file is downloaded and the Alias$@Runtype_xxx variable is used.

The OBJECT tag

Note that plug-ins can be launched from an OBJECT tag as well as EMBED or APPLET. When this happens there are some minor differences to the values in the parameter file. The following table also describes how the attribute names in the HTML tag get mapped to the entries in the parameters file:

Helper applications

This same interface is also used for helper applications. Helper applications are very like plug-ins except that they open their windows external to the parent rather than embedded in the parent's window. This means that they are not constrained to close down when the parent window is closed (e.g. when the browser follows a link to another page) but can still benefit from the communication protocols with the parent. There is a flag in Message_PlugIn_Opening to inform the parent whether a window was embedded or not.

When trying to launch a helper application the process described in the Invocation section is used except that if the initial Message_PlugIn_Opening is not claimed the system variable Alias$@HelperType_xxx is used to start the helper task.

Help protocol

A plug-in may support the Wimp Help protocol. If they do then help mesages are displayed in the browser status bar (if configured). Messages must be limited to at most 40 characters.

About plug-in

A plug-in may display a logo and some associated text (e.g. copyright information) in a browser's window at the user's request. The suggested URL for this is 'about:'. The system variable PlugIn$About_xxx points to a directory containing text files with optional image (PNG, GIF or JPEG) files.

Each file has a two digit reference number to allow a single plug-in to have multiple logos and copyright entries (e.g. each Replay codec). The file 'Aboutyy', where yy is the two digit reference number, contains the text suitable for inclusion inside a table cell of an HTML document. For each About file there is an optional image file, of the name 'yywwwwhhhh', where wwww and hhhh are each four digits for the size that the image will be scaled to (usually the same as the actual image size). It is strongly recommended that the width and height are specified, but a filename of just 'yy' is accepted.

If the plug-in has a single copyright message and logo, the filename 'About' can be used as a shortcut for 'About00'. The optional logo must still be called '00wwwwhhhh' or '00'.

It is the browser's responsibility to enumerate all the PlugIn$About_* system variables and compile an HTML document containing all available plug-in details.

Message &4D540: Message_PlugIn_Open

Sent by the browser to create a plug-in instance

Poll block

R1+16	Message_PlugIn_Open
R1+20 = flags:	bit	meaning if set
	0	Open the file as a helper (else open it as a plug-in)
	1-31	reserved (0)
R1+24	Reserved (0)
R1+28	Browser instance handle (provided by the browser)
R1+32	Parent window handle
R1+36	Bounding box in parent window's work area co-ordinates; 16 bytes (left, bottom, right, top).
R1+52	File type
R1+56	Filename (string_value)

Use

The file specified by "Filename" at R1+56 contains a series of parameters in the form of name-value pairs. This data is the list of attributes and parameters from the APPLET, OBJECT or EMBED tag - see their respective definitions. This data is used by the plug-in to understand what is being requested of it. There are more details in the Data formats section.

If bit 0 of the flags word at R1+20 is set then this is a request to open the file as a helper application, i.e. external to the parent application. In this case the bounding box (offset bytes 36 to 51) are invalid. The parent window handle may be valid or 0 depending on how the file is launched.

Message &4D541: Message_PlugIn_Opening

Sent by the plug-in task to say an instance has been created

Poll block

R1+12	my_ref field from Message_PlugIn_Open
R1+16	Message_PlugIn_Opening
R1+20 = flags:	bit	meaning if set
	0	Plug-in can accept input focus (else it cannot use input focus)
	1	Plug-in wants the code resource fetched for it (else it will fetch this itself)
	2	Plug-in wants the data resource fetched for it (else it will fetch this itself)
	3	Plug-in will delete the parameters file itself (else the browser should delete this file now)
	4	Plug-in has more work to do, keep showing a busy indicator in the browser (if appropriate)
	5	Plug-in does understand the PlugIn_Action message beyond only the STOP reason code
	6	Plug-in task has actually opened a helper window (else it embedded itself in the parent)
	7-31	reserved (0)
R1+24	Plug-in instance handle (invented by the plug-in)
R1+28	Browser instance handle (copied from the Message_PlugIn_Open)

Use

This is sent by the plug-in in response to Message_PlugIn_Open. Note that bit 6 of the flags word at R1+20 may indicate that the Plug-in opened a helper window even if the browser requested that it be embedded as a plug-in.

Message &4D542: Message_PlugIn_Close

Tell a plug-in instance to close down

Poll block

R1+16	Message_PlugIn_Close
R1+20 = flags:	bit	meaning if set
	0	Browser would also like plug-in to exit
	1-31	reserved (0)
R1+24	Plug-in instance handle to close
R1+28	Browser instance handle

Use

This message is sent by the browser to a plug-in, if it wants an instance of a plug-in to be closed down (e.g. because the browser window is being closed, or is moving to a new page). Bit 0 of the flags word at R1+20 may be set if the browser needs urgently to free up memory; it is a hint to the plug-in to free up as much memory itself as it can. Not all plug-ins will read this bit.

Message &4D543: Message_PlugIn_Closed

A plug-in [instance] has closed down

Poll block

R1+12	my_ref field from Message_PlugIn_Close, unless bit 1 of the flags word at R1+20 is set.
R1+16	Message_PlugIn_Closed
R1+20 = flags:	bit	meaning if set
	0	Plug-in itself will exit after this message
	1	The message is not in reply to a Message_PlugIn_Close (so R1+12 is irrelevant).
	2	There is an error message at R1+32 as detailed below.
	3-31	reserved (0)
R1+24	Plug-in instance handle of the closed instance
R1+28	Browser instance handle of the closed instance
If bit 2 of the flags word at R1+20 is set:
R1+32	Error number.
R1+36	Zero terminated message to be displayed by the browser (N.B. this message is always embedded here as the plug-in may be exitting itself).

Use

This message is usually sent as a reply to a Message_PlugIn_Close from the browser, and confirms that the requested instance has been closed down. It may also be sent if the plug-in should exit for its own reasons without the browser asking. An error which the browser should display will be embedded in the message at R1+32, if bit 2 of the flags word at R1+20 is set.

Message &4D544: Message_PlugIn_Reshape

Move or resize a plug-in instance

Poll block

R1+12	my_ref field from Message_PlugIn_Reshape_Request (if applicable)
R1+16	Message_PlugIn_Reshape
R1+20 = flags:	bit	meaning if set
	0-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
R1+32	Parent window handle
R1+36	Bounding box in parent window's work area co-ordinates; 16 bytes (left, bottom, right, top).

Use

This message is sent by a browser to a plug-in. The plug-in should move the specified instance to the specified position; this may involve resizing the embedded window.

Some plug-in types may want to resize the windows themselves (for example, some Java applets do this). In that case, they will send Message_PlugIn_Reshape_Request to the browser and it should reply with Message_PlugIn_Reshape once it has determined where the plug-in should be moved to (since the resizing may affect page formatting and therefore the coordinates of the embedded plug-in window). A plug-in should therefore not expect an immediate reply to the message.

Message &4D545: Message_PlugIn_Reshape_Request

A plug-in instance wants to resize

Poll block

R1+16	Message_PlugIn_Reshape_Request
R1+20 = flags:	bit	meaning if set
	0-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
R1+32	Width (in OS units)
R1+36	Height (in OS units)

Use

A plug-in may sometimes want to resize its embedded window. It sends this message to the browser when it does so. The browser should respond with Message_PlugIn_Reshape, though it may not do so immediately.

On sending this message a plug-in may immediately resize its window, or it may wait; this is undefined. The browser should not assume either. To be sure that the plug-in embedded window ends up in a sensible position, the browser must eventually reply to the message.

Message &4D546: Message_PlugIn_Focus

Move the input focus between plug-in and parent

Poll block

R1+16	Message_PlugIn_Focus
R1+20 = flags:	bit	meaning if set
	0-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle

Use

This message is used to transfer the input focus between a plug-in and its parent. It can be sent in either direction. If the recipient cannot or does not wish to accept the focus then it just ignores the message. Otherwise it should acknowledge the message with message type 19 to prevent it being bounced back to the originator.

Message &4D547: Message_PlugIn_Unlock

[Reserved]

Poll block

R1+16	Message_PlugIn_Unlock
R1+20 = flags:	bit	meaning if set
	0-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
R1+32	URL for which to unlock the cache file (string_value)

Use

This message is reserved, and should not be used.

Message &4D548: Message_PlugIn_Stream_New

Create a new stream

Poll block

R1+16	Message_PlugIn_Stream_New
R1+20 = flags:	bit(s)	meaning if set
	0-3	Stream type field: Value Meaning 0 Normal 1 Seek only 2 As file 3 As file only Other values are reserved, and must not be used.
	4	Stream is seekable
	5-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
R1+32	Plug-in stream instance handle
R1+36	Browser stream instance handle
R1+40	URL of stream source / destination (string_value)
R1+44	End of stream in bytes, or 0 if unknown
R1+48	Last modified date of URL (in Unix time)
R1+52	Notify data
R1+56	MIME type of URL (string_value)
R1+60	Window target (string_value)

Use

This message is part of the stream protocol as already described.

Message &4D549: Message_PlugIn_Stream_Destroy

Destroy a stream

Poll block

R1+16	Message_PlugIn_Stream_Destroy
R1+20 = flags:	bit(s)	meaning if set
	0-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
R1+32	Plug-in stream instance handle
R1+36	Browser stream instance handle
R1+40	URL of stream source / destination (string_value)
R1+44	End of stream in bytes, or 0 if unknown
R1+48	Last modified date of URL (in Unix time)
R1+52	Notify data
R1+56	Reason code: Code Meaning 0 Stream finished successfully 1 Stream finished due to an error 2 Stream finished due to user intervention Other values are reserved, and must not be used.

Use

This message is part of the stream protocol as already described.

Message &4D54A: Message_PlugIn_Stream_Write

Write data to a stream

Poll block

R1+16	Message_PlugIn_Stream_Write
R1+20 = flags:	bit(s)	meaning if set
	0-3	Data type field: Value Meaning 0 string_value 1 Anchor 2 File handle Other values are reserved, and must not be used.
	4-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
R1+32	Plug-in stream instance handle
R1+36	Browser stream instance handle
R1+40	URL of stream source / destination (string_value)
R1+44	End of stream in bytes, or 0 if unknown
R1+48	Last modified date of URL (in Unix time)
R1+52	Notify data
R1+56	Logical offset in stream of data
R1+60	Length of data
R1+64	Data pointer

Use

This message is part of the stream protocol as already described.

Message &4D54B: Message_PlugIn_Stream_Written

Accept data that was written to a stream

Poll block

R1+12	my_ref field from Message_PlugIn_Stream_Write
R1+16	Message_PlugIn_Stream_Written
R1+20 = flags:	bit(s)	meaning if set
	0-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
R1+32	Plug-in stream instance handle
R1+36	Browser stream instance handle
R1+40	URL of stream source / destination (string_value)
R1+44	End of stream in bytes, or 0 if unknown
R1+48	Last modified date of URL (in Unix time)
R1+52	Notify data
R1+56	Length of data consumed; less than zero if the plug-in experienced an error.

Use

This message is part of the stream protocol as already described.

Message &4D54C: Message_PlugIn_Stream_As_File

Send stream data as a file

Poll block

R1+16	Message_PlugIn_Stream_As_File
R1+20 = flags:	bit(s)	meaning if set
	0-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
R1+32	Plug-in stream instance handle
R1+36	Browser stream instance handle
R1+40	URL of stream source / destination (string_value)
R1+44	End of stream in bytes, or 0 if unknown
R1+48	Last modified date of URL (in Unix time)
R1+52	Notify data
R1+52	Filename of stream data (string_value)

Use

This message is part of the stream protocol as already described.

Message &4D54D: Message_PlugIn_URL_Access

Ask the browser to deal with a URL

Poll block

R1+16	Message_PlugIn_URL_Access
R1+20 = flags:	bit(s)	meaning if set
	0	Return a Message_PlugIn_Notify on completion.
	1	Fetch by POST, else fetch by GET.
	2	Should be 0 if bit 1 is unset. If bit 1 is set, bit 2 means POST a file if set, else POST a block of memory.
	3-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
R1+32	URL to access (string_value)
R1+36	Window target (string_value)
R1+40	Notify data to be returned (if bit 0 of the flags word at R1+20 is set)
R1+44	Length of data to be posted
If bit 2 of the flags word at R1+20 is set:
R1+48	Filename (string_value)
If bit 2 of the flags word at R1+20 is unset:
R1+48	Pointer to data (string_value)

Use

This message is sent by a plug-in to the browser, to ask it to deal with a URL in various ways. The plug-in may ask the browser to send it a notification message when it has completed whatever action is required on the URL.

If the window target is non-zero then the URL is fetched to the given window name. Otherwise, a stream is opened and the data is sent to the plug-in.

Message &4D54E: Message_PlugIn_Notify

Signal completion of handling a URL to a plug-in

Poll block

R1+16	Message_PlugIn_Notify
R1+20 = flags:	bit(s)	meaning if set
	0-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
R1+32	URL accessed (string_value)
R1+36	Reason for notify: Code Meaning 0 Stream finished successfully 1 Stream finished due to an error 2 Stream finished due to user intervention Other values are reserved, and must not be used.
R1+40	Notify data

Use

This is sent by the browser to the plug-in, because the plug-in requested it through a Message_PlugIn_URL_Access.

Message &4D54F: Message_PlugIn_Status

Send a status message to the browser

Poll block

R1+16	Message_PlugIn_Status
R1+20 = flags:	bit(s)	meaning if set
	0-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
R1+32	Status message (string_value)

Use

Requests that the parent display some information in its status bar, or similar. The message should be reasonably short.

Message &4D550: Message_PlugIn_Busy

Signal a plug-in state change to the parent

Poll block

R1+16	Message_PlugIn_Busy
R1+20 = flags:	bit(s)	meaning if set
	0	Plug-in is busy
	1	Word at R1+32 has some meaning, else ignore it.
	2-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
If bit 1 of the flags word at R1+20 is set:
R1+32	Plug-in's new state: Value Meaning 0 Stop 1 Play 2 Pause 3 Fast forward 4 Rewind 5 Record Other values are reserved, and must not be used.

Use

Requests that the parent display some indication of business (e.g. spinning logo, etc.). If the plug-in had set the busy bit in its Opening message then it should send this message with bit 0 of the flags word at R1+20 clear when it has finished its loading.

This is also used to notify the parent of any state change by the plug-in in case it needs to update any user interface.

Message &4D551: Message_PlugIn_Action

Send a command to a plug-in

Poll block

R1+16	Message_PlugIn_Action
R1+20 = flags:	bit(s)	meaning if set
	0-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle
If bit 1 of the flags word at R1+20 is set:
R1+32	State the plug-in should move to: Value Meaning 0 Stop 1 Play 2 Pause 3 Fast forward 4 Rewind 5 Record 6 Mute 7 Unmute Other values are reserved, and must not be used.

Use

This message is used for sending specific commands to a plug-in. Not all plug-ins will understand the commands sent.

The new state sent is the state the plug-in should enter. If it is already in that state then it should ignore the message.

After entering the state it should send back a Message_PlugIn_Busy confirming the new state, except for the Mute and Unmute actions.

Message &4D552: Message_PlugIn_Abort

Stop activity for a plug-in instance

Poll block

R1+16	Message_PlugIn_Abort
R1+20 = flags:	bit(s)	meaning if set
	0-31	reserved (0)
R1+24	Plug-in instance handle
R1+28	Browser instance handle

Use

This message is sent by the browser when the user clicks on the Stop icon (or performs its equivalent). The plug-in should stop as much of its activity as possible. Specifically, anything that updates the screen, anything that uses significant CPU time and anything that accesses the network.

Note that this message is sent to each plug-in instance individually and should be treated as such.

The file contains the concatenation of one or more binary records of the following form:

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 plug-in
• all the PARAM elements enclosed within it
• special parameters created by the browser

These parameters are passed exactly as seen in the HTML without any conversions. The data/url/ref distinction is as given in the DTD (for OBJECT attributes) or in the VALUETYPE attribute of the PARAM element.

The plug-in may implement its own URL fetching code, or it may have the browser fetch URLs on its behalf by issuing a Message_URL_Access message to the browser.

Special parameters are created by the browser (rather than being part of the object element). They are:

BASEHREF

(Mandatory)
The full URL of the document containing this object.

USERAGENT

(Mandatory)
The name of the browser.

UAVERSION

(Mandatory)
Version number of the browser (user agent) in format x.y. If the plug-in needs a specific browser feature it may refuse to initialise if this version is not high enough.

APIVERSION

(Mandatory)
Version number of this API in format x.y. Changes in x mean a major incompatible change in formats. If the plug-in doesn't understand this version it should refuse to initialise. Changes in y mean some new functionality introduced in a backwards compatible way.

BGCOLOR

(Optional)
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'.

API Versions

Released versions of this API about are listed below. A plug-in can use this information to alter its behaviour if used with an application supporting an older version of the protocol.

Version 1.00

Original plug-in specification (version 0.09). All messages up to and including STATUS. Supported by NCBrowser 1.06, for example.

Version 1.10

This specification. Adds BUSY, ACTION, ABORT messages and support flags. Adds Helper information. Supported by NCBrowser 1.07 and above, or Browse 1.27 and above, for example.

This specification relies on the existence of a Window Manager with nested window support.

The protocol must be able to cater for the needs of Shockwave and Java plug-ins.

At the time of writing, neither the NCBrowser nor Browse support all of the variations of the STREAM protocol. They do not support POSTing from a plug-in or streaming data from a plug-in to a browser window.

The protocol has been tested during the development testing of a browser and during the creation of plug-ins. Each plug-in listed in the acceptance criteria tested that its interactions with the browser through this protocol performed as expected by this specification. This included deliberately generating errors to check the error recovery of the plug-in and the browser.

Director Player Software Functional Specification

Document reference 2107,711 (covers Shockwave as well as Director Movies). Obtain through Developer Support.

Java Software Functional Specification

Document reference 2107,710. Obtain through Developer Support.

[NC] Browser Software Functional Specification

Obtain through Developer Support.

Acorn Nested Window Manager Functional Specification

Document reference 1215,401/FS.

Wimp message protocol

PRM Volume 3.

Wimp Help protocol

PRM Volume 3.