1QAxBase(3qt) QAxBase(3qt)
2
6 QAxBase - Abstract class that provides an API to initalize and access a
7 COM object
8
10 This class is part of the Qt ActiveQt Extension.
11 #include <qaxbase.h>
13 Inherited by QAxObject and QAxWidget.
15 Public Members
17 QAxBase ( IUnknown * iface = 0 )
18 virtual ~QAxBase ()
19 QString control () const
20 long queryInterface ( const QUuid & uuid, void ** iface ) const
21 QVariant dynamicCall ( const QCString & function, const QVariant & var1
22 = QVariant ( ), const QVariant & var2 = QVariant ( ), const
23 QVariant & var3 = QVariant ( ), const QVariant & var4 = QVariant (
24 ), const QVariant & var5 = QVariant ( ), const QVariant & var6 =
25 QVariant ( ), const QVariant & var7 = QVariant ( ), const QVariant
26 & var8 = QVariant ( ) )
27 QVariant dynamicCall ( const QCString & function, QValueList<QVariant>
28 & vars )
29 QAxObject * querySubObject ( const QCString & name, const QVariant &
30 var1 = QVariant ( ), const QVariant & var2 = QVariant ( ), const
31 QVariant & var3 = QVariant ( ), const QVariant & var4 = QVariant (
32 ), const QVariant & var5 = QVariant ( ), const QVariant & var6 =
33 QVariant ( ), const QVariant & var7 = QVariant ( ), const QVariant
34 & var8 = QVariant ( ) )
35 PropertyBag propertyBag () const
36 void setPropertyBag ( const PropertyBag & bag )
37 QString generateDocumentation ()
38 virtual bool propertyWritable ( const char * prop ) const
39 virtual void setPropertyWritable ( const char * prop, bool ok )
40 bool isNull () const
41 QVariant asVariant () const
42 enum PropertyBag { }
43 virtual void clear ()
44 bool setControl ( const QString & )
45 void disableMetaObject ()
46 void disableClassInfo ()
47 void disableEventSink ()
48 Signals
50 void signal ( const QString & name, int argc, void * argv )
51 void propertyChanged ( const QString & name )
52 void exception ( int code, const QString & source, const QString &
53 desc, const QString & help )
54 Properties
56 QString control - the name of the COM object wrapped by this QAxBase
57 object
58 Protected Members
60 virtual bool initialize ( IUnknown ** ptr )
61 bool initializeRemote ( IUnknown ** ptr )
62 bool initializeLicensed ( IUnknown ** ptr )
63 bool initializeActive ( IUnknown ** ptr )
64
66 This class is defined in the Qt ActiveQt Extension, which can be found
67 in the qt/extensions directory. It is not included in the main Qt API.
68 The QAxBase class is an abstract class that provides an API to
70 initalize and access a COM object.
71 QAxBase is an abstract class that cannot be used directly, and is
73 instantiated through the subclasses QAxObject and QAxWidget. This class
74 provides the API to access the COM object directly through its IUnknown
75 implementation. If the COM object implements the IDispatch interface,
76 the properties and methods of that object become available as Qt
77 properties and slots.
78 connect( buttonBack, SIGNAL(clicked()), webBrowser, SLOT(GoBack()) );
80 Properties exposed by the object's IDispatch implementation can be read
82 and written through the property system provided by the Qt Object Model
83 (both subclasses are QObjects, so you can use setProperty() and
84 property() as with QObject). Properties with multiple parameters are
85 not supported.
86 activeX->setProperty( "text", "some text" );
88 int value = activeX->property( "value" );
89 Write-functions for properties and other methods exposed by the
91 object's IDispatch implementation can be called directly using
92 dynamicCall(), or indirectly as slots connected to a signal.
93 webBrowser->dynamicCall( "GoHome()" );
95 Outgoing events supported by the COM object are emitted as standard Qt
97 signals.
98 connect( webBrowser, SIGNAL(TitleChanged(const QString&)),
100 this, SLOT(setCaption(const QString&)) );
101 QAxBase transparently converts between COM data types and the
103 equivalent Qt data types. Some COM types have no equivalent Qt data
104 structure.
105 Supported COM datatypes are listed in the first column of following
107 table. The second column is the Qt type that can be used with the
108 QObject property functions. The third column is the Qt type that is
109 used in the prototype of generated signals and slots for in-parameters,
110 and the last column is the Qt type that is used in the prototype of
111 signals and slots for out-parameters. <center>.nf
112 </center>
114 Supported are also enumerations, and typedefs to supported types.
116 To call the methods of a COM interface described by the following IDL
118 dispinterface IControl
120 {
121 properties:
122 [id(1)] BSTR text;
123 [id(2)] IFontDisp *font;
124 methods:
125 [id(6)] void showColumn( [in] int i );
126 [id(3)] bool addColumn( [in] BSTR t );
127 [id(4)] int fillList( [in, out] SAFEARRAY(VARIANT) *list );
128 [id(5)] IDispatch *item( [in] int i );
129 };
130 use the QAxBase API like this:
131 QAxObject object( "<CLSID>" );
133 QString text = object.property( "text" ).toString();
134 object.setProperty( "font", QFont( "Times New Roman", 12 ) );
135 connect( this, SIGNAL(clicked(int)), &object, SLOT(showColumn(int)) );
136 bool ok = object.dynamicCall( "addColumn(const QString&)", "Column 1" ).toBool();
137 QValueList<QVariant> varlist;
138 QValueList<QVariant> parameters;
139 parameters << QVariant( varlist );
140 int n = object.dynamicCall( "fillList(QValueList<QVariant>&)", parameters ).toInt();
141 QAxObject *item = object.querySubItem( "item(int)", 5 );
142 Note that the QValueList the object should fill has to be provided as
144 an element in the parameter list of QVariants.
145 If you need to access properties or pass parameters of unsupported
147 datatypes you must access the COM object directly through its IDispatch
148 implementation or other interfaces. Those interfaces can be retrieved
149 through queryInterface().
150 IUnknown *iface = 0;
152 activeX->queryInterface( IID_IUnknown, (void**)&iface );
153 if ( iface ) {
154 // use the interface
155 iface->Release();
156 }
157 To get the definition of the COM interfaces you will have to use the
159 header files provided with the component you want to use. Some
160 compilers can also import type libraries using the #import compiler
161 directive. See the component documentation to find out which type
162 libraries you have to import, and how to use them.
163 If you need to react to events that pass parameters of unsupported
165 datatypes you can use the generic signal that delivers the event data
166 as provided by the COM event.
167 Member Type Documentation
170 A QMap<QString,QVariant> that can store properties as name:value pairs.
171
174 Creates a QAxBase object that wraps the COM object iface. If iface is 0
175 (the default), use setControl() to instantiate a COM object.
176
178 Shuts down the COM object and destroys the QAxBase object.
179 See also clear().
181
183 Returns a QVariant that wraps the COM object. The variant can then be
184 used as a parameter in e.g. dynamicCall().
185
187 Disconnects and destroys the COM object.
188 If you reimplement this function you must also reimplement the
190 destructor to call clear(), and call this implementation at the end of
191 your clear() function.
192
194 Returns the name of the COM object wrapped by this QAxBase object. See
195 the "control" property for details.
196
198 Disables the class info generation for this ActiveX container. If you
199 don't require any class information about the ActiveX control use this
200 function to speed up the meta object generation.
201 Note that this function must be called immediately after construction
203 of the object (without passing an object identifier), and before
204 calling QAxWidget->setControl().
205
207 Disables the event sink implementation for this ActiveX container. If
208 you don't intend to listen to the ActiveX control's events use this
209 function to speed up the meta object generation.
210 Some ActiveX controls might be unstable when connected to an event
212 sink. To get OLE events you must use standard COM methods to register
213 your own event sink. Use queryInterface() to get access to the raw COM
214 object.
215 Note that this function should be called immediately after construction
217 of the object (without passing an object identifier), and before
218 calling QAxWidget->setControl().
219
221 Disables the meta object generation for this ActiveX container. This
222 also disables the event sink and class info generation. If you don't
223 intend to use the Qt meta object implementation call this function to
224 speed up the meta object generation.
225 Some ActiveX controls might be unstable when used with OLE automation.
227 Use standard COM methods to use those controls through the COM
228 interfaces provided by queryInterface().
229 Note that this function must be called immediately after construction
231 of the object (without passing an object identifier), and before
232 calling QAxWidget->setControl().
233
235 var1 = QVariant ( ), const QVariant & var2 = QVariant ( ), const
236 QVariant & var3 = QVariant ( ), const QVariant & var4 = QVariant ( ),
237 const QVariant & var5 = QVariant ( ), const QVariant & var6 = QVariant
238 ( ), const QVariant & var7 = QVariant ( ), const QVariant & var8 =
239 QVariant ( ) )
240 Calls the COM object's method function, passing the parameters var1,
241 var1, var2, var3, var4, var5, var6, var7 and var8, and returns the
242 value returned by the method, or an invalid QVariant if the method does
243 not return a value or when the function call failed.
244 If function is a method of the object the string must be provided as
246 the full prototype, for example as it would be written in a
247 QObject::connect() call.
248 activeX->dynamicCall( "Navigate(const QString&)", "www.trolltech.com" );
250 Alternatively a function can be called passing the parameters embedded
252 in the string, e.g. above function can also be invoked using
253 activeX->dynamicCall("Navigate(\"www.trolltech.com\");
255 All parameters are passed as strings; it depends on the control whether
256 they are interpreted correctly, and is slower than using the prototype
257 with correctly typed parameters.
258 If function is a property the string has to be the name of the
260 property. The property setter is called when var1 is a valid QVariant,
261 otherwise the getter is called.
262 activeX->dynamicCall( "Value", 5 );
264 QString text = activeX->dynamicCall( "Text" ).toString();
265 Note that it is faster to get and set properties using
266 QObject::property() and QObject::setProperty().
267 It is only possible to call functions through dynamicCall() that have
269 parameters or return values of datatypes supported by QVariant. See the
270 QAxBase class documentation for a list of supported and unsupported
271 datatypes. If you want to call functions that have unsupported
272 datatypes in the parameter list, use queryInterface() to retrieve the
273 appropriate COM interface, and use the function directly.
274 IWebBrowser2 *webBrowser = 0;
276 activeX->queryInterface( IID_IWebBrowser2, (void**)&webBrowser );
277 if ( webBrowser ) {
278 webBrowser->Navigate2( pvarURL );
279 webBrowser->Release();
280 }
281 This is also more efficient.
283 Example: qutlook/centralwidget.cpp.
285
287 QValueList<QVariant> & vars )
288 This is an overloaded member function, provided for convenience. It
289 behaves essentially like the above function.
290 Calls the COM object's method function, passing the parameters in vars,
292 and returns the value returned by the method. If the method does not
293 return a value or when the function call failed this function returns
294 an invalid QVariant object.
295 The QVariant objects in vars are updated when the method has out-
297 parameters.
298
300 desc, const QString & help ) [signal]
301 This signal is emitted when the COM object throws an exception while
302 called using the OLE automation interface IDispatch. code, source, desc
303 and help provide information about the exception as provided by the COM
304 server and can be used to provide useful feedback to the end user. help
305 includes the help file, and the help context ID in brackets, e.g.
306 "filename [id]".
307
309 Returns a rich text string with documentation for the wrapped COM
310 object. Dump the string to an HTML-file, or use it in e.g. a
311 QTextBrowser widget.
312
314 This virtual function is called by setControl() and creates the
315 requested COM object. ptr is set to the object's IUnknown
316 implementation. The function returns TRUE if the object initialization
317 succeeded; otherwise the function returns FALSE.
318 The default implementation interprets the string returned by control(),
320 and calls initializeRemote(), initializeLicensed() or
321 initializeActive() if the string matches the respective patterns. If no
322 pattern is matched, or if remote or licensed initialization fails,
323 CoCreateInstance is used directly to create the object.
324 See the control property documentation for details about supported
326 patterns.
327 The interface returned in ptr must be referenced exactly once when this
329 function returns. The interface provided by e.g. CoCreateInstance is
330 already referenced, and there is no need to reference it again.
331
333 Returns an active instance running on the current machine, and returns
334 the IUnknown interface to the running object in ptr. This function
335 returns TRUE if successful, otherwise returns FALSE.
336 This function is called by initialize() if the control string contains
338 the substring "}&".
339 See also initialize().
341
343 Creates an instance of a licensed control, and returns the IUnknown
344 interface to the object in ptr. This functions returns TRUE if
345 successful, otherwise returns FALSE.
346 This function is called by initialize() if the control string contains
348 the substring "}:". The license key needs to follow this substring.
349 See also initialize().
351
353 Creates the instance on a remote server, and returns the IUnknown
354 interface to the object in ptr. This function returns TRUE if
355 successful, otherwise returns FALSE.
356 This function is called by initialize() if the control string contains
358 the substring "/{". The information about the remote machine needs to
359 be provided in front of the substring.
360 See also initialize().
362
364 Returns TRUE if there is no COM object loaded by this wrapper;
365 otherwise return FALSE.
366 See also control.
368
370 Returns a name:value map of all the properties exposed by the COM
371 object.
372 This is more efficient than getting multiple properties individually if
374 the COM object supports property bags.
375 Warning: It is not guaranteed that the property bag implementation of
377 the COM object returns all properties, or that the properties returned
378 are the same as those available through the IDispatch interface.
379
381 If the COM object supports property notification, this signal gets
382 emitted when the property called name is changed.
383
385 Returns TRUE if the property prop is writable; otherwise returns FALSE.
386 By default, all properties are writable.
387 Warning: Depending on the control implementation this setting might be
389 ignored for some properties.
390 See also setPropertyWritable() and propertyChanged().
392
394 Requests the interface uuid from the COM object and sets the value of
395 iface to the provided interface, or to 0 if the requested interface
396 could not be provided.
397 Returns the result of the QueryInterface implementation of the COM
399 object.
400 See also control.
402
404 var1 = QVariant ( ), const QVariant & var2 = QVariant ( ), const
405 QVariant & var3 = QVariant ( ), const QVariant & var4 = QVariant ( ),
406 const QVariant & var5 = QVariant ( ), const QVariant & var6 = QVariant
407 ( ), const QVariant & var7 = QVariant ( ), const QVariant & var8 =
408 QVariant ( ) )
409 Returns a pointer to a QAxObject wrapping the COM object provided by
410 the method or property name, passing passing the parameters var1, var1,
411 var2, var3, var4, var5, var6, var7 and var8.
412 If name is provided by a method the string must include the full
414 function prototype.
415 If name is a property the string must be the name of the property, and
417 var1, ... var8 are ignored.
418 The returned QAxObject is a child of this object (which is either of
420 type QAxObject or QAxWidget), and is deleted when this object is
421 deleted. It is however safe to delete the returned object yourself, and
422 you should do so when you iterate over lists of subobjects.
423 COM enabled applications usually have an object model publishing
425 certain elements of the application as dispatch interfaces. Use this
426 method to navigate the hierarchy of the object model, e.g.
427 QAxWidget outlook( "Outlook.Application" );
429 QAxObject *session = outlook.querySubObject( "Session" );
430 if ( session ) {
431 QAxObject *defFolder = session->querySubObject(
432 "GetDefaultFolder(OlDefaultFolders)",
433 "olFolderContacts" );
434 //...
435 }
436 Example: qutlook/centralwidget.cpp.
438
440 Sets the name of the COM object wrapped by this QAxBase object. See the
441 "control" property for details.
442
444 Sets the properties of the COM object to the corresponding values in
445 bag.
446 Warning: You should only set property bags that have been returned by
448 the propertyBag function, as it cannot be guaranteed that the property
449 bag implementation of the COM object supports the same properties that
450 are available through the IDispatch interface.
451 See also propertyBag().
453
455 Sets the property prop to writable if ok is TRUE, otherwise sets prop
456 to be read-only. By default, all properties are writable.
457 Warning: Depending on the control implementation this setting might be
459 ignored for some properties.
460 See also propertyWritable() and propertyChanged().
462
464 This generic signal gets emitted when the COM object issues the event
465 name. argc is the number of parameters provided by the event
466 (DISPPARAMS.cArgs), and argv is the pointer to the parameter values
467 (DISPPARAMS.rgvarg). Note that the order of parameter values is turned
468 around, ie. the last element of the array is the first parameter in the
469 function.
470 void Receiver::slot( const QString &name, int argc, void *argv )
472 {
473 VARIANTARG *params = (VARIANTARG*)argv;
474 if ( name.startsWith( "BeforeNavigate2(" ) ) {
475 IDispatch *pDisp = params[argc-1].pdispVal;
476 VARIANTARG URL = *params[argc-2].pvarVal;
477 VARIANTARG Flags = *params[argc-3].pvarVal;
478 VARIANTARG TargetFrameName = *params[argc-4].pvarVal;
479 VARIANTARG PostData = *params[argc-5].pvarVal;
480 VARIANTARG Headers = *params[argc-6].pvarVal;
481 bool *Cancel = params[argc-7].pboolVal;
482 }
483 }
484 Use this signal if the event has parameters of unsupported data types.
486 Otherwise, connect directly to the signal name.
487 Property Documentation
490 This property holds the name of the COM object wrapped by this QAxBase
491 object.
492 Setting this property initilializes the COM object. Any COM object
494 previously set is shut down.
495 The most efficient way to set this property is by using the registered
497 component's UUID, e.g.
498 ctrl->setControl( "{8E27C92B-1264-101C-8A2F-040224009C02}" );
500 The second fastest way is to use the registered control's class name
501 (with or without version number), e.g.
502 ctrl->setControl( "MSCal.Calendar" );
504 The slowest, but easiest way to use is to use the control's full name,
505 e.g.
506 ctrl->setControl( "Calendar Control 9.0" );
508 If the component's UUID is used the following patterns can be used to
510 initialize the control on a remote machine, to initialize a licensed
511 control or to connect to a running object:
512 To initialize the control on a different machine use the following
514 pattern:
515 <domain/username>:<password>@server/{8E27C92B-1264-101C-8A2F-040224009C02}
517 To initialize a licensed control use the following pattern:
519 {8E27C92B-1264-101C-8A2F-040224009C02}:<LicenseKey>
521 To connect to an already running object use the following pattern:
523 {8E27C92B-1264-101C-8A2F-040224009C02}&
525 The first two patterns can be combined, e.g. to initialize a
526 licensed control on a remote machine:
527 ctrl->setControl("DOMAIN/user:password@server/{8E27C92B-1264-101C-8A2F-040224009C02}:LicenseKey");
529 The control's read function always returns the control's UUID, if
531 provided including the license key, and the name of the server, but not
532 including the username, the domain or the password.
533 Set this property's value with setControl() and get this property's
535 value with control().
536
539 http://doc.trolltech.com/qaxbase.html
540 http://www.trolltech.com/faq/tech.html
541
543 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
544 license file included in the distribution for a complete license
545 statement.
546
548 Generated automatically from the source code.
549
551 If you find a bug in Qt, please report it as described in
552 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
553 help you. Thank you.
554 The definitive Qt documentation is provided in HTML format; it is
556 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
557 web browser. This man page is provided as a convenience for those users
558 who prefer man pages, although this format is not officially supported
559 by Trolltech.
560 If you find errors in this manual page, please report them to qt-
562 bugs@trolltech.com. Please include the name of the manual page
563 (qaxbase.3qt) and the Qt version (3.3.8).
564Trolltech AS 2 February 2007 QAxBase(3qt)