Compare Revisions

XPCOMUtils.jsm

Revision 45633:

Revision 45633 by mozjonathan on

Revision 45634:

Revision 45634 by Soupdragon on

Title:
XPCOMUtils.jsm
XPCOMUtils.jsm
Slug:
JavaScript_code_modules/XPCOMUtils.jsm
JavaScript_code_modules/XPCOMUtils.jsm
Tags:
NeedsTechnicalReview, XPConnect, "XPCOM:Language Bindings"
NeedsTechnicalReview, XPConnect, "XPCOM:Language Bindings"
Content:

Revision 45633
Revision 45634
nn7    <p>
8      {{ gecko_minversion_header("1.9") }}
9    </p>
10    <p>
11      The <span style="font-family: monospace;">XPCOMUtils</span>
 ><code>.jsm</code> JavaScript code module offers utility routines 
 >for JavaScript components loaded by the JavaScript component load
 >er.
12    </p>
13    <p>
14      To use this, you first need to import the code module into 
 >your JavaScript scope:
15    </p>
16    <pre>
17Components.utils.import("resource://gre/modules/XPCOMUtils.jsm");
18</pre>
19    <h2>
20      Using XPCOMUtils
21    </h2>
22    <p>
23      Exposing a JavaScript class as a component using these util
 >ity methods requires four key steps:
24    </p>
25    <ol>
26      <li>Import <code>XPCOMUtils.jsm</code>, as explained previo
 >usly.
27      </li>
28      <li>Declare the class (or multiple classes)&nbsp;implementi
 >ng the component(s).
29      </li>
30      <li>Create an array of component constructors.
31      </li>
32      <li>Define the <code>NSGetModule()</code> entry point.
33      </li>
34    </ol>
35    <h3>
36      Pseudocode
37    </h3>
38    <p>
39      This section provides some pseudocode that demonstrates how
 > to put together a JavaScript class based on the steps listed abo
 >ve.
40    </p>
41    <h4>
42      Constructor
43    </h4>
44    <p>
45      The constructor is a simple method that handles any require
 >d initialization tasks.
46    </p>
47    <pre class="brush: js">
48function MyComponent() {
49  // initialize the component here
50
51</pre>
52    <h4>
53      Class declaration
54    </h4>
55    <p>
56      Declare the class prototype, using a form similar to this.
57    </p>
58    <pre class="brush: js">
59MyComponent.prototype = {
60  // properties required for XPCOM registration:
61  classDescription: "unique text description",
62  classID:          Components.ID("{xxxxxxxx-xxxx-xxxx-xxxx-xxxxx
 >xxxxxxx}"),
63  contractID:       "@example.com/xxx;1",
64 
65  // [optional] custom factory (an object implementing nsIFactory
 >). If not
66  // provided, the default factory is used, which returns
67  // |(new MyComponent()).QueryInterface(iid)| in its createInsta
 >nce().
68  _xpcom_factory: { ... },
69 
70  // [optional] an array of categories to register this component
 > in.
71  _xpcom_categories: [{
72    // Each object in the array specifies the parameters to pass 
 >to
73    // nsICategoryManager.addCategoryEntry(). 'true' is passed fo
 >r
74    // both aPersist and aReplace params.
75    category: "some-category",
76    // optional, defaults to the object's classDescription
77    entry: "entry name",
78    // optional, defaults to the object's contractID (unless
79    // 'service' is specified)
80    value: "...",
81    // optional, defaults to false. When set to true, and only if
 > 'value'
82    // is not specified, the concatenation of the string "service
 >," and the
83    // object's contractID is passed as aValue parameter of addCa
 >tegoryEntry.
84    service: true,
85    // optional array of applications' IDs in the form:
86    // [ "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}", ... ]
87    // If this is defined, the component is registered in this
88    // category only on the specified applications.
89    apps: [ ... ]
90  }],
91 
92  // QueryInterface implementation, e.g. using the generateQI hel
 >per
93  QueryInterface: XPCOMUtils.generateQI(
94    [Components.interfaces.nsIObserver,
95     Components.interfaces.nsIMyInterface,
96     "nsIFoo",
97     "nsIBar" ]),
98 
99  // ...component implementation...
100};
101</pre>
102    <div class="geckoVersionNote">
103      <p>
104        {{ gecko_callout_heading("2.0") }}
105      </p>
106      <p>
107        The ability to register the component in a category only 
 >on specific applications by adding the apps field to a category e
 >ntry was added in Gecko 2.0 {{ geckoRelease("2.0") }}.
