1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/plugins/test/testplugin/README Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,430 @@
1.4 += Instructions for using the test plugin =
1.5 +
1.6 +== MIME type ==
1.7 +
1.8 +The test plugin registers itself for the MIME type "application/x-test".
1.9 +
1.10 +== Event Model ==
1.11 +
1.12 +* getEventModel()
1.13 +Returns the NPAPI event model in use. On platforms without event models,
1.14 +simply returns 0;
1.15 +
1.16 +== Rendering ==
1.17 +
1.18 +By default, the plugin fills its rectangle with gray, with a black border, and
1.19 +renders the user-agent string (obtained from NPN_UserAgent) centered in black.
1.20 +This rendering method is not supported for the async drawing models.
1.21 +
1.22 +The test plugin supports the following parameters:
1.23 +
1.24 +* drawmode="solid"
1.25 +The plugin will draw a solid color instead of the default rendering described
1.26 +above. The default solid color is completely transparent black (i.e., nothing).
1.27 +This should be specified when using one of the async models.
1.28 +
1.29 +* asyncmodel="bitmap"
1.30 +The plugin will use the NPAPI Async Bitmap drawing model extension. On
1.31 +unsupported platforms this will fallback to non-async rendering.
1.32 +
1.33 +* asyncmodel="dxgi"
1.34 +The plugin will use the NPAPI Async DXGI drawing model extension. Only
1.35 +supported on Windows Vista or higher. On unsupported platforms this will
1.36 +fallback to non-async rendering.
1.37 +
1.38 +* color
1.39 +This specifies the color to use for drawmode="solid". The value should be 8 hex
1.40 +digits, 2 per channel in AARRGGBB format.
1.41 +
1.42 +== Generic API Tests ==
1.43 +
1.44 +* setUndefinedValueTest
1.45 +Attempts to set the value of an undefined variable (0x0) via NPN_SetValue,
1.46 +returns true if it succeeds and false if it doesn't. It should never succeed.
1.47 +
1.48 +* .getReflector()
1.49 +Hands back an object which reflects properties as values, e.g.
1.50 + .getReflector().foo = 'foo'
1.51 + .getReflector()['foo'] = 'foo'
1.52 + .getReflector()[1] = 1
1.53 +
1.54 +* .getNPNVdocumentOrigin()
1.55 +Returns the origin string retrieved from the browser by a NPNVdocumentOrigin
1.56 +variable request. Does not cache the value, gets it from the browser every time.
1.57 +
1.58 +== NPN_ConvertPoint testing ==
1.59 +
1.60 +* convertPointX(sourceSpace, sourceX, sourceY, destSpace)
1.61 +* convertPointY(sourceSpace, sourceX, sourceY, destSpace)
1.62 +The plugin uses NPN_ConvertPoint to convert sourceX and sourceY from the source
1.63 +to dest space and returns the X or Y result based on the call.
1.64 +
1.65 +== NPCocoaEventWindowFocusChanged ==
1.66 +
1.67 +* getTopLevelWindowActivationState()
1.68 +Returns the activation state for the top-level window as set by the last
1.69 +NPCocoaEventWindowFocusChanged event. Returns true for active, false for
1.70 +inactive, and throws an exception if the state is unknown (uninitialized).
1.71 +
1.72 +* getTopLevelWindowActivationEventCount()
1.73 +Returns the number of NPCocoaEventWindowFocusChanged events received by
1.74 +the instance.
1.75 +
1.76 +== Focus Tests ==
1.77 +
1.78 +* getFocusState()
1.79 +Returns the plugin's focus state. Returns true for focused, false for unfocused,
1.80 +and throws an exception if the state is unknown (uninitialized). This does not
1.81 +necessarily correspond to actual input focus - this corresponds to focus as
1.82 +defined by the NPAPI event model in use.
1.83 +
1.84 +* getFocusEventCount()
1.85 +Returns the number of focus events received by the instance.
1.86 +
1.87 +== NPRuntime testing ==
1.88 +
1.89 +The test plugin object supports the following scriptable methods:
1.90 +
1.91 +* identifierToStringTest(ident)
1.92 +Converts a string, int32 or double parameter 'ident' to an NPIdentifier and
1.93 +then to a string, which is returned.
1.94 +
1.95 +* npnEvaluateTest(script)
1.96 +Calls NPN_Evaluate on the 'script' argument, which is a string containing
1.97 +some script to be executed. Returns the result of the evaluation.
1.98 +
1.99 +* npnInvokeTest(method, expected, args...)
1.100 +Causes the plugin to call the specified script method using NPN_Invoke,
1.101 +passing it 1 or more arguments specified in args. The return value of this
1.102 +call is compared against 'expected', and if they match, npnInvokeTest will
1.103 +return true. Otherwise, it will return false.
1.104 +
1.105 +* npnInvokeDefaultTest(object, argument)
1.106 +Causes the plugin to call NPN_InvokeDefault on the specified object,
1.107 +with the specified argument. Returns the result of the invocation.
1.108 +
1.109 +* getError()
1.110 +If an error has occurred during the last stream or npruntime function,
1.111 +this will return a string error message, otherwise it returns "pass".
1.112 +
1.113 +* throwExceptionNextInvoke()
1.114 +Sets a flag which causes the next call to a scriptable method to throw
1.115 +one or more exceptions. If no parameters are passed to the next
1.116 +scriptable method call, it will cause a generic exception to be thrown.
1.117 +Otherwise there will be one exception thrown per argument, with the argument
1.118 +used as the exception message. Example:
1.119 +
1.120 + plugin.throwExceptionNextInvoke();
1.121 + plugin.npnInvokeTest("first exception message", "second exception message");
1.122 +
1.123 +* () - default method
1.124 +Returns a string consisting of the plugin name, concatenated with any
1.125 +arguments passed to the method.
1.126 +
1.127 +* .crash() - Crashes the plugin
1.128 +
1.129 +* getObjectValue() - Returns a custom plugin-implemented scriptable object.
1.130 +* checkObjectValue(obj) - Returns true if the object from setObjectValue() is
1.131 + the same object passed into this function. It should return true when
1.132 + the object is passed to the same plugin instance, and false when passed
1.133 + to other plugin instances, see bug 532246 and
1.134 + test_multipleinstanceobjects.html.
1.135 +
1.136 +* callOnDestroy(fn) - Calls `fn` when the plugin instance is being destroyed
1.137 +
1.138 +* getAuthInfo(protocol, host, port, scheme, realm) - a wrapper for
1.139 +NPN_GetAuthenticationInfo(). Returns a string "username|password" for
1.140 +the specified auth criteria, or throws an exception if no data is
1.141 +available.
1.142 +
1.143 +* timerTest(callback) - initiates tests of NPN_ScheduleTimer &
1.144 +NPN_UnscheduleTimer. When finished, calls the script callback
1.145 +with a boolean value, indicating whether the tests were successful.
1.146 +
1.147 +* asyncCallbackTest(callback) - initiates tests of
1.148 +NPN_PluginThreadAsyncCall. When finished, calls the script callback
1.149 +with a boolean value, indicating whether the tests were successful.
1.150 +
1.151 +* paintscript="..." content attribute
1.152 +If the "paintscript" attribute is set on the plugin element during plugin
1.153 +initialization, then every time the plugin paints it gets the contents of that
1.154 +attribute and evaluates it as a script in the context of the plugin's DOM
1.155 +window. This is useful for testing evil plugin code that might, for example,
1.156 +modify the DOM during painting.
1.157 +
1.158 +== Private browsing ==
1.159 +
1.160 +The test plugin object supports the following scriptable methods:
1.161 +
1.162 +* queryPrivateModeState
1.163 +Returns the value of NPN_GetValue(NPNVprivateModeBool).
1.164 +
1.165 +* lastReportedPrivateModeState
1.166 +Returns the last value set by NPP_SetValue(NPNVprivateModeBool).
1.167 +
1.168 +== Windowed/windowless mode ==
1.169 +
1.170 +The test plugin is windowless by default.
1.171 +
1.172 +The test plugin supports the following parameter:
1.173 +
1.174 +* wmode="window"
1.175 +The plugin will be given a native widget on platforms where we support this
1.176 +(Windows and X).
1.177 +
1.178 +The test plugin object supports the following scriptable method:
1.179 +
1.180 +* hasWidget()
1.181 +Returns true if the plugin has an associated widget. This will return true if
1.182 +wmode="window" was specified and the platform supports windowed plugins.
1.183 +
1.184 +== Plugin invalidation ==
1.185 +
1.186 +* setColor(colorString)
1.187 +Sets the color used for drawmode="solid" and invalidates the plugin area.
1.188 +This calls NPN_Invalidate, even for windowed plugins, since that should work
1.189 +for windowed plugins too (Silverlight depends on it).
1.190 +
1.191 +* getPaintCount()
1.192 +Returns the number of times this plugin instance has processed a paint request.
1.193 +This can be used to detect whether painting has happened in a plugin's
1.194 +window.
1.195 +
1.196 +* getWidthAtLastPaint()
1.197 +Returns the window width that was current when the plugin last painted.
1.198 +
1.199 +* setInvalidateDuringPaint(value)
1.200 +When value is true, every time the plugin paints, it will invalidate
1.201 +itself *during the paint* using NPN_Invalidate.
1.202 +
1.203 +* setSlowPaint(value)
1.204 +When value is true, the instance will sleep briefly during paint.
1.205 +
1.206 +== Plugin geometry ==
1.207 +
1.208 +The test plugin supports the following scriptable methods:
1.209 +
1.210 +* getEdge(edge)
1.211 +Returns the integer screen pixel coordinate of an edge of the plugin's
1.212 +area:
1.213 +-- edge=0: returns left edge coordinate
1.214 +-- edge=1: returns top edge coordinate
1.215 +-- edge=2: returns right edge coordinate
1.216 +-- edge=3: returns bottom edge coordinate
1.217 +The coordinates are relative to the top-left corner of the top-level window
1.218 +containing the plugin, including the window decorations. Therefore:
1.219 +-- On Mac, they're relative to the top-left corner of the toplevel Cocoa
1.220 +window.
1.221 +-- On Windows, they're relative to the top-left corner of the toplevel HWND's
1.222 +non-client area.
1.223 +-- On GTK2, they're relative to the top-left corner of the toplevel window's
1.224 +window manager frame.
1.225 +This means they can be added to Gecko's window.screenX/screenY (if DPI is set
1.226 +to 96) to get screen coordinates.
1.227 +On the platforms that support window-mode plugins (Windows/GTK2), this only
1.228 +works for window-mode plugins. It will throw an error for windowless plugins.
1.229 +
1.230 +* getClipRegionRectCount()
1.231 +Returns the number of rectangles in the plugin's clip region.
1.232 +For plugins with widgets, the clip region is computed as the intersection of the
1.233 +clip region for the widget (if the platform does not support clip regions
1.234 +on native widgets, this would just be the widget's rectangle) with the
1.235 +clip regions of all ancestor widgets which would clip this widget.
1.236 +On the platforms that support window-mode plugins (Windows/GTK2), this only
1.237 +works for window-mode plugins. It will throw an error for windowless plugins.
1.238 +On Mac, all plugins have a clip region containing just a single clip
1.239 +rectangle only. So if you request wmode="window" but the plugin reports
1.240 +!hasWidget, you can assume that complex clip regions are not supported.
1.241 +
1.242 +* getClipRegionRectEdge(i, edge)
1.243 +Returns the integer screen pixel coordinate of an edge of a rectangle from the
1.244 +plugin's clip region. If i is less than zero or greater than or equal to
1.245 +getClipRegionRectCount(), this will throw an error. The coordinates are
1.246 +the same as for getEdge. See getClipRegionRectCount() above for
1.247 +notes on platform plugin limitations.
1.248 +
1.249 +== Keyboard events ==
1.250 +
1.251 +* getLastKeyText()
1.252 +Returns the text which was inputted by last keyboard events. This is cleared at
1.253 +every keydown event.
1.254 +NOTE: Currently, this is implemented only on Windows.
1.255 +
1.256 +== Mouse events ==
1.257 +
1.258 +The test plugin supports the following scriptable methods:
1.259 +
1.260 +* getLastMouseX()
1.261 +Returns the X coordinate of the last mouse event (move, button up, or
1.262 +button down), relative to the left edge of the plugin, or -1 if no mouse
1.263 +event has been received.
1.264 +
1.265 +* getLastMouseX()
1.266 +Returns the Y coordinate of the last mouse event (move, button up, or
1.267 +button down), relative to the top edge of the plugin, or -1 if no mouse
1.268 +event has been received.
1.269 +
1.270 +== Instance lifecycle ==
1.271 +
1.272 +The test plugin supports the following scriptable methods:
1.273 +
1.274 +* startWatchingInstanceCount()
1.275 +Marks all currently running instances as "ignored". Throws an exception if
1.276 +there is already a watch (startWatchingInstanceCount has already been
1.277 +called on some instance without a corresponding stopWatchingInstanceCount).
1.278 +
1.279 +* getInstanceCount()
1.280 +Returns the count of currently running instances that are not ignored.
1.281 +Throws an exception if there is no watch.
1.282 +
1.283 +* stopWatchingInstanceCount()
1.284 +Stops watching. Throws an exception if there is no watch.
1.285 +
1.286 +== NPAPI Timers ==
1.287 +
1.288 +* unscheduleAllTimers()
1.289 +Instructs the plugin instance to cancel all timers created via
1.290 +NPN_ScheduleTimer.
1.291 +
1.292 +== Stream Functionality ==
1.293 +
1.294 +The test plugin enables a variety of NPAPI streaming tests, which are
1.295 +initiated by passing a variety of attributes to the <embed> element which
1.296 +causes the plugin to be initialized. The plugin stream test code is
1.297 +designed to receive a stream from the browser (by specifying a "src",
1.298 +"geturl", or "geturlnotify" attribute), and then (if a "frame" attribute
1.299 +is specified) send the data from that stream back to the browser in another
1.300 +stream, whereupon it will be displayed in the specified frame. If some
1.301 +error occurs during stream processing, an error message will appear in the
1.302 +frame instead of the stream data. If no "frame" attribute is present, a
1.303 +stream can still be received by the plugin, but the plugin will do nothing
1.304 +with it.
1.305 +
1.306 +The attributes which control stream tests are:
1.307 +
1.308 +"streammode": one of "normal", "asfile", "asfileonly", "seek". Sets the
1.309 + stream mode to the specified mode in any call to NPP_NewStream.
1.310 + Defaults to "asfileonly".
1.311 +
1.312 +"streamchunksize": the number of bytes the plugin reports it can accept
1.313 + in calls to NPP_WriteReady. Defaults to 1,024.
1.314 +
1.315 +"src": a url. If specified, the browser will call NPP_NewStream for
1.316 + this url as soon as the plugin is initialized.
1.317 +
1.318 +"geturl": a url. If specified, the plugin will request this url
1.319 + from the browser when the plugin is initialized, via a call to
1.320 + NPN_GetURL.
1.321 +
1.322 +"geturlnotify": a url. If specified, the plugin will request this url
1.323 + from the browser when the plugin is initialized, via a call to
1.324 + NPN_GetURLNotify. The plugin passes some "notifyData" to
1.325 + NPN_GetURLNotify, which it verifies is present in the call to
1.326 + NPP_URLNotify. If the "notifyData" does not match, an error
1.327 + will be displayed in the test frame (if any), instead of the stream
1.328 + data.
1.329 +
1.330 +"frame": the name of a frame in the same HTML document as the <embed>
1.331 + element which instantiated the plugin. For any of the preceding three
1.332 + attributes, a stream is received by the plugin via calls to NPP_NewStream,
1.333 + NPP_WriteReady, NPP_Write, and NPP_DestroyStream. When NPP_DestroyStream
1.334 + is called (or NPP_UrlNotify, in the case of "geturlnotify"), and a
1.335 + "frame" attribute is present, the data from the stream is converted into a
1.336 + data: url, and sent back to the browser in another stream via a call to
1.337 + NPN_GetURL, whereupon it should be displayed in the specified frame.
1.338 +
1.339 +"range": one or more byte ranges, in the format "offset,length;offset,length".
1.340 + Only valid when "streammode" = "seek". When "range" is present, the plugin
1.341 + will request the specified byte ranges from the stream via a call to
1.342 + NPN_RequestRead, which it makes after the browser makes its final call to
1.343 + NPP_Write. The plugin verifies that the browser makes additional calls
1.344 + to NPP_Write according to the requested byte ranges, and that the data
1.345 + received is correct. Any errors will appear in the test "frame", if
1.346 + specified.
1.347 +
1.348 +"posturl": a url. After the plugin receives a stream, and NPP_DestroyStream
1.349 + is called, if "posturl" is specified, the plugin will post the contents
1.350 + of the stream to the specified url via NPN_PostURL. See "postmode" for
1.351 + additional details.
1.352 +
1.353 +"postmode": either "frame" or "stream". If "frame", and a "frame" attribute
1.354 + is present, the plugin will pass the frame name to calls to NPN_PostURL,
1.355 + so that the HTTP response from that operation will be displayed in the
1.356 + specified frame. If "stream", the HTTP response is delivered to the plugin
1.357 + via calls to NPP_NewStream etc, and if a "frame" attribute is present, the
1.358 + contents of that stream will be passed back to the browser and displayed
1.359 + in the specified frame via NPN_GetURL.
1.360 +
1.361 +"newstream": if "true", then any stream which is sent to a frame in the browser
1.362 + is sent via calls to NPN_NewStream and NPN_Write. Doing so will cause
1.363 + the browser to store the stream data in a file, and set the frame's
1.364 + location to the corresponding file:// url.
1.365 +
1.366 +"functiontofail": one of "npp_newstream", "npp_write", "npp_destroystream".
1.367 + When specified, the given function will return an error code (-1 for
1.368 + NPP_Write, or else the value of the "failurecode" attribute) the first time
1.369 + it is called by the browser.
1.370 +
1.371 +"failurecode": one of the NPError constants. Used to specify the error
1.372 + that will be returned by the "functiontofail".
1.373 +
1.374 +If the plugin is instantiated as a full-page plugin, the following defaults
1.375 +are used:
1.376 + streammode="seek" frame="testframe" range="100,100"
1.377 +
1.378 +* streamTest(url, doPost, postData, writeCallback, notifyCallback, redirectCallback, allowRedirects)
1.379 +This will test how NPN_GetURLNotify and NPN_PostURLNotify behave when they are
1.380 +called with arbitrary (malformed) URLs. The function will return `true` if
1.381 +NPN_[Get/Post]URLNotify succeeds, and `false` if it fails.
1.382 +@url url to request
1.383 +@param doPost whether to call NPN_PostURLNotify
1.384 +@param postData null, or a string to send a postdata
1.385 +@writeCallback will be called when data is received for the stream
1.386 +@notifyCallback will be called when the urlnotify is received with the notify result
1.387 +@redirectCallback will be called from urlredirectnotify if a redirect is attempted
1.388 +@allowRedirects boolean value indicating whether or not to allow redirects
1.389 +
1.390 +* setPluginWantsAllStreams(wantsAllStreams)
1.391 +Set the value returned by the plugin for NPPVpluginWantsAllNetworkStreams.
1.392 +
1.393 +== Internal consistency ==
1.394 +
1.395 +* doInternalConsistencyCheck()
1.396 +Does internal consistency checking, returning an empty string if everything is
1.397 +OK, otherwise returning some kind of error string. On Windows, in windowed
1.398 +mode, this checks that the position of the plugin's internal child
1.399 +window has not been disturbed relative to the plugin window.
1.400 +
1.401 +== Windows native widget message behaviour ==
1.402 +
1.403 +* Mouse events are handled (saving the last mouse event coordinate) and not
1.404 +passed to the overridden windowproc.
1.405 +
1.406 +* WM_MOUSEWHEEL events are handled and not passed to the parent window or the
1.407 +overridden windowproc.
1.408 +
1.409 +* WM_MOUSEACTIVATE events are handled by calling SetFocus on the plugin's
1.410 +widget, if the plugin is windowed. If it's not windowed they're passed to
1.411 +the overriden windowproc (but hopefully never sent by the browser anyway).
1.412 +
1.413 +== Getting and Setting Cookies ==
1.414 +
1.415 +* setCookie(string)
1.416 +Sets the given string as the cookie for window's URL.
1.417 +
1.418 +* getCookie()
1.419 +Returns the cookie string for the window's URL, the cookie set by setCookie.
1.420 +
1.421 +== FPU Control ==
1.422 +
1.423 +x86-only on some OSes:
1.424 +
1.425 +* The .enableFPExceptions() method will enable floating-point exceptions,
1.426 + as evil plugins or extensions might do.
1.427 +
1.428 +== HiDPI Mode ==
1.429 +
1.430 +* queryContentsScaleFactor()
1.431 +Returns the contents scale factor. On platforms without support for this query
1.432 +always returns 1.0 (a double value). Likewise on hardware without HiDPI mode
1.433 +support.
