The Tor Browser / file comparison
comparison: dom/plugins/test/testplugin/README
dom/plugins/test/testplugin/README
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
equal
deleted
inserted
replaced
| -1:000000000000 | 0:15d449c7cb44 |
|---|---|
| 1 = Instructions for using the test plugin = | |
| 2 | |
| 3 == MIME type == | |
| 4 | |
| 5 The test plugin registers itself for the MIME type "application/x-test". | |
| 6 | |
| 7 == Event Model == | |
| 8 | |
| 9 * getEventModel() | |
| 10 Returns the NPAPI event model in use. On platforms without event models, | |
| 11 simply returns 0; | |
| 12 | |
| 13 == Rendering == | |
| 14 | |
| 15 By default, the plugin fills its rectangle with gray, with a black border, and | |
| 16 renders the user-agent string (obtained from NPN_UserAgent) centered in black. | |
| 17 This rendering method is not supported for the async drawing models. | |
| 18 | |
| 19 The test plugin supports the following parameters: | |
| 20 | |
| 21 * drawmode="solid" | |
| 22 The plugin will draw a solid color instead of the default rendering described | |
| 23 above. The default solid color is completely transparent black (i.e., nothing). | |
| 24 This should be specified when using one of the async models. | |
| 25 | |
| 26 * asyncmodel="bitmap" | |
| 27 The plugin will use the NPAPI Async Bitmap drawing model extension. On | |
| 28 unsupported platforms this will fallback to non-async rendering. | |
| 29 | |
| 30 * asyncmodel="dxgi" | |
| 31 The plugin will use the NPAPI Async DXGI drawing model extension. Only | |
| 32 supported on Windows Vista or higher. On unsupported platforms this will | |
| 33 fallback to non-async rendering. | |
| 34 | |
| 35 * color | |
| 36 This specifies the color to use for drawmode="solid". The value should be 8 hex | |
| 37 digits, 2 per channel in AARRGGBB format. | |
| 38 | |
| 39 == Generic API Tests == | |
| 40 | |
| 41 * setUndefinedValueTest | |
| 42 Attempts to set the value of an undefined variable (0x0) via NPN_SetValue, | |
| 43 returns true if it succeeds and false if it doesn't. It should never succeed. | |
| 44 | |
| 45 * .getReflector() | |
| 46 Hands back an object which reflects properties as values, e.g. | |
| 47 .getReflector().foo = 'foo' | |
| 48 .getReflector()['foo'] = 'foo' | |
| 49 .getReflector()[1] = 1 | |
| 50 | |
| 51 * .getNPNVdocumentOrigin() | |
| 52 Returns the origin string retrieved from the browser by a NPNVdocumentOrigin | |
| 53 variable request. Does not cache the value, gets it from the browser every time. | |
| 54 | |
| 55 == NPN_ConvertPoint testing == | |
| 56 | |
| 57 * convertPointX(sourceSpace, sourceX, sourceY, destSpace) | |
| 58 * convertPointY(sourceSpace, sourceX, sourceY, destSpace) | |
| 59 The plugin uses NPN_ConvertPoint to convert sourceX and sourceY from the source | |
| 60 to dest space and returns the X or Y result based on the call. | |
| 61 | |
| 62 == NPCocoaEventWindowFocusChanged == | |
| 63 | |
| 64 * getTopLevelWindowActivationState() | |
| 65 Returns the activation state for the top-level window as set by the last | |
| 66 NPCocoaEventWindowFocusChanged event. Returns true for active, false for | |
| 67 inactive, and throws an exception if the state is unknown (uninitialized). | |
| 68 | |
| 69 * getTopLevelWindowActivationEventCount() | |
| 70 Returns the number of NPCocoaEventWindowFocusChanged events received by | |
| 71 the instance. | |
| 72 | |
| 73 == Focus Tests == | |
| 74 | |
| 75 * getFocusState() | |
| 76 Returns the plugin's focus state. Returns true for focused, false for unfocused, | |
| 77 and throws an exception if the state is unknown (uninitialized). This does not | |
| 78 necessarily correspond to actual input focus - this corresponds to focus as | |
| 79 defined by the NPAPI event model in use. | |
| 80 | |
| 81 * getFocusEventCount() | |
| 82 Returns the number of focus events received by the instance. | |
| 83 | |
| 84 == NPRuntime testing == | |
| 85 | |
| 86 The test plugin object supports the following scriptable methods: | |
| 87 | |
| 88 * identifierToStringTest(ident) | |
| 89 Converts a string, int32 or double parameter 'ident' to an NPIdentifier and | |
| 90 then to a string, which is returned. | |
| 91 | |
| 92 * npnEvaluateTest(script) | |
| 93 Calls NPN_Evaluate on the 'script' argument, which is a string containing | |
| 94 some script to be executed. Returns the result of the evaluation. | |
| 95 | |
| 96 * npnInvokeTest(method, expected, args...) | |
| 97 Causes the plugin to call the specified script method using NPN_Invoke, | |
| 98 passing it 1 or more arguments specified in args. The return value of this | |
| 99 call is compared against 'expected', and if they match, npnInvokeTest will | |
| 100 return true. Otherwise, it will return false. | |
| 101 | |
| 102 * npnInvokeDefaultTest(object, argument) | |
| 103 Causes the plugin to call NPN_InvokeDefault on the specified object, | |
| 104 with the specified argument. Returns the result of the invocation. | |
| 105 | |
| 106 * getError() | |
| 107 If an error has occurred during the last stream or npruntime function, | |
| 108 this will return a string error message, otherwise it returns "pass". | |
| 109 | |
| 110 * throwExceptionNextInvoke() | |
| 111 Sets a flag which causes the next call to a scriptable method to throw | |
| 112 one or more exceptions. If no parameters are passed to the next | |
| 113 scriptable method call, it will cause a generic exception to be thrown. | |
| 114 Otherwise there will be one exception thrown per argument, with the argument | |
| 115 used as the exception message. Example: | |
| 116 | |
| 117 plugin.throwExceptionNextInvoke(); | |
| 118 plugin.npnInvokeTest("first exception message", "second exception message"); | |
| 119 | |
| 120 * () - default method | |
| 121 Returns a string consisting of the plugin name, concatenated with any | |
| 122 arguments passed to the method. | |
| 123 | |
| 124 * .crash() - Crashes the plugin | |
| 125 | |
| 126 * getObjectValue() - Returns a custom plugin-implemented scriptable object. | |
| 127 * checkObjectValue(obj) - Returns true if the object from setObjectValue() is | |
| 128 the same object passed into this function. It should return true when | |
| 129 the object is passed to the same plugin instance, and false when passed | |
| 130 to other plugin instances, see bug 532246 and | |
| 131 test_multipleinstanceobjects.html. | |
| 132 | |
| 133 * callOnDestroy(fn) - Calls `fn` when the plugin instance is being destroyed | |
| 134 | |
| 135 * getAuthInfo(protocol, host, port, scheme, realm) - a wrapper for | |
| 136 NPN_GetAuthenticationInfo(). Returns a string "username|password" for | |
| 137 the specified auth criteria, or throws an exception if no data is | |
| 138 available. | |
| 139 | |
| 140 * timerTest(callback) - initiates tests of NPN_ScheduleTimer & | |
| 141 NPN_UnscheduleTimer. When finished, calls the script callback | |
| 142 with a boolean value, indicating whether the tests were successful. | |
| 143 | |
| 144 * asyncCallbackTest(callback) - initiates tests of | |
| 145 NPN_PluginThreadAsyncCall. When finished, calls the script callback | |
| 146 with a boolean value, indicating whether the tests were successful. | |
| 147 | |
| 148 * paintscript="..." content attribute | |
| 149 If the "paintscript" attribute is set on the plugin element during plugin | |
| 150 initialization, then every time the plugin paints it gets the contents of that | |
| 151 attribute and evaluates it as a script in the context of the plugin's DOM | |
| 152 window. This is useful for testing evil plugin code that might, for example, | |
| 153 modify the DOM during painting. | |
| 154 | |
| 155 == Private browsing == | |
| 156 | |
| 157 The test plugin object supports the following scriptable methods: | |
| 158 | |
| 159 * queryPrivateModeState | |
| 160 Returns the value of NPN_GetValue(NPNVprivateModeBool). | |
| 161 | |
| 162 * lastReportedPrivateModeState | |
| 163 Returns the last value set by NPP_SetValue(NPNVprivateModeBool). | |
| 164 | |
| 165 == Windowed/windowless mode == | |
| 166 | |
| 167 The test plugin is windowless by default. | |
| 168 | |
| 169 The test plugin supports the following parameter: | |
| 170 | |
| 171 * wmode="window" | |
| 172 The plugin will be given a native widget on platforms where we support this | |
| 173 (Windows and X). | |
| 174 | |
| 175 The test plugin object supports the following scriptable method: | |
| 176 | |
| 177 * hasWidget() | |
| 178 Returns true if the plugin has an associated widget. This will return true if | |
| 179 wmode="window" was specified and the platform supports windowed plugins. | |
| 180 | |
| 181 == Plugin invalidation == | |
| 182 | |
| 183 * setColor(colorString) | |
| 184 Sets the color used for drawmode="solid" and invalidates the plugin area. | |
| 185 This calls NPN_Invalidate, even for windowed plugins, since that should work | |
| 186 for windowed plugins too (Silverlight depends on it). | |
| 187 | |
| 188 * getPaintCount() | |
| 189 Returns the number of times this plugin instance has processed a paint request. | |
| 190 This can be used to detect whether painting has happened in a plugin's | |
| 191 window. | |
| 192 | |
| 193 * getWidthAtLastPaint() | |
| 194 Returns the window width that was current when the plugin last painted. | |
| 195 | |
| 196 * setInvalidateDuringPaint(value) | |
| 197 When value is true, every time the plugin paints, it will invalidate | |
| 198 itself *during the paint* using NPN_Invalidate. | |
| 199 | |
| 200 * setSlowPaint(value) | |
| 201 When value is true, the instance will sleep briefly during paint. | |
| 202 | |
| 203 == Plugin geometry == | |
| 204 | |
| 205 The test plugin supports the following scriptable methods: | |
| 206 | |
| 207 * getEdge(edge) | |
| 208 Returns the integer screen pixel coordinate of an edge of the plugin's | |
| 209 area: | |
| 210 -- edge=0: returns left edge coordinate | |
| 211 -- edge=1: returns top edge coordinate | |
| 212 -- edge=2: returns right edge coordinate | |
| 213 -- edge=3: returns bottom edge coordinate | |
| 214 The coordinates are relative to the top-left corner of the top-level window | |
| 215 containing the plugin, including the window decorations. Therefore: | |
| 216 -- On Mac, they're relative to the top-left corner of the toplevel Cocoa | |
| 217 window. | |
| 218 -- On Windows, they're relative to the top-left corner of the toplevel HWND's | |
| 219 non-client area. | |
| 220 -- On GTK2, they're relative to the top-left corner of the toplevel window's | |
| 221 window manager frame. | |
| 222 This means they can be added to Gecko's window.screenX/screenY (if DPI is set | |
| 223 to 96) to get screen coordinates. | |
| 224 On the platforms that support window-mode plugins (Windows/GTK2), this only | |
| 225 works for window-mode plugins. It will throw an error for windowless plugins. | |
| 226 | |
| 227 * getClipRegionRectCount() | |
| 228 Returns the number of rectangles in the plugin's clip region. | |
| 229 For plugins with widgets, the clip region is computed as the intersection of the | |
| 230 clip region for the widget (if the platform does not support clip regions | |
| 231 on native widgets, this would just be the widget's rectangle) with the | |
| 232 clip regions of all ancestor widgets which would clip this widget. | |
| 233 On the platforms that support window-mode plugins (Windows/GTK2), this only | |
| 234 works for window-mode plugins. It will throw an error for windowless plugins. | |
| 235 On Mac, all plugins have a clip region containing just a single clip | |
| 236 rectangle only. So if you request wmode="window" but the plugin reports | |
| 237 !hasWidget, you can assume that complex clip regions are not supported. | |
| 238 | |
| 239 * getClipRegionRectEdge(i, edge) | |
| 240 Returns the integer screen pixel coordinate of an edge of a rectangle from the | |
| 241 plugin's clip region. If i is less than zero or greater than or equal to | |
| 242 getClipRegionRectCount(), this will throw an error. The coordinates are | |
| 243 the same as for getEdge. See getClipRegionRectCount() above for | |
| 244 notes on platform plugin limitations. | |
| 245 | |
| 246 == Keyboard events == | |
| 247 | |
| 248 * getLastKeyText() | |
| 249 Returns the text which was inputted by last keyboard events. This is cleared at | |
| 250 every keydown event. | |
| 251 NOTE: Currently, this is implemented only on Windows. | |
| 252 | |
| 253 == Mouse events == | |
| 254 | |
| 255 The test plugin supports the following scriptable methods: | |
| 256 | |
| 257 * getLastMouseX() | |
| 258 Returns the X coordinate of the last mouse event (move, button up, or | |
| 259 button down), relative to the left edge of the plugin, or -1 if no mouse | |
| 260 event has been received. | |
| 261 | |
| 262 * getLastMouseX() | |
| 263 Returns the Y coordinate of the last mouse event (move, button up, or | |
| 264 button down), relative to the top edge of the plugin, or -1 if no mouse | |
| 265 event has been received. | |
| 266 | |
| 267 == Instance lifecycle == | |
| 268 | |
| 269 The test plugin supports the following scriptable methods: | |
| 270 | |
| 271 * startWatchingInstanceCount() | |
| 272 Marks all currently running instances as "ignored". Throws an exception if | |
| 273 there is already a watch (startWatchingInstanceCount has already been | |
| 274 called on some instance without a corresponding stopWatchingInstanceCount). | |
| 275 | |
| 276 * getInstanceCount() | |
| 277 Returns the count of currently running instances that are not ignored. | |
| 278 Throws an exception if there is no watch. | |
| 279 | |
| 280 * stopWatchingInstanceCount() | |
| 281 Stops watching. Throws an exception if there is no watch. | |
| 282 | |
| 283 == NPAPI Timers == | |
| 284 | |
| 285 * unscheduleAllTimers() | |
| 286 Instructs the plugin instance to cancel all timers created via | |
| 287 NPN_ScheduleTimer. | |
| 288 | |
| 289 == Stream Functionality == | |
| 290 | |
| 291 The test plugin enables a variety of NPAPI streaming tests, which are | |
| 292 initiated by passing a variety of attributes to the <embed> element which | |
| 293 causes the plugin to be initialized. The plugin stream test code is | |
| 294 designed to receive a stream from the browser (by specifying a "src", | |
| 295 "geturl", or "geturlnotify" attribute), and then (if a "frame" attribute | |
| 296 is specified) send the data from that stream back to the browser in another | |
| 297 stream, whereupon it will be displayed in the specified frame. If some | |
| 298 error occurs during stream processing, an error message will appear in the | |
| 299 frame instead of the stream data. If no "frame" attribute is present, a | |
| 300 stream can still be received by the plugin, but the plugin will do nothing | |
| 301 with it. | |
| 302 | |
| 303 The attributes which control stream tests are: | |
| 304 | |
| 305 "streammode": one of "normal", "asfile", "asfileonly", "seek". Sets the | |
| 306 stream mode to the specified mode in any call to NPP_NewStream. | |
| 307 Defaults to "asfileonly". | |
| 308 | |
| 309 "streamchunksize": the number of bytes the plugin reports it can accept | |
| 310 in calls to NPP_WriteReady. Defaults to 1,024. | |
| 311 | |
| 312 "src": a url. If specified, the browser will call NPP_NewStream for | |
| 313 this url as soon as the plugin is initialized. | |
| 314 | |
| 315 "geturl": a url. If specified, the plugin will request this url | |
| 316 from the browser when the plugin is initialized, via a call to | |
| 317 NPN_GetURL. | |
| 318 | |
| 319 "geturlnotify": a url. If specified, the plugin will request this url | |
| 320 from the browser when the plugin is initialized, via a call to | |
| 321 NPN_GetURLNotify. The plugin passes some "notifyData" to | |
| 322 NPN_GetURLNotify, which it verifies is present in the call to | |
| 323 NPP_URLNotify. If the "notifyData" does not match, an error | |
| 324 will be displayed in the test frame (if any), instead of the stream | |
| 325 data. | |
| 326 | |
| 327 "frame": the name of a frame in the same HTML document as the <embed> | |
| 328 element which instantiated the plugin. For any of the preceding three | |
| 329 attributes, a stream is received by the plugin via calls to NPP_NewStream, | |
| 330 NPP_WriteReady, NPP_Write, and NPP_DestroyStream. When NPP_DestroyStream | |
| 331 is called (or NPP_UrlNotify, in the case of "geturlnotify"), and a | |
| 332 "frame" attribute is present, the data from the stream is converted into a | |
| 333 data: url, and sent back to the browser in another stream via a call to | |
| 334 NPN_GetURL, whereupon it should be displayed in the specified frame. | |
| 335 | |
| 336 "range": one or more byte ranges, in the format "offset,length;offset,length". | |
| 337 Only valid when "streammode" = "seek". When "range" is present, the plugin | |
| 338 will request the specified byte ranges from the stream via a call to | |
| 339 NPN_RequestRead, which it makes after the browser makes its final call to | |
| 340 NPP_Write. The plugin verifies that the browser makes additional calls | |
| 341 to NPP_Write according to the requested byte ranges, and that the data | |
| 342 received is correct. Any errors will appear in the test "frame", if | |
| 343 specified. | |
| 344 | |
| 345 "posturl": a url. After the plugin receives a stream, and NPP_DestroyStream | |
| 346 is called, if "posturl" is specified, the plugin will post the contents | |
| 347 of the stream to the specified url via NPN_PostURL. See "postmode" for | |
| 348 additional details. | |
| 349 | |
| 350 "postmode": either "frame" or "stream". If "frame", and a "frame" attribute | |
| 351 is present, the plugin will pass the frame name to calls to NPN_PostURL, | |
| 352 so that the HTTP response from that operation will be displayed in the | |
| 353 specified frame. If "stream", the HTTP response is delivered to the plugin | |
| 354 via calls to NPP_NewStream etc, and if a "frame" attribute is present, the | |
| 355 contents of that stream will be passed back to the browser and displayed | |
| 356 in the specified frame via NPN_GetURL. | |
| 357 | |
| 358 "newstream": if "true", then any stream which is sent to a frame in the browser | |
| 359 is sent via calls to NPN_NewStream and NPN_Write. Doing so will cause | |
| 360 the browser to store the stream data in a file, and set the frame's | |
| 361 location to the corresponding file:// url. | |
| 362 | |
| 363 "functiontofail": one of "npp_newstream", "npp_write", "npp_destroystream". | |
| 364 When specified, the given function will return an error code (-1 for | |
| 365 NPP_Write, or else the value of the "failurecode" attribute) the first time | |
| 366 it is called by the browser. | |
| 367 | |
| 368 "failurecode": one of the NPError constants. Used to specify the error | |
| 369 that will be returned by the "functiontofail". | |
| 370 | |
| 371 If the plugin is instantiated as a full-page plugin, the following defaults | |
| 372 are used: | |
| 373 streammode="seek" frame="testframe" range="100,100" | |
| 374 | |
| 375 * streamTest(url, doPost, postData, writeCallback, notifyCallback, redirectCallback, allowRedirects) | |
| 376 This will test how NPN_GetURLNotify and NPN_PostURLNotify behave when they are | |
| 377 called with arbitrary (malformed) URLs. The function will return `true` if | |
| 378 NPN_[Get/Post]URLNotify succeeds, and `false` if it fails. | |
| 379 @url url to request | |
| 380 @param doPost whether to call NPN_PostURLNotify | |
| 381 @param postData null, or a string to send a postdata | |
| 382 @writeCallback will be called when data is received for the stream | |
| 383 @notifyCallback will be called when the urlnotify is received with the notify result | |
| 384 @redirectCallback will be called from urlredirectnotify if a redirect is attempted | |
| 385 @allowRedirects boolean value indicating whether or not to allow redirects | |
| 386 | |
| 387 * setPluginWantsAllStreams(wantsAllStreams) | |
| 388 Set the value returned by the plugin for NPPVpluginWantsAllNetworkStreams. | |
| 389 | |
| 390 == Internal consistency == | |
| 391 | |
| 392 * doInternalConsistencyCheck() | |
| 393 Does internal consistency checking, returning an empty string if everything is | |
| 394 OK, otherwise returning some kind of error string. On Windows, in windowed | |
| 395 mode, this checks that the position of the plugin's internal child | |
| 396 window has not been disturbed relative to the plugin window. | |
| 397 | |
| 398 == Windows native widget message behaviour == | |
| 399 | |
| 400 * Mouse events are handled (saving the last mouse event coordinate) and not | |
| 401 passed to the overridden windowproc. | |
| 402 | |
| 403 * WM_MOUSEWHEEL events are handled and not passed to the parent window or the | |
| 404 overridden windowproc. | |
| 405 | |
| 406 * WM_MOUSEACTIVATE events are handled by calling SetFocus on the plugin's | |
| 407 widget, if the plugin is windowed. If it's not windowed they're passed to | |
| 408 the overriden windowproc (but hopefully never sent by the browser anyway). | |
| 409 | |
| 410 == Getting and Setting Cookies == | |
| 411 | |
| 412 * setCookie(string) | |
| 413 Sets the given string as the cookie for window's URL. | |
| 414 | |
| 415 * getCookie() | |
| 416 Returns the cookie string for the window's URL, the cookie set by setCookie. | |
| 417 | |
| 418 == FPU Control == | |
| 419 | |
| 420 x86-only on some OSes: | |
| 421 | |
| 422 * The .enableFPExceptions() method will enable floating-point exceptions, | |
| 423 as evil plugins or extensions might do. | |
| 424 | |
| 425 == HiDPI Mode == | |
| 426 | |
| 427 * queryContentsScaleFactor() | |
| 428 Returns the contents scale factor. On platforms without support for this query | |
| 429 always returns 1.0 (a double value). Likewise on hardware without HiDPI mode | |
| 430 support. |
