[Table - 3 rows and 1 column] [Row 1, column 1] [Image] [Row 2, column 1] Acorn Plug-In Protocol Functional Specification [Row 3, column 1] [Image] Document Status [Table - 11 rows and 2 columns] [Row 1, column 1] Distribution:   [Row 1, column 2] General Release [Row 2, column 1] Title:   [Row 2, column 2] Acorn Plug-In Protocol Functional Specification [Row 3, column 1] Drawing Number:   [Row 3, column 2] 1116,010/FS [Row 4, column 1] Issue:   [Row 4, column 2] 2 [Row 5, column 1] Author(s):   [Row 5, column 2] Simon Middleton [Row 6, column 1]   [Row 6, column 2] Piers Wombwell [Row 7, column 1]   [Row 7, column 2] Andrew Hodgkinson [Row 8, column 1] Date:   [Row 8, column 2] 26/03/98 [Row 9, column 1] Revision:   [Row 9, column 2] 1.3 [Row 10, column 1] Change Number:   [Row 10, column 2] ECO 4049 [Row 11, column 1] Last Issue:   [Row 11, column 2] N/A Contents i. Document Status [Ref 1] ii. Issue / revision History [Ref 2] iii. Overview [Ref 3] iv. Outstanding issues [Ref 4] v. Technical Background [Ref 5] vi. User Interface [Ref 6] vii. Programmer's Interface [Ref 7] 1. Invocation [Ref 8] 2. Shutdown [Ref 9] 3. Plug-in death [Ref 10] 4. Browser death [Ref 11] 5. Window events [Ref 12] 6. Data pointers [Ref 13] 7. Stream protocol [Ref 14] 8. System variables [Ref 15] 9. The [Ref 16]OBJECT tag 10. Helper applications [Ref 17] 11. Help protocol [Ref 18] 12. About plug-in [Ref 19] viii. Data interchange [Ref 20] 1. Message_PlugIn_Open (&4D540) [Ref 21] 2. Message_PlugIn_Opening (&4D541) [Ref 22] 3. Message_PlugIn_Close (&4D542) [Ref 23] 4. Message_PlugIn_Closed (&4D543) [Ref 24] 5. Message_PlugIn_Reshape (&4D544) [Ref 25] 6. Message_PlugIn_Reshape_Request (&4D545) [Ref 26] 7. Message_PlugIn_Focus (&4D546) [Ref 27] 8. Message_PlugIn_Unlock (&4D547) [Ref 28] 9. Message_PlugIn_Stream_New (&4D548) [Ref 29] 10. Message_PlugIn_Stream_Destroy (&4D549) [Ref 30] 11. Message_PlugIn_Stream_Write (&4D54A) [Ref 31] 12. Message_PlugIn_Stream_Written (&4D54B) [Ref 32] 13. Message_PlugIn_Stream_As_File (&4D54C) [Ref 33] 14. Message_PlugIn_URL_Access (&4D54D) [Ref 34] 15. Message_PlugIn_Notify (&4D54E) [Ref 35] 16. Message_PlugIn_Status (&4D54F) [Ref 36] 17. Message_PlugIn_Busy (&4D550) [Ref 37] 18. Message_PlugIn_Action (&4D551) [Ref 38] 19. Message_PlugIn_Abort (&4D552) [Ref 39] ix. Data formats [Ref 40] 1. API versions [Ref 41] x. External dependencies [Ref 42] xi. Acceptance test [Ref 43] xii. Non compliances [Ref 44] xiii. Development test strategy [Ref 45] xiv. Glossary [Ref 46] xv. References [Ref 47] 1. Director Player Software Functional Specification [Ref 48] 2. Java Software Functional Specification [Ref 49] 3. [NC] Browser Software Functional Specification [Ref 50] 4. Acorn Nested Window Manager Functional Specification [Ref 51] 5. Wimp message protocol [Ref 52] 6. Wimp Help protocol [Ref 53] Issue / revision history This document has a fairly long history; originally it was an internal-only specification (2103,740); it later became available to developers in a revised form (2107,740 and recently 1116,010/FS issue 1) and is now on general release (1116,010/FS issue 2). [Table - 22 rows and 3 columns] [Row 1, column 1] 2107,740 issue 1 [Row 1, column 3] (Developers only) [Row 2, column 1] 0.01 [Row 2, column 2] 09/01/97 [Row 2, column 3] Created from 2103,740 and added BUSY notification protocol (SJM) [Row 3, column 1] 1.2 [Row 3, column 2] 06/02/97 [Row 3, column 3] New format (SJM) [Row 4, column 1] 1.3 [Row 4, column 2] 07/02/97 [Row 4, column 3] Fixed errors in Message numbers (SJM) [Row 5, column 1] 1.4 [Row 5, column 2] 14/02/97 [Row 5, column 3] Added PASSWORDS. Changed API version. Added Glossary (SJM) [Row 6, column 1] 1.5 [Row 6, column 2] 18/02/97 [Row 6, column 3] Changed PASSWORDS to file. Added Message_PlugIn_Action. Added Helper app info (SJM) [Row 7, column 1] 1.6 [Row 7, column 2] 24/02/97 [Row 7, column 3] Added ABORT message to replace some uses of STOP (SJM) [Row 8, column 1] 1.7 [Row 8, column 2] 24/02/97 [Row 8, column 3] Fixed error in states. Changed API info (SJM) [Row 9, column 1] 1.9 [Row 9, column 2] 26/02/97 [Row 9, column 3] Added mute (SJM) [Row 10, column 1] 1.12 [Row 10, column 2] 09/04/97 [Row 10, column 3] Added missing history comments for 1.10 and 1.11, updated with comments from SG. Added glossary, references and development test strategy. Added Helper launching system variable (SJM) [Row 11, column 1] 1.13 [Row 11, column 2] 11/04/97 [Row 11, column 3] Fixed typos after review (SJM) [Row 12, column 1] 1.14 [Row 12, column 2] 11/04/97 [Row 12, column 3] Fixed some links (SJM) [Row 13, column 1] 2.1 [Row 13, column 2] 11/04/97 [Row 13, column 3] Signed off, AMR allocated [Row 14, column 1] 3.1 [Row 14, column 2] 11/08/97 [Row 14, column 3] Few small changes; then signed off, ECO 3995 allocated [Row 15, column 1] 1116,010/FS issue 1 [Row 15, column 3] (Developers only) [Row 16, column 1] 1.0 [Row 16, column 2] 26/01/98 [Row 16, column 3] Added "About Plug-in" (PW) [Row 17, column 1] 1.1 [Row 17, column 2] 06/02/98 [Row 17, column 3] Added BGCOLOR special parameter (PW); AMR 4903 allocated [Row 18, column 1] 1116,010/FS Issue 2 [Row 18, column 3] (General release) [Row 19, column 1] 1.0 [Row 19, column 2] 20/02/98 [Row 19, column 3] HTML style changes for publishing on the Web; some clarifications here and there in the body content. Various minor 'tweaks' such as changing, for example, "Netscape" to read "Navigator". There are a few more in-document links to make finding things easier. Some typos corrected (e.g. 'data' changed to 'date'). A few history and references bits removed ready for general public release (that's why the revision list given here has gaps in it). [Row 20, column 1] 1.1 [Row 20, column 2] 23/02/98 [Row 20, column 3] AMR allocation details corrected in this history section [Row 21, column 1] 1.2 [Row 21, column 2] 25/02/98 [Row 21, column 3] ECO 4049 allocated. [Row 22, column 1] 1.3 [Row 22, column 2] 26/03/98 [Row 22, column 3] Created revision 1.3 purely to fix the erroneous reference to the Nested Wimp specification [Ref 54] which gave an incorrect drawing number. No ECO allocated for such a trivial change. Overview 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 (by Sun [Ref 55] for Java), (by Netscape [Ref 56]) and (by W3C [Ref 57]). 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. Outstanding issues There are no outstanding issues. Technical background Navigator for the Mac and Windows supports plug-ins in the form of dynamically loaded code resources (DLLs). On finding data of a type it cannot display itself, the browser seeks a DLL which is capable of handling it. If it finds one, it calls standard entry points in the DLL to get it to display the data in the browser's window. 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 [Ref 58], 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. User interface There is no user interface component to this specification. Programmer interface 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 Having determined the best RISC OS filetype for the data, the browser performs the following sequence of actions: 1. Broadcast Message_PlugIn_Open [Ref 59], 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 [Ref 60] 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 [Ref 61] 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 [Ref 62]. 9. If during startup the plug-in encounters an unrecoverable error it tidies up after itself and sends a Message_PlugIn_Closed [Ref 63] 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 When the browser wishes the data to be forgotten, for example when the user quits the browser or leaves the current page, the following actions are taken. If multiple pieces of data have been farmed out (to the same or multiple plug-ins) the sequence below is performed for each such piece of data. 1. Browser sends Message_PlugIn_Close [Ref 64] 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 [Ref 65]. 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 If the browser receives a Message_Task_CloseDown, it checks to see whether the exiting task was a plug-in that was currently displaying data on behalf of the browser. If so, all data being displayed by that plug-in is marked as undisplayable. The Window Manager has already deleted the child window(s) associated with the task. The browser might not issue any error in this case (for example, the NCBrowser does not); other possibilities are relaunching the plug-in or reporting the exit to the user. Browser death If the plug-in receives a Message_Task_CloseDown, it checks to see whether it is displaying data on behalf of the exiting task. If so, it deallocates any state or data associated with that task, and reduces its reference count by the correct amount. If the reference count reaches zero (i.e. the dead task was the only task using the plug-in), then the plug-in may exit if it wants to. 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 [Ref 66] 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 [Ref 67] 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 [Ref 68]. There are several ways a stream can be instigated, as follows A. The browser wishes to transfer the initial data which launched the plug-in B. The plug-in requests some data be fetched for it with Message_PlugIn_URL_Access [Ref 69] C. The plug-in requests some data be posted for it with Message_PlugIn_URL_Access D. 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 [Ref 70]. 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 [Ref 71] 2. Plug-in replies with Message_PlugIn_Stream_Written [Ref 72] 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 [Ref 73] with appropriate reason code. Plug-in requests data be fetched or posted 1. Plug-in sends the Message_PlugIn_URL_Access [Ref 74] 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 [Ref 75]. 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 [Ref 76] * Browser replies with Message_PlugIn_Stream_Written [Ref 77] 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 [Ref 78] 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 [Ref 79] 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 Set File$Type_AE4 Java Set PlugIn$Type_AE4 Java Set PlugIn$About_AE4 .About SetMacro Alias$@RunType_AE4 /.!RunImage -standalone %%*0 SetMacro Alias$@PlugInType_AE4 /.!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 ) 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 [Ref 80]. The following table also describes how the attribute names in the HTML tag get mapped to the entries in the parameters file: [Table - 2 rows and 2 columns] [Row 1, column 1] EMBED [Row 1, column 2] APPLET [Row 2, column 1] The SRC attribute is named DATA [Row 2, column 2] The ALT attribute is named STANDBY The CODE attribute is named CLASSID The value of CLASSID may not have the ".class" suffix The value of CLASSID may have a prefix "java:" 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 [Ref 81] 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 [Ref 82] 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. Data interchange The following new Wimp messages are defined. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D540: Message_PlugIn_Open [Row 2, column 1] Sent by the browser to create a plug-in instance Poll block [Table - 16 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Open [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0  [Row 5, column 3] Open the file as a helper (else open it as a plug-in) [Row 6, column 1]   [Row 6, column 2] 1-31  [Row 6, column 3] reserved (0) [Row 7, column 1] [Image] [Row 8, column 1] R1+24 [Row 8, column 2] Reserved (0) [Row 9, column 1] [Image] [Row 10, column 1] R1+28 [Row 10, column 2] Browser instance handle (provided by the browser) [Row 11, column 1] [Image] [Row 12, column 1] R1+32 [Row 12, column 2] Parent window handle [Row 13, column 1] R1+36 [Row 13, column 2] Bounding box in parent window's work area co-ordinates; 16 bytes (left, bottom, right, top). [Row 14, column 1] [Image] [Row 15, column 1] R1+52 [Row 15, column 2] File type [Row 16, column 1] R1+56 [Row 16, column 2] Filename (string_value [Ref 83]) 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 [Ref 84] 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. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D541: Message_PlugIn_Opening [Row 2, column 1] Sent by the plug-in task to say an instance has been created Poll block [Table - 17 rows and 3 columns] [Row 1, column 1] R1+12 [Row 1, column 2] my_ref field from Message_PlugIn_Open [Ref 85] [Row 2, column 1] [Image] [Row 3, column 1] R1+16 [Row 3, column 2] Message_PlugIn_Opening [Row 4, column 1] [Image] [Row 5, column 1] R1+20 = flags:  [Row 5, column 2] bit [Row 5, column 3] meaning if set [Row 6, column 1] [Image] [Row 7, column 1]   [Row 7, column 2] 0  [Row 7, column 3] Plug-in can accept input focus (else it cannot use input focus) [Row 8, column 1]   [Row 8, column 2] 1  [Row 8, column 3] Plug-in wants the code resource fetched for it (else it will fetch this itself) [Row 9, column 1]   [Row 9, column 2] 2  [Row 9, column 3] Plug-in wants the data resource fetched for it (else it will fetch this itself) [Row 10, column 1]   [Row 10, column 2] 3  [Row 10, column 3] Plug-in will delete the parameters file itself (else the browser should delete this file now) [Row 11, column 1]   [Row 11, column 2] 4  [Row 11, column 3] Plug-in has more work to do, keep showing a busy indicator in the browser (if appropriate) [Row 12, column 1]   [Row 12, column 2] 5  [Row 12, column 3] Plug-in does understand the PlugIn_Action message beyond only the STOP reason code [Row 13, column 1]   [Row 13, column 2] 6  [Row 13, column 3] Plug-in task has actually opened a helper window (else it embedded itself in the parent) [Row 14, column 1]   [Row 14, column 2] 7-31  [Row 14, column 3] reserved (0) [Row 15, column 1] [Image] [Row 16, column 1] R1+24 [Row 16, column 2] Plug-in instance handle (invented by the plug-in) [Row 17, column 1] R1+28 [Row 17, column 2] Browser instance handle (copied from the Message_PlugIn_Open [Ref 86]) Use This is sent by the plug-in in response to Message_PlugIn_Open [Ref 87]. 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. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D542: Message_PlugIn_Close [Row 2, column 1] Tell a plug-in instance to close down Poll block [Table - 9 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Close [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0  [Row 5, column 3] Browser would also like plug-in to exit [Row 6, column 1]   [Row 6, column 2] 1-31  [Row 6, column 3] reserved (0) [Row 7, column 1] [Image] [Row 8, column 1] R1+24 [Row 8, column 2] Plug-in instance handle to close [Row 9, column 1] R1+28 [Row 9, column 2] 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. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D543: Message_PlugIn_Closed [Row 2, column 1] A plug-in [instance] has closed down Poll block [Table - 18 rows and 3 columns] [Row 1, column 1] R1+12 [Row 1, column 2] my_ref field from Message_PlugIn_Close [Ref 88], unless bit 1 of the flags word at R1+20 is set. [Row 2, column 1] [Image] [Row 3, column 1] R1+16 [Row 3, column 2] Message_PlugIn_Closed [Row 4, column 1] [Image] [Row 5, column 1] R1+20 = flags:  [Row 5, column 2] bit [Row 5, column 3] meaning if set [Row 6, column 1] [Image] [Row 7, column 1]   [Row 7, column 2] 0  [Row 7, column 3] Plug-in itself will exit after this message [Row 8, column 1]   [Row 8, column 2] 1  [Row 8, column 3] The message is not in reply to a Message_PlugIn_Close (so R1+12 is irrelevant). [Row 9, column 1]   [Row 9, column 2] 2  [Row 9, column 3] There is an error message at R1+32 as detailed below. [Row 10, column 1]   [Row 10, column 2] 3-31  [Row 10, column 3] reserved (0) [Row 11, column 1] [Image] [Row 12, column 1] R1+24 [Row 12, column 2] Plug-in instance handle of the closed instance [Row 13, column 1] R1+28 [Row 13, column 2] Browser instance handle of the closed instance [Row 14, column 1] [Image] [Row 15, column 1] If bit 2 of the flags word at R1+20 is set: [Row 16, column 1] [Image] [Row 17, column 1] R1+32 [Row 17, column 2] Error number. [Row 18, column 1] R1+36 [Row 18, column 2] 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 [Ref 89] 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. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D544: Message_PlugIn_Reshape [Row 2, column 1] Move or resize a plug-in instance Poll block [Table - 13 rows and 3 columns] [Row 1, column 1] R1+12 [Row 1, column 2] my_ref field from Message_PlugIn_Reshape_Request [Ref 90] (if applicable) [Row 2, column 1] [Image] [Row 3, column 1] R1+16 [Row 3, column 2] Message_PlugIn_Reshape [Row 4, column 1] [Image] [Row 5, column 1] R1+20 = flags:  [Row 5, column 2] bit [Row 5, column 3] meaning if set [Row 6, column 1] [Image] [Row 7, column 1]   [Row 7, column 2] 0-31  [Row 7, column 3] reserved (0) [Row 8, column 1] [Image] [Row 9, column 1] R1+24 [Row 9, column 2] Plug-in instance handle [Row 10, column 1] R1+28 [Row 10, column 2] Browser instance handle [Row 11, column 1] [Image] [Row 12, column 1] R1+32 [Row 12, column 2] Parent window handle [Row 13, column 1] R1+36 [Row 13, column 2] 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 [Ref 91] 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. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D545: Message_PlugIn_Reshape_Request [Row 2, column 1] A plug-in instance wants to resize Poll block [Table - 11 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Reshape_Request [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0-31  [Row 5, column 3] reserved (0) [Row 6, column 1] [Image] [Row 7, column 1] R1+24 [Row 7, column 2] Plug-in instance handle [Row 8, column 1] R1+28 [Row 8, column 2] Browser instance handle [Row 9, column 1] [Image] [Row 10, column 1] R1+32 [Row 10, column 2] Width (in OS units) [Row 11, column 1] R1+36 [Row 11, column 2] 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 [Ref 92], 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. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D546: Message_PlugIn_Focus [Row 2, column 1] Move the input focus between plug-in and parent Poll block [Table - 8 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Focus [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0-31  [Row 5, column 3] reserved (0) [Row 6, column 1] [Image] [Row 7, column 1] R1+24 [Row 7, column 2] Plug-in instance handle [Row 8, column 1] R1+28 [Row 8, column 2] 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. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D547: Message_PlugIn_Unlock [Row 2, column 1] [Reserved] Poll block [Table - 10 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Unlock [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0-31  [Row 5, column 3] reserved (0) [Row 6, column 1] [Image] [Row 7, column 1] R1+24 [Row 7, column 2] Plug-in instance handle [Row 8, column 1] R1+28 [Row 8, column 2] Browser instance handle [Row 9, column 1] [Image] [Row 10, column 1] R1+32 [Row 10, column 2] URL for which to unlock the cache file (string_value [Ref 93]) Use This message is reserved, and should not be used. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D548: Message_PlugIn_Stream_New [Row 2, column 1] Create a new stream Poll block [Table - 23 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Stream_New [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit(s) [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0-3  [Row 5, column 3] Stream type field: [Table - 5 rows and 2 columns] [Row 1, column 1] Value [Row 1, column 2] Meaning [Row 2, column 1] 0 [Row 2, column 2] Normal [Row 3, column 1] 1 [Row 3, column 2] Seek only [Row 4, column 1] 2 [Row 4, column 2] As file [Row 5, column 1] 3 [Row 5, column 2] As file only Other values are reserved, and must not be used. [Row 6, column 1] [Image] [Row 7, column 1]   [Row 7, column 2] 4  [Row 7, column 3] Stream is seekable [Row 8, column 1]   [Row 8, column 2] 5-31  [Row 8, column 3] reserved (0) [Row 9, column 1] [Image] [Row 10, column 1] R1+24 [Row 10, column 2] Plug-in instance handle [Row 11, column 1] R1+28 [Row 11, column 2] Browser instance handle [Row 12, column 1] [Image] [Row 13, column 1] R1+32 [Row 13, column 2] Plug-in stream instance handle [Row 14, column 1] R1+36 [Row 14, column 2] Browser stream instance handle [Row 15, column 1] [Image] [Row 16, column 1] R1+40 [Row 16, column 2] URL of stream source / destination (string_value [Ref 94]) [Row 17, column 1] R1+44 [Row 17, column 2] End of stream in bytes, or 0 if unknown [Row 18, column 1] R1+48 [Row 18, column 2] Last modified date of URL (in Unix time) [Row 19, column 1] R1+52 [Row 19, column 2] Notify data [Row 20, column 1] [Image] [Row 21, column 1] R1+56 [Row 21, column 2] MIME type of URL (string_value [Ref 95]) [Row 22, column 1] [Image] [Row 23, column 1] R1+60 [Row 23, column 2] Window target (string_value [Ref 96]) Use This message is part of the stream protocol [Ref 97] as already described. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D549: Message_PlugIn_Stream_Destroy [Row 2, column 1] Destroy a stream Poll block [Table - 18 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Stream_Destroy [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit(s) [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0-31  [Row 5, column 3] reserved (0) [Row 6, column 1] [Image] [Row 7, column 1] R1+24 [Row 7, column 2] Plug-in instance handle [Row 8, column 1] R1+28 [Row 8, column 2] Browser instance handle [Row 9, column 1] [Image] [Row 10, column 1] R1+32 [Row 10, column 2] Plug-in stream instance handle [Row 11, column 1] R1+36 [Row 11, column 2] Browser stream instance handle [Row 12, column 1] [Image] [Row 13, column 1] R1+40 [Row 13, column 2] URL of stream source / destination (string_value [Ref 98]) [Row 14, column 1] R1+44 [Row 14, column 2] End of stream in bytes, or 0 if unknown [Row 15, column 1] R1+48 [Row 15, column 2] Last modified date of URL (in Unix time) [Row 16, column 1] R1+52 [Row 16, column 2] Notify data [Row 17, column 1] [Image] [Row 18, column 1] R1+56 [Row 18, column 2] Reason code: [Table - 4 rows and 2 columns] [Row 1, column 1] Code [Row 1, column 2] Meaning [Row 2, column 1] 0 [Row 2, column 2] Stream finished successfully [Row 3, column 1] 1 [Row 3, column 2] Stream finished due to an error [Row 4, column 1] 2 [Row 4, column 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 [Ref 99] as already described. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D54A: Message_PlugIn_Stream_Write [Row 2, column 1] Write data to a stream Poll block [Table - 22 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Stream_Write [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit(s) [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0-3  [Row 5, column 3] Data type field: [Table - 4 rows and 2 columns] [Row 1, column 1] Value [Row 1, column 2] Meaning [Row 2, column 1] 0 [Row 2, column 2] string_value [Ref 100] [Row 3, column 1] 1 [Row 3, column 2] Anchor [Row 4, column 1] 2 [Row 4, column 2] File handle Other values are reserved, and must not be used. [Row 6, column 1] [Image] [Row 7, column 1]   [Row 7, column 2] 4-31  [Row 7, column 3] reserved (0) [Row 8, column 1] [Image] [Row 9, column 1] R1+24 [Row 9, column 2] Plug-in instance handle [Row 10, column 1] R1+28 [Row 10, column 2] Browser instance handle [Row 11, column 1] [Image] [Row 12, column 1] R1+32 [Row 12, column 2] Plug-in stream instance handle [Row 13, column 1] R1+36 [Row 13, column 2] Browser stream instance handle [Row 14, column 1] [Image] [Row 15, column 1] R1+40 [Row 15, column 2] URL of stream source / destination (string_value [Ref 101]) [Row 16, column 1] R1+44 [Row 16, column 2] End of stream in bytes, or 0 if unknown [Row 17, column 1] R1+48 [Row 17, column 2] Last modified date of URL (in Unix time) [Row 18, column 1] R1+52 [Row 18, column 2] Notify data [Row 19, column 1] [Image] [Row 20, column 1] R1+56 [Row 20, column 2] Logical offset in stream of data [Row 21, column 1] R1+60 [Row 21, column 2] Length of data [Row 22, column 1] R1+64 [Row 22, column 2] Data pointer Use This message is part of the stream protocol [Ref 102] as already described. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D54B: Message_PlugIn_Stream_Written [Row 2, column 1] Accept data that was written to a stream Poll block [Table - 19 rows and 3 columns] [Row 1, column 1] R1+12 [Row 1, column 2] my_ref field from Message_PlugIn_Stream_Write [Ref 103] [Row 2, column 1] R1+16 [Row 2, column 2] Message_PlugIn_Stream_Written [Row 3, column 1] [Image] [Row 4, column 1] R1+20 = flags:  [Row 4, column 2] bit(s) [Row 4, column 3] meaning if set [Row 5, column 1] [Image] [Row 6, column 1]   [Row 6, column 2] 0-31  [Row 6, column 3] reserved (0) [Row 7, column 1] [Image] [Row 8, column 1] R1+24 [Row 8, column 2] Plug-in instance handle [Row 9, column 1] R1+28 [Row 9, column 2] Browser instance handle [Row 10, column 1] [Image] [Row 11, column 1] R1+32 [Row 11, column 2] Plug-in stream instance handle [Row 12, column 1] R1+36 [Row 12, column 2] Browser stream instance handle [Row 13, column 1] [Image] [Row 14, column 1] R1+40 [Row 14, column 2] URL of stream source / destination (string_value [Ref 104]) [Row 15, column 1] R1+44 [Row 15, column 2] End of stream in bytes, or 0 if unknown [Row 16, column 1] R1+48 [Row 16, column 2] Last modified date of URL (in Unix time) [Row 17, column 1] R1+52 [Row 17, column 2] Notify data [Row 18, column 1] [Image] [Row 19, column 1] R1+56 [Row 19, column 2] Length of data consumed; less than zero if the plug-in experienced an error. Use This message is part of the stream protocol [Ref 105] as already described. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D54C: Message_PlugIn_Stream_As_File [Row 2, column 1] Send stream data as a file Poll block [Table - 18 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Stream_As_File [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit(s) [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0-31  [Row 5, column 3] reserved (0) [Row 6, column 1] [Image] [Row 7, column 1] R1+24 [Row 7, column 2] Plug-in instance handle [Row 8, column 1] R1+28 [Row 8, column 2] Browser instance handle [Row 9, column 1] [Image] [Row 10, column 1] R1+32 [Row 10, column 2] Plug-in stream instance handle [Row 11, column 1] R1+36 [Row 11, column 2] Browser stream instance handle [Row 12, column 1] [Image] [Row 13, column 1] R1+40 [Row 13, column 2] URL of stream source / destination (string_value [Ref 106]) [Row 14, column 1] R1+44 [Row 14, column 2] End of stream in bytes, or 0 if unknown [Row 15, column 1] R1+48 [Row 15, column 2] Last modified date of URL (in Unix time) [Row 16, column 1] R1+52 [Row 16, column 2] Notify data [Row 17, column 1] [Image] [Row 18, column 1] R1+52 [Row 18, column 2] Filename of stream data (string_value [Ref 107]) Use This message is part of the stream protocol [Ref 108] as already described. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D54D: Message_PlugIn_URL_Access [Row 2, column 1] Ask the browser to deal with a URL Poll block [Table - 25 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_URL_Access [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit(s) [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0  [Row 5, column 3] Return a Message_PlugIn_Notify [Ref 109] on completion. [Row 6, column 1]   [Row 6, column 2] 1 [Row 6, column 3] Fetch by POST, else fetch by GET.  [Row 7, column 1]   [Row 7, column 2] 2 [Row 7, column 3] 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. [Row 8, column 1]   [Row 8, column 2] 3-31  [Row 8, column 3] reserved (0) [Row 9, column 1] [Image] [Row 10, column 1] R1+24 [Row 10, column 2] Plug-in instance handle [Row 11, column 1] R1+28 [Row 11, column 2] Browser instance handle [Row 12, column 1] [Image] [Row 13, column 1] R1+32 [Row 13, column 2] URL to access (string_value [Ref 110]) [Row 14, column 1] R1+36 [Row 14, column 2] Window target (string_value [Ref 111]) [Row 15, column 1] [Image] [Row 16, column 1] R1+40 [Row 16, column 2] Notify data to be returned (if bit 0 of the flags word at R1+20 is set) [Row 17, column 1] R1+44 [Row 17, column 2] Length of data to be posted [Row 18, column 1] [Image] [Row 19, column 1] If bit 2 of the flags word at R1+20 is set: [Row 20, column 1] [Image] [Row 21, column 1] R1+48 [Row 21, column 2] Filename (string_value [Ref 112]) [Row 22, column 1] [Image] [Row 23, column 1] If bit 2 of the flags word at R1+20 is unset: [Row 24, column 1] [Image] [Row 25, column 1] R1+48 [Row 25, column 2] Pointer to data (string_value [Ref 113]) 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. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D54E: Message_PlugIn_Notify [Row 2, column 1] Signal completion of handling a URL to a plug-in Poll block [Table - 14 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Notify [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit(s) [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0-31  [Row 5, column 3] reserved (0) [Row 6, column 1] [Image] [Row 7, column 1] R1+24 [Row 7, column 2] Plug-in instance handle [Row 8, column 1] R1+28 [Row 8, column 2] Browser instance handle [Row 9, column 1] [Image] [Row 10, column 1] R1+32 [Row 10, column 2] URL accessed (string_value [Ref 114]) [Row 11, column 1] [Image] [Row 12, column 1] R1+36 [Row 12, column 2] Reason for notify: [Table - 4 rows and 2 columns] [Row 1, column 1] Code [Row 1, column 2] Meaning [Row 2, column 1] 0 [Row 2, column 2] Stream finished successfully [Row 3, column 1] 1 [Row 3, column 2] Stream finished due to an error [Row 4, column 1] 2 [Row 4, column 2] Stream finished due to user intervention Other values are reserved, and must not be used. [Row 13, column 1] [Image] [Row 14, column 1] R1+40 [Row 14, column 2] 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 [Ref 115]. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D54F: Message_PlugIn_Status [Row 2, column 1] Send a status message to the browser Poll block [Table - 10 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Status [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit(s) [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0-31  [Row 5, column 3] reserved (0) [Row 6, column 1] [Image] [Row 7, column 1] R1+24 [Row 7, column 2] Plug-in instance handle [Row 8, column 1] R1+28 [Row 8, column 2] Browser instance handle [Row 9, column 1] [Image] [Row 10, column 1] R1+32 [Row 10, column 2] Status message (string_value [Ref 116]) Use Requests that the parent display some information in its status bar, or similar. The message should be reasonably short. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D550: Message_PlugIn_Busy [Row 2, column 1] Signal a plug-in state change to the parent Poll block [Table - 14 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Busy [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit(s) [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0 [Row 5, column 3] Plug-in is busy [Row 6, column 1]   [Row 6, column 2] 1 [Row 6, column 3] Word at R1+32 has some meaning, else ignore it. [Row 7, column 1]   [Row 7, column 2] 2-31  [Row 7, column 3] reserved (0) [Row 8, column 1] [Image] [Row 9, column 1] R1+24 [Row 9, column 2] Plug-in instance handle [Row 10, column 1] R1+28 [Row 10, column 2] Browser instance handle [Row 11, column 1] [Image] [Row 12, column 1] If bit 1 of the flags word at R1+20 is set: [Row 13, column 1] [Image] [Row 14, column 1] R1+32 [Row 14, column 2] Plug-in's new state: [Table - 7 rows and 2 columns] [Row 1, column 1] Value [Row 1, column 2] Meaning [Row 2, column 1] 0 [Row 2, column 2] Stop [Row 3, column 1] 1 [Row 3, column 2] Play [Row 4, column 1] 2 [Row 4, column 2] Pause [Row 5, column 1] 3 [Row 5, column 2] Fast forward [Row 6, column 1] 4 [Row 6, column 2] Rewind [Row 7, column 1] 5 [Row 7, column 2] 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. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D551: Message_PlugIn_Action [Row 2, column 1] Send a command to a plug-in Poll block [Table - 12 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Action [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit(s) [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0-31  [Row 5, column 3] reserved (0) [Row 6, column 1] [Image] [Row 7, column 1] R1+24 [Row 7, column 2] Plug-in instance handle [Row 8, column 1] R1+28 [Row 8, column 2] Browser instance handle [Row 9, column 1] [Image] [Row 10, column 1] If bit 1 of the flags word at R1+20 is set: [Row 11, column 1] [Image] [Row 12, column 1] R1+32 [Row 12, column 2] State the plug-in should move to: [Table - 9 rows and 2 columns] [Row 1, column 1] Value [Row 1, column 2] Meaning [Row 2, column 1] 0 [Row 2, column 2] Stop [Row 3, column 1] 1 [Row 3, column 2] Play [Row 4, column 1] 2 [Row 4, column 2] Pause [Row 5, column 1] 3 [Row 5, column 2] Fast forward [Row 6, column 1] 4 [Row 6, column 2] Rewind [Row 7, column 1] 5 [Row 7, column 2] Record [Row 8, column 1] 6 [Row 8, column 2] Mute [Row 9, column 1] 7 [Row 9, column 2] 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 [Ref 117] confirming the new state, except for the Mute and Unmute actions. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4D552: Message_PlugIn_Abort [Row 2, column 1] Stop activity for a plug-in instance Poll block [Table - 8 rows and 3 columns] [Row 1, column 1] R1+16 [Row 1, column 2] Message_PlugIn_Abort [Row 2, column 1] [Image] [Row 3, column 1] R1+20 = flags:  [Row 3, column 2] bit(s) [Row 3, column 3] meaning if set [Row 4, column 1] [Image] [Row 5, column 1]   [Row 5, column 2] 0-31  [Row 5, column 3] reserved (0) [Row 6, column 1] [Image] [Row 7, column 1] R1+24 [Row 7, column 2] Plug-in instance handle [Row 8, column 1] R1+28 [Row 8, column 2] 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. Data formats The Message_PlugIn_Open [Ref 118] contains a filename that refers to a file of parameters and attributes. The plug-in uses this information to locate the correct data, classes, implementation etc. The file contains the concatenation of one or more binary records of the following form: [Table - 6 rows and 2 columns] [Row 1, column 1] Record size [Row 1, column 2] Record contents [Row 2, column 1] 4 bytes [Row 2, column 2] Type: 0 = terminator (this is the last word in the file) 1 = data from PARAM 2 = URL from PARAM 3 = object ref PARAM 4 = special parameter from browser [Row 3, column 1] 4 bytes [Row 3, column 2] Size of record (without header): (4+n+p) + (4+s+q) + (4+t+r) bytes [Row 4, column 1] 4 bytes n bytes p bytes [Row 4, column 2] n = size of name (unpadded) Name Padding to word boundary [Row 5, column 1] 4 bytes s bytes q bytes [Row 5, column 2] s = size of data (unpadded) Data Padding to word boundary [Row 6, column 1] 4 bytes t bytes r bytes [Row 6, column 2] t = size of mime type (unpadded) Mime type Padding 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 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 [Ref 119] 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 [Ref 120] 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. External dependencies This specification relies on the existence of a Window Manager with nested window support. Acceptance test The protocol must be able to cater for the needs of Shockwave [Ref 121] and Java [Ref 122] plug-ins. Non-compliances At the time of writing, neither the NCBrowser nor Browse support all of the variations of the STREAM protocol [Ref 123]. They do not support POSTing from a plug-in or streaming data from a plug-in to a browser window. Development test strategy 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 [Ref 124] 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. Glossary [Table - 0 rows and 0 columns] [Row 1, column 1] API [Row 1, column 1] Application Programmer Interface. [Row 1, column 1] Applet [Row 1, column 1] Small application, usually written in Java, embedded in a web page. [Row 1, column 1] ARM [Row 1, column 1] Acorn RISC Machine OR Advanced RISC Machines Ltd. [Row 1, column 1] Cache [Row 1, column 1] Area of disk or memory used to store recently accessed files. [Row 1, column 1] Caret [Row 1, column 1] Text cursor. [Row 1, column 1] Codec [Row 1, column 1] COder-DECoder. [Row 1, column 1] Director Player [Row 1, column 1] MacroMedia multi-media animation player. [Row 1, column 1] DLL [Row 1, column 1] Dynamically linked library (loaded at runtime). [Row 1, column 1] Frame [Row 1, column 1] An independently scrollable portion of an HTML page. [Row 1, column 1] GUI [Row 1, column 1] Graphical User Interface. [Row 1, column 1] HTML [Row 1, column 1] HyperText Markup Language. [Row 1, column 1] HTML 4 [Row 1, column 1] The current base-line HTML standard. [Row 1, column 1] Java [Row 1, column 1] Machine independent interpreted programming language. [Row 1, column 1] MIME [Row 1, column 1] Multipurpose Internet Mail Extensions. [Row 1, column 1] NC [Row 1, column 1] Network Computer. [Row 1, column 1] OS [Row 1, column 1] Operating System. [Row 1, column 1] Plug-in [Row 1, column 1] A program that extends the browser by handling a particular type of file embedded in an HTML page. [Row 1, column 1] PRM [Row 1, column 1] Programmers Reference Manual. [Row 1, column 1] RAM [Row 1, column 1] Random Access Memory. [Row 1, column 1] RISC [Row 1, column 1] Reduced Instruction Set Computer. [Row 1, column 1] RISC OS [Row 1, column 1] Acorn's operating system, the basis of RISC OS. [Row 1, column 1] ROM [Row 1, column 1] Read Only Memory. [Row 1, column 1] Shockwave [Row 1, column 1] MacroMedia multi-media browser plug-in player. [Row 1, column 1] Sprite [Row 1, column 1] An Acorn proprietary bitmap graphics file format. [Row 1, column 1] SWI [Row 1, column 1] Software Interrupt. [Row 1, column 1] UI [Row 1, column 1] User Interface. [Row 1, column 1] URL [Row 1, column 1] Uniform Resource Locator (HTML link). [Row 1, column 1] Wimp [Row 1, column 1] Colloquialism for Window Manager. References The following references may be of interest: 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 [Ref 125] Document reference 1215,401/FS. Wimp message protocol PRM [Ref 126] Volume 3. Wimp Help protocol PRM Volume 3. home [Ref 127] - manual [Ref 128] - downloads [Ref 129] - f.a.q [Ref 130] - feedback [Ref 131] hints and tips [Ref 132] - specifications [Ref 133] - other sites [Ref 134] - site map [Ref 135] [Table - 0 rows and 0 columns] [Row 1, column 1] Last updated 26 March 1998 — Site comments? EMail webmaster@acorn.com [Ref 136] © Acorn Computers Limited, 1997 [Ref 137] [Row 1, column 1] [Valid HTML 4.0] [Ref 138] ============================================================================== References in this document: 1. http://www.acorn.com/browser/plug-in/funcspec.html#dost 2. http://www.acorn.com/browser/plug-in/funcspec.html#irhi 3. http://www.acorn.com/browser/plug-in/funcspec.html#overview 4. http://www.acorn.com/browser/plug-in/funcspec.html#outstanding 5. http://www.acorn.com/browser/plug-in/funcspec.html#technical 6. http://www.acorn.com/browser/plug-in/funcspec.html#user 7. http://www.acorn.com/browser/plug-in/funcspec.html#programmer 8. http://www.acorn.com/browser/plug-in/funcspec.html#programmer_invocation 9. http://www.acorn.com/browser/plug-in/funcspec.html#programmer_shutdown 10. http://www.acorn.com/browser/plug-in/funcspec.html#programmer_plug-in_death 11. http://www.acorn.com/browser/plug-in/funcspec.html#programmer_browser_death 12. http://www.acorn.com/browser/plug-in/funcspec.html#programmer_window_events 13. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 14. http://www.acorn.com/browser/plug-in/funcspec.html#streams 15. http://www.acorn.com/browser/plug-in/funcspec.html#variables 16. http://www.acorn.com/browser/plug-in/funcspec.html#programmer_object_tag 17. http://www.acorn.com/browser/plug-in/funcspec.html#programmer_helper_applications 18. http://www.acorn.com/browser/plug-in/funcspec.html#programmer_help_protocol 19. http://www.acorn.com/browser/plug-in/funcspec.html#programmer_about_plug-in 20. http://www.acorn.com/browser/plug-in/funcspec.html#interchange 21. http://www.acorn.com/browser/plug-in/funcspec.html#message_open 22. http://www.acorn.com/browser/plug-in/funcspec.html#message_opening 23. http://www.acorn.com/browser/plug-in/funcspec.html#message_close 24. http://www.acorn.com/browser/plug-in/funcspec.html#message_closed 25. http://www.acorn.com/browser/plug-in/funcspec.html#message_reshape 26. http://www.acorn.com/browser/plug-in/funcspec.html#message_reshape_request 27. http://www.acorn.com/browser/plug-in/funcspec.html#message_focus 28. http://www.acorn.com/browser/plug-in/funcspec.html#message_unlock 29. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_new 30. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_destroy 31. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_write 32. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_written 33. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_as_file 34. http://www.acorn.com/browser/plug-in/funcspec.html#message_url_access 35. http://www.acorn.com/browser/plug-in/funcspec.html#message_notify 36. http://www.acorn.com/browser/plug-in/funcspec.html#message_status 37. http://www.acorn.com/browser/plug-in/funcspec.html#message_busy 38. http://www.acorn.com/browser/plug-in/funcspec.html#message_action 39. http://www.acorn.com/browser/plug-in/funcspec.html#message_abort 40. http://www.acorn.com/browser/plug-in/funcspec.html#formats 41. http://www.acorn.com/browser/plug-in/funcspec.html#api_versions 42. http://www.acorn.com/browser/plug-in/funcspec.html#external 43. http://www.acorn.com/browser/plug-in/funcspec.html#acceptance 44. http://www.acorn.com/browser/plug-in/funcspec.html#noncompliances 45. http://www.acorn.com/browser/plug-in/funcspec.html#test 46. http://www.acorn.com/browser/plug-in/funcspec.html#glossary 47. http://www.acorn.com/browser/plug-in/funcspec.html#references 48. http://www.acorn.com/browser/plug-in/funcspec.html#ref1 49. http://www.acorn.com/browser/plug-in/funcspec.html#ref2 50. http://www.acorn.com/browser/plug-in/funcspec.html#ref4 51. http://www.acorn.com/browser/plug-in/funcspec.html#ref5 52. http://www.acorn.com/browser/plug-in/funcspec.html#ref6 53. http://www.acorn.com/browser/plug-in/funcspec.html#ref7 54. http://www.acorn.com/browser/plug-in/funcspec.html#ref5 55. http://www.sun.com/ 56. http://www.netscape.com/ 57. http://www.w3.org/ 58. http://www.acorn.com/browser/nested_wimp/funcspec.html 59. http://www.acorn.com/browser/plug-in/funcspec.html#message_open 60. http://www.acorn.com/browser/plug-in/funcspec.html#message_opening 61. http://www.acorn.com/browser/plug-in/funcspec.html#streams 62. http://www.acorn.com/browser/plug-in/funcspec.html#message_url_access 63. http://www.acorn.com/browser/plug-in/funcspec.html#message_closed 64. http://www.acorn.com/browser/plug-in/funcspec.html#message_close 65. http://www.acorn.com/browser/plug-in/funcspec.html#message_close 66. http://www.acorn.com/browser/plug-in/funcspec.html#message_reshape 67. http://www.acorn.com/browser/plug-in/funcspec.html#message_reshape_request 68. http://www.acorn.com/browser/plug-in/funcspec.html#noncompliances 69. http://www.acorn.com/browser/plug-in/funcspec.html#message_url_access 70. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_new 71. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_write 72. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_written 73. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_destroy 74. http://www.acorn.com/browser/plug-in/funcspec.html#message_url_access 75. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_new 76. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_write 77. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_written 78. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_destroy 79. http://www.acorn.com/browser/plug-in/funcspec.html#programmer_about_plug-in 80. http://www.acorn.com/browser/plug-in/funcspec.html#formats 81. http://www.acorn.com/browser/plug-in/funcspec.html#message_opening 82. http://www.acorn.com/browser/plug-in/funcspec.html#programmer_invocation 83. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 84. http://www.acorn.com/browser/plug-in/funcspec.html#formats 85. http://www.acorn.com/browser/plug-in/funcspec.html#message_open 86. http://www.acorn.com/browser/plug-in/funcspec.html#message_open 87. http://www.acorn.com/browser/plug-in/funcspec.html#message_open 88. http://www.acorn.com/browser/plug-in/funcspec.html#message_close 89. http://www.acorn.com/browser/plug-in/funcspec.html#message_close 90. http://www.acorn.com/browser/plug-in/funcspec.html#message_reshape_request 91. http://www.acorn.com/browser/plug-in/funcspec.html#message_reshape_request 92. http://www.acorn.com/browser/plug-in/funcspec.html#message_reshape 93. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 94. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 95. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 96. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 97. http://www.acorn.com/browser/plug-in/funcspec.html#streams 98. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 99. http://www.acorn.com/browser/plug-in/funcspec.html#streams 100. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 101. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 102. http://www.acorn.com/browser/plug-in/funcspec.html#streams 103. http://www.acorn.com/browser/plug-in/funcspec.html#message_stream_write 104. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 105. http://www.acorn.com/browser/plug-in/funcspec.html#streams 106. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 107. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 108. http://www.acorn.com/browser/plug-in/funcspec.html#streams 109. http://www.acorn.com/browser/plug-in/funcspec.html#message_notify 110. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 111. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 112. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 113. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 114. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 115. http://www.acorn.com/browser/plug-in/funcspec.html#message_url_access 116. http://www.acorn.com/browser/plug-in/funcspec.html#string_value 117. http://www.acorn.com/browser/plug-in/funcspec.html#message_busy 118. http://www.acorn.com/browser/plug-in/funcspec.html#message_open 119. http://www.acorn.com/browser/plug-in/funcspec.html#message_url_access 120. http://www.acorn.com/browser/plug-in/funcspec.html#api_versions 121. http://www.acorn.com/browser/plug-in/funcspec.html#ref1 122. http://www.acorn.com/browser/plug-in/funcspec.html#ref2 123. http://www.acorn.com/browser/plug-in/funcspec.html#streams 124. http://www.acorn.com/browser/plug-in/funcspec.html#acceptance 125. http://www.acorn.com/browser/nested_wimp/funcspec.html 126. http://www.acorn.com/browser/plug-in/funcspec.html#glossary 127. http://www.acorn.com/browser/ 128. http://www.acorn.com/browser/Manuals/Cover.html 129. http://www.acorn.com/browser/download.html 130. http://www.acorn.com/browser/faq.html 131. http://www.acorn.com/browser/bugform.html 132. http://www.acorn.com/browser/hints.html 133. http://www.acorn.com/browser/specs.html 134. http://www.acorn.com/browser/links.html 135. http://www.acorn.com/browser/map.html 136. mailto:webmaster@acorn.com 137. http://www.acorn.com/acorn/copyright.html 138. http://validator.w3.org/