0
# Automation and IDispatch
1
2
COM automation support for interacting with automation servers like Microsoft Office applications. Provides VARIANT handling, dispatch interfaces, type conversion, and late-bound method invocation capabilities.
3
4
## Capabilities
5
6
### Dispatch Interface
7
8
Primary interface for COM automation that enables late-bound method and property access through dispatch identifiers.
9
10
```python { .api }
11
class IDispatch(IUnknown):
12
"""Standard automation interface for late-bound COM object access."""
13
14
def GetTypeInfoCount(self):
15
"""
16
Get number of type information interfaces.
17
18
Returns:
19
int: Number of type info interfaces (0 or 1)
20
"""
21
22
def GetTypeInfo(self, itinfo, lcid):
23
"""
24
Get type information interface.
25
26
Args:
27
itinfo (int): Type info index (usually 0)
28
lcid (int): Locale identifier
29
30
Returns:
31
ITypeInfo: Type information interface
32
"""
33
34
def GetIDsOfNames(self, names, lcid=0):
35
"""
36
Map member names to dispatch identifiers.
37
38
Args:
39
names (list): List of member names
40
lcid (int, optional): Locale identifier
41
42
Returns:
43
list: List of dispatch IDs
44
45
Raises:
46
COMError: If name not found (DISP_E_UNKNOWNNAME)
47
"""
48
49
def Invoke(self, dispid, lcid, flags, args, named_args=None):
50
"""
51
Invoke method or access property by dispatch ID.
52
53
Args:
54
dispid (int): Dispatch identifier
55
lcid (int): Locale identifier
56
flags (int): Invocation flags (INVOKE_METHOD, INVOKE_PROPERTYGET, etc.)
57
args (tuple): Positional arguments as VARIANTs
58
named_args (dict, optional): Named arguments
59
60
Returns:
61
VARIANT: Return value
62
63
Raises:
64
COMError: If invocation fails
65
"""
66
```
67
68
### VARIANT Type System
69
70
Universal data type for COM automation that can hold various data types with automatic conversion support.
71
72
```python { .api }
73
class VARIANT:
74
"""Universal data type for COM automation."""
75
76
def __init__(self, value=None, vt=None):
77
"""
78
Create VARIANT from Python value.
79
80
Args:
81
value: Python value to convert
82
vt (int, optional): Explicit variant type (VT_ constant)
83
"""
84
85
@property
86
def vt(self):
87
"""Get variant type (VT_ constant)."""
88
89
@property
90
def value(self):
91
"""Get Python value from VARIANT."""
92
93
def __bool__(self):
94
"""Boolean evaluation of VARIANT."""
95
96
def __str__(self):
97
"""String representation of VARIANT value."""
98
99
def __eq__(self, other):
100
"""Compare VARIANTs for equality."""
101
102
class tagVARIANT:
103
"""Low-level VARIANT structure."""
104
vt: int # Variant type
105
wReserved1: int # Reserved
106
wReserved2: int # Reserved
107
wReserved3: int # Reserved
108
# Union of all possible values
109
llVal: int # 8-byte integer
110
lVal: int # 4-byte integer
111
bVal: int # 1-byte value
112
iVal: int # 2-byte integer
113
fltVal: float # 4-byte float
114
dblVal: float # 8-byte double
115
boolVal: int # Boolean value
116
scode: int # SCODE value
117
cyVal: object # Currency value
118
date: float # DATE value
119
bstrVal: str # BSTR string
120
punkVal: object # IUnknown pointer
121
pdispVal: object # IDispatch pointer
122
parray: object # SAFEARRAY pointer
123
```
124
125
### VARIANT Type Constants
126
127
Constants defining the data types that can be stored in VARIANT structures.
128
129
```python { .api }
130
# Basic types
131
VT_EMPTY: int # 0 - No value
132
VT_NULL: int # 1 - Null value
133
VT_I2: int # 2 - 2-byte signed integer
134
VT_I4: int # 3 - 4-byte signed integer
135
VT_R4: int # 4 - 4-byte float
136
VT_R8: int # 5 - 8-byte double
137
VT_CY: int # 6 - Currency
138
VT_DATE: int # 7 - Date/time
139
VT_BSTR: int # 8 - Basic string
140
VT_DISPATCH: int # 9 - IDispatch pointer
141
VT_ERROR: int # 10 - SCODE error code
142
VT_BOOL: int # 11 - Boolean value
143
VT_VARIANT: int # 12 - VARIANT pointer
144
VT_UNKNOWN: int # 13 - IUnknown pointer
145
VT_DECIMAL: int # 14 - Decimal value
146
147
# Extended types
148
VT_I1: int # 16 - 1-byte signed integer
149
VT_UI1: int # 17 - 1-byte unsigned integer
150
VT_UI2: int # 18 - 2-byte unsigned integer
151
VT_UI4: int # 19 - 4-byte unsigned integer
152
VT_I8: int # 20 - 8-byte signed integer
153
VT_UI8: int # 21 - 8-byte unsigned integer
154
VT_INT: int # 22 - Native integer
155
VT_UINT: int # 23 - Native unsigned integer
156
VT_VOID: int # 24 - Void type
157
VT_HRESULT: int # 25 - HRESULT value
158
VT_PTR: int # 26 - Pointer type
159
VT_SAFEARRAY: int # 27 - SAFEARRAY
160
VT_CARRAY: int # 28 - C-style array
161
VT_USERDEFINED: int # 29 - User-defined type
162
VT_LPSTR: int # 30 - ANSI string pointer
163
VT_LPWSTR: int # 31 - Unicode string pointer
164
VT_RECORD: int # 36 - Record type
165
VT_INT_PTR: int # 37 - Integer pointer
166
VT_UINT_PTR: int # 38 - Unsigned integer pointer
167
168
# Extended types
169
VT_FILETIME: int # 64 - FILETIME
170
VT_BLOB: int # 65 - Binary large object
171
VT_STREAM: int # 66 - Stream interface
172
VT_STORAGE: int # 67 - Storage interface
173
VT_STREAMED_OBJECT: int # 68 - Streamed object
174
VT_STORED_OBJECT: int # 69 - Stored object
175
VT_BLOB_OBJECT: int # 70 - BLOB object
176
VT_CF: int # 71 - Clipboard format
177
VT_CLSID: int # 72 - Class ID
178
VT_VERSIONED_STREAM: int # 73 - Versioned stream
179
VT_BSTR_BLOB: int # 4095 - BSTR blob
180
VT_VECTOR: int # 4096 - Vector flag
181
VT_ILLEGAL: int # 65535 - Illegal value
182
VT_ILLEGALMASKED: int # 4095 - Masked illegal value
183
VT_TYPEMASK: int # 4095 - Type mask
184
185
# Array and reference flags
186
VT_ARRAY: int # 0x2000 - Array flag
187
VT_BYREF: int # 0x4000 - Reference flag
188
VT_RESERVED: int # 0x8000 - Reserved flag
189
```
190
191
### Invocation Constants
192
193
Constants for specifying how dispatch methods and properties should be invoked.
194
195
```python { .api }
196
# Invocation kinds
197
INVOKE_FUNC: int # 1 - Invoke as method
198
INVOKE_PROPERTYGET: int # 2 - Get property value
199
INVOKE_PROPERTYPUT: int # 4 - Set property value
200
INVOKE_PROPERTYPUTREF: int # 8 - Set property by reference
201
202
# Dispatch flags
203
DISPATCH_METHOD: int # 1 - Method invocation
204
DISPATCH_PROPERTYGET: int # 2 - Property get
205
DISPATCH_PROPERTYPUT: int # 4 - Property put
206
DISPATCH_PROPERTYPUTREF: int # 8 - Property put by reference
207
```
208
209
### String Types
210
211
Specialized string types for COM automation with proper memory management.
212
213
```python { .api }
214
class BSTR:
215
"""
216
The Windows BSTR data type for COM automation strings.
217
218
A length-prefixed Unicode string type used by COM automation.
219
Inherits from ctypes._SimpleCData for proper COM memory management.
220
"""
221
def __init__(self, value=None): ...
222
def __repr__(self): ...
223
def __ctypes_from_outparam__(self): ...
224
```
225
226
### Locale Support
227
228
Locale identifier type for internationalization support in automation.
229
230
```python { .api }
231
LCID = int # Type alias for locale identifier
232
233
# Common locale identifiers
234
LOCALE_SYSTEM_DEFAULT: int # System default locale
235
LOCALE_USER_DEFAULT: int # User default locale
236
LOCALE_NEUTRAL: int # Language neutral
237
```
238
239
### Dispatch Parameters
240
241
Structures for passing parameters to dispatch method invocations.
242
243
```python { .api }
244
class tagDISPPARAMS:
245
"""Parameters for dispatch method invocation."""
246
rgvarg: list # Array of VARIANT arguments (reverse order)
247
rgdispidNamedArgs: list # Array of named argument dispatch IDs
248
cArgs: int # Number of arguments
249
cNamedArgs: int # Number of named arguments
250
251
class tagEXCEPINFO:
252
"""Exception information for dispatch errors."""
253
wCode: int # Error code
254
wReserved: int # Reserved
255
bstrSource: str # Error source
256
bstrDescription: str # Error description
257
bstrHelpFile: str # Help file path
258
dwHelpContext: int # Help context ID
259
pvReserved: object # Reserved
260
pfnDeferredFillIn: object # Deferred fill function
261
scode: int # SCODE error
262
```
263
264
### Type Information
265
266
Data types and constants for working with type library information.
267
268
```python { .api }
269
DISPID = int # Type alias for dispatch identifier
270
SCODE = int # Type alias for status code
271
VARTYPE = int # Type alias for variant type
272
273
# Special dispatch IDs
274
DISPID_UNKNOWN: int # -1 - Unknown member
275
DISPID_VALUE: int # 0 - Default member
276
DISPID_PROPERTYPUT: int # -3 - Property put
277
DISPID_NEWENUM: int # -4 - New enumerator
278
DISPID_EVALUATE: int # -5 - Evaluate
279
DISPID_CONSTRUCTOR: int # -6 - Constructor
280
DISPID_DESTRUCTOR: int # -7 - Destructor
281
DISPID_COLLECT: int # -8 - Collect
282
```
283
284
### VARIANT Enumerator
285
286
Interface for enumerating collections of VARIANT values.
287
288
```python { .api }
289
class IEnumVARIANT(IUnknown):
290
"""Enumerator for VARIANT collections."""
291
292
def Next(self, count):
293
"""
294
Get next variants from enumeration.
295
296
Args:
297
count (int): Maximum number of items to retrieve
298
299
Returns:
300
tuple: (variants_list, actual_count)
301
"""
302
303
def Skip(self, count):
304
"""
305
Skip specified number of variants.
306
307
Args:
308
count (int): Number of items to skip
309
"""
310
311
def Reset(self):
312
"""Reset enumeration to beginning."""
313
314
def Clone(self):
315
"""
316
Create copy of enumerator.
317
318
Returns:
319
IEnumVARIANT: Cloned enumerator
320
"""
321
```
322
323
### Currency and Decimal Types
324
325
Specialized numeric types for high-precision financial calculations.
326
327
```python { .api }
328
class tagCY:
329
"""Currency type for exact financial calculations."""
330
int64: int # 64-bit integer scaled by 10000
331
332
def __init__(self, value): ...
333
def __float__(self): ...
334
def __str__(self): ...
335
336
class tagDEC:
337
"""Decimal type for high-precision arithmetic."""
338
wReserved: int # Reserved
339
scale: int # Scale factor (0-28)
340
sign: int # Sign (0=positive, 0x80=negative)
341
Hi32: int # High 32 bits
342
Lo64: int # Low 64 bits
343
344
def __init__(self, value): ...
345
def __float__(self): ...
346
def __str__(self): ...
347
```
348
349
## Usage Examples
350
351
### Basic VARIANT Operations
352
353
```python
354
from comtypes.automation import VARIANT, VT_BSTR, VT_I4
355
356
# Create VARIANTs from Python values
357
str_var = VARIANT("Hello World")
358
int_var = VARIANT(42)
359
bool_var = VARIANT(True)
360
361
# Access values
362
print(str_var.value) # "Hello World"
363
print(int_var.value) # 42
364
print(bool_var.value) # True
365
366
# Check types
367
print(str_var.vt == VT_BSTR) # True
368
print(int_var.vt == VT_I4) # True
369
```
370
371
### Dispatch Method Invocation
372
373
```python
374
from comtypes.automation import IDispatch, INVOKE_METHOD, INVOKE_PROPERTYGET
375
376
# Assume 'obj' is an IDispatch interface
377
# Get dispatch ID for method name
378
dispids = obj.GetIDsOfNames(["SomeMethod"])
379
method_id = dispids[0]
380
381
# Invoke method with arguments
382
args = (VARIANT("arg1"), VARIANT(123))
383
result = obj.Invoke(method_id, 0, INVOKE_METHOD, args)
384
385
# Get property value
386
prop_dispids = obj.GetIDsOfNames(["SomeProperty"])
387
prop_value = obj.Invoke(prop_dispids[0], 0, INVOKE_PROPERTYGET, ())
388
```