root/MGET/Trunk/PythonPackage/src/GeoEco/COM.py

# COM.py - Provides an infrastructure for exposing GeoEco classes as Microsoft
# COM Automation classes.
#
# Copyright (C) 2007 Jason J. Roberts
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License (available in the file LICENSE.TXT)
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

import sys

# Skip everything unless we're running on Windows.

if sys.platform.lower() == u'win32':

    import datetime
    import inspect
    import logging
    import new
    import re
    import sys
    import types

    import pythoncom
    import pywintypes
    import win32com.client
    import win32com.server.dispatcher
    from win32com.server.exception import COMException
    import win32com.server.policy
    import winerror

    from GeoEco.DynamicDocString import DynamicDocString
    from GeoEco.Internationalization import *
    from GeoEco.Metadata import *
    from GeoEco.Types import *


    TypeLibraryGUID = '{B062A595-DFFC-4980-9212-EBC8A54A4845}'          # Do not change this unless you know what you're doing
    TypeLibraryVersion = (0,5)                                          # TODO: Automatically generate this version number (question: when should it change?) -- Trac ticket #32
    TypeLibraryLCID = 0                                                 # LOCALE_USER_DEFAULT, which is what pythoncom uses by default


    class ExceptionTranslatingDispatcher(win32com.server.dispatcher.DispatcherBase):
        
        def __init__(self, policyClass, obj):
            win32com.server.dispatcher.DispatcherBase.__init__(self, policyClass, obj)


    class MetadataDesignatedWrapPolicy(win32com.server.policy.DesignatedWrapPolicy):
        
        def _wrap_(self, ob):

            # Obtain the metadata for the class that was just instantiated by
            # pythoncom.

            classMetadata = ob.__doc__.Obj

            # Initialize variables required by the base class _wrap_ method.
            # That method will read the type library, look up the interface
            # definition using the COM IID, and configure a wrapper that will
            # pass COM calls to the wrapped class's methods.

            ob._com_interfaces_ = [u'I' + classMetadata.Name]
            ob._typelib_guid_ = globals()[u'TypeLibraryGUID']
            ob._typelib_version_ = globals()[u'TypeLibraryVersion']
            ob._typelib_lcid_ = globals()[u'TypeLibraryLCID']

            # Call the base class _wrap_ to perform the wrapping.

            self._Log(_(u'COM object 0x%08x: Initializing wrapper for %s.%s instance exposing interface %s (I%s) from type library %s, version %i.%i, LCID %i'), id(ob), classMetadata.Module.Name, classMetadata.Name, classMetadata.COMIID, classMetadata.Name, globals()['TypeLibraryGUID'], globals()['TypeLibraryVersion'][0], globals()['TypeLibraryVersion'][1], globals()['TypeLibraryLCID'])
            win32com.server.policy.DesignatedWrapPolicy._wrap_(self, ob)

        def _invokeex_(self, dispid, lcid, wFlags, args, kwArgs, serviceProvider):

            # Generate a display string for wFlags for a log message.

            wFlagsDisplayStrings = []

            if wFlags & pythoncom.DISPATCH_METHOD:
                wFlagsDisplayStrings.append(u'DISPATCH_METHOD')
            if wFlags & pythoncom.DISPATCH_PROPERTYGET:
                wFlagsDisplayStrings.append(u'DISPATCH_PROPERTYGET')
            if wFlags & pythoncom.DISPATCH_PROPERTYPUT:
                wFlagsDisplayStrings.append(u'DISPATCH_PROPERTYPUT')
            if wFlags & pythoncom.DISPATCH_PROPERTYPUTREF:
                wFlagsDisplayStrings.append(u'DISPATCH_PROPERTYPUTREF')
            if len(wFlagsDisplayStrings) <= 0 or wFlags & ~(pythoncom.DISPATCH_METHOD | pythoncom.DISPATCH_PROPERTYGET | pythoncom.DISPATCH_PROPERTYPUT | pythoncom.DISPATCH_PROPERTYPUTREF) > 0:
                wFlagsDisplayStrings.append(_(u'unknown flags!'))

            wFlagsDisplayString = u' | '.join(wFlagsDisplayStrings)

            # Look up the name of the member in the base class's dictionaries.

            memberName = None

            if wFlags & pythoncom.DISPATCH_METHOD:
                try:
                    memberName = self._dispid_to_func_[dispid]
                except KeyError:
                    pass
            
            if memberName is None and wFlags & pythoncom.DISPATCH_PROPERTYGET:
                try:
                    memberName = self._dispid_to_get_[dispid]
                except KeyError:
                    pass
            
            if memberName is None and wFlags & (pythoncom.DISPATCH_PROPERTYPUT | pythoncom.DISPATCH_PROPERTYPUTREF):
                try:
                    memberName = self._dispid_to_put_[dispid]
                except KeyError:
                    pass

            # If we found the member's name, look up its metadata.

            if memberName is None:
                memberName = _(u'member not found!')
                memberType = u''
                memberMetadata = None
            else:
                if not isinstance(self._obj_.__class__.__doc__, DynamicDocString) or not isinstance(self._obj_.__class__.__doc__.Obj, ClassMetadata):
                    raise COMException(scode=winerror.DISP_E_EXCEPTION, source=_(u'GeoEco.COM.MetadataDesignatedWrapPolicy Python class'), description=_(u'Programming error in the %s class. In order for this class to expose itself to COM callers using GeoEco.COM.MetadataDesignatedWrapPolicy, it must set its __doc__ member to an instance of GeoEco.Metadata.DynamicDocString and initialize it to an instance of GeoEco.Metadata.ClassMetadata. Please contact the developer of %s for assistance.') % (self._obj_.__class__.__name__, self._obj_.__class__.__name__))
                classMetadata = self._obj_.__class__.__doc__.Obj
                if inspect.ismethod(getattr(classMetadata.Object, memberName)):
                    if not isinstance(getattr(classMetadata.Object, memberName).__doc__, DynamicDocString) or not isinstance(getattr(classMetadata.Object, memberName).__doc__.Obj, MethodMetadata):
                        raise COMException(scode=winerror.DISP_E_EXCEPTION, source=_(u'GeoEco.COM.MetadataDesignatedWrapPolicy Python class'), description=_(u'Programming error in the %s class. In order for this class to expose member %s to COM callers using GeoEco.COM.MetadataDesignatedWrapPolicy, it must set the __doc__ member of %s to an instance of GeoEco.Metadata.DynamicDocString and initialize it to an instance of GeoEco.Metadata.MethodMetadata. Please contact the developer of %s for assistance.') % (self._obj_.__class__.__name__, methodName, methodName, self._obj_.__class__.__name__))
                    memberType = _(u' method')
                elif inspect.isdatadescriptor(getattr(classMetadata.Object, memberName)):
                    if not isinstance(getattr(classMetadata.Object, memberName).__doc__, DynamicDocString) or not isinstance(getattr(classMetadata.Object, memberName).__doc__.Obj, PropertyMetadata):
                        raise COMException(scode=winerror.DISP_E_EXCEPTION, source=_(u'GeoEco.COM.MetadataDesignatedWrapPolicy Python class'), description=_(u'Programming error in the %s class. In order for this class to expose member %s to COM callers using GeoEco.COM.MetadataDesignatedWrapPolicy, it must set the __doc__ member of %s to an instance of GeoEco.Metadata.DynamicDocString and initialize it to an instance of GeoEco.Metadata.PropertyMetadata. Please contact the developer of %s for assistance.') % (self._obj_.__class__.__name__, methodName, methodName, self._obj_.__class__.__name__))
                    memberType = _(u' property')
                else:
                    raise COMException(scode=winerror.DISP_E_EXCEPTION, source=_(u'GeoEco.COM.MetadataDesignatedWrapPolicy Python class'), description=_(u'Programming error in the %s class. In order for this class to expose member %s to COM callers using GeoEco.COM.MetadataDesignatedWrapPolicy, %s must be an instance method, a class method, or a property. Please contact the developer of %s for assistance.') % (self._obj_.__class__.__name__, methodName, methodName, self._obj_.__class__.__name__))
                memberMetadata = getattr(classMetadata.Object, memberName).__doc__.Obj

            self._Log(_(u'COM object 0x%08X: InvokeEx called: dispid = %i (%s%s), lcid = %i, wFlags = %i (%s), args = %s, kwArgs = %s, serviceProvider = %s'), id(self._obj_), dispid, memberName, memberType, lcid, wFlags, wFlagsDisplayString, repr(args), repr(kwArgs), serviceProvider)

            # Convert the tuple of arguments provided by pythoncom to a list, in
            # preparation for some modifications we may need to apply to them.

            args = list(args)
            argsChanged = False

            # Handle argument modifications that are specific to properties:

            if isinstance(memberMetadata, PropertyMetadata):

                # Pythoncom always passes array arguments in as tuples. If the
                # caller wants to assign the value of a property that expects a
                # list, convert the argument to a list.

                if len(args) == 1 and isinstance(args[0], types.TupleType) and isinstance(memberMetadata.Type, ListTypeMetadata):
                    args = (self._TuplesToLists(args[0], memberMetadata.Type),)
                    argsChanged = True

            # Handle argument modifications that are specific to methods:

            elif isinstance(memberMetadata, MethodMetadata):

                # If this method returns multiple results, they were encoded in
                # IDL as [in, out] parameters that occur between the formal
                # input parameters ([in], [in, defaultvalue], and
                # [in, optional]) and the arbitrary input arbitrary argument
                # list ([vararg]), if one is present. We ignore these inputs and
                # must not pass them to the method. (Because they do not appear
                # in the method's definition, we would get a "too many
                # arguments" exception if we passed them.) We remove them from
                # the args list.

                if len(memberMetadata.Results) > 1:
                    argsToRemove = len(memberMetadata.Results) - 1
                    if memberMetadata.Arguments[len(memberMetadata.Arguments) - 1].IsArbitraryArgumentList:
                        formalArgCount = len(memberMetadata.Arguments) - 2
                    else:
                        formalArgCount = len(memberMetadata.Arguments) - 1
                    while argsToRemove > 0 and len(args) > formalArgCount:
                        del args[formalArgCount]
                    argsChanged = True
                
                # Pythoncom always passes array arguments in as tuples. If the
                # caller wants to invoke a method that accepts a list(s) as an
                # input parameter(s), convert the argument(s) to a list(s).

                for i in range(len(memberMetadata.Arguments) - 1):
                    if i < len(args) and memberMetadata.Arguments[i + 1].IsFormalParameter and isinstance(args[i], types.TupleType) and isinstance(memberMetadata.Arguments[i + 1].Type, SequenceTypeMetadata):
                        args[i] = self._TuplesToLists(args[i], memberMetadata.Arguments[i + 1].Type)
                        argsChanged = True

                # Under COM rules, an argument that is declared [in, optional] must
                # be a VARIANT, and the caller can pass VT_ERROR with error code
                # DISP_E_PARAMNOTFOUND (-2147352572) to indicate that a value is not
                # being supplied. From C#, for example, this is accomplished by
                # passing System.Type.Missing for the argument. When pythoncom
                # receives a VT_ERROR VARIANT, it passes us the int error code as
                # the argument.
                #
                # When we receive -2147352572 for an argument that has a default, we
                # pass the default to the method (instead of -2147352572). We do
                # this regardless of whether the argument was defined in the type
                # library as [in, defaultvalue] or [in, optional]. Pythoncom does
                # not appear to distinguish between the two, and late-bound callers
                # do not even read the type library. Thus the type library is really
                # only a convience to early-bound callers so they can perform some
                # type checking at compile time.
                #
                # IMPORTANT NOTE:
                #
                # There appears to be no way to distinguish between the COM caller
                # sending a VT_I4 that happens to contain the value -2147352572 and
                # sending a VT_ERROR with the error code set to
                # DISP_E_PARAMNOTFOUND. Thus, if the argument's metadata declares it
                # to be a IntegerTypeMetadata, we assume the caller passed the VT_I4, not
                # the VT_ERROR, but issue a warning about it. This means that
                # callers must explicitly send all integer arguments.

                if not memberMetadata.Arguments[len(memberMetadata.Arguments) - 1].IsArbitraryArgumentList:      # No [in, optional] or [in, defaultvalue] args are allowed if varargs parameter is present
                    for i in range(0, len(args)):
                        if args[i] == winerror.DISP_E_PARAMNOTFOUND and i < len(memberMetadata.Arguments) - 1:
                            argMetadata = memberMetadata.Arguments[i + 1]
                            if argMetadata.IsFormalParameter and argMetadata.HasDefault:
                                if not isinstance(argMetadata.Type, IntegerTypeMetadata):
                                    args[i] = argMetadata.Default
                                    argsChanged = True
                                else:
                                    logger = logging.getLogger(u'GeoEco.COM')
                                    if logger is not None:
                                        logger.warning(_(u'COM object 0x%08X: Method %s.%s received the value %i for the %s parameter. Due to the design of the pythoncom Python library, this method cannot determine if the caller provided an integer with this value or a VARIANT of type VT_ERROR with error code DISP_E_PARAMNOTFOUND, indicating that the caller is not providing a value. (From .Net code, this is done by passing System.Type.Missing.) This method will assume that the caller provided the integer, not the VT_ERROR VARIANT. If this was not your intention, and you wanted the method to use its default value for this parameter, you should pass in the default value %i explicitly.'), id(self._obj_), argMetadata.Method.Name, argMetadata.Method.Class.Name, winerror.DISP_E_PARAMNOTFOUND, argMetadata.Name, argMetadata.Default)

                # If the last argument of this method is an arbitrary argument list - 
                # [vararg] in IDL - then we must handle a quirk (bug?) in pythoncom
                # that relates to how the method is invoked. According to the COM
                # rules, methods that have a [vararg] must pass the remaining args
                # in a SAFEARRAY, and it is the responsibility of the called method
                # to unpack the SAFEARRAY. When we're invoked through the IDispatch
                # mechanism, the pythoncom code seems to do this for us, and the
                # additional args appear as additional elements in the "args"
                # parameter of _invokeex_. But when we're invoked through normal
                # COM (a "vtable" call), the pythoncom code that is used in that
                # situation (the "universal dispatcher"?) does not seem to unpack
                # the array for us: the additional args appear in a single tuple
                # appended to the "args" parameter of _invokeex_.
                #
                # So, if the last argument of this method is a [vararg], inspect the
                # stack to determine whether we were invoked through the "universal
                # dispatcher". (The only way I know how to tell is to inspect the
                # stack.) If so, unpack the tuple.

                if memberMetadata.Arguments[len(memberMetadata.Arguments) - 1].IsArbitraryArgumentList and len(args) == len(memberMetadata.Arguments) - 1:
                    if isinstance(args[len(args) - 1], types.TupleType) and self._InvokedByUniversalDispatcher():
                        varargTuple = args.pop()
                        args = args + list(varargTuple)
                        argsChanged = True

            # Convert the arguments list back to a tuple.
            
            args = tuple(args)

            if argsChanged:            
                self._Log(_(u'COM object 0x%08X: Fixed arguments provided by pythoncom. New args = %s'), id(self._obj_), repr(args))

            # Use the base class to invoke the member and capture its result. If
            # we were unable to look up the method name, the base class will
            # raise a COMException.

            returnedValue = win32com.server.policy.DesignatedWrapPolicy._invokeex_(self, dispid, lcid, wFlags, args, kwArgs, serviceProvider)

            # If the member is either a property that is a Python tuple or a
            # method that returns a one result that is a tuple, coerce this
            # tuple into a list before returning it. This will prevent pythoncom
            # from trying to unpack multiple return values from it. (Pythoncom
            # treats all tuples as multiple return values, which is reasonable
            # given that it has no access to our metadata. If it receives a
            # tuple of four values, it cannot tell if it is four separate return
            # values or one array value with four elements.)

            if isinstance(returnedValue, types.TupleType) and (isinstance(memberMetadata, PropertyMetadata) and isinstance(memberMetadata.Type, TupleTypeMetadata) or isinstance(memberMetadata, MethodMetadata) and len(memberMetadata.Results) == 1 and isinstance(memberMetadata.Results[0].Type, TupleTypeMetadata)):
                returnedValue = list(returnedValue)
                self._Log(_(u'COM object 0x%08X: Coerced the returned Python tuple into a Python list, so pythoncom will return it as a SAFEARRAY'), id(self._obj_))

            # If the member is a method that returns multiple results and we
            # were invoked through normal COM (a "vtable" call, which comes
            # through pythoncom's "universal dispatcher"), pythoncom is
            # expecting the first value of the returned tuple to be an HRESULT.
            # This is a behavior difference in pythoncom: it does not expect the
            # HRESULT to be prepended to the output tuple when the method is
            # invoked through the IDispatch mechanism. I noticed an email
            # exchange in the pywin32 forum in late 2006 indicating that Mark
            # Hammond is now aware of this problem. For now, we have to prepend
            # the HRESULT S_OK (0) when invoked through the universal
            # dispatcher, or it will fail with an error similar to this:
            #
            #     exceptions.TypeError: Expected 5 return values, got: 4
            #
            # (In this example, the method returned four results. Pythoncom was
            # looking for a fifth, the HRESULT.)

            if isinstance(memberMetadata, MethodMetadata) and len(memberMetadata.Results) > 1 and isinstance(returnedValue, types.TupleType) and len(returnedValue) == len(memberMetadata.Results) and self._InvokedByUniversalDispatcher():
                returnedValue = tuple([winerror.S_OK] + list(returnedValue))
                self._Log(_(u'COM object 0x%08X: Prepended the HRESULT S_OK to the tuple of output arguments, so pythoncom\'s "universal dispatcher" will not fail.'), id(self._obj_))
                # NOTE: IT STILL FAILS, JUST IN A DIFFERENT PLACE. I DO NOT KNOW WHAT TO DO...

            # Return the result.
            
            self._Log(_(u'COM object 0x%08X: InvokeEx returning %s'), id(self._obj_), repr(returnedValue))
            return returnedValue            

        def _Log(self, format, *args):            
            logger = logging.getLogger(u'GeoEco.COM')
            if logger is not None:
                logger.debug(format, *args)

        def _TuplesToLists(self, arg, typeMetadata, depthToDescend=None):

            # It may be that we have several levels of nesting. If the developer
            # cooked up some esoteric data structure such as a tuple of tuples
            # of lists, we need to convert only the most-interior sequences to
            # lists. But the outer tuples are immutable, so to accomplish this,
            # we must convert them to lists, change the inner-most tuples to
            # lists, convert the outer ones back to tuples. To accomplish this
            # most efficiently, we determine ahead of time how deeply we need
            # to descend into the nested sequences.

            if depthToDescend is None:
                currentDepth = 0
                depthToDescend = 0
                t = typeMetadata
                while isinstance(t, SequenceTypeMetadata):
                    currentDepth += 1
                    t = t.ElementType
                    if isinstance(t, ListTypeMetadata):
                        depthToDescend = currentDepth

            # If the arg at the current level should be a list, convert it now.                        

            if isinstance(arg, types.TupleType) and isinstance(typeMetadata, ListTypeMetadata):
                arg = list(arg)

            # If a deeper level needs conversion, convert the current level to a
            # list, do the child levels, and convert the current level back if
            # necessary.

            if depthToDescend > 0:
                arg = list(arg)
                for i in range(len(arg)):
                    arg[i] = self._TuplesToLists(arg[i], typeMetadata.ElementType, depthToDescend - 1)
                if isinstance(typeMetadata, TupleTypeMetadata):
                    arg = tuple(arg)

            # Return
            
            return arg

        def _InvokedByUniversalDispatcher(self):
            currentFrame = inspect.currentframe()
            try:
                outerFrames = inspect.getouterframes(currentFrame)
                try:
                    for frame in outerFrames:
                        if frame[1].endswith(u'win32com\\universal.py'):
                            return True
                finally:
                    del outerFrames
            finally:
                del currentFrame
            return False


    def ValidateClassMetadata(cls):
        assert inspect.isclass(cls), u'cls must be a class'
        assert isinstance(cls.__doc__, DynamicDocString) and isinstance(cls.__doc__.Obj, ClassMetadata), u'cls.__doc__ must be an instance of GeoEco.Metadata.DynamicDocString and cls.__doc__.Obj must be an instance of GeoEco.Metadata.ClassMetadata.'

        # Validate the class-level metadata.

        classMetadata = cls.__doc__.Obj
        
        assert classMetadata.IsExposedAsCOMServer, u'cls.__doc__.Obj.IsExposedAsCOMServer must be True'
        assert classMetadata.COMIID is not None, u'Class %s.%s is flagged for exposure by COM but its COMIID property is None. You must specify a value for COMIID; here is a randomly generated value you can use: %s. See the documentation for GeoEco.Metadata.ClassMetadata.COMIID for more information.' % (classMetadata.Module.Name, classMetadata.Name, repr(unicode(pythoncom.CreateGuid())))
        assert classMetadata.COMCLSID is not None, u'Class %s.%s is flagged for exposure by COM but its COMCLSID property is None. You must specify a value for COMCLSID; here is a randomly generated value you can use: %s. See the documentation for GeoEco.Metadata.ClassMetadata.COMCLSID for more information.' % (classMetadata.Module.Name, classMetadata.Name, repr(unicode(pythoncom.CreateGuid())))
        assert classMetadata.COMIID != classMetadata.COMCLSID, u'Class %s.%s is flagged for exposure by COM but its COMCLSID property has the same value as is COMIID property. These two values must not be the same. Please change one to a unique GUID; here is a randomly generated value you can use: %s. See the documentation for GeoEco.Metadata.ClassMetadata.COMCLSID for more information.' % (classMetadata.Module.Name, classMetadata.Name, repr(unicode(pythoncom.CreateGuid())))

        # Validate the properties' metadata.

        atLeastOneExposed = False

        for propName, prop in inspect.getmembers(cls, inspect.isdatadescriptor):
            if hasattr(prop, u'__doc__') and isinstance(prop.__doc__, DynamicDocString) and isinstance(prop.__doc__.Obj, PropertyMetadata) and prop.__doc__.Obj.IsExposedByCOM:
                atLeastOneExposed = True
                propMetadata = prop.__doc__.Obj
                assert propMetadata.Type.CanBeCOMParameter, u'Property %s.%s.%s is flagged for exposure by COM but %s.%s.%s.Type.CanBeCOMParameter is False. Change the property\'s type to one that can be exposed as a COM parameter or do not designate this property for exposure by COM.' % (propMetadata.Class.Module.Name, propMetadata.Class.Name, propMetadata.Name, propMetadata.Class.Module.Name, propMetadata.Class.Name, propMetadata.Name)
                assert propMetadata.Type.COMIDLType is not None, u'Property %s.%s.%s is flagged for exposure by COM but %s.%s.%s.Type.COMIDLType is None. This should not be possible, since the type\'s CanBeCOMParameter property is True. Please fix the definition of this type to include a COMIDLType or to assign CanBeCOMParameter to False.' % (propMetadata.Class.Module.Name, propMetadata.Class.Name, propMetadata.Name, propMetadata.Class.Module.Name, propMetadata.Class.Name, propMetadata.Name)
                assert not propMetadata.Type.CanBeNone or propMetadata.Type.COMIDLType == 'VARIANT', u'Property %s.%s.%s is flagged for exposure by COM but its Type.CanBeNone == True while its Type.COMIDLType != \'VARIANT\'. This is not allowed; if Type.CanBeNone is True then Type.COMIDLType must be \'VARIANT\', so that COM callers can pass a VT_NULL or VT_EMPTY. Please fix this.' % (propMetadata.Class.Module.Name, propMetadata.Class.Name, propMetadata.Name)
                assert prop.fget is not None, u'Property %s.%s.%s is flagged for exposure by COM but it has no "fget" method. This means it is a write-only property, which is not presently supported by GeoEco. Please give this property an fget method or do not flag it for exposure using COM.' % (propMetadata.Class.Module.Name, propMetadata.Class.Name, propMetadata.Name)

        # Validate the methods' metadata.        

        for methodName, method in inspect.getmembers(cls, inspect.ismethod):

            # If this is the __init__ method, make sure all of its arguments
            # have defaults. pythoncom cannot instantiate the class if any
            # __init__ arguments require values.

            (args, varargs, varkw, defaults) = inspect.getargspec(method)

            if methodName == u'__init__':
                assert len(args) >= 1, u'Method %s.%s.%s must have at least one argument ("self") because it is the class\'s constructor.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name)
                assert len(args) <= 1 or isinstance(defaults, types.TupleType) and len(defaults) == len(args) - 1, u'Class %s.%s is flagged for exposure by COM but not all of the arguments to its __init__ have default values. All __init__ arguments must have default values for pythoncom to be able to instantiate the class. Please provide defaults for every argument (except the "self" argument) or do not expose the class using COM.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name)

            # If this method is flagged for exposure by COM, validate the
            # metadata for its arguments and results.
            
            if hasattr(method, u'__doc__') and isinstance(method.__doc__, DynamicDocString) and isinstance(method.__doc__.Obj, MethodMetadata) and method.__doc__.Obj.IsExposedByCOM:
                atLeastOneExposed = True
                methodMetadata = method.__doc__.Obj

                # Validate the arguments' metadata.

                assert varkw is None, u'Method %s.%s.%s is flagged for exposure by COM but it has an optional keywords dictionary argument (**%s). This is not supported by COM. Please remove this argument or do not expose this method by COM.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name, varkw)
                expectedArgCount = len(args)
                if varargs is not None:
                    expectedArgCount += 1
                assert len(methodMetadata.Arguments) == expectedArgCount, u'Method %s.%s.%s is flagged for exposure by COM but its metadata is not consistent with its definition: the metadata lists a different number of arguments than the method definition. Please correct the metadata.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name)

                foundArgWithDefault = False
                
                for i in range(len(methodMetadata.Arguments)):
                    argMetadata = methodMetadata.Arguments[i]
                    if i < len(args):
                        assert args[i] == argMetadata.Name, u'Method %s.%s.%s is flagged for exposure by COM but its metadata is not consistent with its definition: Argument %i is named %s in the metadata but %s in the definition. Please correct the metadata.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name, i, argMetadata.Name, args[i])
                    else:
                        assert varargs == argMetadata.Name, u'Method %s.%s.%s is flagged for exposure by COM but its metadata is not consistent with its definition: Argument %i is named %s in the metadata but %s in the definition. Please correct the metadata.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name, i, argMetadata.Name, varargs)
                    if i > 0:
                        assert argMetadata.Type.CanBeCOMParameter, u'Method %s.%s.%s is flagged for exposure by COM but the metadata for its "%s" argument has Type.CanBeCOMParameter == False. Change the arguments\'s type to one that can be exposed as a COM parameter or do not designate this method for exposure by COM.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name, argMetadata.Name)
                        assert argMetadata.Type.COMIDLType is not None, u'Method %s.%s.%s is flagged for exposure by COM but the metadata for its "%s" argument has Type.COMIDLType == None. This should not be possible, since the type\'s CanBeCOMParameter property is True. Please fix the definition of this type to include a COMIDLType or to assign CanBeCOMParameter to False.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name, argMetadata.Name)
                        assert not argMetadata.Type.CanBeNone or argMetadata.Type.COMIDLType == 'VARIANT', u'Method %s.%s.%s is flagged for exposure by COM but the metadata for its "%s" argument has Type.CanBeNone == True but Type.COMIDLType != \'VARIANT\'. This is not allowed; if Type.CanBeNone is True then Type.COMIDLType must be \'VARIANT\', so that COM callers can pass a VT_NULL or VT_EMPTY. Please fix this.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name, argMetadata.Name)

                # Validate the results' metadata.
                
                for resultMetadata in methodMetadata.Results:
                    assert resultMetadata.Type.CanBeCOMParameter, u'Method %s.%s.%s is flagged for exposure by COM but the metadata for its "%s" result has Type.CanBeCOMParameter == False. Change the result\'s type to one that can be exposed as a COM parameter or do not designate this method for exposure by COM.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name, resultMetadata.Name)
                    assert resultMetadata.Type.COMIDLType is not None, u'Method %s.%s.%s is flagged for exposure by COM but the metadata for its "%s" result has Type.COMIDLType == None. This should not be possible, since the type\'s CanBeCOMParameter property is True. Please fix the definition of this type to include a COMIDLType or to assign CanBeCOMParameter to False.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name, resultMetadata.Name)
                    assert not resultMetadata.Type.CanBeNone or resultMetadata.Type.COMIDLType == 'VARIANT', u'Method %s.%s.%s is flagged for exposure by COM but the metadata for its "%s" result has Type.CanBeNone == True but Type.COMIDLType != \'VARIANT\'. This is not allowed; if Type.CanBeNone is True then Type.COMIDLType must be \'VARIANT\', so that a VT_NULL VARIANT may be returned to the COM when the Python method returns None. Please fix this.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name, resultMetadata.Name)

        # Validate that the caller is not trying to expose static methods using
        # COM.

        for funcName, func in inspect.getmembers(cls, inspect.isfunction):
            if hasattr(func, u'__doc__') and isinstance(func.__doc__, DynamicDocString) and isinstance(func.__doc__.Obj, MethodMetadata) and func.__doc__.Obj.IsExposedByCOM:
                methodMetadata = func.__doc__.Obj
                assert not methodMetadata.IsStaticMethod, u'Static method %s.%s.%s is flagged for exposure by COM. This is not supported. Please change this method to a class method if you want to expose it using COM.' % (methodMetadata.Class.Module.Name, methodMetadata.Class.Name, methodMetadata.Name)

        # Validate that at least one property or method is flagged for exposure
        # by COM.

        assert atLeastOneExposed, u'Class %s.%s is flagged for exposure by COM but it does not have any properties or methods flagged for exposure by COM. At least one property or method must be flagged for exposure, or you should not flag the class for exposure.' % (classMetadata.Module.Name, classMetadata.Name)


    def GetIDLInterfaceDefinitionFromMetadata(classMetadata):
        assert isinstance(classMetadata, ClassMetadata), u'classMetadata must be an instance of GeoEco.Metadata.ClassMetadata'

        # Build the IDL header.
        
        header = '[\n    dual,\n    uuid(%s),\n    helpstring("I%s Interface"),\n    pointer_default(unique)\n]\ninterface I%s : IDispatch\n{\n' % (classMetadata.COMIID[1:-1], classMetadata.Name, classMetadata.Name)

        # Build a list of IDL property definitions.

        dispID = 1
        propertiesIDL = []

        properties = inspect.getmembers(classMetadata.Object, inspect.isdatadescriptor)
        for (name, prop) in properties:
            if isinstance(prop.__doc__, DynamicDocString) and isinstance(prop.__doc__.Obj, PropertyMetadata) and prop.__doc__.Obj.IsExposedByCOM:
                if len(propertiesIDL) <= 0:
                    propertiesIDL = ['    // Properties\n']
                propertiesIDL.append(GetIDLPropertyDefinitionFromMetadata(prop.__doc__.Obj, dispID))
                dispID += 1

        # Build a list of IDL method definitions.

        methodsIDL = []

        methods = inspect.getmembers(classMetadata.Object, inspect.ismethod)
        for (name, method) in methods:
            if isinstance(method.__doc__, DynamicDocString) and isinstance(method.__doc__.Obj, MethodMetadata) and method.__doc__.Obj.IsExposedByCOM:
                if len(methodsIDL) <= 0:
                    methodsIDL = ['    // Methods\n']
                methodsIDL.append(GetIDLMethodDefinitionFromMetadata(method.__doc__.Obj, dispID))
                dispID += 1

        # Build the IDL footer.
        
        footer = '};\n'

        # Return the complete IDL inteface definition.

        return header + ''.join(propertiesIDL) + ''.join(methodsIDL) + footer


    def GetIDLPropertyDefinitionFromMetadata(propertyMetadata, dispID):
        assert isinstance(propertyMetadata, PropertyMetadata), u'propertyMetadata must be an instance of GeoEco.Metadata.PropertyMetadata'
        assert isinstance(dispID, types.IntType), u'dispID must be an int'

        # If the IDL for the property's type is a SAFEARRAY, use a VARIANT
        # instead to work-around a pythoncom bug: when early-bound callers
        # invoke a method that a returns a SAFEARRAY, pythoncom raises a
        # TypeError when the method returns, similar to this:
        #
        #     exceptions.TypeError: The VARIANT type is unknown (0x600c).
        #
        # The error does not occur when we specify a VARIANT in the IDL rather
        # than a SAFEARRAY. The unfortunate side effect is that early-bound
        # callers lose the benefits of type checking.
        #
        # Note that we cannot use a SAFEARRAY for the propput function and a
        # VARIANT for the propget function. This causes the .Net compiler to
        # become confused and issue an error.

        typeIDL = propertyMetadata.Type.COMIDLType
        if typeIDL.upper().startswith('SAFEARRAY'):        
            typeIDL = 'VARIANT'

        # Generate a propget entry.

        idl = '    [id(%s), propget, helpstring("%s Property")] HRESULT %s([out, retval] %s *pValue);\n' % (dispID, propertyMetadata.Name, propertyMetadata.Name, typeIDL)

        # If the property is not read-only, generate a propput entry.

        if not propertyMetadata.IsReadOnly:
            idl = idl + '    [id(%s), propput, helpstring("%s Property")] HRESULT %s([in] %s value);\n' % (dispID, propertyMetadata.Name, propertyMetadata.Name, typeIDL)

        return idl


    def GetIDLMethodDefinitionFromMetadata(methodMetadata, dispID):
        assert isinstance(methodMetadata, MethodMetadata), u'methodMetadata must be an instance of GeoEco.Metadata.MethodMetadata'
        assert isinstance(dispID, types.IntType), u'dispID must be an int'

        # Generate IDL for the method's arguments. The correct order is:
        #
        # 1. Required input arguments (those without a default)
        # 2. Optional input arguments (those with a default)
        # 3. 2nd and subsequent results (if any) as IDL [in, out] parameters
        # 4. The varargs input argument (if any)
        # 5. The 1st result (if any) as an IDL [out, retval] parameter
        #
        # The ValidateClassMetadata function, which should have been called
        # prior to invoking this one, validates the correct order.

        (args, varargs, varkw, defaults) = inspect.getargspec(methodMetadata.Object)

        requiredInputParams = []
        optionalInputParams = []
        inOutParams = []
        varargParam = []
        retvalParam = []

        foundOptionalVariant = False
        foundDefaultvalue = False
        varargAttribute = ''

        # Loop through the input arguments, populating the lists defined above.        

        for i in range(1, len(methodMetadata.Arguments)):
            argMetadata = methodMetadata.Arguments[i]

            # If the argument is a formal parameter (i.e. not varargs)...

            if argMetadata.IsFormalParameter:
                assert len(varargParam) == 0, u'Programming error in GeoEco.COM: got formal parameter but varargParam is not empty'         # Python itself should prevent this from ever happening

                # If the argument has no default, then it is a required input
                # parameter. Also, if the method specifies a varargs parameter,
                # then ALL arguments are required, according to COM rules.

                if not argMetadata.HasDefault or varargs is not None:
                    assert len(optionalInputParams) == 0, u'Programming error in GeoEco.COM: got required input argument but optionalInputParams is not empty'      # Python itself should prevent this from ever happening
                    requiredInputParams.append('[in] %s %s' % (argMetadata.Type.COMIDLType, argMetadata.Name))

                # The argument has a default. Try to produce an IDL 
                # representation of it. (Python allows specification of very
                # sophisticated default values; IDL does not.)

                else:
                    if argMetadata.Default is not None:
                        idlForDefault = argMetadata.Type.COMIDLRepresentationOfValue(argMetadata.Default)
                    else:
                        idlForDefault = None
                    assert isinstance(idlForDefault, (types.StringType, types.NoneType)), u'Programming error in %s: COMIDLRepresentationOfValue must return an 8-bit string or None.' % argMetadata.Type.__class__.__name__

                    # If we failed to produce an IDL representation for the
                    # parameter, we would like to promote this parameter from
                    # optional to required, because the caller will have to
                    # specify it (because we can't tell IDL the default value).
                    # Specify it as required so long as it can't be None (in
                    # which case it should be [in, optional]) and we haven't
                    # processed any previous optional parameters.

                    if idlForDefault is None and not argMetadata.Type.CanBeNone and len(optionalInputParams) <= 0:
                        requiredInputParams.append('[in] %s %s' % (argMetadata.Type.COMIDLType, argMetadata.Name))

                    # Either the argument's default can be represented in IDL, or
                    # it can be None, or we have already processed a previous
                    # optional parameter. We want to specify this argument as
                    # [in, defaultvalue] but may be forced to specify it as
                    # [in, optional] due to some IDL esoterics.
                    #
                    # As above, if the argument's Type.CanBeNone is True, we
                    # MUST use VARIANT as the IDL parameter type. But when we
                    # do, the MIDL compiler does not let us specify
                    # [in, defaultvalue] for the parameter, we can only specify
                    # [in, optional].
                    #
                    # On the other hand, if the argument's Type.CanBeNone is
                    # False, we can use the argument's Type.COMIDLType and
                    # specify [in, defaultvalue], but ONLY IF we have not
                    # specified [in, optional] for any previous parameters. Once
                    # we have specified one [in, optional], all following [in]
                    # parameters must be [in, optional] (unless they are
                    # [in, out] which is convered later, when the IDL for
                    # methodMetadata.Results is generated).
                    #
                    # Finally if we the argument's default cannot be represented
                    # in IDL, we have no choice but to use [in, optional], since
                    # we don't know how to specify [defaultvalue].
                    #
                    # This situation is quite complicated and goes against older COM
                    # documentation, which showed that you could specify
                    # [in, optional, defaultvalue] parameters. Now [optional] and
                    # [defaultvalue] are mutually exclusive. The design chosen here
                    # is a compromise: so long as the method developer puts all
                    # optional, CanBeNone arguments at the end of the method
                    # definition, strong IDL types will be used for the preceding
                    # optional, non-CanBeNone arguments.

                    else:
                        if idlForDefault is None or argMetadata.Type.CanBeNone or foundOptionalVariant:
                            optionalInputParams.append('[in, optional] VARIANT %s' % argMetadata.Name)
                            foundOptionalVariant = True
                        else:
                            requiredInputParams.append('[in, defaultvalue(%s)] %s %s' % (idlForDefault, argMetadata.Type.COMIDLType, argMetadata.Name))
                            foundDefaultvalue = True

            # If the argument is the arbitrary argument list (the "varargs"
            # parameter) we have to specify it in IDL as
            # [in] SAFEARRAY(VARIANT).
            
            elif argMetadata.IsArbitraryArgumentList:
                assert len(varargParam) == 0, u'Programming error in GeoEco.COM: got vararg but varargParam is not empty'       # Python itself should prevent this from ever happening
                varargParam.append('[in] SAFEARRAY(VARIANT) %s' % argMetadata.Name)
                varargAttribute = ', vararg'

            # The argument must be the keyword argument dictionary ("kwargs").
            # We do not support exposing methods with this kind of argument
            # through COM because COM has no support for it. Raise an error.
            # Note that this is a programming error in GeoEco.COM because we
            # should have detected this problem previously when we validated the
            # method in ValidateClassMetadata.

            else:
                assert False, u'Programming error in GeoEco.COM: argMetadata.IsArbitraryArgumentList is True'

        # Loop through the results, populating the lists defined above.        

        for i in range(len(methodMetadata.Results)):
            resultMetadata = methodMetadata.Results[i]
            idlType = resultMetadata.Type.COMIDLType

            # If the IDL for the return type is a SAFEARRAY, use a VARIANT
            # instead to work-around a pythoncom bug: when early-bound
            # callers invoke a method that a returns a SAFEARRAY, pythoncom
            # raises a TypeError when the method returns, similar to this:
            #
            #    exceptions.TypeError: The VARIANT type is unknown (0x600c).
            #
            # The error does not occur when we specify a VARIANT in the IDL
            # rather than a SAFEARRAY. The unfortunate side effect is that
            # early-bound callers lose the benefits of type checking.

            if idlType.upper().startswith('SAFEARRAY'):
                idlType = 'VARIANT'

            # If this is the first result, it will be the IDL [out, retval]
            # parameter, which is the actual return value of the method.
            # Otherwise it is an [in, out] parameter that is overwritten by the
            # method.

            if i == 0:
                retvalParam.append('[out, retval] %s *%s' % (idlType, resultMetadata.Name))

            # Otherwise, if the input parameters did not include any
            # [in, optional] or [in, defaultvalue] parameters, this result
            # should be an [in, out] parameter.
            
            elif not foundOptionalVariant and not foundDefaultvalue:
                inOutParams.append('[in, out] %s *%s' % (idlType, resultMetadata.Name))

            # Otherwise this result must be an [in, out, optional] VARIANT * or
            # the MIDL compiler will fail.

            else:
                inOutParams.append('[in, out, optional] VARIANT *%s' % (resultMetadata.Name))

        # Return the full IDL method signature.

        idl = '    [id(%s), helpstring("%s Method")%s] HRESULT %s(%s);\n' % (dispID, methodMetadata.Name, varargAttribute, methodMetadata.Name, ', '.join(requiredInputParams + optionalInputParams + inOutParams + varargParam + retvalParam))
        return idl        


    def RegisterCOMServerUsingClassMetadata(moduleName, className):

        # Import the module and obtain the class's metadata.

        assert isinstance(moduleName, basestring), u'moduleName must be a string.'
        assert isinstance(className, basestring), u'className must be a string.'
        __import__(moduleName)
        classMetadata = sys.modules[moduleName].__dict__[className].__doc__.Obj

        # Register the class.

        import win32com.server.register
        try:
            win32com.server.register.RegisterServer(clsid=classMetadata.COMCLSID,
                                                    pythonInstString=moduleName + '.' + className,
                                                    desc=classMetadata.ShortDescription,
                                                    progID=classMetadata.COMVersionIndependentProgID,
                                                    verProgID=classMetadata.COMVersionDependentProgID,
                                                    policy=__name__ + '.' + MetadataDesignatedWrapPolicy.__name__,
                                                    dispatcher=__name__ + '.' + ExceptionTranslatingDispatcher.__name__)
        except Exception, e:
            return 'The Python win32com.server.register.RegisterServer function raised %s: %s' % (e.__class__.__name__, str(e))

        return None


    def UnregisterCOMServerUsingClassMetadata(moduleName, className):

        # Import the module and obtain the class's metadata.

        assert isinstance(moduleName, basestring), u'moduleName must be a string.'
        assert isinstance(className, basestring), u'className must be a string.'
        __import__(moduleName)
        classMetadata = sys.modules[moduleName].__dict__[className].__doc__.Obj

        # Unregister the class.

        import win32com.server.register
        try:
            win32com.server.register.UnregisterServer(clsid=classMetadata.COMCLSID,
                                                      progID=classMetadata.COMVersionIndependentProgID,
                                                      verProgID=classMetadata.COMVersionDependentProgID)
        except:
            pass


    class COMAutomationObject(object):

        def __init__(self, progID, obj=None):
            assert isinstance(progID, basestring), u'progID must be a string.'
            assert isinstance(obj, (win32com.client.CDispatch, types.NoneType)), u'obj must be an instance of win32com.client.CDispatch, or None.'

            self._ProgID = unicode(progID)
            self._WrappedMethods = {}

            if obj is not None:
                self._Object = obj
            else:
                try:
                    self._Object = win32com.client.Dispatch(progID)
                except pythoncom.com_error, (hr, msg, exc, arg):
                    from GeoEco.Logging import Logger
                    Logger.RaiseException(RuntimeError(_(u'Failed to instantiate the %(progid)s COM Automation object. win32com.client.Dispatch reported %(error)s') % {u'progid': progID, u'error': FormatCOMError(hr, msg, exc, arg)}))
                except Exception, e:
                    from GeoEco.Logging import Logger
                    Logger.RaiseException(RuntimeError(_(u'Failed to instantiate the %(progid)s COM Automation object. win32com.client.Dispatch reported %(error)s: %(msg)s') % {u'progid': progID, u'error': e.__class__.__name__, u'msg': unicode(e)}))
                
                self._LogDebug(_(u'%(progid)s COM Automation object 0x%(id)08X: Instantiated.') % {u'progid': self._ProgID, u'id': id(self._Object)})

        def __del__(self):            
            self._LogDebug(_(u'%(progid)s COM Automation object 0x%(id)08X: Last reference released.') % {u'progid': self._ProgID, u'id': id(self._Object)})

        def _LogDebug(self, format, *args, **kwargs):
            try:
                logging.getLogger(u'GeoEco.COM').debug(format, *args, **kwargs)
            except:
                pass

        def _LogInfo(self, format, *args, **kwargs):
            try:
                logging.getLogger(u'GeoEco.COM').info(format, *args, **kwargs)
            except:
                pass

        def _LogWarning(self, format, *args, **kwargs):
            try:
                logging.getLogger(u'GeoEco.COM').warning(format, *args, **kwargs)
            except:
                pass

        def _LogError(self, format, *args, **kwargs):
            try:
                logging.getLogger(u'GeoEco.COM').error(format, *args, **kwargs)
            except:
                pass

        def __getattr__(self, name):
            assert isinstance(name, basestring), u'name must be a string.'

            # If the caller is asking for a private attribute (the name starts with
            # an underscore), he wants an attribute of the wrapper class instance,
            # not of the wrapped object. In this case, we must use the object
            # class's implementation of __getattr__.

            if isinstance(name, types.StringType):
                name = unicode(name)
            if name.startswith(u'_'):
                return object.__getattribute__(self, name)

            # The caller is asking for a data attribute or a method of the wrapped
            # object. If we already built a wrapper method for the specified name,
            # it means the caller asked for it before and we determined that it was
            # a method. Return the wrapped method to the caller now.

            if self._WrappedMethods.has_key(name.lower()):
                return new.instancemethod(self._WrappedMethods[name.lower()], self, COMAutomationObject)

            # Retrieve the attribute from the wrapped object.

            try:
                value = getattr(self._Object, name)
            except pythoncom.com_error, (hr, msg, exc, arg):
                from GeoEco.Logging import Logger
                Logger.RaiseException(AttributeError(_(u'Failed to get the %(attr)s property or method of the %(progid)s COM Automation object 0x%(id)08X. win32com.client.Dispatch reported %(error)s') % {u'attr': name, u'progid': self._ProgID, u'id': id(self._Object), u'error': FormatCOMError(hr, msg, exc, arg)}))
            except Exception, e:
                from GeoEco.Logging import Logger
                Logger.RaiseException(AttributeError(_(u'Failed to get the %(attr)s property or method of the %(progid)s COM Automation object 0x%(id)08X. win32com.client.Dispatch reported %(error)s: %(msg)s') % {u'attr': name, u'progid': self._ProgID, u'id': id(self._Object), u'error': e.__class__.__name__, u'msg': unicode(e)}))

            # If it is a method, create a wrapper, add it to our dictionary of
            # wrapped methods, and return the wrapper.

            if isinstance(value, (types.MethodType, types.BuiltinFunctionType, types.BuiltinMethodType)):

                # Write the methods's definition. If the method has VT_MISSING
                # or VT_EMPTY as default values, these are represented by
                # pythoncom.Missing and pythoncom.Empty. inspect.formatargspec
                # puts in the strings '<PyOleMissing object at 0x0148DFF8>' and
                # '<PyOleEmpty object at 0x01481C40>' (with different hex
                # addresses). These strings will not compile, so we must replace
                # them with pythoncom.Missing and pythoncom.Empty.

                (args, varargs, varkw, defaults) = inspect.getargspec(value)
                sourceCode = 'def %s%s:\n' % (str(name), inspect.formatargspec(args, varargs, varkw, defaults))
                sourceCode = re.subn('<PyOleMissing object at 0x........>', 'pythoncom.Missing', sourceCode)[0]
                sourceCode = re.subn('<PyOleEmpty object at 0x........>', 'pythoncom.Empty', sourceCode)[0]

                # Write the method's body.
                
                sourceCode = sourceCode + '    return self._InvokeMethod(self._Object.%s)\n' % name

                # Compile the method.
                
                _locals = {}
                exec sourceCode in globals(), _locals

                # Add it to our dictionary of wrapped methods.
                
                self._WrappedMethods[name.lower()] = _locals[name]

                # Return it to the caller.
                
                return new.instancemethod(_locals[name], self, COMAutomationObject)

            # Log the returned value.

            self._LogDebug(_(u'%(progid)s COM Automation object 0x%(id)08X: Get %(name)s returned %(value)s') % {u'progid': self._ProgID, u'id': id(self._Object), u'name': name, u'value': repr(value)})

            # The returned value is a property. Convert it from pythoncom's
            # preferred type to the type we prefer.

            value = self._FromPythonCOMType(value)

            # Return the value.

            return value

        def __setattr__(self, name, value):
            assert isinstance(name, basestring), u'name must be a string.'

            # If the caller is asking for a private attribute (the name starts with
            # an underscore), he wants to set an attribute of the wrapper class
            # instance, not of the wrapped object. In this case, we must use the
            # object class's implementation of __setattr__.

            if isinstance(name, types.StringType):
                name = unicode(name)
            if name.startswith(u'_'):
                return object.__setattr__(self, name, value)

            # The caller wants to set a property of the wrapped object. First
            # convert it from the type we prefer to the one perferred by
            # pythoncom.

            value = self._ToPythonCOMType(value)            

            # Set the property.

            try:
                setattr(self._Object, name, value)
            except pythoncom.com_error, (hr, msg, exc, arg):
                from GeoEco.Logging import Logger
                Logger.RaiseException(AttributeError(_(u'Failed to set the %(attr)s property of the %(progid)s COM Automation object 0x%(id)08X to %(value)s. win32com.client.Dispatch reported %(error)s') % {u'attr': name, u'progid': self._ProgID, u'id': id(self._Object), u'value': repr(value), u'error': FormatCOMError(hr, msg, exc, arg)}))
            except Exception, e:
                from GeoEco.Logging import Logger
                Logger.RaiseException(AttributeError(_(u'Failed to set the %(attr)s property of the %(progid)s COM Automation object 0x%(id)08X to %(value)s. win32com.client.Dispatch reported %(error)s: %(msg)s') % {u'attr': name, u'progid': self._ProgID, u'id': id(self._Object), u'value': repr(value), u'error': e.__class__.__name__, u'msg': unicode(e)}))

            # Log the set value.

            if isinstance(value, COMAutomationObject):
                self._LogDebug(_(u'%(progid)s COM Automation object 0x%(id)08X: Set %(name)s to %(progid2)s COM Automation object 0x%(id2)08X.') % {u'progid': self._ProgID, u'id': id(self._Object), u'name': name, u'progid2': value._ProgID, u'id2': id(value._Object)})
            else:
                self._LogDebug(_(u'%(progid)s COM Automation object 0x%(id)08X: Set %(name)s to %(value)s') % {u'progid': self._ProgID, u'id': id(self._Object), u'name': name, u'value': repr(value)})

        def _InvokeMethod(self, method):

            # Convert the arguments from the types we prefer to those preferred
            # by pythoncom.

            (_args, _varargs, _varkw, _locals) = inspect.getargvalues(inspect.currentframe().f_back)
            del _args[0]

            for argName in _args:
                _locals[argName] = self._ToPythonCOMType(_locals[argName])

            if _varargs is not None:
                _locals[_varargs] = self._ToPythonCOMType(_locals[_varargs])

            # Build the source code needed to invoke the method.

            sourceCode = 'self._Object.%s(' % method.__name__
            for argName in _args:
                if not sourceCode.endswith('('):
                    sourceCode = sourceCode + ', '
                sourceCode = sourceCode + '%s=_locals[\'%s\']' % (argName, argName)
            if _varargs is not None:
                if not sourceCode.endswith('('):
                    sourceCode = sourceCode + ', '
                sourceCode = sourceCode + '*_locals[\'%s\'] ' % _varargs
            sourceCode = sourceCode + ')'

            # Invoke the method.

            self._LogDebug(_(u'%(progid)s COM Automation object 0x%(id)08X: Invoking %(name)s%(args)s.') % {u'progid': self._ProgID, u'id': id(self._Object), u'name': method.__name__, u'args': inspect.formatargvalues(_args, _varargs, _varkw, _locals)})
            
            try:
                value = eval(sourceCode, globals(), locals())
            except pythoncom.com_error, (hr, msg, exc, arg):
                from GeoEco.Logging import Logger
                Logger.RaiseException(RuntimeError(_(u'Execution of %(name)s%(args)s failed for the %(progid)s COM Automation object 0x%(id)08X. The function reported %(error)s') % {u'name': method.__name__, u'args': inspect.formatargvalues(_args, _varargs, _varkw, _locals), u'progid': self._ProgID, u'id': id(self._Object), u'error': FormatCOMError(hr, msg, exc, arg)}))
            except Exception, e:
                from GeoEco.Logging import Logger
                Logger.RaiseException(RuntimeError(_(u'Execution of %(name)s%(args)s failed for the %(progid)s COM Automation object 0x%(id)08X. win32com.client.Dispatch reported %(error)s: %(msg)s') % {u'name': method.__name__, u'args': inspect.formatargvalues(_args, _varargs, _varkw, _locals), u'progid': self._ProgID, u'id': id(self._Object), u'error': e.__class__.__name__, u'msg': unicode(e)}))

            # Log the returned value.

            self._LogDebug(_(u'%(progid)s COM Automation object 0x%(id)08X: %(method)s returned %(value)s') % {u'progid': self._ProgID, u'id': id(self._Object), u'method': method.__name__, u'value': repr(value)})

            # Convert the returned value from pythoncom's preferred type to the
            # type we prefer.

            value = self._FromPythonCOMType(value)
                
            # Return the returned value.
            
            return value

        def _ToPythonCOMType(self, obj):
            if isinstance(obj, types.ListType):
                return self._ToPythonCOMTypeList(obj)
            if isinstance(obj, types.TupleType):
                l = list(obj)
                l = self._ToPythonCOMTypeList(l)
                return tuple(l)
            if isinstance(obj, types.StringType):
                return UserPreferredEncodingToUnicode(obj)
            if isinstance(obj, datetime.datetime):
                return pywintypes.Time((obj.year, obj.month, obj.day, obj.hour, obj.minute, obj.second, 0, 0, 0))
            if isinstance(obj, COMAutomationObject):
                return obj._Object
            return obj

        def _ToPythonCOMTypeList(self, obj):
            for i in range(len(obj)):
                obj[i] = self._ToPythonCOMType(obj[i])
            return obj

        def _FromPythonCOMType(self, obj):
            if isinstance(obj, types.ListType):
                return self._FromPythonCOMTypeList(obj)
            if isinstance(obj, types.TupleType):
                l = list(obj)
                l = self._FromPythonCOMTypeList(l)
                return tuple(l)
            if isinstance(obj, pywintypes.TimeType):
                return datetime.datetime(obj.year, obj.month, obj.day, obj.hour, obj.minute, obj.second, obj.msec)
            if isinstance(obj, win32com.client.CDispatch):
                return COMAutomationObject(u'<unnamed>', obj)
            return obj

        def _FromPythonCOMTypeList(self, obj):
            for i in range(len(obj)):
                obj[i] = self._FromPythonCOMType(obj[i])
            return obj


    def FormatCOMError(hr, msg, exc, arg):

        # Adjust hr so that it will print out properly in hexadecimal.
        #
        # HRESULTs are 32-bit signed integers. In Intel architectures, like most
        # others, signed integers are stored in twos-complement form. In unsigned
        # hexadecimal, HRESULTS range from 0x80000000 to 087FFFFFF, which
        # corresponds to decimal numbers -2147483648 to -134217729.
        #
        # We want to print out the unsigned hexadecimal representation, since this
        # is what programmers are used to seeing, and what you can Google easily.
        # But Python 2.4.2's % formatter seems to be buggy:
        #
        #     >>> '%08X' % -2147483648      # We want '8000000'
        #     '-80000000'
        #     >>> '%08X' % -1               # We want 'FFFFFFFF'
        #     '-0000001'    
        #
        # But if we add 4294967296 (2^32), we get what we want:
        #
        #     >>> '%08X' % (-2147483648 + 4294967296)
        #     '80000000'
        #     >>> '%08X' % (-1 + 4294967296)
        #     'FFFFFFFF'

        if hr < 0:
            hr = hr + 4294967296

        # Format the message.
            
        s = u'COM Error 0x%08X' % hr
        if isinstance(msg, basestring):
            s = u'%s: "%s"' % (s, msg.strip())
        if not s.endswith(u'.'):
            s += u'.'
        if exc is not None:
            moreInfo = []
            (wcode, source, description, helpFile, helpId, scode) = exc
            if isinstance(source, basestring):
                moreInfo.append(u'source="%s"' % source.strip())
            if isinstance(description, basestring):
                moreInfo.append(u'description="%s"' % description.strip())
            if isinstance(scode, int) and scode != 0:
                scodeMsg = None
                try:
                    import win32api
                    scodeMsg = win32api.FormatMessage(scode)
                except:
                    pass
                if scode < 0:
                    scode += 4294967296
                if scodeMsg is not None:
                    moreInfo.append(u'scode=0x%08X ("%s")' % (scode, scodeMsg))
                else:
                    moreInfo.append(u'scode=0x%08X' % scode)
            if isinstance(wcode, int) and wcode != 0:
                moreInfo.append(u'wcode=%i' % wcode)        # wcode is a 16-bit integer. I'm not sure how to best represent it.
            s += u' Error details: ' + u', '.join(moreInfo)
            if not s.endswith(u'.'):
                s += u'.'
            if isinstance(helpFile, basestring) and isinstance(helpId, int):
                s = _(u'%s More information may be found under topic %i of help file "%s".') % (s, helpId, helpFile)

        return s


    ###############################################################################
    # Names exported by this module
    ###############################################################################

    __all__ = ['TypeLibraryGUID',
               'TypeLibraryVersion',
               'TypeLibraryLCID',
               'ValidateClassMetadata',
               'GetIDLInterfaceDefinitionFromMetadata',
               'GetIDLPropertyDefinitionFromMetadata',
               'GetIDLMethodDefinitionFromMetadata',
               'RegisterCOMServerUsingClassMetadata',
               'UnregisterCOMServerUsingClassMetadata',
               'COMAutomationObject',
               'FormatCOMError']

else:
    __all__ = []