108      </p>
109    </div>
110    <p>
111      Notice that the <code>QueryInterface()</code>&nbsp;method i
 >mplemented by the component simply calls the <a href="/en/JavaScr
 >ipt/Code_modules/XPCOMUtils.jsm#generateQI()" title="en/JavaScrip
 >t code modules/XPCOMUtils.jsm#generateQI()"><code>generateQI()</c
 >ode></a> method provided by the XPCOMUtils code module.
112    </p>
113    <h4>
114      Create an array of component constructors
115    </h4>
116    <p>
117      You need to create an array that lists the constructors for
 > each component. This array can of course have just one entry:
118    </p>
119    <pre>
120var components = [MyComponent];
121</pre>
122    <p>
123      Here, we're calling the array <code>components</code>.
124    </p>
125    <h4>
126      Create the NSGetModule()&nbsp;entry point
127    </h4>
128    <p>
129      Finally, you need to implement the <code>NSGetModule()</cod
 >e> entry point so Gecko can start up your component:
130    </p>
131    <pre>
132function NSGetModule(compMgr, fileSpec) {
133  // "components" is the array created in the previous section
134 
135  return XPCOMUtils.generateModule(components);
136}
137</pre>
n14            <code>function <a href="/en/JavaScript_code_modules/Xn145            <code>function <a href="/en/JavaScript/Code_modules/X
>PCOMUtils.jsm#defineLazyGetter()" title="en/JavaScript code modul>PCOMUtils.jsm#defineLazyGetter()" title="en/JavaScript code modul
>es/XPCOMUtils.jsm#defineLazyGetter()">defineLazyGetter</a>(aObjec>es/XPCOMUtils.jsm#defineLazyGetter()">defineLazyGetter</a>(aObjec
>t, aName, aLambda);</code> {{ gecko_minversion_inline("1.9.2") }}>t, aName, aLambda);</code> {{ gecko_minversion_inline("1.9.2") }}
n19            <code>function <a href="/en/JavaScript_code_modules/Xn150            <code>function <a href="/en/JavaScript/Code_modules/X
>PCOMUtils.jsm#defineLazyServiceGetter()" title="en/JavaScript cod>PCOMUtils.jsm#defineLazyServiceGetter()" title="en/JavaScript cod
>e modules/XPCOMUtils.jsm#defineLazyServiceGetter()">defineLazySer>e modules/XPCOMUtils.jsm#defineLazyServiceGetter()">defineLazySer
>viceGetter</a>(aObject, aName, aContract, aInterfaceName);</code>>viceGetter</a>(aObject, aName, aContract, aInterfaceName);</code>
> {{ gecko_minversion_inline("1.9.2") }}> {{ gecko_minversion_inline("1.9.2") }}
n24            <code>nsIModule <a href="/en/JavaScript_code_modules/n155            <code>nsIModule <a href="/en/JavaScript/Code_modules/
>XPCOMUtils.jsm#generateModule()" title="en/JavaScript code module>XPCOMUtils.jsm#generateModule()" title="en/JavaScript code module
>s/XPCOMUtils.jsm#generateModule()">generateModule</a>(componentsA>s/XPCOMUtils.jsm#generateModule()">generateModule</a>(componentsA
>rray, postRegister, preUnregister);</code>>rray, postRegister, preUnregister);</code>
n29            <code>function <a href="/en/JavaScript_code_modules/Xn160            <code>function <a href="/en/JavaScript/Code_modules/X
>PCOMUtils.jsm#generateNSGetModule()" title="en/JavaScript code mo>PCOMUtils.jsm#generateNSGetModule()" title="en/JavaScript code mo
>dules/XPCOMUtils.jsm#generateNSGetModule()">generateNSGetModule</>dules/XPCOMUtils.jsm#generateNSGetModule()">generateNSGetModule</
>a>(componentsArray, postRegister, preUnregister);</code>>a>(componentsArray, postRegister, preUnregister);</code>
n34            <code>function <a href="/en/JavaScript_code_modules/Xn165            <code>function <a href="/en/JavaScript/Code_modules/X
>PCOMUtils.jsm#generateQI()" title="en/JavaScript code modules/XPC>PCOMUtils.jsm#generateQI()" title="en/JavaScript code modules/XPC
>OMUtils.jsm#generateQI()">generateQI</a>(interfaces);</code>>OMUtils.jsm#generateQI()">generateQI</a>(interfaces);</code>
35          </td>
36        </tr>
37        <tr>
38          <td>
39            <code>function <a href="/en/JavaScript_code_modules/X
>PCOMUtils.jsm#importRelative()" title="en/JavaScript code modules 
>/XPCOMUtils.jsm#importRelative()">importRelative</a>(that, path); 
></code> {{ gecko_minversion_inline("6") }} 
tt170    <h2>
171      Methods
172    </h2>
173    <p>
174      {{ method_gecko_minversion("defineLazyGetter", "1.9.2") }}
175    </p>
176    <p>
177      Defines a function on a specified object that acts as a get
 >ter which will be created the first time it's used.
