1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/sample/xpconnect-sample.html Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,224 @@
1.4 +<!-- This Source Code Form is subject to the terms of the Mozilla Public
1.5 + - License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
1.7 +
1.8 +
1.9 +<center><b><font size=+2>XPConnect Sample</font></b>
1.10 +
1.11 +<p>
1.12 +<a href="mailto:arielb@rice.edu">Ariel Blackenroth <arielb@rice.edu></a>
1.13 +<br>
1.14 +<a href="mailto:mang@subcarrier.org">Michael Ang <mang@subcarrier.org></a>
1.15 +<br>
1.16 +Last modified
1.17 +<script>
1.18 +document.write(document.lastModified);
1.19 +</script>
1.20 +</center>
1.21 +
1.22 +<p>In the spirit of "worse is better" this somewhat rough guide is being
1.23 +released to the world. It will be expanded upon and improved.
1.24 +
1.25 +<p>XPConnect allows JavaScript
1.26 +to transparantly access and manipulate XPCOM objects; this communication
1.27 +between JavaScript and
1.28 +native code is done by having their interfaces defined in the XPIDL interface
1.29 +definition language. See the <a href="http://www.mozilla.org/scriptable/roadmap.html">Roadmap
1.30 +for documentation on XPCOM, XPConnect, XPTCall and XPIDL</a> for more information.
1.31 +
1.32 +<p><b>Overview</b>
1.33 +
1.34 +<p>
1.35 +This sample demonstrates accessing a XPCOM object through XPConnect.
1.36 +The JavaScript executed when this page loads creates an instance
1.37 +of the object by
1.38 +using the <tt>Components</tt> object, then accesses it through
1.39 +the <a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/nsISample.idl">nsISample</a> interface by calling <tt>QueryInterface</tt>:
1.40 +<br>
1.41 +<pre>
1.42 +netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
1.43 +var sample = Components.classes["@mozilla.org/sample;1"].createInstance();
1.44 +sample = sample.QueryInterface(Components.interfaces.nsISample);
1.45 +</pre>
1.46 +
1.47 +<p>
1.48 +The buttons on the form are connected to JavaScript event handlers which
1.49 +call the methods defined in C++.
1.50 +
1.51 +
1.52 +<p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsISample.idl">nsISample.idl</a></b>
1.53 +<p>This is the interface declaration for the XPCOM object. It defines
1.54 +two functions, their parameters, and one attribute. It also defines
1.55 +the interface's id. The idl file is compiled by the xpidl compiler
1.56 +into a C++ header, nsISample.h and a .xpt file which is a binary representation
1.57 +of the interface used at runtime.
1.58 +<br><tt>attribute string value;</tt>
1.59 +<br><tt>void writeValue(in string aPrefix);</tt>
1.60 +<br><tt>void poke(in string aValue);</tt><b></b>
1.61 +<p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSample.cpp">nsSample.cpp</a></b>
1.62 +<p>This contains the implementation of nsISample.idl. SampleImpl
1.63 +inherits from nsISample.h, the header dynamically created by the xpidl
1.64 +compiler. The attribute Value has been expanded into a get and set
1.65 +and the return values have been modified to NS_IMETHOD, a success status
1.66 +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>
1.67 +defines the inherited methods from nsISupports.h.
1.68 +<br><tt>NS_IMPL_ISUPPORTS(SampleImpl, nsISample)</tt>
1.69 +<br>In the constructor, the macro NS_INIT_REFCNT is called which sets the
1.70 +reference count to 0.<p>
1.71 +Note that the methods in the C++ bindings use InterCaps style, while the IDL
1.72 +and JavaScript versions should use interCaps naming. The JavaScript binding
1.73 +matches the case of the IDL, <b>except</b> <a
1.74 +href="http://bugzilla.mozilla.org/show_bug.cgi?id=14460">QueryInterface</a>.
1.75 +<p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSampleFactory.cpp">nsSampleFactory.cpp</a></b>
1.76 +<p>This is the class which builds the instance of the nsSample class.
1.77 +The COM framework uses factories to create instance of implementations
1.78 +rather than having the implementations instantiate themselves in order to
1.79 +increase portability of code. This factory inherits from nsFactory,
1.80 +which is also an XPCOM object. To gain more knowledge of factories
1.81 +see the <a href="http://www.mozilla.org/projects/xpcom/generic-factory.html">generic
1.82 +factory document</a> or the <a href="http://www.mozilla.org/docs/modunote.htm#Basics">Modularization techniques document</a>.
1.83 +<p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSample.js">nsSample.js</a></b>
1.84 +<p>This file implements the nsISample interface, and associated factory glue,
1.85 +in JavaScript.
1.86 +
1.87 +<p><b>Compiling the idl</b>
1.88 +
1.89 +<p>The XPIDL compiler (xpidl on Unix, xpidl.exe on Windows, and a CodeWarrior plugin on Mac)
1.90 +is compiled at build time (except on Mac) thus
1.91 +you will have to build mozilla in order to test this out. If you
1.92 +have already built mozilla then the compiler will be located at <tt>mozilla\dist\WIN32_D.OBJ\bin\xpidl.exe</tt>.
1.93 +
1.94 +<p>Once you have the XPIDL compiler enter the following command at your
1.95 +prompt:
1.96 +<br><tt>D:\mozilla\xpcom\sample>d:\mozilla\dist\WIN32_D.OBJ\bin\xpidl -I
1.97 +d:\mozilla\dist\idl -m header nsISample.idl</tt>
1.98 +
1.99 +<p>The <tt>-I d:\mozilla\dist\idl</tt> points the compiler to the folder
1.100 +containing the other idl files, needed because nsISample.idl inherits from
1.101 +nsISupports.idl. The <tt>-m header</tt> instruction tells the compiler
1.102 +to build the C++ header. To build the .xpt file substitute <tt>-m
1.103 +typelib</tt>.
1.104 +
1.105 +<p>
1.106 +For more information on compilation see the <a href="http://www.mozilla.org/scriptable/xpidl/">xpidl
1.107 +compiler page</a>.
1.108 +
1.109 +<p><b>Building the Sample</b>
1.110 +
1.111 +<p>To build the Sample just enter
1.112 +<br><tt>d:\mozilla\xpcom\sample>nmake /f makefile.win</tt>
1.113 +
1.114 +<p>In order to do this you need to have your environment variables set
1.115 +correctly. See the <a href="http://www.mozilla.org/build/">Build</a>
1.116 +page for more information.
1.117 +
1.118 +<p><b>Running the sample</b>
1.119 +<p>Using Mozilla, load
1.120 +<a href="resource://res/samples/xpconnect-sample.html">resource://res/samples/xpconnect-sample.html</a> (i.e. what
1.121 +you're reading now). Pay attention
1.122 +to the console when clicking "write". Notice that the value
1.123 +printed is calculated in C++ code defined in <a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/nsSample.cpp">nsSample.cpp</a>.
1.124 +
1.125 +<!-- XXX keep in sync with stuff in pre tag below -->
1.126 +<script>
1.127 +/* to use nsSample.js version, use "@mozilla.org/jssample;1" */
1.128 +netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
1.129 +var sample = Components.classes["@mozilla.org/sample;1"].createInstance();
1.130 +sample = sample.QueryInterface(Components.interfaces.nsISample);
1.131 +dump("sample = " + sample + "\n");
1.132 +
1.133 +function get()
1.134 +{
1.135 + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
1.136 + var field = document.getElementById('Value');
1.137 + field.value = sample.value;
1.138 +}
1.139 +
1.140 +function set()
1.141 +{
1.142 + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
1.143 + var field = document.getElementById('Value');
1.144 + sample.value = field.value;
1.145 +}
1.146 +
1.147 +function poke()
1.148 +{
1.149 + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
1.150 + var field = document.getElementById('Value');
1.151 + sample.poke(field.value);
1.152 +}
1.153 +
1.154 +function sampleWrite()
1.155 +{
1.156 + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
1.157 + sample.writeValue("here is what I'm writing: ");
1.158 +}
1.159 +</script>
1.160 +
1.161 +<p>
1.162 +<form name="form">
1.163 +<input type="button" value="Get" onclick="get();">
1.164 +<input type="button" value="Set" onclick="set();">
1.165 +<input type="button" value="Poke" onclick="poke();">
1.166 +<input type="text" id="Value">
1.167 +<input type="button" value="Write" onclick="sampleWrite();">
1.168 +<form>
1.169 +
1.170 +<hr>
1.171 +
1.172 +<p>
1.173 +JavaScript and form source:
1.174 +
1.175 +<!-- XXX keep in sync with actual script -->
1.176 +<pre>
1.177 +<script>
1.178 +/* to use nsSample.js version, use "@mozilla.org/jssample;1" */
1.179 +netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
1.180 +var sample = Components.classes["@mozilla.org/sample;1"].createInstance();
1.181 +sample = sample.QueryInterface(Components.interfaces.nsISample);
1.182 +dump("sample = " + sample + "\n");
1.183 +
1.184 +function get()
1.185 +{
1.186 + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); var field = document.getElementById('Value');
1.187 + field.value = sample.value;
1.188 +}
1.189 +
1.190 +function set()
1.191 +{
1.192 + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); var field = document.getElementById('Value');
1.193 + sample.value = field.value;
1.194 +}
1.195 +
1.196 +function poke()
1.197 +{
1.198 + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); var field = document.getElementById('Value');
1.199 + sample.poke(field.value);
1.200 +}
1.201 +
1.202 +function sampleWrite()
1.203 +{
1.204 + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
1.205 + sample.writeValue("here is what I'm writing: ");
1.206 +}
1.207 +</script>
1.208 +
1.209 +<form name="form">
1.210 +<input type="button" value="Get" onclick="get();">
1.211 +<input type="button" value="Set" onclick="set();">
1.212 +<input type="button" value="Poke" onclick="poke();">
1.213 +<input type="text" id="Value">
1.214 +<input type="button" value="Write" onclick="sampleWrite();">
1.215 +<form>
1.216 +
1.217 +</pre>
1.218 +
1.219 +<p>
1.220 +<hr>
1.221 +<b>Resources:</b>
1.222 +<ul>
1.223 +<li><a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/">mozilla/xpcom/sample source directory</a>
1.224 +</ul>
1.225 +<hr>
1.226 +<b>Comments to:</b>
1.227 +<a href="mailto:mang@subcarrier.org?Subject=XPCOM sample documentation">Michael Ang <mang@subcarrier.org></a>
