1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 *

     5 * This program is free software: you can redistribute it and/or modify

     6 * it under the terms of the GNU Lesser General Public License as published by

     7 * the Free Software Foundation, version 2.1 of the License.

     8 * 

     9 * This program is distributed in the hope that it will be useful,

    10 * but WITHOUT ANY WARRANTY; without even the implied warranty of

    11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    12 * GNU Lesser General Public License for more details.

    13 *

    14 * You should have received a copy of the GNU Lesser General Public License

    15 * along with this program.  If not, 

    16 * see "http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html/".

    17 *

    18 * Description:

    19 *

    20 */

    21 

    22 #include "xqservicelog.h"

    23 #include <xqaiwinterfacedescriptor_p.h>

    24 #include <xqaiwinterfacedescriptor.h>

    25 #ifndef QT_NO_DATASTREAM

    26 #include <qdatastream.h>

    27 #endif

    28 

    29 #include <QDebug>

    30 

    31 //QT_BEGIN_NAMESPACE

    32 

    33 /*!

    34     \class XQAiwInterfaceDescriptor

    35     \brief The XQAiwInterfaceDescriptor class identifies a service implementation.

    36 

    37     A service can implement multiple interfaces and each interface can have multiple implementations. 

    38     The XQAiwInterfaceDescriptor class enscapsulates this information, as illustrated

    39     by the diagram below.

    40 

    41     \image XQAiwInterfaceDescriptor.png Service-Interface-Implementation

    42 

    43     The major version tag indicates the interface version and the minor version tag identifies the implementation

    44     version. Subsequent versions of the same interface must be binary compatible to previous versions 

    45     of the same interface. 

    46 

    47     In the above example service A and B implement the interface \i com.nokia.qt.x.

    48     In fact Service A provides two different implementations for the very same interface. 

    49     This is indicated by the changed minor version number. Although Service B is 

    50     using the same interface it's implementation actually utilizes the second version of

    51     the interface \i com.nokia.qt.x. Binary compatibility guarantees that clients 

    52     who know version 1 can utilize version 2. If an existing interface has to be changed

    53     in a non-compatible way a new interface (name) is required.

    54 

    55     \section1 Namespaces

    56 

    57     A XQAiwInterfaceDescriptor (the quadruble of service name, 

    58     interface name, interface version and implementation version) uniquely 

    59     identifies a service implementation on a device. Interface names follow 

    60     the java namespace convention.

    61     

    62     The namespace \i com.nokia.qt.* is reserved for future Qt development.

    63 

    64     \sa QServiceFilter, QServiceManager

    65 */

    66 

    67 /*!

    68     \enum XQAiwInterfaceDescriptor::PropertyKey

    69 

    70     This enum describes the possible property types which can be attached

    71     to a XQAiwInterfaceDescriptor.

    72 */

    73 

    74 /*! \var XQAiwInterfaceDescriptor::PropertyKey  XQAiwInterfaceDescriptor::Capabilities

    75     

    76     The capabilities property is a QStringList and

    77     describes the capabilities that a service client

    78     would require to use the service if capability 

    79     checks are enforced.

    80 */

    81 

    82 /*! \var XQAiwInterfaceDescriptor::PropertyKey  XQAiwInterfaceDescriptor::Location

    83     

    84     This property points to the location

    85     where the plug-in providing this service is stored.

    86     If the service is plug-in based the location is the

    87     name and/or path of the plugin.

    88 */

    89 

    90 /*! \var XQAiwInterfaceDescriptor::PropertyKey  XQAiwInterfaceDescriptor::ServiceDescription

    91     

    92     This property provides a general description for

    93     the service.

    94 */

    95 

    96 /*! \var XQAiwInterfaceDescriptor::PropertyKey  XQAiwInterfaceDescriptor::InterfaceDescription

    97     

    98     This property provides a description for the interface 

    99     implementation.

   100 */

   101 

   102 /*! \var XQAiwInterfaceDescriptor::PropertyKey  XQAiwInterfaceDescriptor::ImplementationId

   103 

   104     Extension: settable property, contains implementation id

   105 */

   106 

   107 /*!

   108     Creates a new XQAiwInterfaceDescriptor.

   109 */

   110 XQAiwInterfaceDescriptor::XQAiwInterfaceDescriptor()

   111     :  d(0)

   112 {

   113   XQSERVICE_DEBUG_PRINT("XQAiwInterfaceDescriptor");

   114   // Memory allocated in assigment operator !!!

   115 }

   116 

   117 /*!

   118     Destroys the XQAiwInterfaceDescriptor object.

   119 */

   120 XQAiwInterfaceDescriptor::~XQAiwInterfaceDescriptor()

   121 {

   122     XQSERVICE_DEBUG_PRINT("~XQAiwInterfaceDescriptor");

   123     if (d)

   124         delete d;

   125 }

   126 

   127 /*!

   128     Creates a copy of XQAiwInterfaceDescriptor contained in \a other.

   129     \param other Reference to the other XQAiwInterfaceDescriptor object, from

   130                  which new object will be created

   131 */

   132 XQAiwInterfaceDescriptor::XQAiwInterfaceDescriptor(const XQAiwInterfaceDescriptor& other)

   133     : d(0)

   134 {

   135     (*this) = other; //use assignment operator

   136 }

   137 

   138 

   139 /*!

   140     Copies the content of the XQAiwInterfaceDescriptor object contained 

   141     in \a other into this one.

   142     \param other Reference to XQAiwInterfaceDescriptor object, from which content will be copied

   143 */

   144 XQAiwInterfaceDescriptor& XQAiwInterfaceDescriptor::operator=(const XQAiwInterfaceDescriptor& other)

   145 {

   146     XQSERVICE_DEBUG_PRINT("XQAiwInterfaceDescriptor: operator=");

   147     if ( !other.isValid() ) {

   148         XQSERVICE_DEBUG_PRINT("other is invalid !!!");

   149         if (d) 

   150             delete d;

   151         d = 0;

   152         return *this;  // Create empty descriptor

   153     }

   154     if (!d)

   155         d = new XQAiwInterfaceDescriptorPrivate;

   156     (*d) = *(other.d);

   157     XQSERVICE_DEBUG_PRINT("XQAiwInterfaceDescriptor: operator= done");

   158     return *this;

   159 }

   160 

   161 /*!

   162     Compares a XQAiwInterfaceDescriptor to \a other.

   163     \param other Reference to XQAiwInterfaceDescriptor object, which will be compared

   164                  to this one.

   165     \return True if both instances are equal, false otherwise.

   166 */

   167 bool XQAiwInterfaceDescriptor::operator==(const XQAiwInterfaceDescriptor& other) const

   168 {

   169     XQSERVICE_DEBUG_PRINT("XQAiwInterfaceDescriptor: operator==");

   170     

   171     if (! (isValid() && other.isValid()) )

   172         return false;

   173 

   174     if (!d)

   175         return false;

   176 

   177     if ((*d) == *(other.d))

   178     {

   179         XQSERVICE_DEBUG_PRINT("== true");

   180         return true;

   181     }

   182     

   183     XQSERVICE_DEBUG_PRINT("== false");

   184     return false;

   185 }

   186 

   187 /*!

   188     \fn bool XQAiwInterfaceDescriptor::operator!=(const XQAiwInterfaceDescriptor& other) const

   189 

   190     Compares a XQAiwInterfaceDescriptor to \a other. Returns true

   191     if they are not equal and false otherwise.

   192     \param other Reference to XQAiwInterfaceDescriptor object, which will be compared

   193                  to this one.

   194     \return False if both instances are equal, true otherwise.

   195 */

   196 

   197 /*!

   198     Checks if the descriptor is valid.

   199     \return True if this descriptor is valid, false otherwise

   200 */

   201 bool XQAiwInterfaceDescriptor::isValid() const

   202 {

   203     XQSERVICE_DEBUG_PRINT("XQAiwInterfaceDescriptor:isValid");

   204     if (d)

   205     {

   206         XQSERVICE_DEBUG_PRINT("isValid=yes");

   207         return true;

   208     }

   209     XQSERVICE_DEBUG_PRINT("isValid=false");

   210     return false;

   211 }

   212 

   213 /*!

   214     Checks if this implementation is provided for all users on the system.

   215     \return True if this implementation is provided for all users on the system,

   216             false otherwise

   217 

   218     \sa QServiceManager::Scope

   219 */

   220 bool XQAiwInterfaceDescriptor::inSystemScope() const

   221 {

   222     return d ? d->systemScope : false;

   223 }

   224 

   225 /*!

   226     Gets the name of service that provides this implementation.

   227     \return Name of service

   228 */

   229 QString XQAiwInterfaceDescriptor::serviceName() const

   230 {

   231     return d ? d->serviceName : QString();

   232 }

   233 

   234 /*!

   235     Gets the name of the interface that is implemented.

   236     \return Name of the interface

   237 */

   238 QString XQAiwInterfaceDescriptor::interfaceName() const

   239 {

   240     return d ? d->interfaceName : QString();

   241 }

   242 

   243 

   244 /*!

   245     Gets the version of the interface. 

   246     Subsequent versions of an interface are binary compatible 

   247     to previous versions of the same interface. If an intcerface 

   248     is broken it must use a new interface name.

   249     \return Interface version as integer value

   250 */

   251 int XQAiwInterfaceDescriptor::majorVersion() const

   252 {

   253     return d ? d->major : -1;

   254 }

   255 

   256 /*!

   257     Gets the version of the implementation.

   258     \return Implementation version as integer value

   259 */

   260 int XQAiwInterfaceDescriptor::minorVersion() const

   261 {

   262     return d ? d->minor : -1;

   263 }

   264 

   265 /*!

   266     Gets the value for the property.

   267     \param key Key of the property

   268     \return Value of the property, invalid QVariant if does not exist

   269 */

   270 QVariant XQAiwInterfaceDescriptor::property(XQAiwInterfaceDescriptor::PropertyKey key) const

   271 {

   272     if (d)

   273     {

   274         return d->properties.value(key);

   275     }

   276     return QVariant();

   277 }

   278 

   279 /*!

   280     Extension:

   281     Sets given property. To be used by service management only.

   282 */

   283 bool XQAiwInterfaceDescriptor::setProperty(XQAiwInterfaceDescriptor::PropertyKey key, const QVariant value )

   284 {

   285     XQSERVICE_DEBUG_PRINT("XQAiwInterfaceDescriptor::setPropery %d", key);

   286     if (key < ImplementationId)

   287     {

   288         return false;  // Do not allow changing other properties

   289     }

   290     

   291     if (!d)

   292         d = new XQAiwInterfaceDescriptorPrivate;  // Ensure allocation

   293     

   294     if (d)

   295     {

   296         d->properties[key] = value;

   297         return true;

   298     }

   299     return false;

   300 }

   301 

   302 

   303 /*!

   304     Gets the value for the property.

   305     \param key Key of the custom property

   306     \return Value of the custom property, invalid null if does not exist

   307 */

   308 QString XQAiwInterfaceDescriptor::customProperty(const QString& key) const

   309 {

   310     XQSERVICE_DEBUG_PRINT("XQAiwInterfaceDescriptor::customProperty %s", qPrintable(key));

   311     QString val;

   312     if (d)

   313     {

   314         val = d->customProperties[key];

   315     }

   316     XQSERVICE_DEBUG_PRINT("XQAiwInterfaceDescriptor::customProperty value %s", qPrintable(val));

   317     

   318     return val;

   319 }

   320 

   321 /*!

   322     Gets list of custom property keys.

   323     \return list of custom property keys

   324 */

   325 QStringList XQAiwInterfaceDescriptor::customPropertyKeys() const

   326 {

   327     XQSERVICE_DEBUG_PRINT("XQAiwInterfaceDescriptor::customPropertyKeys");

   328     if (d)

   329     {

   330         return d->customProperties.keys();

   331     }

   332 

   333     return QStringList();

   334 }

   335 

   336 #ifndef QT_NO_DEBUG_STREAM

   337 QDebug operator<<(QDebug dbg, const XQAiwInterfaceDescriptor &desc)

   338 {

   339     if (desc.isValid()) {

   340         QString interface = QString("%1 %2.%3").arg(desc.interfaceName())

   341                 .arg(desc.majorVersion() < 0 ? '?' : desc.majorVersion())

   342                 .arg(desc.minorVersion() < 0 ? '?' : desc.minorVersion());

   343         dbg.nospace() << "XQAiwInterfaceDescriptor(";

   344         dbg.nospace() << "service=" << desc.serviceName() << ", ";

   345         dbg.nospace() << "interface=" << interface;

   346         dbg.nospace() << ")";

   347     } else {

   348         dbg.nospace() << "XQAiwInterfaceDescriptor(invalid)";

   349     }

   350     return dbg.space();

   351 }

   352 #endif

   353 

   354 #ifndef QT_NO_DATASTREAM

   355 

   356 QDataStream &operator<<(QDataStream &out, const XQAiwInterfaceDescriptor::PropertyKey &k)

   357 {

   358     out << qint8(k);

   359     return out;

   360 }

   361 

   362 QDataStream &operator>>(QDataStream &in, XQAiwInterfaceDescriptor::PropertyKey &k)

   363 {

   364     quint8 key;

   365     in >> key;

   366     k = (XQAiwInterfaceDescriptor::PropertyKey)key;

   367     return in;

   368 }

   369 /*! 

   370     \fn QDataStream &operator<<(QDataStream &out, const XQAiwInterfaceDescriptor &dc)

   371     \relates XQAiwInterfaceDescriptor

   372 

   373     Writes service interface descriptor \a dc to the stream \a out and returns a reference

   374     to the stream.

   375     \param out Stream to write to

   376     \param dc Interface descriptor written to stream

   377     \return Reference to the stream

   378 */

   379 

   380 QDataStream &operator<<(QDataStream &out, const XQAiwInterfaceDescriptor &dc)

   381 {

   382     const quint32 magicNumber = 0x77AFAFA;

   383     const quint16 majorVersion = 1;

   384     const quint16 minorVersion = 0;

   385     const qint8 valid = dc.isValid();

   386     out << magicNumber << majorVersion << minorVersion;

   387     out << valid;

   388     if (valid) {

   389        out << dc.d->serviceName; 

   390        out << dc.d->interfaceName;

   391        out << dc.d->major;

   392        out << dc.d->minor;

   393        out << dc.d->properties;

   394        out << dc.d->customProperties;

   395        out << dc.d->systemScope;

   396     }

   397     return out;

   398 }

   399 

   400 /*!

   401     \fn QDataStream &operator>>(QDataStream &in, XQAiwInterfaceDescriptor &dc)

   402     \relates XQAiwInterfaceDescriptor

   403 

   404     Reads a service interface descriptor into \a dc from the stream \a in and returns a

   405     reference to the stream.

   406     \param in Stream to read from

   407     \param dc Interface descriptor read from stream

   408     \return Reference to the stream

   409 */

   410 QDataStream &operator>>(QDataStream &in, XQAiwInterfaceDescriptor &dc)

   411 {

   412     const quint32 magicNumber = 0x77AFAFA;

   413     quint32 storedMagicNumber;

   414     in >> storedMagicNumber;

   415     if (storedMagicNumber != magicNumber) {

   416         qWarning() << "Datastream doesn't provide searialized XQAiwInterfaceDescriptor";

   417         return in;

   418     }

   419     

   420     const quint16 currentMajorVersion = 1;

   421     quint16 majorVersion = 0;

   422     quint16 minorVersion = 0;

   423 

   424     in >> majorVersion >> minorVersion;

   425     if (majorVersion != currentMajorVersion) {

   426         qWarning() << "Unknown serialization format for XQAiwInterfaceDescriptor.";

   427         return in;

   428     }

   429     //Allow all minor versions.

   430 

   431     qint8 valid;

   432     in >> valid;

   433     if (valid) {

   434         if (!dc.isValid())

   435             dc.d = new XQAiwInterfaceDescriptorPrivate;

   436         in >> dc.d->serviceName;

   437         in >> dc.d->interfaceName;

   438         in >> dc.d->major;

   439         in >> dc.d->minor;

   440         in >> dc.d->properties;

   441         in >> dc.d->customProperties;

   442         in >> dc.d->systemScope;

   443     } else { //input stream contains invalid descriptor

   444         //use assignment operator

   445         dc = XQAiwInterfaceDescriptor();

   446     }

   447 

   448     return in;

   449 }

   450 #endif //QT_NO_DATASTREAM

   451 

   452 

   453 

   454 //QT_END_NAMESPACE

   455