1QAxBase(3qt)                                                      QAxBase(3qt)
2
3
4

NAME

6       QAxBase - Abstract class that provides an API to initalize and access a
7       COM object
8

SYNOPSIS

10       This class is part of the Qt ActiveQt Extension.
11
12       #include <qaxbase.h>
13
14       Inherited by QAxObject and QAxWidget.
15
16   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
49   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
55   Properties
56       QString control - the name of the COM object wrapped by this QAxBase
57           object
58
59   Protected Members
60       virtual bool initialize ( IUnknown ** ptr )
61       bool initializeRemote ( IUnknown ** ptr )
62       bool initializeLicensed ( IUnknown ** ptr )
63       bool initializeActive ( IUnknown ** ptr )
64

DESCRIPTION

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
69       The QAxBase class is an abstract class that provides an API to
70       initalize and access a COM object.
71
72       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
79           connect( buttonBack, SIGNAL(clicked()), webBrowser, SLOT(GoBack()) );
80
81       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
87           activeX->setProperty( "text", "some text" );
88           int value = activeX->property( "value" );
89
90       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
94           webBrowser->dynamicCall( "GoHome()" );
95
96       Outgoing events supported by the COM object are emitted as standard Qt
97       signals.
98
99           connect( webBrowser, SIGNAL(TitleChanged(const QString&)),
100                    this, SLOT(setCaption(const QString&)) );
101
102       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
106       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
113       </center>
114
115       Supported are also enumerations, and typedefs to supported types.
116
117       To call the methods of a COM interface described by the following IDL
118
119           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
132           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
143       Note that the QValueList the object should fill has to be provided as
144       an element in the parameter list of QVariants.
145
146       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
151           IUnknown *iface = 0;
152           activeX->queryInterface( IID_IUnknown, (void**)&iface );
153           if ( iface ) {
154               // use the interface
155               iface->Release();
156           }
157
158       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
164       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
168   Member Type Documentation

QAxBase::PropertyBag

170       A QMap<QString,QVariant> that can store properties as name:value pairs.
171

MEMBER FUNCTION DOCUMENTATION

QAxBase::QAxBase ( IUnknown * iface = 0 )

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

QAxBase::~QAxBase () [virtual]

178       Shuts down the COM object and destroys the QAxBase object.
179
180       See also clear().
181

QVariant QAxBase::asVariant () const

183       Returns a QVariant that wraps the COM object. The variant can then be
184       used as a parameter in e.g. dynamicCall().
185

void QAxBase::clear () [virtual]

187       Disconnects and destroys the COM object.
188
189       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

QString QAxBase::control () const

194       Returns the name of the COM object wrapped by this QAxBase object. See
195       the "control" property for details.
196

void QAxBase::disableClassInfo ()

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
202       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

void QAxBase::disableEventSink ()

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
211       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
216       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

void QAxBase::disableMetaObject ()

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
226       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
230       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

