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>Much of the design for the Python XPCOM Package has been borrowed from the Python MS-COM
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncextensions in <i>win32com</i>. Most of the major limitations and drawbacks in the <i>win32com</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncdesign have been addressed, mainly "auto-wrapping" of
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncinterface objects, which is not supported by <i>win32com</i>.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>Like <i>win32com</i>, this architecture includes the concept of <i>client COM</i> and <i>server
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>is supported by <i>PyInterfaces</i> implemented in C++, which assists
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncin making the COM calls</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>is supported by <i>PyGateways</i>, which assists in receiving
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncexternal COM calls and dispatching them to the correct Python object</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li> is supported in the <i>xpcom/client</i> package</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>implements interfaces for use by other XPCOM applications or components</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>The XPConnect framework is very powerful, and far exceeds what COM's <i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncIDispatch</i> can offer. Thus, we are able to get by with far fewer interfaces
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncsupported in the C++ level, and defer most things to the Python code that uses
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncXPConnect. As a result, the requirement for a huge number of interfaces to
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncexist in the <i>.pyd</i> does not exist. There are, however, a number of
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncinterfaces that do require native C++ support: these are interfaces
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncrequired to "boot" the XPConnect support (i.e., the interfaces that are
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncused to get information about interfaces), and also two gateways that need to
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncwork without interface information available. This last requirement is
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncdue to the XPCOM shutdown-ordering - it may be a bug, but is not an unreasonable
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncamount of code anyway.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p><b>Auto-wrapping</b> of COM objects is supported by both client COM and
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncserver COM. For client COM, auto-wrapping means that the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncPython programmer always sees Python "component" objects, rather than
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncraw C++ interface objects; to the user, it all appears to "just
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncwork". This is a major source of frustration in the <i>win32com</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncframework.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>For server COM, auto-wrapping means that you can
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncpass Python instances wherever a COM object is expected. If the Python
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncinstance supports COM interfaces, by virtue of having a <i>_com_interfaces_</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncattribute that lists the interface requested, it will be automatically wrapped
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncin the correct COM object. </p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p><b>Error Handling:</b> The C++ framework has good error handling support,
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncand uses the XPCOM console service to log debug messages, Python exceptions and
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynctracebacks. <i>win32com</i> does not have good exception/traceback support
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncat the C++ level, mainly because COM does not define a service like
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncthe console where debug messages can go. This does mean that in Mozilla
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncrelease builds, these debug messages are likely to be lost, but the <i>--console</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynccommand line option to a release Mozilla will get them back. Therefore,
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncthe other error-support utilities, such as the error callbacks made on the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncpolicy object, may be used.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p><b>Component Loader, Modules and Factories:</b> XPCOM has the concept
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncof a component loader - a module used to load all components of a
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncparticular type. For example, the <i>moz.jsloader.1</i> component loads all
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncthe JavaScript components. Similarly, the <i>moz.pyloader.1</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynccomponent loads all Python components. However, unlike
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncJavaScript, the Python component loader is actually implemented in Python
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncitself! Since the Python component loader can not be used to load
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncitself, this component has some special code, <i>pyloader.dll,</i> to boot-strap itself.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>This means is that all XPCOM components, including the Python loader itself and all
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncXPCOM module and factory interfaces, are implemented in
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncPython. <b>There are no components or interfaces implemented purely in C++