The Tor Browser: dom/plugins/test/testplugin/README@129ffea94266 (annotated)

dom/plugins/test/testplugin/README@129ffea94266 (annotated)

dom/plugins/test/testplugin/README

Sat, 03 Jan 2015 20:18:00 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Sat, 03 Jan 2015 20:18:00 +0100
branch: TOR_BUG_3246
changeset 7: 129ffea94266
permissions: -rw-r--r--

Conditionally enable double key logic according to:
private browsing mode or privacy.thirdparty.isolate preference and
implement in GetCookieStringCommon and FindCookie where it counts...
With some reservations of how to convince FindCookie users to test
condition and pass a nullptr when disabling double key logic.

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

The Tor Browser / annotate

dom/plugins/test/testplugin/README@129ffea94266 (annotated)

dom/plugins/test/testplugin/README