зеркало из https://github.com/mozilla/gecko-dev.git
100 строки
5.0 KiB
HTML
100 строки
5.0 KiB
HTML
|
|
||
|
<center><b><font size=+2>XPConnect Sample</font></b>
|
||
|
|
||
|
<p>
|
||
|
<a href="mailto:arielb@netscape.com">Ariel Blackeroth <arielb@netscape.com></a>
|
||
|
<br>
|
||
|
<a href="mailto:mang@subcarrier.org">Michael Ang <mang@subcarrier.org></a>
|
||
|
<br>
|
||
|
Last modified July 9, 1999
|
||
|
</center>
|
||
|
|
||
|
<hr>
|
||
|
<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><b>Overview</b>
|
||
|
<br>This sample is located in the Mozilla tree at mozilla/xpcom/sample
|
||
|
and is a simple demonstration of XPConnect. 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.
|
||
|
The sample demonstrates how a JavaScript call can access and manipulate
|
||
|
a XPCOM interface.<b></b>
|
||
|
<p><b>nsISample.idl</b>
|
||
|
<br>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>nsSample.cpp</b>
|
||
|
<br>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 mozilla/xpcom/public/nsISupportsUtils.h
|
||
|
defines the inherited methods from nsISupports.h.
|
||
|
<br><tt>NS_IMPL_ISUPPORTS(SampleImpl, nsISample::GetIID());</tt>
|
||
|
<br>In the constructor, the macro NS_INIT_REFCNT is called which sets the
|
||
|
reference count to 0.
|
||
|
<p><b>nsSampleFactory.cpp</b>
|
||
|
<br>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 instatiate 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/tplist/catFlow/modunote.htm#Basics">
|
||
|
Modularization techniques document</a>.
|
||
|
<p><b>xpconnect-sample.html</b>
|
||
|
<br>This contains the calls from JavaScript to the XPCOM object.
|
||
|
In the first two lines JavaScript obtains a reference to the XPCOM object.
|
||
|
<br><tt>var sample = Components.classes["component://netscape/sample/sample-world"].createInstance();</tt>
|
||
|
<br><tt>sample = sample.QueryInterface(Components.interfaces.nsISample);</tt>
|
||
|
<br>After these instructions, the sample object is available seemlessly
|
||
|
to the script.
|
||
|
<p><b>Compiling the idl</b>
|
||
|
<br>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>.
|
||
|
<br>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>
|
||
|
<br>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>.
|
||
|
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>
|
||
|
<br>To build the Sample just enter
|
||
|
<br><tt>d:\mozilla\xpcom\sample>nmake /f makefile.win</tt>
|
||
|
<br>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>
|
||
|
<br>Using your mozilla browser, load the xpconnect-sample.html document.
|
||
|
The mozilla binary is located at <tt>\mozilla\dist\WIN32_D.OBJ\bin\apprunner.exe</tt>.
|
||
|
Set the url to <tt>file:///D|/mozilla/xpcom/sample/xpconnect-sample.html
|
||
|
</tt>or wherever you have the samle html file located. Pay attention
|
||
|
to the console when clicking write. Notice that the value printed is calculated in C++ code
|
||
|
defined in nsSample.cpp.
|
||
|
|
||
|
<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 <mang@subcarrier.org></a>
|