Skip to content

O
OSGeo4W64
Switch branch/tag
Find file
Normal viewHistoryPermalink
variant.html 5.74 KB
Newer Older
xuebingbing's avatar
开发用的osgeo4w64
e40adc9e
 
xuebingbing committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 
<HTML>
<HEAD>
    <TITLE>win32com.client.VARIANT</TITLE>
</HEAD>
<BODY>

<H2>Introduction</H2>
<p>
win32com attempts to provide a seamless COM interface and hide many COM 
implementation details, including the use of COM VARIANT structures.  This 
means that in most cases, you just call a COM object using normal Python 
objects as parameters and get back normal Python objects as results.
</p>

<p>
However, in some cases this doesn't work very well, particularly when using
"dynamic" (aka late-bound) objects, or when using "makepy" (aka early-bound)
objects which only declare a parameter is a VARIANT.
</p>

<p>
The <code>win32com.client.VARIANT</code> object is designed to overcome these 
problems.
</p>

<h2>Drawbacks</h2>
The primary issue with this approach is that the programmer must learn more 
about COM VARIANTs than otherwise - they need to know concepts such as 
variants being <em>byref</em>, holding arrays, or that some may hold 32bit 
unsigned integers while others hold 64bit signed ints, and they need to 
understand this in the context of a single method call.  In short, this is
a relatively advanced feature.  The good news though is that use of these
objects should never cause your program to hard-crash - the worst you should
expect are Python or COM exceptions being thrown.

<h2>The VARIANT object</h2>

The VARIANT object lives in <code>win32com.client</code>.  The constructor 
takes 2 parameters - the 'variant type' and the value.  The 'variant type' is 
an integer and can be one or more of the <code>pythoncom.VT_*</code> values,
possibly or'd together.

<p>For example, to create a VARIANT object which defines a byref array of 
32bit integers, you could use:

<pre>
>>> from win32com.client import VARIANT
>>> import pythoncom
>>> v = VARIANT(pythoncom.VT_BYREF | pythoncom.VT_ARRAY | pythoncom.VT_I4,
...             [1,2,3,4])
>>> v
win32com.client.VARIANT(24579, [1, 2, 3, 4])
>>>
</pre>

This variable can then be used whereever a COM VARIANT is expected.

<h2>Example usage with dynamic objects.</h2>

For this example we will use the COM object used for win32com testing, 
<code>PyCOMTest.PyCOMTest</code>.  This object defines a method which is
defined in IDL as:
<pre>
HRESULT DoubleInOutString([in,out] BSTR *str);
</pre>

As you can see, it takes a single string parameter which is also used as
an "out" parameter - the single parameter will be updated after the call.
The implementation of the method simply "doubles" the string.

<p>If the object has a type-library, this method works fine with makepy
generated support.  For example:

<pre>
>>> from win32com.client.gencache import EnsureDispatch
>>> ob = EnsureDispatch("PyCOMTest.PyCOMTest")
>>> ob.DoubleInOutString("Hello")
u'HelloHello'
>>>
</pre>

However, if makepy support is not available the method does not work as
expected.  For the next example we will use <code>DumbDispatch</code> to
simulate the object not having a type-library.

<pre>
>>> import win32com.client.dynamic
>>> ob = win32com.client.dynamic.DumbDispatch("PyCOMTest.PyCOMTest")
>>> ob.DoubleInOutString("Hello")
>>>
</pre>

As you can see, no result came back from the function.  This is because
win32com has no type information available to use, so doesn't know the
parameter should be passed as a <code>byref</code> parameter.  To work
around this, we can use the <code>VARIANT</code> object.

<p>The following example explicitly creates a VARIANT object with a
variant type of a byref string and a value 'Hello'.  After making the
call with this VARIANT the value is updated.

<pre>
>>> import win32com.client.dynamic
>>> from win32com.client import VARIANT
>>> import pythoncom
>>> ob = win32com.client.dynamic.DumbDispatch("PyCOMTest.PyCOMTest")
>>> variant = VARIANT(pythoncom.VT_BYREF | pythoncom.VT_BSTR, "Hello")
>>> variant.value # check the value before the call.
'Hello'
>>> ob.DoubleInOutString(variant)
>>> variant.value
u'HelloHello'
>>>
</pre>

<h2>Usage with generated objects</h2>

In most cases, objects with makepy support (ie, 'generated' objects) don't 
need to use the VARIANT object - the type information means win32com can guess
the right thing to pass.  However, in some cases the VARIANT object can still
be useful.

Imagine a poorly specified object with IDL like:

<pre>
HRESULT DoSomething([in] VARIANT value);
</pre>

But also imagine that the object has a limitation that if the parameter is an 
integer, it must be a 32bit unsigned value - any other integer representation
will fail.

<p>If you just pass a regular Python integer to this function, it will 
generally be passed as a 32bit signed integer and given the limitation above,
will fail.  The VARIANT object allows you to work around the limitation - just
create a variant object <code>VARIANT(pythoncom.VT_UI4, int_value)</code> and 
pass that - the function will then be called with the explicit type you 
specified and will succeed.

<p>Note that you can not use a VARIANT object to override the types described
in a type library.  If a makepy generated class specifies that a VT_UI2 is 
expected, attempting to pass a VARIANT object will fail.  In this case you 
would need to hack around the problem.  For example, imagine <code>ob</code>
was a COM object which a method called <code>foo</code> and you wanted to 
override the type declaration for <code>foo</code> by passing a VARIANT.
You could do something like:

<pre>
>>> import win32com.client.dynamic
>>> from win32com.client import VARIANT
>>> import pythoncom
>>> dumbob = win32com.client.dynamic.DumbDispatch(ob)
>>> variant = VARIANT(pythoncom.VT_BYREF | pythoncom.VT_BSTR, "Hello")
>>> dumbob.foo(variant)
</pre>

The code above converts the makepy supported <code>ob</code> into a
'dumb' (ie, non-makepy supported) version of the object, which will then
allow you to use VARIANT objects for the problematic methods.

</BODY>
</HTML>