16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<!-- ***** BEGIN LICENSE BLOCK *****
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - The contents of this file are subject to the Mozilla Public License Version
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - 1.1 (the "License"); you may not use this file except in compliance with
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - the License. You may obtain a copy of the License at
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - Software distributed under the License is distributed on an "AS IS" basis,
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - for the specific language governing rights and limitations under the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - The Original Code is PyXPCOM.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - The Initial Developer of the Original Code is
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - ActiveState Tool Corporation.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - Portions created by the Initial Developer are Copyright (C) 2000-2001
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - the Initial Developer. All Rights Reserved.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - Contributor(s):
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - Alternatively, the contents of this file may be used under the terms of
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - either the GNU General Public License Version 2 or later (the "GPL"), or
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - in which case the provisions of the GPL or the LGPL are applicable instead
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - of those above. If you wish to allow use of your version of this file only
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - under the terms of either the GPL or the LGPL, and not to allow others to
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - use your version of this file under the terms of the MPL, indicate your
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - decision by deleting the provisions above and replace them with the notice
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - and other provisions required by the LGPL or the GPL. If you do not delete
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - the provisions above, a recipient may use your version of this file under
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - the terms of any one of the MPL, the GPL or the LGPL.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - ***** END LICENSE BLOCK ***** -->
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<meta name="ProgId" content="FrontPage.Editor.Document">
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>This document contains a series of tidbits that don't fit
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncanywhere else. As the Python XPCOM Package documentation matures, most of
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncthese topics will have another home.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>An XPCOM service is simply a singleton registered by name. Python has
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncfull support for both using and implementing XPCOM services. To use a
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncservice, use <i>xpcom.components.services</i> just like the JavaScript
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynccounterpart. There is nothing special about implementing a service in
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncPython; see the standard XPCOM documentation on services for more information.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>There is (almost) full support for <i>nsIVariant</i>. Any <i>nsIVariant</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncparameters will automatically be translated to and from regular Python objects
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncgiving, in effect, a multi-type parameter. This should be automatic, so
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncthere is not much else to say! Note that if you really want, you can
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynccreate and pass your own <i>nsIVariant</i> object instead of a regular Python
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncobject, thereby allowing explicit control over the type of variant created.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>There is a set of interfaces described in <i>nsISupportsPrimitives.idl</i>, which I
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncterm collectively the <i>nsISupports Primitives Interfaces</i>. These
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncare a set of interfaces a component can support to allow automatic conversion to
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncand from many basic types. For example, an interface can define that it
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncsupports the <i>nsISupportsCString</i> interface, and this could be used by any
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncprogram that wishes to get a string representation of the object. If an
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncinterface wishes to expose itself as a "boolean value", it may choose
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncto support the <i>nsISupportsPRBool</i> interface.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>When you call an XPCOM object (i.e., you have an XPCOM interface you are
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynccalling), you can use
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncthe builtin functions <i>str()</i>, <i>int()</i>, <i>long()</i> etc., on the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynccase of <i>str()</i>, if the object does not support the <i>nsISupportsCString</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncor <i>nsISupportsString</i> interfaces, the default string <i>str()</i> for the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncobject will be returned (i.e., what is normally returned for most XPCOM objects -
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncsupport for these interface is not very common!). In the case of the numeric functions, a <i>ValueError</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncexception will be raised if the objects do not support any interface that can be
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncused for the conversion. <i>ValueError</i> is used instead of <i>TypeError</i>,
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncas the type itself (i.e., an XPCOM object) can sometimes be used in this context -
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynchence it is the specific <i>value</i> of the object that is the problem.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>The use of <i>repr()</i> on an XPCOM interface object prevents support
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncattempts for these interfaces, and allows you to see the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync"real" object, rather than what the object wants you to see!</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>When you implement an XPCOM object, you have two choices for implementation
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncof these interfaces:</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>You can explicitly handle these interfaces like any other interface.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync In this case, you have full control. However, if you
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync implement only one of these standard interfaces, then you are only
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync overriding the default behavior for that specific interface - all other
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync interfaces not explicitly listed in your class will still get the behavior
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync described below.<br>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>If your class does not define support for these interfaces, the framework
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync will use standard Python class semantics to implement them - i.e., if your
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync class provides a <i>__str__</i> method, it will be used to implement <i>nsISupportsCString</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync and <i>nsISupportsString</i>, if you provide <i>__int__</i>, <i>__long__</i>,
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <i>__float__</i> etc., methods, they will be used to implement the numeric
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync interfaces. If your class defines no such special methods, then the <i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync QueryInterface()</i> for those interfaces fails (rather than the QI succeeding
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync and the operation to fetch the data failing).</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<blockquote>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>This allows for an interesting feature that would not normally be
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncpossible. Consider Python code that does a <i>str()</i> on an XPCOM
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncinterface, and where the XPCOM interface itself is implemented in Python and
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncprovides a <i>__str__</i> method. The <i>str()</i> on the original
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncinterface queries for the <i>nsISupportsCString</i> interface. The
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncPython implemented object responds to this interface and delegates to the <i>__str__</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncmethod. At the end of all this, <i>str()</i> returns the same result
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncas if the objects were native Python objects with no XPCOM layer in between.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync</blockquote>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>The primary enumerator used by XPCOM is <i>nsISimpleEnumerator</i>.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncAlthough the Python XPCOM package has full support for <i>nsIEnumerator</i>,
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncsince this interface is not "scriptable", you should avoided using it in interfaces
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncyou design.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>When you use <i>nsISimpleEnumerator</i> from Python, the following enhancements
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncare available:</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>The <i>GetNext()</i> method takes an optional IID as a parameter. If
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync this is specified, the returned object will be of this interface. This
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync prevents the manual <i>QueryInterface()</i> generally required from other
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync languages.</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>There is a <i>FetchBlock(num, [iid])</i> method, which fetches the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync specified number of elements in one operation and returns a Python
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync list. This can be useful for large enumerator sets, so the loop
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync iterating the elements runs at full C++ speed.</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p><i>nsIEnumerator</i> has similar enhancements.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>When implementing a Python XPCOM object, the Python class <i>xpcom.server.enumerator.SimpleEnumerator()</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynccan be used. You can pass a standard Python sequence (list, etc), and it
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncwill be correctly wrapped in an <i>nsISimpleEnumerator</i> interface.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>The Python XPCOM package provides an <i> xpcom.file</i> module. This implements
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynca Python-like file object on top of the XPCOM/Mozilla stream interfaces.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncWhen run from within the Mozilla environment, this allows you to open almost any
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncURL supported by Mozilla (including "chrome://" etc.,).</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>See this module for more information, including test code.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>XPCOM has defined rules for object identity and for how objects must behave
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncin their <i> QueryInterface()</i> implementations. The Python XPCOM framework
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncmanages this for you; your code can return new Python instances etc., when
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncresponding to new interfaces, and the framework itself will ensure the XPCOM
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncsemantics are followed. Critically, the framework provides no mechanism
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncfor breaking these rules.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>The Python XPCOM framework has the concept of "policies" that
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncdefine how XPCOM semantics are mapped to Python objects. It is the policy
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncthat implements delegation of <i> QueryInterface()</i>, translates property
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncreferences into direct property references, and failing that, "get_name"
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncand "set_name" calls, decides how to handle exceptions in the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynccomponent, and so on.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>The default policy is very flexible and suitable for most purposes.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncIndeed, the Komodo project has never had to implement a custom policy.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncHowever, you should be aware the feature exists should you wish to do some
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncbizarre things, such as using Python as a bridge between XPCOM and some other
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynccomponent technology.</p>