QVariant QAxBase::dynamicCall ( const QCString & function, const QVariant &

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
245       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
249           activeX->dynamicCall( "Navigate(const QString&)", "www.trolltech.com" );
250
251       Alternatively a function can be called passing the parameters embedded
252       in the string, e.g. above function can also be invoked using
253
254           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
259       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
263           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
268       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
275           IWebBrowser2 *webBrowser = 0;
276           activeX->queryInterface( IID_IWebBrowser2, (void**)&webBrowser );
277           if ( webBrowser ) {
278               webBrowser->Navigate2( pvarURL );
279               webBrowser->Release();
280           }
281
282       This is also more efficient.
283
284       Example: qutlook/centralwidget.cpp.
285

QVariant QAxBase::dynamicCall ( const QCString & function,

287       QValueList<QVariant> & vars )
288       This is an overloaded member function, provided for convenience. It
289       behaves essentially like the above function.
290
291       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
296       The QVariant objects in vars are updated when the method has out-
297       parameters.
298

void QAxBase::exception ( int code, const QString & source, const QString &

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

QString QAxBase::generateDocumentation ()

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

bool QAxBase::initialize ( IUnknown ** ptr ) [virtual protected]

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
319       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
325       See the control property documentation for details about supported
326       patterns.
327
328       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

bool QAxBase::initializeActive ( IUnknown ** ptr ) [protected]

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
337       This function is called by initialize() if the control string contains
338       the substring "}&".
339
340       See also initialize().
341

bool QAxBase::initializeLicensed ( IUnknown ** ptr ) [protected]

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
347       This function is called by initialize() if the control string contains
348       the substring "}:". The license key needs to follow this substring.
349
350       See also initialize().
351

bool QAxBase::initializeRemote ( IUnknown ** ptr ) [protected]

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
357       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
361       See also initialize().
362

bool QAxBase::isNull () const

364       Returns TRUE if there is no COM object loaded by this wrapper;
365       otherwise return FALSE.
366
367       See also control.
368

PropertyBag QAxBase::propertyBag () const

370       Returns a name:value map of all the properties exposed by the COM
371       object.
372
373       This is more efficient than getting multiple properties individually if
374       the COM object supports property bags.
375
376       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

void QAxBase::propertyChanged ( const QString & name ) [signal]

381       If the COM object supports property notification, this signal gets
382       emitted when the property called name is changed.
383

bool QAxBase::propertyWritable ( const char * prop ) const [virtual]

385       Returns TRUE if the property prop is writable; otherwise returns FALSE.
386       By default, all properties are writable.
387
388       Warning: Depending on the control implementation this setting might be
389       ignored for some properties.
390
391       See also setPropertyWritable() and propertyChanged().
392

long QAxBase::queryInterface ( const QUuid & uuid, void ** iface ) const

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
398       Returns the result of the QueryInterface implementation of the COM
399       object.
400
401       See also control.
402

QAxObject * QAxBase::querySubObject ( const QCString & name, const QVariant &

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
413       If name is provided by a method the string must include the full
414       function prototype.
415
416       If name is a property the string must be the name of the property, and
417       var1, ... var8 are ignored.
418
419       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
424       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
428           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
437       Example: qutlook/centralwidget.cpp.
438

bool QAxBase::setControl ( const QString & )

440       Sets the name of the COM object wrapped by this QAxBase object. See the
441       "control" property for details.
442

void QAxBase::setPropertyBag ( const PropertyBag & bag )

444       Sets the properties of the COM object to the corresponding values in
445       bag.
446
447       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
452       See also propertyBag().
453

void QAxBase::setPropertyWritable ( const char * prop, bool ok ) [virtual]

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
458       Warning: Depending on the control implementation this setting might be
459       ignored for some properties.
460
461       See also propertyWritable() and propertyChanged().
462

void QAxBase::signal ( const QString & name, int argc, void * argv ) [signal]

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
471           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
485       Use this signal if the event has parameters of unsupported data types.
486       Otherwise, connect directly to the signal name.
487
488   Property Documentation

QString control

490       This property holds the name of the COM object wrapped by this QAxBase
491       object.
492
493       Setting this property initilializes the COM object. Any COM object
494       previously set is shut down.
495
496       The most efficient way to set this property is by using the registered
497       component's UUID, e.g.
498
499           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
503           ctrl->setControl( "MSCal.Calendar" );
504       The slowest, but easiest way to use is to use the control's full name,
505       e.g.
506
507           ctrl->setControl( "Calendar Control 9.0" );
508
509       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
513       To initialize the control on a different machine use the following
514       pattern:
515
516                  <domain/username>:<password>@server/{8E27C92B-1264-101C-8A2F-040224009C02}
517
518       To initialize a licensed control use the following pattern:
519
520                  {8E27C92B-1264-101C-8A2F-040224009C02}:<LicenseKey>
521
522       To connect to an already running object use the following pattern:
523
524                  {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
528           ctrl->setControl("DOMAIN/user:password@server/{8E27C92B-1264-101C-8A2F-040224009C02}:LicenseKey");
529
530       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
534       Set this property's value with setControl() and get this property's
535       value with control().
536
537

SEE ALSO

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

AUTHOR

548       Generated automatically from the source code.
549

BUGS

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
555       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
561       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).
564
565
566
567Trolltech AS                    2 February 2007                   QAxBase(3qt)
Impressum