michael@0: = Instructions for using the test plugin =
michael@0: 
michael@0: == MIME type ==
michael@0: 
michael@0: The test plugin registers itself for the MIME type "application/x-test".
michael@0: 
michael@0: == Event Model ==
michael@0: 
michael@0: * getEventModel()
michael@0: Returns the NPAPI event model in use. On platforms without event models,
michael@0: simply returns 0;
michael@0: 
michael@0: == Rendering ==
michael@0: 
michael@0: By default, the plugin fills its rectangle with gray, with a black border, and
michael@0: renders the user-agent string (obtained from NPN_UserAgent) centered in black.
michael@0: This rendering method is not supported for the async drawing models.
michael@0: 
michael@0: The test plugin supports the following parameters:
michael@0: 
michael@0: * drawmode="solid"
michael@0: The plugin will draw a solid color instead of the default rendering described
michael@0: above. The default solid color is completely transparent black (i.e., nothing).
michael@0: This should be specified when using one of the async models.
michael@0: 
michael@0: * asyncmodel="bitmap"
michael@0: The plugin will use the NPAPI Async Bitmap drawing model extension. On
michael@0: unsupported platforms this will fallback to non-async rendering.
michael@0: 
michael@0: * asyncmodel="dxgi"
michael@0: The plugin will use the NPAPI Async DXGI drawing model extension. Only
michael@0: supported on Windows Vista or higher. On unsupported platforms this will
michael@0: fallback to non-async rendering.
michael@0: 
michael@0: * color
michael@0: This specifies the color to use for drawmode="solid". The value should be 8 hex
michael@0: digits, 2 per channel in AARRGGBB format.
michael@0: 
michael@0: == Generic API Tests ==
michael@0: 
michael@0: * setUndefinedValueTest
michael@0: Attempts to set the value of an undefined variable (0x0) via NPN_SetValue,
michael@0: returns true if it succeeds and false if it doesn't. It should never succeed.
michael@0: 
michael@0: * .getReflector()
michael@0: Hands back an object which reflects properties as values, e.g.
michael@0:   .getReflector().foo = 'foo'
michael@0:   .getReflector()['foo'] = 'foo'
michael@0:   .getReflector()[1] = 1
michael@0: 
michael@0: * .getNPNVdocumentOrigin()
michael@0: Returns the origin string retrieved from the browser by a NPNVdocumentOrigin
michael@0: variable request. Does not cache the value, gets it from the browser every time.
michael@0: 
michael@0: == NPN_ConvertPoint testing ==
michael@0: 
michael@0: * convertPointX(sourceSpace, sourceX, sourceY, destSpace)
michael@0: * convertPointY(sourceSpace, sourceX, sourceY, destSpace)
michael@0: The plugin uses NPN_ConvertPoint to convert sourceX and sourceY from the source
michael@0: to dest space and returns the X or Y result based on the call.
michael@0: 
michael@0: == NPCocoaEventWindowFocusChanged ==
michael@0: 
michael@0: * getTopLevelWindowActivationState()
michael@0: Returns the activation state for the top-level window as set by the last
michael@0: NPCocoaEventWindowFocusChanged event. Returns true for active, false for
michael@0: inactive, and throws an exception if the state is unknown (uninitialized).
michael@0: 
michael@0: * getTopLevelWindowActivationEventCount()
michael@0: Returns the number of NPCocoaEventWindowFocusChanged events received by
michael@0: the instance.
michael@0: 
michael@0: == Focus Tests ==
michael@0: 
michael@0: * getFocusState()
michael@0: Returns the plugin's focus state. Returns true for focused, false for unfocused,
michael@0: and throws an exception if the state is unknown (uninitialized). This does not
michael@0: necessarily correspond to actual input focus - this corresponds to focus as
michael@0: defined by the NPAPI event model in use.
michael@0: 
michael@0: * getFocusEventCount()
michael@0: Returns the number of focus events received by the instance.
michael@0: 
michael@0: == NPRuntime testing ==
michael@0: 
michael@0: The test plugin object supports the following scriptable methods:
michael@0: 
michael@0: * identifierToStringTest(ident)
michael@0: Converts a string, int32 or double parameter 'ident' to an NPIdentifier and
michael@0: then to a string, which is returned.
michael@0: 
michael@0: * npnEvaluateTest(script)
michael@0: Calls NPN_Evaluate on the 'script' argument, which is a string containing
michael@0: some script to be executed.  Returns the result of the evaluation.
michael@0: 
michael@0: * npnInvokeTest(method, expected, args...)
michael@0: Causes the plugin to call the specified script method using NPN_Invoke, 
michael@0: passing it 1 or more arguments specified in args.  The return value of this 
michael@0: call is compared against 'expected', and if they match, npnInvokeTest will 
michael@0: return true.  Otherwise, it will return false.
michael@0: 
michael@0: * npnInvokeDefaultTest(object, argument)
michael@0: Causes the plugin to call NPN_InvokeDefault on the specified object,
michael@0: with the specified argument.  Returns the result of the invocation.
michael@0: 
michael@0: * getError()
michael@0: If an error has occurred during the last stream or npruntime function,
michael@0: this will return a string error message, otherwise it returns "pass".
michael@0: 
michael@0: * throwExceptionNextInvoke()
michael@0: Sets a flag which causes the next call to a scriptable method to throw
michael@0: one or more exceptions.  If no parameters are passed to the next
michael@0: scriptable method call, it will cause a generic exception to be thrown. 
michael@0: Otherwise there will be one exception thrown per argument, with the argument
michael@0: used as the exception message.  Example:
michael@0: 
michael@0:   plugin.throwExceptionNextInvoke();
michael@0:   plugin.npnInvokeTest("first exception message", "second exception message");
michael@0: 
michael@0: * () - default method
michael@0: Returns a string consisting of the plugin name, concatenated with any 
michael@0: arguments passed to the method.
michael@0: 
michael@0: * .crash() - Crashes the plugin
michael@0: 
michael@0: * getObjectValue() - Returns a custom plugin-implemented scriptable object.
michael@0: * checkObjectValue(obj) - Returns true if the object from setObjectValue() is
michael@0:   the same object passed into this function. It should return true when
michael@0:   the object is passed to the same plugin instance, and false when passed
michael@0:   to other plugin instances, see bug 532246 and
michael@0:   test_multipleinstanceobjects.html.
michael@0: 
michael@0: * callOnDestroy(fn) - Calls `fn` when the plugin instance is being destroyed
michael@0:   
michael@0: * getAuthInfo(protocol, host, port, scheme, realm) - a wrapper for 
michael@0: NPN_GetAuthenticationInfo().  Returns a string "username|password" for
michael@0: the specified auth criteria, or throws an exception if no data is
michael@0: available.
michael@0: 
michael@0: * timerTest(callback) - initiates tests of NPN_ScheduleTimer &
michael@0: NPN_UnscheduleTimer.  When finished, calls the script callback
michael@0: with a boolean value, indicating whether the tests were successful.
michael@0: 
michael@0: * asyncCallbackTest(callback) - initiates tests of
michael@0: NPN_PluginThreadAsyncCall.  When finished, calls the script callback
michael@0: with a boolean value, indicating whether the tests were successful.
michael@0: 
michael@0: * paintscript="..." content attribute
michael@0: If the "paintscript" attribute is set on the plugin element during plugin
michael@0: initialization, then every time the plugin paints it gets the contents of that
michael@0: attribute and evaluates it as a script in the context of the plugin's DOM
michael@0: window. This is useful for testing evil plugin code that might, for example,
michael@0: modify the DOM during painting.
michael@0: 
michael@0: == Private browsing ==
michael@0: 
michael@0: The test plugin object supports the following scriptable methods:
michael@0: 
michael@0: * queryPrivateModeState
michael@0: Returns the value of NPN_GetValue(NPNVprivateModeBool).
michael@0: 
michael@0: * lastReportedPrivateModeState
michael@0: Returns the last value set by NPP_SetValue(NPNVprivateModeBool).
michael@0: 
michael@0: == Windowed/windowless mode ==
michael@0: 
michael@0: The test plugin is windowless by default.
michael@0: 
michael@0: The test plugin supports the following parameter:
michael@0: 
michael@0: * wmode="window"
michael@0: The plugin will be given a native widget on platforms where we support this
michael@0: (Windows and X).
michael@0: 
michael@0: The test plugin object supports the following scriptable method:
michael@0: 
michael@0: * hasWidget()
michael@0: Returns true if the plugin has an associated widget. This will return true if
michael@0: wmode="window" was specified and the platform supports windowed plugins.
michael@0: 
michael@0: == Plugin invalidation ==
michael@0: 
michael@0: * setColor(colorString)
michael@0: Sets the color used for drawmode="solid" and invalidates the plugin area.
michael@0: This calls NPN_Invalidate, even for windowed plugins, since that should work
michael@0: for windowed plugins too (Silverlight depends on it).
michael@0: 
michael@0: * getPaintCount()
michael@0: Returns the number of times this plugin instance has processed a paint request.
michael@0: This can be used to detect whether painting has happened in a plugin's
michael@0: window.
michael@0: 
michael@0: * getWidthAtLastPaint()
michael@0: Returns the window width that was current when the plugin last painted.
michael@0: 
michael@0: * setInvalidateDuringPaint(value)
michael@0: When value is true, every time the plugin paints, it will invalidate
michael@0: itself *during the paint* using NPN_Invalidate.
michael@0: 
michael@0: * setSlowPaint(value)
michael@0: When value is true, the instance will sleep briefly during paint.
michael@0: 
michael@0: == Plugin geometry ==
michael@0: 
michael@0: The test plugin supports the following scriptable methods:
michael@0: 
michael@0: * getEdge(edge)
michael@0: Returns the integer screen pixel coordinate of an edge of the plugin's
michael@0: area:
michael@0: -- edge=0: returns left edge coordinate
michael@0: -- edge=1: returns top edge coordinate
michael@0: -- edge=2: returns right edge coordinate
michael@0: -- edge=3: returns bottom edge coordinate
michael@0: The coordinates are relative to the top-left corner of the top-level window
michael@0: containing the plugin, including the window decorations. Therefore:
michael@0: -- On Mac, they're relative to the top-left corner of the toplevel Cocoa
michael@0: window.
michael@0: -- On Windows, they're relative to the top-left corner of the toplevel HWND's
michael@0: non-client area.
michael@0: -- On GTK2, they're relative to the top-left corner of the toplevel window's
michael@0: window manager frame.
michael@0: This means they can be added to Gecko's window.screenX/screenY (if DPI is set
michael@0: to 96) to get screen coordinates.
michael@0: On the platforms that support window-mode plugins (Windows/GTK2), this only
michael@0: works for window-mode plugins. It will throw an error for windowless plugins.
michael@0: 
michael@0: * getClipRegionRectCount()
michael@0: Returns the number of rectangles in the plugin's clip region.
michael@0: For plugins with widgets, the clip region is computed as the intersection of the
michael@0: clip region for the widget (if the platform does not support clip regions
michael@0: on native widgets, this would just be the widget's rectangle) with the
michael@0: clip regions of all ancestor widgets which would clip this widget.
michael@0: On the platforms that support window-mode plugins (Windows/GTK2), this only
michael@0: works for window-mode plugins. It will throw an error for windowless plugins.
michael@0: On Mac, all plugins have a clip region containing just a single clip
michael@0: rectangle only. So if you request wmode="window" but the plugin reports
michael@0: !hasWidget, you can assume that complex clip regions are not supported.
michael@0: 
michael@0: * getClipRegionRectEdge(i, edge)
michael@0: Returns the integer screen pixel coordinate of an edge of a rectangle from the
michael@0: plugin's clip region. If i is less than zero or greater than or equal to
michael@0: getClipRegionRectCount(), this will throw an error. The coordinates are
michael@0: the same as for getEdge. See getClipRegionRectCount() above for
michael@0: notes on platform plugin limitations.
michael@0: 
michael@0: == Keyboard events ==
michael@0: 
michael@0: * getLastKeyText()
michael@0: Returns the text which was inputted by last keyboard events. This is cleared at
michael@0: every keydown event.
michael@0: NOTE: Currently, this is implemented only on Windows.
michael@0: 
michael@0: == Mouse events ==
michael@0: 
michael@0: The test plugin supports the following scriptable methods:
michael@0: 
michael@0: * getLastMouseX()
michael@0: Returns the X coordinate of the last mouse event (move, button up, or
michael@0: button down), relative to the left edge of the plugin, or -1 if no mouse
michael@0: event has been received.
michael@0: 
michael@0: * getLastMouseX()
michael@0: Returns the Y coordinate of the last mouse event (move, button up, or
michael@0: button down), relative to the top edge of the plugin, or -1 if no mouse
michael@0: event has been received.
michael@0: 
michael@0: == Instance lifecycle ==
michael@0: 
michael@0: The test plugin supports the following scriptable methods:
michael@0: 
michael@0: * startWatchingInstanceCount()
michael@0: Marks all currently running instances as "ignored". Throws an exception if
michael@0: there is already a watch (startWatchingInstanceCount has already been
michael@0: called on some instance without a corresponding stopWatchingInstanceCount).
michael@0: 
michael@0: * getInstanceCount()
michael@0: Returns the count of currently running instances that are not ignored.
michael@0: Throws an exception if there is no watch.
michael@0: 
michael@0: * stopWatchingInstanceCount()
michael@0: Stops watching. Throws an exception if there is no watch.
michael@0: 
michael@0: == NPAPI Timers ==
michael@0: 
michael@0: * unscheduleAllTimers()
michael@0: Instructs the plugin instance to cancel all timers created via
michael@0: NPN_ScheduleTimer.
michael@0: 
michael@0: == Stream Functionality ==
michael@0: 
michael@0: The test plugin enables a variety of NPAPI streaming tests, which are
michael@0: initiated by passing a variety of attributes to the <embed> element which
michael@0: causes the plugin to be initialized.  The plugin stream test code is 
michael@0: designed to receive a stream from the browser (by specifying a "src",
michael@0: "geturl", or "geturlnotify" attribute), and then (if a "frame" attribute
michael@0: is specified) send the data from that stream back to the browser in another
michael@0: stream, whereupon it will be displayed in the specified frame.  If some
michael@0: error occurs during stream processing, an error message will appear in the
michael@0: frame instead of the stream data. If no "frame" attribute is present, a 
michael@0: stream can still be received by the plugin, but the plugin will do nothing
michael@0: with it.
michael@0: 
michael@0: The attributes which control stream tests are:
michael@0: 
michael@0: "streammode": one of "normal", "asfile", "asfileonly", "seek". Sets the
michael@0:   stream mode to the specified mode in any call to NPP_NewStream.
michael@0:   Defaults to "asfileonly".
michael@0: 
michael@0: "streamchunksize": the number of bytes the plugin reports it can accept
michael@0:   in calls to NPP_WriteReady.  Defaults to 1,024.
michael@0: 
michael@0: "src": a url.  If specified, the browser will call NPP_NewStream for
michael@0:   this url as soon as the plugin is initialized.
michael@0: 
michael@0: "geturl": a url.  If specified, the plugin will request this url
michael@0:   from the browser when the plugin is initialized, via a call to
michael@0:   NPN_GetURL.
michael@0: 
michael@0: "geturlnotify": a url.  If specified, the plugin will request this url
michael@0:   from the browser when the plugin is initialized, via a call to
michael@0:   NPN_GetURLNotify. The plugin passes some "notifyData" to 
michael@0:   NPN_GetURLNotify, which it verifies is present in the call to
michael@0:   NPP_URLNotify.  If the "notifyData" does not match, an error
michael@0:   will be displayed in the test frame (if any), instead of the stream 
michael@0:   data.
michael@0: 
michael@0: "frame": the name of a frame in the same HTML document as the <embed>
michael@0:   element which instantiated the plugin. For any of the preceding three
michael@0:   attributes, a stream is received by the plugin via calls to NPP_NewStream,
michael@0:   NPP_WriteReady, NPP_Write, and NPP_DestroyStream.  When NPP_DestroyStream
michael@0:   is called (or NPP_UrlNotify, in the case of "geturlnotify"), and a 
michael@0:   "frame" attribute is present, the data from the stream is converted into a
michael@0:   data: url, and sent back to the browser in another stream via a call to
michael@0:   NPN_GetURL, whereupon it should be displayed in the specified frame.
michael@0: 
michael@0: "range": one or more byte ranges, in the format "offset,length;offset,length".
michael@0:   Only valid when "streammode" = "seek".  When "range" is present, the plugin
michael@0:   will request the specified byte ranges from the stream via a call to
michael@0:   NPN_RequestRead, which it makes after the browser makes its final call to
michael@0:   NPP_Write.  The plugin verifies that the browser makes additional calls
michael@0:   to NPP_Write according to the requested byte ranges, and that the data
michael@0:   received is correct.  Any errors will appear in the test "frame", if
michael@0:   specified.
michael@0: 
michael@0: "posturl": a url.  After the plugin receives a stream, and NPP_DestroyStream
michael@0:   is called, if "posturl" is specified, the plugin will post the contents
michael@0:   of the stream to the specified url via NPN_PostURL.  See "postmode" for
michael@0:   additional details.
michael@0: 
michael@0: "postmode": either "frame" or "stream".  If "frame", and a "frame" attribute
michael@0:   is present, the plugin will pass the frame name to calls to NPN_PostURL,
michael@0:   so that the HTTP response from that operation will be displayed in the
michael@0:   specified frame.  If "stream", the HTTP response is delivered to the plugin
michael@0:   via calls to NPP_NewStream etc, and if a "frame" attribute is present, the
michael@0:   contents of that stream will be passed back to the browser and displayed
michael@0:   in the specified frame via NPN_GetURL.
michael@0: 
michael@0: "newstream": if "true", then any stream which is sent to a frame in the browser
michael@0:   is sent via calls to NPN_NewStream and NPN_Write.  Doing so will cause 
michael@0:   the browser to store the stream data in a file, and set the frame's
michael@0:   location to the corresponding file:// url.
michael@0: 
michael@0: "functiontofail": one of "npp_newstream", "npp_write", "npp_destroystream".
michael@0:   When specified, the given function will return an error code (-1 for
michael@0:   NPP_Write, or else the value of the "failurecode" attribute) the first time
michael@0:   it is called by the browser.
michael@0: 
michael@0: "failurecode": one of the NPError constants.  Used to specify the error
michael@0:   that will be returned by the "functiontofail".
michael@0: 
michael@0: If the plugin is instantiated as a full-page plugin, the following defaults
michael@0: are used:
michael@0:   streammode="seek" frame="testframe" range="100,100"
michael@0: 
michael@0: * streamTest(url, doPost, postData, writeCallback, notifyCallback, redirectCallback, allowRedirects)
michael@0: This will test how NPN_GetURLNotify and NPN_PostURLNotify behave when they are
michael@0: called with arbitrary (malformed) URLs. The function will return `true` if
michael@0: NPN_[Get/Post]URLNotify succeeds, and `false` if it fails.
michael@0: @url url to request
michael@0: @param doPost whether to call NPN_PostURLNotify
michael@0: @param postData null, or a string to send a postdata
michael@0: @writeCallback will be called when data is received for the stream
michael@0: @notifyCallback will be called when the urlnotify is received with the notify result
michael@0: @redirectCallback will be called from urlredirectnotify if a redirect is attempted
michael@0: @allowRedirects boolean value indicating whether or not to allow redirects
michael@0: 
michael@0: * setPluginWantsAllStreams(wantsAllStreams)
michael@0: Set the value returned by the plugin for NPPVpluginWantsAllNetworkStreams.
michael@0: 
michael@0: == Internal consistency ==
michael@0: 
michael@0: * doInternalConsistencyCheck()
michael@0: Does internal consistency checking, returning an empty string if everything is
michael@0: OK, otherwise returning some kind of error string. On Windows, in windowed
michael@0: mode, this checks that the position of the plugin's internal child
michael@0: window has not been disturbed relative to the plugin window.
michael@0: 
michael@0: == Windows native widget message behaviour ==
michael@0: 
michael@0: * Mouse events are handled (saving the last mouse event coordinate) and not
michael@0: passed to the overridden windowproc.
michael@0: 
michael@0: * WM_MOUSEWHEEL events are handled and not passed to the parent window or the
michael@0: overridden windowproc.
michael@0: 
michael@0: * WM_MOUSEACTIVATE events are handled by calling SetFocus on the plugin's
michael@0: widget, if the plugin is windowed. If it's not windowed they're passed to
michael@0: the overriden windowproc (but hopefully never sent by the browser anyway).
michael@0: 
michael@0: == Getting and Setting Cookies ==
michael@0: 
michael@0: * setCookie(string)
michael@0: Sets the given string as the cookie for window's URL.
michael@0: 
michael@0: * getCookie()
michael@0: Returns the cookie string for the window's URL, the cookie set by setCookie.
michael@0: 
michael@0: == FPU Control ==
michael@0: 
michael@0: x86-only on some OSes:
michael@0: 
michael@0: * The .enableFPExceptions() method will enable floating-point exceptions,
michael@0:   as evil plugins or extensions might do.
michael@0: 
michael@0: == HiDPI Mode ==
michael@0: 
michael@0: * queryContentsScaleFactor()
michael@0: Returns the contents scale factor. On platforms without support for this query
michael@0: always returns 1.0 (a double value). Likewise on hardware without HiDPI mode
michael@0: support.