178    </p>
179    <pre>
180<code>function defineLazyGetter(<br>  aObject,<br>  aName,<br>  a
 >Lambda<br>);</code> 
181</pre>
182    <h6>
183      Parameters
184    </h6>
185    <dl>
186      <dt>
187        <code>aObject<br></code>
188      </dt>
189      <dd>
190        The object into which to add the new lazy getter function
 >.
191      </dd>
192      <dt>
193        <code>aName</code>
194      </dt>
195      <dd>
196        The name of the getter function to create.
197      </dd>
198      <dt>
199        <code>aLambda</code>
200      </dt>
201      <dd>
202        A function that returns the value the getter should retur
 >n. This function is called exactly once.&nbsp; <code>this</code> 
 >will reference <code>aObject</code> during execution of the funct
 >ion.
203      </dd>
204    </dl>
205    <h6>
206      Return value
207    </h6>
208    <p>
209      The created function, which has been added to <code>aObject
 ></code> using the name <code>aName</code>.
210    </p>
211    <p>
212      {{ method_gecko_minversion("defineLazyServiceGetter", "1.9.
 >2") }}
213    </p>
214    <p>
215      Defines a function on a specified object which acts as a ge
 >tter for a service. The service isn't obtained until the first ti
 >me it's used.
216    </p>
217    <pre>
218function defineLazyServiceGetter(
219  aObject,
220  aName,
221  aContract,
222  aInterfaceName
223);
224</pre>
225    <h6>
226      Parameters
227    </h6>
228    <dl>
229      <dt>
230        <code>aObject</code>
231      </dt>
232      <dd>
233        The object into which to ad the new lazy service getter f
 >unction.
234      </dd>
235      <dt>
236        <code>aName</code>
237      </dt>
238      <dd>
239        The name of the getter function to create.
240      </dd>
241      <dt>
242        <code>aContract</code>
243      </dt>
244      <dd>
245        The contract to use to obtain the service.
246      </dd>
247      <dt>
248        <code>aInterfaceName</code>
249      </dt>
250      <dd>
251        The name of the interface to query the service to.
252      </dd>
253    </dl>
254    <h6>
255      Return value
256    </h6>
257    <p>
258      The created function, which has been added to <code>aObject
 ></code> with the name <code>aName</code>.
259    </p>
260    <h3>
261      generateModule()
262    </h3>
263    <p>
264      Generates a module implementation.
265    </p>
266    <pre>
267nsIModule generateModule(
268  componentsArray,
269  postRegister,
270  preUnregister
271); 
272</pre>
273    <h6>
274      Parameters
275    </h6>
276    <dl>
277      <dt>
278        <code>componentsArray</code>
279      </dt>
280      <dd>
281        An array of component constructors.
282      </dd>
283      <dt>
284        <code>postRegister</code>
285      </dt>
286      <dd>
287        An optional function that is called after the module is r
 >egistered. See Post-registration callback.
288      </dd>
289      <dt>
290        <code>preUnregister</code>
291      </dt>
292      <dd>
293        An optional function that's called before the module is u
 >nregistered. See Pre-unregistration callback.
294      </dd>
295    </dl>
296    <h6>
297      Return value
298    </h6>
299    <p>
300      An {{ interface("nsIModule") }} that implements the module.
301    </p>
302    <h3>
303      generateNSGetModule()
304    </h3>
305    <p>
306      Generates the <code>NSGetModule()</code>&nbsp;function alon
 >g with the module definition. You can use this instead of <a href
 >="/en/JavaScript/Code_modules/XPCOMUtils.jsm#generateModule()" ti
 >tle="en/JavaScript code modules/XPCOMUtils.jsm#generateModule()">
 ><code>generateModule()</code></a> to create both the module and t
 >he <code>NSGetModule()</code>&nbsp;function at the same time.
307    </p>
308    <pre>
309nsIModule generateNSGetModule(
310  componentsArray,
311  postRegister,
312  preUnregister
313); 
314</pre>
315    <h6>
316      Parameters
317    </h6>
318    <dl>
319      <dt>
320        <code>componentsArray</code>
321      </dt>
322      <dd>
323        An array of component constructors.
324      </dd>
325      <dt>
326        <code>postRegister</code>
327      </dt>
328      <dd>
329        An optional function that is called after the module is r
 >egistered. See Post-registration callback.
330      </dd>
331      <dt>
332        <code>preUnregister</code>
333      </dt>
334      <dd>
335        An optional function that's called before the module is u
 >nregistered. See Pre-unregistration callback.
336      </dd>
337    </dl>
338    <h6>
339      Return value
340    </h6>
341    <p>
342      An {{ interface("nsIModule") }} that implements the module.
343    </p>
344    <h3>
345      generateQI()
346    </h3>
347    <p>
348      Generates a <code>QueryInterface()</code>&nbsp;function imp
 >lementation. You need to assign the returned function to the <cod
 >e>QueryInterface</code> property of a JavaScript object.
349    </p>
350    <p>
351      When the generated method is invoked on that object, it che
 >cks to see if the specified IID is listed in the array specified 
 >by the <code>interfaces</code> parameter; if it is, <code>this</c
 >ode> (that is, the object itself)&nbsp;is returned. Otherwise, <c
 >ode>null</code> is returned.
352    </p>
353    <pre>
354function generateQI(
355  interfaces
356); 
357</pre>
358    <h6>
359      Parameters
360    </h6>
361    <dl>
362      <dt>
363        interfaces
364      </dt>
365      <dd>
366        An array of interfaces implemented by the component.
367      </dd>
368    </dl>
369    <h6>
370      Return value
371    </h6>
372    <p>
373      A <code>QueryInterface()</code>&nbsp;function implementatio
 >n.
374    </p>
375    <h2>
376      Post-registration callback
377    </h2>
378    <p>
379      The post-registration callback called by <a href="/en/JavaS
 >cript/Code_modules/XPCOMUtils.jsm#generateModule()" title="en/Jav
 >aScript code modules/XPCOMUtils.jsm#generateModule()"><code>gener
 >ateModule()</code></a> should have the following signature:
380    </p>
381    <pre>
382postRegister(
383  nsIComponentManager compMgr,
384  nsIFile fileSpec,
385  componentsArray
386);
387</pre>
388    <h6>
389      Parameters
390    </h6>
391    <dl>
392      <dt>
393        <code>compMgr</code>
394      </dt>
395      <dd>
396        An {{ interface("nsIComponentManager") }} instance to use
 > for managing the component.
397      </dd>
398      <dt>
399        <code>fileSpec</code>
400      </dt>
401      <dd>
402        An {{ interface("nsIFile") }} instance for... what?
403      </dd>
404      <dt>
405        <code>componentsArray</code>
406      </dt>
407      <dd>
408        An array of the components, as passed to <code>generateMo
 >dule()</code>.
409      </dd>
410    </dl>
411    <p>
412      The function doesn't need to return a value.
413    </p>
414    <h2>
415      Pre-unregistration callback
416    </h2>
417    <p>
418      The pre-unregistration callback passed to <a href="/en/Java
 >Script/Code_modules/XPCOMUtils.jsm#generateModule()" title="en/Ja
 >vaScript code modules/XPCOMUtils.jsm#generateModule()"><code>gene
 >rateModule()</code></a> should have the following signature:
419    </p>
420    <pre>
421preUnregister(
422  nsIComponentManager compMgr,
423  nsIFile fileSpec,
424  componentsArray
425); 
426</pre>
427    <h6>
428      Parameters
429    </h6>
430    <dl>
431      <dt>
432        <code>compMgr</code>
433      </dt>
434      <dd>
435        The {{ interface("nsIComponentManager") }} instance to us
 >e for managing the component.
436      </dd>
437      <dt>
438        <code>fileSpec</code>
439      </dt>
440      <dd>
441        An {{ interface("nsIFile") }} instance for... what?
442      </dd>
443      <dt>
444        <code>componentsArray</code>
445      </dt>
446      <dd>
447        The array of components passed to <code>generateModule()<
 >/code>.
448      </dd>
449    </dl>
450    <p>
451      This function doesn't need to return a value.
452    </p>
453    <h2>
454      See also
455    </h2>
456    <ul>
457      <li>
458        <a class="internal" href="/en/JavaScript/Code_modules/Usi
 >ng" title="en/JavaScript code modules/Using JavaScript code modul
 >es">Using JavaScript code modules</a>
459      </li>
460      <li>
461        <a class="internal" href="/en/JavaScript/Code_modules" ti
 >tle="en/JavaScript code modules">JavaScript code modules</a>
462      </li>
463    </ul>
464    <p>
465      {{ languages( { "es": "es/XPCOMUtils.jsm", "ja": "ja/XPCOMU
 >tils.jsm" } ) }}
466    </p>

Back to History