summaryrefslogtreecommitdiffstats
path: root/dom/plugins/test/testplugin/README
diff options
context:
space:
mode:
Diffstat (limited to 'dom/plugins/test/testplugin/README')
-rw-r--r--dom/plugins/test/testplugin/README424
1 files changed, 424 insertions, 0 deletions
diff --git a/dom/plugins/test/testplugin/README b/dom/plugins/test/testplugin/README
new file mode 100644
index 0000000000..993de360ce
--- /dev/null
+++ b/dom/plugins/test/testplugin/README
@@ -0,0 +1,424 @@
+= 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:
+
+"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.
+
+"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".
+
+* streamTest(url, doPost, postData, writeCallback, notifyCallback, redirectCallback, allowRedirects, postFile = false)
+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
+@postFile boolean optional, defaults to false, set to true if postData contains a filename
+
+* postFileToURLTest(url)
+Calls NPN_PostURL/NPN_PostURLNotify to make a POST request to the URL with
+request from postFile.
+The function will return `0` if NPN_PostURL/NPN_PostURLNotify succeeds, and
+the error code if it fails.
+@param url string, url to request
+
+* 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).
+
+== 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).