gecko/modules/plugin/test/testplugin/README

= Instructions for using the test plugin =

== MIME type ==

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

== 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.

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).

* 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.

== 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.

== 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.

== 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.

== 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.

== 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".

The .streamTest(url, doPost, postData, callback) function will test how
NPN_GetURLNotify and NPN_PostURLNotify behave when they are called with
arbitrary (malformed) URLs. The function will return `true` if NPN_GetURLNotify
succeeds, and `false` if it fails.
@param doPost whether to call NPN_PostURLNotify
@param postData null, or a string to send a postdata
@callback which will be called when the urlnotify is received with the notify
result

== 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.