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