diff options
Diffstat (limited to 'src/libs/xpcom18a4/python/doc/advanced.html')
| -rw-r--r-- | src/libs/xpcom18a4/python/doc/advanced.html | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/src/libs/xpcom18a4/python/doc/advanced.html b/src/libs/xpcom18a4/python/doc/advanced.html new file mode 100644 index 00000000..ab6994fc --- /dev/null +++ b/src/libs/xpcom18a4/python/doc/advanced.html @@ -0,0 +1,176 @@ +<html> +<!-- ***** BEGIN LICENSE BLOCK ***** + - Version: MPL 1.1/GPL 2.0/LGPL 2.1 + - + - The contents of this file are subject to the Mozilla Public License Version + - 1.1 (the "License"); you may not use this file except in compliance with + - the License. You may obtain a copy of the License at + - http://www.mozilla.org/MPL/ + - + - Software distributed under the License is distributed on an "AS IS" basis, + - WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License + - for the specific language governing rights and limitations under the + - License. + - + - The Original Code is PyXPCOM. + - + - The Initial Developer of the Original Code is + - ActiveState Tool Corporation. + - Portions created by the Initial Developer are Copyright (C) 2000-2001 + - the Initial Developer. All Rights Reserved. + - + - Contributor(s): + - + - Alternatively, the contents of this file may be used under the terms of + - either the GNU General Public License Version 2 or later (the "GPL"), or + - the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), + - in which case the provisions of the GPL or the LGPL are applicable instead + - of those above. If you wish to allow use of your version of this file only + - under the terms of either the GPL or the LGPL, and not to allow others to + - use your version of this file under the terms of the MPL, indicate your + - decision by deleting the provisions above and replace them with the notice + - and other provisions required by the LGPL or the GPL. If you do not delete + - the provisions above, a recipient may use your version of this file under + - the terms of any one of the MPL, the GPL or the LGPL. + - + - ***** END LICENSE BLOCK ***** --> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Python XPCOM Advanced Topics</title> +</head> + +<body> + +<h1>Python XPCOM Advanced Topics</h1> + +<p>This document contains a series of tidbits that don't fit +anywhere else. As the Python XPCOM Package documentation matures, most of +these topics will have another home.</p> + +<h2>XPCOM Services</h2> +<p>An XPCOM service is simply a singleton registered by name. Python has +full support for both using and implementing XPCOM services. To use a +service, use <i>xpcom.components.services</i> just like the JavaScript +counterpart. There is nothing special about implementing a service in +Python; see the standard XPCOM documentation on services for more information.</p> + +<h2>nsIVariant</h2> + +<p>There is (almost) full support for <i>nsIVariant</i>. Any <i>nsIVariant</i> +parameters will automatically be translated to and from regular Python objects +giving, in effect, a multi-type parameter. This should be automatic, so +there is not much else to say! Note that if you really want, you can +create and pass your own <i>nsIVariant</i> object instead of a regular Python +object, thereby allowing explicit control over the type of variant created.</p> + +<h2>nsISupports Primitives.</h2> + +<p>There is a set of interfaces described in <i>nsISupportsPrimitives.idl</i>, which I +term collectively the <i>nsISupports Primitives Interfaces</i>. These +are a set of interfaces a component can support to allow automatic conversion to +and from many basic types. For example, an interface can define that it +supports the <i>nsISupportsCString</i> interface, and this could be used by any +program that wishes to get a string representation of the object. If an +interface wishes to expose itself as a "boolean value", it may choose +to support the <i>nsISupportsPRBool</i> interface.</p> +<p>When you call an XPCOM object (i.e., you have an XPCOM interface you are +calling), you can use +the builtin functions <i>str()</i>, <i>int()</i>, <i>long()</i> etc., on the +object<i>.</i> In the +case of <i>str()</i>, if the object does not support the <i>nsISupportsCString</i> +or <i>nsISupportsString</i> interfaces, the default string <i>str()</i> for the +object will be returned (i.e., what is normally returned for most XPCOM objects - +support for these interface is not very common!). In the case of the numeric functions, a <i>ValueError</i> +exception will be raised if the objects do not support any interface that can be +used for the conversion. <i>ValueError</i> is used instead of <i>TypeError</i>, +as the type itself (i.e., an XPCOM object) can sometimes be used in this context - +hence it is the specific <i>value</i> of the object that is the problem.</p> +<p>The use of <i>repr()</i> on an XPCOM interface object prevents support +attempts for these interfaces, and allows you to see the +"real" object, rather than what the object wants you to see!</p> +<p>When you implement an XPCOM object, you have two choices for implementation +of these interfaces:</p> +<ul> + <li>You can explicitly handle these interfaces like any other interface. + In this case, you have full control. However, if you + implement only one of these standard interfaces, then you are only + overriding the default behavior for that specific interface - all other + interfaces not explicitly listed in your class will still get the behavior + described below.<br> + </li> + <li>If your class does not define support for these interfaces, the framework + will use standard Python class semantics to implement them - i.e., if your + class provides a <i>__str__</i> method, it will be used to implement <i>nsISupportsCString</i> + and <i>nsISupportsString</i>, if you provide <i>__int__</i>, <i>__long__</i>, + <i>__float__</i> etc., methods, they will be used to implement the numeric + interfaces. If your class defines no such special methods, then the <i> + QueryInterface()</i> for those interfaces fails (rather than the QI succeeding + and the operation to fetch the data failing).</li> +</ul> +<blockquote> +<p>This allows for an interesting feature that would not normally be +possible. Consider Python code that does a <i>str()</i> on an XPCOM +interface, and where the XPCOM interface itself is implemented in Python and +provides a <i>__str__</i> method. The <i>str()</i> on the original +interface queries for the <i>nsISupportsCString</i> interface. The +Python implemented object responds to this interface and delegates to the <i>__str__</i> +method. At the end of all this, <i>str()</i> returns the same result +as if the objects were native Python objects with no XPCOM layer in between.</p> + +</blockquote> + +<h2>Enumerators</h2> + +<p>The primary enumerator used by XPCOM is <i>nsISimpleEnumerator</i>. +Although the Python XPCOM package has full support for <i>nsIEnumerator</i>, +since this interface is not "scriptable", you should avoided using it in interfaces +you design.</p> + +<p>When you use <i>nsISimpleEnumerator</i> from Python, the following enhancements +are available:</p> +<ul> + <li>The <i>GetNext()</i> method takes an optional IID as a parameter. If + this is specified, the returned object will be of this interface. This + prevents the manual <i>QueryInterface()</i> generally required from other + languages.</li> + <li>There is a <i>FetchBlock(num, [iid])</i> method, which fetches the + specified number of elements in one operation and returns a Python + list. This can be useful for large enumerator sets, so the loop + iterating the elements runs at full C++ speed.</li> +</ul> +<p><i>nsIEnumerator</i> has similar enhancements.</p> +<p>When implementing a Python XPCOM object, the Python class <i>xpcom.server.enumerator.SimpleEnumerator()</i> +can be used. You can pass a standard Python sequence (list, etc), and it +will be correctly wrapped in an <i>nsISimpleEnumerator</i> interface.</p> +<h2>Files</h2> +<p>The Python XPCOM package provides an <i> xpcom.file</i> module. This implements +a Python-like file object on top of the XPCOM/Mozilla stream interfaces. +When run from within the Mozilla environment, this allows you to open almost any +URL supported by Mozilla (including "chrome://" etc.,).</p> +<p>See this module for more information, including test code.</p> +<h2>XPCOM Object Identity</h2> +<p>XPCOM has defined rules for object identity and for how objects must behave +in their <i> QueryInterface()</i> implementations. The Python XPCOM framework +manages this for you; your code can return new Python instances etc., when +responding to new interfaces, and the framework itself will ensure the XPCOM +semantics are followed. Critically, the framework provides no mechanism +for breaking these rules.</p> +<h2>Policies</h2> +<p>The Python XPCOM framework has the concept of "policies" that +define how XPCOM semantics are mapped to Python objects. It is the policy +that implements delegation of <i> QueryInterface()</i>, translates property +references into direct property references, and failing that, "get_name" +and "set_name" calls, decides how to handle exceptions in the +component, and so on.</p> +<p>The default policy is very flexible and suitable for most purposes. +Indeed, the Komodo project has never had to implement a custom policy. +However, you should be aware the feature exists should you wish to do some +bizarre things, such as using Python as a bridge between XPCOM and some other +component technology.</p> + +</body> + +</html> |