1 files changed, 441 insertions, 0 deletions
diff --git a/dom/plugins/test/testplugin/README b/dom/plugins/test/testplugin/README
new file mode 100644
index 000000000..b7ac70363
--- /dev/null
+++ b/dom/plugins/test/testplugin/README
@@ -0,0 +1,441 @@
+= 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 getObjectValue() 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.
+
+== Plugin audio channel support ==
+
+* startAudioPlayback()
+Simulates the plugin starting to play back audio.
+
+* stopAudioPlayback()
+Simulates the plugin stopping to play back audio.
+
+* audioMuted()
+Returns the last value set by NPP_SetValue(NPNVmuteAudioBool).