1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the ActiveQt framework of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:BSD$

    10 ** You may use this file under the terms of the BSD license as follows:

    11 **

    12 ** "Redistribution and use in source and binary forms, with or without

    13 ** modification, are permitted provided that the following conditions are

    14 ** met:

    15 **   * Redistributions of source code must retain the above copyright

    16 **     notice, this list of conditions and the following disclaimer.

    17 **   * Redistributions in binary form must reproduce the above copyright

    18 **     notice, this list of conditions and the following disclaimer in

    19 **     the documentation and/or other materials provided with the

    20 **     distribution.

    21 **   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor

    22 **     the names of its contributors may be used to endorse or promote

    23 **     products derived from this software without specific prior written

    24 **     permission.

    25 **

    26 ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

    27 ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

    28 ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

    29 ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

    30 ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

    31 ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

    32 ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

    33 ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

    34 ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

    35 ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

    36 ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."

    37 ** $QT_END_LICENSE$

    38 **

    39 ****************************************************************************/

    40 

    41 #include "qaxbindable.h"

    42 

    43 #ifndef QT_NO_WIN_ACTIVEQT

    44 

    45 #include <qmetaobject.h>

    46 

    47 #include <qt_windows.h> // for IUnknown

    48 #include "../shared/qaxtypes.h"

    49 

    50 QT_BEGIN_NAMESPACE

    51 

    52 /*!

    53     \class QAxBindable

    54     \brief The QAxBindable class provides an interface between a

    55     QWidget and an ActiveX client.

    56 

    57     \inmodule QAxServer

    58 

    59     The functions provided by this class allow an ActiveX control to

    60     communicate property changes to a client application. Inherit

    61     your control class from both QWidget (directly or indirectly) and

    62     this class to get access to this class's functions. The

    63     \l{moc}{meta-object compiler} requires you to inherit from

    64     QWidget first.

    65 

    66     \snippet doc/src/snippets/code/src_activeqt_control_qaxbindable.cpp 0

    67 

    68     When implementing the property write function, use

    69     requestPropertyChange() to get permission from the ActiveX client

    70     application to change this property. When the property changes,

    71     call propertyChanged() to notify the ActiveX client application

    72     about the change. If a fatal error occurs in the control, use the

    73     static reportError() function to notify the client.

    74 

    75     Use the interface returned by clientSite() to call the ActiveX

    76     client. To implement additional COM interfaces in your ActiveX

    77     control, reimplement createAggregate() to return a new object of a

    78     QAxAggregated subclass.

    79 

    80     The ActiveQt \l{activeqt/opengl}{OpenGL} example shows how to use

    81     QAxBindable to implement additional COM interfaces.

    82 

    83     \sa QAxAggregated, QAxFactory, {ActiveQt Framework}

    84 */

    85 

    86 /*!

    87     Constructs an empty QAxBindable object.

    88 */

    89 QAxBindable::QAxBindable()

    90 :activex(0)

    91 {

    92 }

    93 

    94 /*!

    95     Destroys the QAxBindable object.

    96 */

    97 QAxBindable::~QAxBindable()

    98 {

    99 }

   100 

   101 /*!

   102     Call this function to request permission to change the property

   103     \a property from the client that is hosting this ActiveX control.

   104     Returns true if the client allows the change; otherwise returns

   105     false.

   106 

   107     This function is usually called first in the write function for \a

   108     property, and writing is abandoned if the function returns false.

   109 

   110     \snippet doc/src/snippets/code/src_activeqt_control_qaxbindable.cpp 1

   111 

   112     \sa propertyChanged()

   113 */

   114 bool QAxBindable::requestPropertyChange(const char *property)

   115 {

   116     if (!activex)

   117         return true;

   118 

   119     return activex->emitRequestPropertyChange(property);

   120 }

   121 

   122 /*!

   123     Call this function to notify the client that is hosting this

   124     ActiveX control that the property \a property has been changed.

   125 

   126     This function is usually called at the end of the property's write

   127     function.

   128 

   129     \sa requestPropertyChange()

   130 */

   131 void QAxBindable::propertyChanged(const char *property)

   132 {

   133     if (!activex)

   134         return;

   135 

   136     activex->emitPropertyChanged(property);

   137 }

   138 

   139 /*!

   140     Returns a pointer to the client site interface for this ActiveX object,

   141     or null if no client site has been set.

   142 

   143     Call \c QueryInterface() on the returned interface to get the

   144     interface you want to call.

   145 */

   146 IUnknown *QAxBindable::clientSite() const

   147 {

   148     if (!activex)

   149         return 0;

   150 

   151     return activex->clientSite();

   152 }

   153 

   154 /*!

   155     Reimplement this function when you want to implement additional

   156     COM interfaces in the ActiveX control, or when you want to provide

   157     alternative implementations of COM interfaces. Return a new object

   158     of a QAxAggregated subclass.

   159 

   160     The default implementation returns the null pointer.

   161 */

   162 QAxAggregated *QAxBindable::createAggregate()

   163 {

   164     return 0;

   165 }

   166 

   167 /*!

   168     Reports an error to the client application. \a code is a

   169     control-defined error code. \a desc is a human-readable description

   170     of the error intended for the application user. \a src is the name

   171     of the source for the error, typically the ActiveX server name. \a

   172     context can be the location of a help file with more information

   173     about the error. If \a context ends with a number in brackets,

   174     e.g. [12], this number will be interpreted as the context ID in

   175     the help file.

   176 */

   177 void QAxBindable::reportError(int code, const QString &src, const QString &desc, const QString &context)

   178 {

   179     if (!activex)

   180         return;

   181 

   182     activex->reportError(code, src, desc, context);

   183 }

   184 

   185 /*!

   186     \since 4.1

   187 

   188     If the COM object supports a MIME type then this function is called

   189     to initialize the COM object from the data \a source in \a format.

   190     You have to open \a source for reading before you can read from it.

   191 

   192     Returns true to indicate success. If the function returns false,

   193     then ActiveQt will process the data by setting the properties

   194     through the meta object system.

   195 

   196     If you reimplement this function you also have to implement

   197     writeData().  The default implementation does nothing and returns

   198     false.

   199 

   200     \warning ActiveX controls embedded in HTML can use either the 

   201     \c type and \c data attribute of the \c object tag to read data,

   202     or use a list of \c param tags to initialize properties. If

   203     \c param tags are used, then Internet Explorer will ignore the

   204     \c data attribute, and readData will not be called.

   205 

   206     \sa writeData()

   207 */

   208 bool QAxBindable::readData(QIODevice *source, const QString &format)

   209 {

   210     Q_UNUSED(source);

   211     Q_UNUSED(format);

   212     return false;

   213 }

   214 

   215 /*!

   216     \since 4.1

   217 

   218     If the COM object supports a MIME type then this function is called

   219     to store the COM object into \a sink.

   220     You have to open \a sink for writing before you can write to it.

   221 

   222     Returns true to indicate success. If the function returns false,

   223     then ActiveQt will serialize the object by storing the property

   224     values.

   225 

   226     If you reimplement this function you also have to implement

   227     readData(). The default implementation does nothing and returns

   228     false.

   229 

   230     \sa readData()

   231 */

   232 bool QAxBindable::writeData(QIODevice *sink)

   233 {

   234     Q_UNUSED(sink);

   235     return false;

   236 }

   237 

   238 /*!

   239     \class QAxAggregated

   240     \brief The QAxAggregated class is an abstract base class for implementations of

   241     additional COM interfaces.

   242 

   243     \inmodule QAxServer

   244 

   245     Create a subclass of QAxAggregated and reimplement

   246     queryInterface() to support additional COM interfaces. Use

   247     multiple inheritance from those COM interfaces. Implement the

   248     IUnknown interface of those COM interfaces by delegating the

   249     calls to \c QueryInterface(), \c AddRef() and \c Release() to the

   250     interface provided by controllingUnknown().

   251 

   252     Use the widget() method if you need to make calls to the QWidget

   253     implementing the ActiveX control. You must not store that pointer

   254     in your subclass (unless you use QPointer), as the QWidget can

   255     be destroyed by the ActiveQt framework at any time.

   256 

   257     \sa QAxBindable, QAxFactory, {ActiveQt Framework}

   258 */

   259 

   260 /*!

   261     \fn QAxAggregated::~QAxAggregated()

   262 

   263     The destructor is called internally by Qt.

   264 */

   265 

   266 /*!

   267     \fn long QAxAggregated::queryInterface(const QUuid &iid, void **iface)

   268 

   269     Reimplement this pure virtual function to support additional COM

   270     interfaces. Set the value of \a iface to point to this object to

   271     support the interface \a iid. Note that you must cast the \c

   272     this pointer to the appropriate superclass.

   273 

   274     \snippet doc/src/snippets/code/src_activeqt_control_qaxbindable.cpp 2

   275 

   276     Return the standard COM results \c S_OK (interface is supported)

   277     or \c E_NOINTERFACE (requested interface is not supported).

   278 

   279     \warning

   280     Even though you must implement the \c IUnknown interface if you

   281     implement any COM interface you must not support the \c IUnknown

   282     interface in your queryInterface() implementation.

   283 */

   284 

   285 /*!

   286     \fn IUnknown *QAxAggregated::controllingUnknown() const

   287 

   288     Returns the \c IUnknown interface of the ActiveX control. Implement

   289     the \c IUnknown interface in your QAxAggregated subclass to

   290     delegate calls to \c QueryInterface(), \c AddRef(), and \c

   291     Release() to the interface provided by this function.

   292 

   293     \snippet doc/src/snippets/code/src_activeqt_control_qaxbindable.cpp 3

   294 

   295     Instead of declaring and implementing these three functions

   296     manually, you can use the \c QAXAGG_IUNKNOWN macro in the class

   297     declaration of your subclass.

   298 */

   299 

   300 /*!

   301     \fn QObject *QAxAggregated::object() const

   302 

   303     Returns a pointer to the QObject subclass implementing the COM object.

   304     This function might return 0.

   305 

   306     \warning

   307     You must not store the returned pointer, unless you use a

   308     QPointer, since the QObject can be destroyed by ActiveQt at any

   309     time.

   310 */

   311 

   312 /*!

   313     \fn QWidget *QAxAggregated::widget() const

   314 

   315     Returns a pointer to the QWidget subclass implementing the ActiveX control.

   316     This function might return 0.

   317 

   318     \warning

   319     You must not store the returned pointer, unless you use a

   320     QPointer, since the QWidget can be destroyed by ActiveQt at any

   321     time.

   322 */

   323 

   324 QT_END_NAMESPACE

   325 #endif // QT_NO_WIN_ACTIVEQT