The Tor Browser / file revision

 = Instructions for using the test plugin =

 == MIME type ==

 The test plugin registers itself for the MIME type "application/x-test".

 == Event Model ==

 * getEventModel()

 Returns the NPAPI event model in use. On platforms without event models,

 simply returns 0;

 == Rendering ==

 By default, the plugin fills its rectangle with gray, with a black border, and

 renders the user-agent string (obtained from NPN_UserAgent) centered in black.

 This rendering method is not supported for the async drawing models.

 The test plugin supports the following parameters:

 * drawmode="solid"

 The plugin will draw a solid color instead of the default rendering described

 above. The default solid color is completely transparent black (i.e., nothing).

 This should be specified when using one of the async models.

 * asyncmodel="bitmap"

 The plugin will use the NPAPI Async Bitmap drawing model extension. On

 unsupported platforms this will fallback to non-async rendering.

 * asyncmodel="dxgi"

 The plugin will use the NPAPI Async DXGI drawing model extension. Only

 supported on Windows Vista or higher. On unsupported platforms this will

 fallback to non-async rendering.

 * color

 This specifies the color to use for drawmode="solid". The value should be 8 hex

 digits, 2 per channel in AARRGGBB format.

 == Generic API Tests ==

 * setUndefinedValueTest

 Attempts to set the value of an undefined variable (0x0) via NPN_SetValue,

 returns true if it succeeds and false if it doesn't. It should never succeed.

 * .getReflector()

 Hands back an object which reflects properties as values, e.g.

   .getReflector().foo = 'foo'

   .getReflector()['foo'] = 'foo'

   .getReflector()[1] = 1

 * .getNPNVdocumentOrigin()

 Returns the origin string retrieved from the browser by a NPNVdocumentOrigin

 variable request. Does not cache the value, gets it from the browser every time.

 == NPN_ConvertPoint testing ==

 * convertPointX(sourceSpace, sourceX, sourceY, destSpace)

 * convertPointY(sourceSpace, sourceX, sourceY, destSpace)

 The plugin uses NPN_ConvertPoint to convert sourceX and sourceY from the source

 to dest space and returns the X or Y result based on the call.

 == NPCocoaEventWindowFocusChanged ==

 * getTopLevelWindowActivationState()

 Returns the activation state for the top-level window as set by the last

 NPCocoaEventWindowFocusChanged event. Returns true for active, false for

 inactive, and throws an exception if the state is unknown (uninitialized).

 * getTopLevelWindowActivationEventCount()

 Returns the number of NPCocoaEventWindowFocusChanged events received by

 the instance.

 == Focus Tests ==

 * getFocusState()

 Returns the plugin's focus state. Returns true for focused, false for unfocused,

 and throws an exception if the state is unknown (uninitialized). This does not

 necessarily correspond to actual input focus - this corresponds to focus as

 defined by the NPAPI event model in use.

 * getFocusEventCount()

 Returns the number of focus events received by the instance.

 == NPRuntime testing ==

 The test plugin object supports the following scriptable methods:

 * identifierToStringTest(ident)

 Converts a string, int32 or double parameter 'ident' to an NPIdentifier and

 then to a string, which is returned.

 * npnEvaluateTest(script)

 Calls NPN_Evaluate on the 'script' argument, which is a string containing

 some script to be executed.  Returns the result of the evaluation.

 * npnInvokeTest(method, expected, args...)

 Causes the plugin to call the specified script method using NPN_Invoke, 

 passing it 1 or more arguments specified in args.  The return value of this 

 call is compared against 'expected', and if they match, npnInvokeTest will 

 return true.  Otherwise, it will return false.

 * npnInvokeDefaultTest(object, argument)

 Causes the plugin to call NPN_InvokeDefault on the specified object,

 with the specified argument.  Returns the result of the invocation.

 * getError()

 If an error has occurred during the last stream or npruntime function,

 this will return a string error message, otherwise it returns "pass".

 * throwExceptionNextInvoke()

 Sets a flag which causes the next call to a scriptable method to throw

 one or more exceptions.  If no parameters are passed to the next

 scriptable method call, it will cause a generic exception to be thrown. 

 Otherwise there will be one exception thrown per argument, with the argument

 used as the exception message.  Example:

   plugin.throwExceptionNextInvoke();

   plugin.npnInvokeTest("first exception message", "second exception message");

 * () - default method

 Returns a string consisting of the plugin name, concatenated with any 

 arguments passed to the method.

 * .crash() - Crashes the plugin

 * getObjectValue() - Returns a custom plugin-implemented scriptable object.

 * checkObjectValue(obj) - Returns true if the object from setObjectValue() is

   the same object passed into this function. It should return true when

   the object is passed to the same plugin instance, and false when passed

   to other plugin instances, see bug 532246 and

   test_multipleinstanceobjects.html.

 * callOnDestroy(fn) - Calls `fn` when the plugin instance is being destroyed

 * getAuthInfo(protocol, host, port, scheme, realm) - a wrapper for 

 NPN_GetAuthenticationInfo().  Returns a string "username|password" for

 the specified auth criteria, or throws an exception if no data is

 available.

 * timerTest(callback) - initiates tests of NPN_ScheduleTimer &

 NPN_UnscheduleTimer.  When finished, calls the script callback

 with a boolean value, indicating whether the tests were successful.

 * asyncCallbackTest(callback) - initiates tests of

 NPN_PluginThreadAsyncCall.  When finished, calls the script callback

 with a boolean value, indicating whether the tests were successful.

 * paintscript="..." content attribute

 If the "paintscript" attribute is set on the plugin element during plugin

 initialization, then every time the plugin paints it gets the contents of that

 attribute and evaluates it as a script in the context of the plugin's DOM

 window. This is useful for testing evil plugin code that might, for example,

 modify the DOM during painting.

 == Private browsing ==

 The test plugin object supports the following scriptable methods:

 * queryPrivateModeState

 Returns the value of NPN_GetValue(NPNVprivateModeBool).

 * lastReportedPrivateModeState

 Returns the last value set by NPP_SetValue(NPNVprivateModeBool).

 == Windowed/windowless mode ==

 The test plugin is windowless by default.

 The test plugin supports the following parameter:

 * wmode="window"

 The plugin will be given a native widget on platforms where we support this

 (Windows and X).

 The test plugin object supports the following scriptable method:

 * hasWidget()

 Returns true if the plugin has an associated widget. This will return true if

 wmode="window" was specified and the platform supports windowed plugins.

 == Plugin invalidation ==

 * setColor(colorString)

 Sets the color used for drawmode="solid" and invalidates the plugin area.

 This calls NPN_Invalidate, even for windowed plugins, since that should work

 for windowed plugins too (Silverlight depends on it).

 * getPaintCount()

 Returns the number of times this plugin instance has processed a paint request.

 This can be used to detect whether painting has happened in a plugin's

 window.

 * getWidthAtLastPaint()

 Returns the window width that was current when the plugin last painted.

 * setInvalidateDuringPaint(value)

 When value is true, every time the plugin paints, it will invalidate

 itself *during the paint* using NPN_Invalidate.

 * setSlowPaint(value)

 When value is true, the instance will sleep briefly during paint.

 == Plugin geometry ==

 The test plugin supports the following scriptable methods:

 * getEdge(edge)

 Returns the integer screen pixel coordinate of an edge of the plugin's

 area:

 -- edge=0: returns left edge coordinate

 -- edge=1: returns top edge coordinate

 -- edge=2: returns right edge coordinate

 -- edge=3: returns bottom edge coordinate

 The coordinates are relative to the top-left corner of the top-level window

 containing the plugin, including the window decorations. Therefore:

 -- On Mac, they're relative to the top-left corner of the toplevel Cocoa

 window.

 -- On Windows, they're relative to the top-left corner of the toplevel HWND's

 non-client area.

 -- On GTK2, they're relative to the top-left corner of the toplevel window's

 window manager frame.

 This means they can be added to Gecko's window.screenX/screenY (if DPI is set

 to 96) to get screen coordinates.

 On the platforms that support window-mode plugins (Windows/GTK2), this only

 works for window-mode plugins. It will throw an error for windowless plugins.

 * getClipRegionRectCount()

 Returns the number of rectangles in the plugin's clip region.

 For plugins with widgets, the clip region is computed as the intersection of the

 clip region for the widget (if the platform does not support clip regions

 on native widgets, this would just be the widget's rectangle) with the

 clip regions of all ancestor widgets which would clip this widget.

 On the platforms that support window-mode plugins (Windows/GTK2), this only

 works for window-mode plugins. It will throw an error for windowless plugins.

 On Mac, all plugins have a clip region containing just a single clip

 rectangle only. So if you request wmode="window" but the plugin reports

 !hasWidget, you can assume that complex clip regions are not supported.

 * getClipRegionRectEdge(i, edge)

 Returns the integer screen pixel coordinate of an edge of a rectangle from the

 plugin's clip region. If i is less than zero or greater than or equal to

 getClipRegionRectCount(), this will throw an error. The coordinates are

 the same as for getEdge. See getClipRegionRectCount() above for

 notes on platform plugin limitations.

 == Keyboard events ==

 * getLastKeyText()

 Returns the text which was inputted by last keyboard events. This is cleared at

 every keydown event.

 NOTE: Currently, this is implemented only on Windows.

 == Mouse events ==

 The test plugin supports the following scriptable methods:

 * getLastMouseX()

 Returns the X coordinate of the last mouse event (move, button up, or

 button down), relative to the left edge of the plugin, or -1 if no mouse

 event has been received.

 * getLastMouseX()

 Returns the Y coordinate of the last mouse event (move, button up, or

 button down), relative to the top edge of the plugin, or -1 if no mouse

 event has been received.

 == Instance lifecycle ==

 The test plugin supports the following scriptable methods:

 * startWatchingInstanceCount()

 Marks all currently running instances as "ignored". Throws an exception if

 there is already a watch (startWatchingInstanceCount has already been

 called on some instance without a corresponding stopWatchingInstanceCount).

 * getInstanceCount()

 Returns the count of currently running instances that are not ignored.

 Throws an exception if there is no watch.

 * stopWatchingInstanceCount()

 Stops watching. Throws an exception if there is no watch.

 == NPAPI Timers ==

 * unscheduleAllTimers()

 Instructs the plugin instance to cancel all timers created via

 NPN_ScheduleTimer.

 == Stream Functionality ==

 The test plugin enables a variety of NPAPI streaming tests, which are

 initiated by passing a variety of attributes to the <embed> element which

 causes the plugin to be initialized.  The plugin stream test code is 

 designed to receive a stream from the browser (by specifying a "src",

 "geturl", or "geturlnotify" attribute), and then (if a "frame" attribute

 is specified) send the data from that stream back to the browser in another

 stream, whereupon it will be displayed in the specified frame.  If some

 error occurs during stream processing, an error message will appear in the

 frame instead of the stream data. If no "frame" attribute is present, a 

 stream can still be received by the plugin, but the plugin will do nothing

 with it.

 The attributes which control stream tests are:

 "streammode": one of "normal", "asfile", "asfileonly", "seek". Sets the

   stream mode to the specified mode in any call to NPP_NewStream.

   Defaults to "asfileonly".

 "streamchunksize": the number of bytes the plugin reports it can accept

   in calls to NPP_WriteReady.  Defaults to 1,024.

 "src": a url.  If specified, the browser will call NPP_NewStream for

   this url as soon as the plugin is initialized.

 "geturl": a url.  If specified, the plugin will request this url

   from the browser when the plugin is initialized, via a call to

   NPN_GetURL.

 "geturlnotify": a url.  If specified, the plugin will request this url

   from the browser when the plugin is initialized, via a call to

   NPN_GetURLNotify. The plugin passes some "notifyData" to 

   NPN_GetURLNotify, which it verifies is present in the call to

   NPP_URLNotify.  If the "notifyData" does not match, an error

   will be displayed in the test frame (if any), instead of the stream 

   data.

 "frame": the name of a frame in the same HTML document as the <embed>

   element which instantiated the plugin. For any of the preceding three

   attributes, a stream is received by the plugin via calls to NPP_NewStream,

   NPP_WriteReady, NPP_Write, and NPP_DestroyStream.  When NPP_DestroyStream

   is called (or NPP_UrlNotify, in the case of "geturlnotify"), and a 

   "frame" attribute is present, the data from the stream is converted into a

   data: url, and sent back to the browser in another stream via a call to

   NPN_GetURL, whereupon it should be displayed in the specified frame.

 "range": one or more byte ranges, in the format "offset,length;offset,length".

   Only valid when "streammode" = "seek".  When "range" is present, the plugin

   will request the specified byte ranges from the stream via a call to

   NPN_RequestRead, which it makes after the browser makes its final call to

   NPP_Write.  The plugin verifies that the browser makes additional calls

   to NPP_Write according to the requested byte ranges, and that the data

   received is correct.  Any errors will appear in the test "frame", if

   specified.

 "posturl": a url.  After the plugin receives a stream, and NPP_DestroyStream

   is called, if "posturl" is specified, the plugin will post the contents

   of the stream to the specified url via NPN_PostURL.  See "postmode" for

   additional details.

 "postmode": either "frame" or "stream".  If "frame", and a "frame" attribute

   is present, the plugin will pass the frame name to calls to NPN_PostURL,

   so that the HTTP response from that operation will be displayed in the

   specified frame.  If "stream", the HTTP response is delivered to the plugin

   via calls to NPP_NewStream etc, and if a "frame" attribute is present, the

   contents of that stream will be passed back to the browser and displayed

   in the specified frame via NPN_GetURL.

 "newstream": if "true", then any stream which is sent to a frame in the browser

   is sent via calls to NPN_NewStream and NPN_Write.  Doing so will cause 

   the browser to store the stream data in a file, and set the frame's

   location to the corresponding file:// url.

 "functiontofail": one of "npp_newstream", "npp_write", "npp_destroystream".

   When specified, the given function will return an error code (-1 for

   NPP_Write, or else the value of the "failurecode" attribute) the first time

   it is called by the browser.

 "failurecode": one of the NPError constants.  Used to specify the error

   that will be returned by the "functiontofail".

 If the plugin is instantiated as a full-page plugin, the following defaults

 are used:

   streammode="seek" frame="testframe" range="100,100"

 * streamTest(url, doPost, postData, writeCallback, notifyCallback, redirectCallback, allowRedirects)

 This will test how NPN_GetURLNotify and NPN_PostURLNotify behave when they are

 called with arbitrary (malformed) URLs. The function will return `true` if

 NPN_[Get/Post]URLNotify succeeds, and `false` if it fails.

 @url url to request

 @param doPost whether to call NPN_PostURLNotify

 @param postData null, or a string to send a postdata

 @writeCallback will be called when data is received for the stream

 @notifyCallback will be called when the urlnotify is received with the notify result

 @redirectCallback will be called from urlredirectnotify if a redirect is attempted

 @allowRedirects boolean value indicating whether or not to allow redirects

 * setPluginWantsAllStreams(wantsAllStreams)

 Set the value returned by the plugin for NPPVpluginWantsAllNetworkStreams.

 == Internal consistency ==

 * doInternalConsistencyCheck()

 Does internal consistency checking, returning an empty string if everything is

 OK, otherwise returning some kind of error string. On Windows, in windowed

 mode, this checks that the position of the plugin's internal child

 window has not been disturbed relative to the plugin window.

 == Windows native widget message behaviour ==

 * Mouse events are handled (saving the last mouse event coordinate) and not

 passed to the overridden windowproc.

 * WM_MOUSEWHEEL events are handled and not passed to the parent window or the

 overridden windowproc.

 * WM_MOUSEACTIVATE events are handled by calling SetFocus on the plugin's

 widget, if the plugin is windowed. If it's not windowed they're passed to

 the overriden windowproc (but hopefully never sent by the browser anyway).

 == Getting and Setting Cookies ==

 * setCookie(string)

 Sets the given string as the cookie for window's URL.

 * getCookie()

 Returns the cookie string for the window's URL, the cookie set by setCookie.

 == FPU Control ==

 x86-only on some OSes:

 * The .enableFPExceptions() method will enable floating-point exceptions,

   as evil plugins or extensions might do.

 == HiDPI Mode ==

 * queryContentsScaleFactor()

 Returns the contents scale factor. On platforms without support for this query

 always returns 1.0 (a double value). Likewise on hardware without HiDPI mode

 support.