From 8b5d3c6b75744cf5938f253d20f367999e92b1a7 Mon Sep 17 00:00:00 2001 From: Trevor Elliott Date: Fri, 7 Jun 2013 16:42:11 -0700 Subject: Remove the addon-sdk from the repo, and download it on demand --- .../addon-sdk-1.5/packages/api-utils/docs/xpcom.md | 227 --------------------- 1 file changed, 227 deletions(-) delete mode 100644 tools/addon-sdk-1.5/packages/api-utils/docs/xpcom.md (limited to 'tools/addon-sdk-1.5/packages/api-utils/docs/xpcom.md') diff --git a/tools/addon-sdk-1.5/packages/api-utils/docs/xpcom.md b/tools/addon-sdk-1.5/packages/api-utils/docs/xpcom.md deleted file mode 100644 index e62aaa7..0000000 --- a/tools/addon-sdk-1.5/packages/api-utils/docs/xpcom.md +++ /dev/null @@ -1,227 +0,0 @@ - - -Using this module you can: - -* register a component with -[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components), -making it available to all XPCOM clients -* retrieve a factory for a given XPCOM component -* generate a UUID - -The module also exposes the -[XPCOMUtils](https://developer.mozilla.org/en/JavaScript_code_modules/XPCOMUtils.jsm) -module. - - -@function - -Makes a component available through XPCOM. - -This function creates and registers a factory for a component given a -constructor for it and some metadata: a -[class ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#CID), a [contract ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#Contract_ID), -and a name. - -In this example the HelloWorld component is available to JavaScript only, so we use the technique documented under the "Using wrappedJSObject" section of [How to Build an XPCOM Component in JavaScript](https://developer.mozilla.org/en/How_to_Build_an_XPCOM_Component_in_Javascript). - - var xpcom = require("xpcom"); - - function HelloWorld() { - this.wrappedJSObject = this; - } - - HelloWorld.prototype = { - QueryInterface: xpcom.utils.generateQI(), - hello: function() { - return "Hello World!"; - } - }; - - xpcom.register({name: "Hello World Component", - contractID: "@me.org/myComponent", - create: HelloWorld}); - -XPCOM clients can subsequently access this factory and use it to create -instances of the component. - - var {Ci} = require("chrome"); - - var factory = xpcom.getClass("@me.org/myComponent", Ci.nsIFactory); - var helloWorld = factory.createInstance(null, Ci.nsISupports).wrappedJSObject; - console.log(helloWorld.hello()); - -`register()` returns a Factory object for the component which implements -the `createInstance()` and `QueryInterface()` functions of the -[`nsIFactory`](https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIFactory) and -[`nsISupports`](https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsISupports) -interfaces, as well as defining an `unregister()` function to remove the -component from XPCOM. - -When the module is unloaded, all components registered via the `register()` -function are automatically unregistered. - -@param options {object} - -@prop [uuid] {nsIDPtr} -A [UUID](https://developer.mozilla.org/en/Generating_GUIDs) which will be -used as the -[class ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#CID) -for this component. If you don't include this option, the `register()` -function will generate a new UUID. - -@prop create {function} -The constructor for the component. - -@prop name {string} -A human-readable name for the component. - -@prop contractID {string} -A human-readable string which will be used as the -[contract ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#Contract_ID) -for the component. An XPCOM client will be able to use this value to access -the component. - -@returns {Factory} -See the documentation for the `Factory` class in this page. - - - -@function -Returns the factory object for the class specified by `contractID`. - -For example, given a registered XPCOM component which is identified with -the contract ID "@me.org/myComponent", we can access a factory and then -use it to instantiate the component in the following way: - - var xpcom = require("xpcom"); - var {Ci} = require("chrome"); - - var factory = xpcom.getClass("@me.org/myComponent", Ci.nsIFactory); - var helloWorld = factory.createInstance(null, Ci.nsISupports).wrappedJSObject; - console.log(helloWorld.hello()); - -@param contractID {string} -The -[contract ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#Contract_ID) -for the component whose factory will be returned. - -@param [iid] {iid} -The interface type to be returned. These objects are usually accessed through -the `Components.interfaces`, or `Ci`, object. - -The methods of this interface will be callable on the returned factory object. -Usually you want this to be -[`Ci.nsIFactory`](https://developer.mozilla.org/En/nsIFactory), but if you know -a component has a factory that implements a more specific type of factory -interface, you can pass that interface here. If you don't include this option -only the methods of -[`nsISupports`](https://developer.mozilla.org/En/NsISupports) -will be callable, which is probably not what you want. - -@returns {object} -The factory object. The type of this object will depend on the value of the -`iid` argument. If no `iid` argument is specified it will be of type -[`nsISupports`](https://developer.mozilla.org/En/NsISupports). - -Note that this object is not a `Factory` object as defined by this module. -If you previously registered the component by calling the `register()` -function and you need to access the `Factory` object for the component, for -example to call the `Factory`'s `unregister()` method, you can do so by -getting the -[`wrappedJSObject`](https://developer.mozilla.org/en/wrappedJSObject) -property of the returned object: - - var factory = xpcom.getClass("@me.org/myComp", Ci.nsIFactory).wrappedJSObject; - factory.unregister(); - - - - -@property {object} -The -[XPCOMUtils](https://developer.mozilla.org/en/JavaScript_code_modules/XPCOMUtils.jsm) -module. - - - -@function -Generates and returns a new -[UUID](https://developer.mozilla.org/en/Generating_GUIDs). - -Calling `toString()` on this object will yield the UUID in string form. -@returns {nsIDPtr} - - - -@class - -When a component is made available through XPCOM using the `register()` -function, `register()` returns a `Factory` object that can be used to -instantiate the component using its `createInstance()` function: - - var factory = require("xpcom").register({ - name: "My Component", - contractID: "@me.org/myComponent", - create: MyComponent - }); - - var {Ci} = require("chrome"); - var component = factory.createInstance(null, Ci.nsISupports).wrappedJSObject; - -In this example we haven't defined a custom interface ID for the component. -Instead we pass `Ci.nsISupports` as the interface ID, and use `wrappedJSObject` -to retrieve the component. For more details on this technique see the -[guide to building XPCOM components in JavaScript](https://developer.mozilla.org/en/How_to_Build_an_XPCOM_Component_in_Javascript). - -`Factory` also implements its own `unregister()` function, -which unregisters the component from XPCOM. - - -@method -Creates an instance of the component associated with this factory. - -@param outer {nsISupports} -This argument must be `null`, or the function throws -`Cr.NS_ERROR_NO_AGGREGATION`. - -@param iid {iid} -Interface identifier. These objects are usually accessed through -the `Components.interfaces`, or `Ci`, object. The methods of this -interface will be callable on the returned object. - -If the object implements an interface that's already defined in XPCOM, you -can pass that in here: - - var about = aboutFactory.createInstance(null, Ci.nsIAboutModule); - // You can now access the nsIAboutModule interface of the 'about' object - -If you will be getting the `wrappedJSObject` property from the returned -object to access its JavaScript implementation, pass `Ci.nsISupports` here: - - var custom = factory.createInstance(null, Ci.nsISupports).wrappedJSObject; - // You can now access the interface defined for the 'custom' object - - - - -@method -This method is called automatically by XPCOM, so usually you don't need -to call it yourself. It returns the `Factory` object itself such that the -methods of the given interface are callable on it. - -@param interfaces {iid} -There are only two legal values for this parameter: `Ci.nsIFactory` and -`Ci.nsISupports`. Any other value will cause this method to throw -`Cr.NS_ERROR_NO_INTERFACE`. - -@returns {Factory} - - - -@method -Unregisters the factory's component. - - - -- cgit v1.2.3