The Tor Browser / file revision

 <!-- This Source Code Form is subject to the terms of the Mozilla Public

    - License, v. 2.0. If a copy of the MPL was not distributed with this

    - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->

 <center><b><font size=+2>XPConnect Sample</font></b>

 <p>

 <a href="mailto:arielb@rice.edu">Ariel Blackenroth &lt;arielb@rice.edu&gt;</a>

 <br>

 <a href="mailto:mang@subcarrier.org">Michael Ang &lt;mang@subcarrier.org&gt;</a>

 <br>

 Last modified 

 <script>

 document.write(document.lastModified);

 </script>

 </center>

 <p>In the spirit of "worse is better" this somewhat rough guide is being

 released to the world.  It will be expanded upon and improved.

 <p>XPConnect allows JavaScript

 to transparantly access and manipulate XPCOM objects; this communication

 between JavaScript and

 native code is done by having their interfaces defined in the XPIDL interface

 definition language. See the <a href="http://www.mozilla.org/scriptable/roadmap.html">Roadmap

 for documentation on XPCOM, XPConnect, XPTCall and XPIDL</a> for more information.

 <p><b>Overview</b>

 <p>

 This sample demonstrates accessing a XPCOM object through XPConnect.

 The JavaScript executed when this page loads creates an instance

 of the object by

 using the <tt>Components</tt> object, then accesses it through

 the <a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/nsISample.idl">nsISample</a> interface by calling <tt>QueryInterface</tt>:

 <br>

 <pre>

 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");

 var sample = Components.classes["@mozilla.org/sample;1"].createInstance();

 sample = sample.QueryInterface(Components.interfaces.nsISample);

 </pre>

 <p>

 The buttons on the form are connected to JavaScript event handlers which

 call the methods defined in C++.

 <p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsISample.idl">nsISample.idl</a></b>

 <p>This is the interface declaration for the XPCOM object. It defines

 two functions, their parameters, and one attribute. It also defines

 the interface's id. The idl file is compiled by the xpidl compiler

 into a C++ header, nsISample.h and a .xpt file which is a binary representation

 of the interface used at runtime.

 <br><tt>attribute string value;</tt>

 <br><tt>void writeValue(in string aPrefix);</tt>

 <br><tt>void poke(in string aValue);</tt><b></b>

 <p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSample.cpp">nsSample.cpp</a></b>

 <p>This contains the implementation of nsISample.idl. SampleImpl

 inherits from nsISample.h, the header dynamically created by the xpidl

 compiler. The attribute Value has been expanded into a get and set

 and the return values have been modified to NS_IMETHOD, a success status

 for the method. The macro NS_DECL_ISUPPORTS, defined in <a href="http://lxr.mozilla.org/mozilla/source/xpcom/base/nsISupportsUtils.h">mozilla/xpcom/public/nsISupportsUtils.h</a>

 defines the inherited methods from nsISupports.h.

 <br><tt>NS_IMPL_ISUPPORTS(SampleImpl, nsISample)</tt>

 <br>In the constructor, the macro NS_INIT_REFCNT is called which sets the

 reference count to 0.<p>

 Note that the methods in the C++ bindings use InterCaps style, while the IDL

 and JavaScript versions should use interCaps naming.  The JavaScript binding

 matches the case of the IDL, <b>except</b> <a

 href="http://bugzilla.mozilla.org/show_bug.cgi?id=14460">QueryInterface</a>.

 <p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSampleFactory.cpp">nsSampleFactory.cpp</a></b>

 <p>This is the class which builds the instance of the nsSample class.

 The COM framework uses factories to create instance of implementations

 rather than having the implementations instantiate themselves in order to

 increase portability of code. This factory inherits from nsFactory,

 which is also an XPCOM object. To gain more knowledge of factories

 see the <a href="http://www.mozilla.org/projects/xpcom/generic-factory.html">generic

 factory document</a> or the <a href="http://www.mozilla.org/docs/modunote.htm#Basics">Modularization techniques document</a>.

 <p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSample.js">nsSample.js</a></b>

 <p>This file implements the nsISample interface, and associated factory glue,

 in JavaScript.

 <p><b>Compiling the idl</b>

 <p>The XPIDL compiler (xpidl on Unix, xpidl.exe on Windows, and a CodeWarrior plugin on Mac)

 is compiled at build time (except on Mac) thus

 you will have to build mozilla in order to test this out. If you

 have already built mozilla then the compiler will be located at <tt>mozilla\dist\WIN32_D.OBJ\bin\xpidl.exe</tt>.

 <p>Once you have the XPIDL compiler enter the following command at your

 prompt:

 <br><tt>D:\mozilla\xpcom\sample>d:\mozilla\dist\WIN32_D.OBJ\bin\xpidl -I

 d:\mozilla\dist\idl -m header nsISample.idl</tt>

 <p>The <tt>-I d:\mozilla\dist\idl</tt> points the compiler to the folder

 containing the other idl files, needed because nsISample.idl inherits from

 nsISupports.idl. The <tt>-m header</tt> instruction tells the compiler

 to build the C++ header. To build the .xpt file substitute <tt>-m

 typelib</tt>. 

 <p>

 For more information on compilation see the <a href="http://www.mozilla.org/scriptable/xpidl/">xpidl

 compiler page</a>.

 <p><b>Building the Sample</b>

 <p>To build the Sample just enter

 <br><tt>d:\mozilla\xpcom\sample>nmake /f makefile.win</tt>

 <p>In order to do this you need to have your environment variables set

 correctly. See the <a href="http://www.mozilla.org/build/">Build</a>

 page for more information.

 <p><b>Running the sample</b>

 <p>Using Mozilla, load

 <a href="resource://res/samples/xpconnect-sample.html">resource://res/samples/xpconnect-sample.html</a> (i.e. what

 you're reading now). Pay attention

 to the console when clicking "write". Notice that the value

 printed is calculated in C++ code defined in <a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/nsSample.cpp">nsSample.cpp</a>.

 <!-- XXX keep in sync with stuff in pre tag below -->

 <script>

 /* to use nsSample.js version, use "@mozilla.org/jssample;1" */

 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");

 var sample = Components.classes["@mozilla.org/sample;1"].createInstance();

 sample = sample.QueryInterface(Components.interfaces.nsISample);

 dump("sample = " + sample + "\n");

 function get()

 {

   netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");

   var field = document.getElementById('Value');

   field.value = sample.value;

 }

 function set()

 {

   netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");

   var field = document.getElementById('Value');

   sample.value = field.value;

 }

 function poke()

 {

   netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");

   var field = document.getElementById('Value');

   sample.poke(field.value);

 }

 function sampleWrite()

 {

   netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");

   sample.writeValue("here is what I'm writing: ");

 }

 </script>

 <p>

 <form name="form">

 <input type="button" value="Get" onclick="get();">

 <input type="button" value="Set" onclick="set();">

 <input type="button" value="Poke" onclick="poke();">

 <input type="text" id="Value">

 <input type="button" value="Write" onclick="sampleWrite();">

 <form>

 <hr>

 <p>

 JavaScript and form source:

 <!-- XXX keep in sync with actual script -->

 <pre>

 <script>

 /* to use nsSample.js version, use "@mozilla.org/jssample;1" */

 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");

 var sample = Components.classes["@mozilla.org/sample;1"].createInstance();

 sample = sample.QueryInterface(Components.interfaces.nsISample);

 dump("sample = " + sample + "\n");

 function get()

 {

   netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");  var field = document.getElementById('Value');

   field.value = sample.value;

 }

 function set()

 {

   netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");  var field = document.getElementById('Value');

   sample.value = field.value;

 }

 function poke()

 {

   netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");  var field = document.getElementById('Value');

   sample.poke(field.value);

 }

 function sampleWrite()

 {

   netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");

   sample.writeValue("here is what I'm writing: ");

 }

 </script>

 <form name="form">

 <input type="button" value="Get" onclick="get();">

 <input type="button" value="Set" onclick="set();">

 <input type="button" value="Poke" onclick="poke();">

 <input type="text" id="Value">

 <input type="button" value="Write" onclick="sampleWrite();">

 <form>

 </pre>

 <p>

 <hr>

 <b>Resources:</b>

 <ul>

 <li><a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/">mozilla/xpcom/sample source directory</a>

 </ul>

 <hr>

 <b>Comments to:</b>

 <a href="mailto:mang@subcarrier.org?Subject=XPCOM sample documentation">Michael Ang &lt;mang@subcarrier.org&gt;</a>