1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtDBus module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qdbusargument.h"
43 #include "qdbusargument_p.h"
46 #include <qbytearray.h>
50 #include <qstringlist.h>
52 #include <qdatetime.h>
56 #include "qdbusmetatype_p.h"
57 #include "qdbusutil_p.h"
63 QDBusArgumentPrivate::~QDBusArgumentPrivate()
66 q_dbus_message_unref(message);
69 QByteArray QDBusArgumentPrivate::createSignature(int id)
71 if (!qdbus_loadLibDBus())
75 QDBusMarshaller *marshaller = new QDBusMarshaller(0);
76 marshaller->ba = &signature;
81 QDBusArgument arg(marshaller);
82 QDBusMetaType::marshall(arg, v.userType(), v.constData());
86 bool ok = marshaller->ok;
89 if (signature.isEmpty() || !ok || !QDBusUtil::isValidSingleSignature(QString::fromLatin1(signature))) {
90 qWarning("QDBusMarshaller: type `%s' produces invalid D-BUS signature `%s' "
91 "(Did you forget to call beginStructure() ?)",
92 QMetaType::typeName(id),
93 signature.isEmpty() ? "<empty>" : signature.constData());
95 } else if ((signature.at(0) != DBUS_TYPE_ARRAY && signature.at(0) != DBUS_STRUCT_BEGIN_CHAR) ||
96 (signature.at(0) == DBUS_TYPE_ARRAY && (signature.at(1) == DBUS_TYPE_BYTE ||
97 signature.at(1) == DBUS_TYPE_STRING))) {
98 qWarning("QDBusMarshaller: type `%s' attempts to redefine basic D-BUS type '%s' (%s) "
99 "(Did you forget to call beginStructure() ?)",
100 QMetaType::typeName(id),
101 signature.constData(),
102 QMetaType::typeName(QDBusMetaType::signatureToType(signature)));
108 bool QDBusArgumentPrivate::checkWrite(QDBusArgumentPrivate *&d)
112 if (d->direction == Marshalling) {
113 if (!d->marshaller()->ok)
116 if (d->message && d->ref.load() != 1) {
117 QDBusMarshaller *dd = new QDBusMarshaller(d->capabilities);
118 dd->message = q_dbus_message_copy(d->message);
119 q_dbus_message_iter_init_append(dd->message, &dd->iterator);
129 qFatal("QDBusArgument: write from a read-only object");
131 qWarning("QDBusArgument: write from a read-only object");
136 bool QDBusArgumentPrivate::checkRead(QDBusArgumentPrivate *d)
140 if (d->direction == Demarshalling)
144 qFatal("QDBusArgument: read from a write-only object");
146 qWarning("QDBusArgument: read from a write-only object");
152 bool QDBusArgumentPrivate::checkReadAndDetach(QDBusArgumentPrivate *&d)
155 return false; // don't bother
157 if (d->ref.load() == 1)
158 return true; // no need to detach
160 QDBusDemarshaller *dd = new QDBusDemarshaller(d->capabilities);
161 dd->message = q_dbus_message_ref(d->message);
162 dd->iterator = static_cast<QDBusDemarshaller*>(d)->iterator;
175 \brief The QDBusArgument class is used to marshall and demarshall D-Bus arguments.
177 The class is used to send arguments over D-Bus to remote
178 applications and to receive them back. D-Bus offers an extensible
179 type system, based on a few primitive types and associations of
180 them. See the \l {qdbustypesystem.html}{QtDBus type system} page
181 for more information on the type system.
183 QDBusArgument is the central class in the QtDBus type system,
184 providing functions to marshall and demarshall the primitive
185 types. The compound types are then created by association of one
186 or more of the primitive types in arrays, dictionaries or
189 The following example illustrates how a structure containing an
190 integer and a string can be constructed using the \l
191 {qdbustypesystem.html}{QtDBus type system}:
193 \snippet code/src_qdbus_qdbusargument.cpp 0
195 The type has to be registered with qDBusRegisterMetaType() before
196 it can be used with QDBusArgument. Therefore, somewhere in your
197 program, you should add the following code:
199 \snippet code/src_qdbus_qdbusargument.cpp 1
201 Once registered, a type can be used in outgoing method calls
202 (placed with QDBusAbstractInterface::call()), signal emissions
203 from registered objects or in incoming calls from remote
206 It is important to note that the \c{operator<<} and \c{operator>>}
207 streaming functions must always produce the same number of entries
208 in case of structures, both in reading and in writing (marshalling
209 and demarshalling), otherwise calls and signals may start to
212 The following example illustrates this wrong usage
213 in context of a class that may contain invalid data:
216 // Wrongly marshall the MyTime data into a D-Bus argument
217 QDBusArgument &operator<<(QDBusArgument &argument, const MyTime &mytime)
219 argument.beginStructure();
221 argument << true << mytime.hour
222 << mytime.minute << mytime.second;
225 argument.endStructure();
230 In this example, both the \c{operator<<} and the \c{operator>>}
231 functions may produce a different number of reads/writes. This can
232 confuse the QtDBus type system and should be avoided.
234 \sa QDBusAbstractInterface, {qdbustypesystem.html}{The QtDBus type
235 system}, {usingadaptors.html}{Using Adaptors}, qdbus_cast()
239 \enum QDBusArgument::ElementType
242 This enum describes the type of element held by the argument.
244 \value BasicType A basic element, which is understood by
245 QVariant. The following types are considered basic: bool,
246 byte, short, ushort, int, uint, qint64, quint64, double,
247 QString, QByteArray, QDBusObjectPath, QDBusSignature
249 \value VariantType The variant element (QDBusVariant)
251 \value ArrayType An array element, usually represented by QList<T>
252 or QVector<T>. Note: QByteArray and associative maps are not
253 considered arrays, even if the D-Bus protocol transports them as such.
255 \value StructureType A custom type represented by a structure,
256 like QDateTime, QPoint, etc.
258 \value MapType An associative container, like QMap<Key, Value> or
261 \value MapEntryType One entry in an associative container: both
262 the key and the value form one map-entry type.
264 \value UnknownType The type is unknown or we have reached the end
271 \fn qdbus_cast(const QDBusArgument &argument)
272 \relates QDBusArgument
275 Attempts to demarshall the contents of \a argument into the type
278 \snippet code/src_qdbus_qdbusargument.cpp 2
280 Note that it is equivalent to the following:
282 \snippet code/src_qdbus_qdbusargument.cpp 3
286 Constructs an empty QDBusArgument argument.
288 An empty QDBusArgument object does not allow either reading or
289 writing to be performed.
291 QDBusArgument::QDBusArgument()
293 if (!qdbus_loadLibDBus()) {
298 QDBusMarshaller *dd = new QDBusMarshaller(0);
301 // create a new message with any type, we won't sent it anyways
302 dd->message = q_dbus_message_new(DBUS_MESSAGE_TYPE_METHOD_CALL);
303 q_dbus_message_iter_init_append(dd->message, &dd->iterator);
307 Constructs a copy of the \a other QDBusArgument object.
309 Both objects will therefore contain the same state from this point
310 forward. QDBusArguments are explicitly shared and, therefore, any
311 modification to either copy will affect the other one too.
313 QDBusArgument::QDBusArgument(const QDBusArgument &other)
323 QDBusArgument::QDBusArgument(QDBusArgumentPrivate *dd)
329 Copies the \a other QDBusArgument object into this one.
331 Both objects will therefore contain the same state from this point
332 forward. QDBusArguments are explicitly shared and, therefore, any
333 modification to either copy will affect the other one too.
335 QDBusArgument &QDBusArgument::operator=(const QDBusArgument &other)
337 qAtomicAssign(d, other.d);
342 Disposes of the resources associated with this QDBusArgument
345 QDBusArgument::~QDBusArgument()
347 if (d && !d->ref.deref())
352 Appends the primitive value \a arg of type \c{BYTE} to the D-Bus stream.
354 QDBusArgument &QDBusArgument::operator<<(uchar arg)
356 if (QDBusArgumentPrivate::checkWrite(d))
357 d->marshaller()->append(arg);
363 Appends the primitive value \a arg of type \c{BOOLEAN} to the D-Bus stream.
365 QDBusArgument &QDBusArgument::operator<<(bool arg)
367 if (QDBusArgumentPrivate::checkWrite(d))
368 d->marshaller()->append(arg);
374 Appends the primitive value \a arg of type \c{INT16} to the D-Bus stream.
376 QDBusArgument &QDBusArgument::operator<<(short arg)
378 if (QDBusArgumentPrivate::checkWrite(d))
379 d->marshaller()->append(arg);
385 Appends the primitive value \a arg of type \c{UINT16} to the D-Bus stream.
387 QDBusArgument &QDBusArgument::operator<<(ushort arg)
389 if (QDBusArgumentPrivate::checkWrite(d))
390 d->marshaller()->append(arg);
396 Appends the primitive value \a arg of type \c{INT32} to the D-Bus stream.
398 QDBusArgument &QDBusArgument::operator<<(int arg)
400 if (QDBusArgumentPrivate::checkWrite(d))
401 d->marshaller()->append(arg);
407 Appends the primitive value \a arg of type \c{UINT32} to the D-Bus stream.
409 QDBusArgument &QDBusArgument::operator<<(uint arg)
411 if (QDBusArgumentPrivate::checkWrite(d))
412 d->marshaller()->append(arg);
418 Appends the primitive value \a arg of type \c{INT64} to the D-Bus stream.
420 QDBusArgument &QDBusArgument::operator<<(qlonglong arg)
422 if (QDBusArgumentPrivate::checkWrite(d))
423 d->marshaller()->append(arg);
429 Appends the primitive value \a arg of type \c{UINT64} to the D-Bus stream.
431 QDBusArgument &QDBusArgument::operator<<(qulonglong arg)
433 if (QDBusArgumentPrivate::checkWrite(d))
434 d->marshaller()->append(arg);
440 Appends the primitive value \a arg of type \c{DOUBLE} (double-precision
441 floating-point) to the D-Bus stream.
443 QDBusArgument &QDBusArgument::operator<<(double arg)
445 if (QDBusArgumentPrivate::checkWrite(d))
446 d->marshaller()->append(arg);
452 Appends the primitive value \a arg of type \c{STRING} (Unicode character
453 string) to the D-Bus stream.
455 QDBusArgument &QDBusArgument::operator<<(const QString &arg)
457 if (QDBusArgumentPrivate::checkWrite(d))
458 d->marshaller()->append(arg);
465 Appends the primitive value \a arg of type \c{OBJECT_PATH} (path to a D-Bus
466 object) to the D-Bus stream.
468 QDBusArgument &QDBusArgument::operator<<(const QDBusObjectPath &arg)
470 if (QDBusArgumentPrivate::checkWrite(d))
471 d->marshaller()->append(arg);
478 Appends the primitive value \a arg of type \c{SIGNATURE} (D-Bus type
479 signature) to the D-Bus stream.
481 QDBusArgument &QDBusArgument::operator<<(const QDBusSignature &arg)
483 if (QDBusArgumentPrivate::checkWrite(d))
484 d->marshaller()->append(arg);
492 Appends the primitive value \a arg of type \c{UNIX_FILE_DESCRIPTOR} (Unix
493 File Descriptor) to the D-Bus stream.
495 QDBusArgument &QDBusArgument::operator<<(const QDBusUnixFileDescriptor &arg)
497 if (QDBusArgumentPrivate::checkWrite(d))
498 d->marshaller()->append(arg);
504 Appends the primitive value \a arg of type \c{VARIANT} to the D-Bus stream.
506 A D-Bus variant type can contain any type, including other
507 variants. It is similar to the Qt QVariant type.
509 QDBusArgument &QDBusArgument::operator<<(const QDBusVariant &arg)
511 if (QDBusArgumentPrivate::checkWrite(d))
512 d->marshaller()->append(arg);
518 Appends the QStringList given by \a arg as \c{ARRAY of STRING}
521 QStringList and QByteArray are the only two non-primitive types
522 that are supported directly by QDBusArgument because of their
523 widespread usage in Qt applications.
525 Other arrays are supported through compound types in QtDBus.
527 QDBusArgument &QDBusArgument::operator<<(const QStringList &arg)
529 if (QDBusArgumentPrivate::checkWrite(d))
530 d->marshaller()->append(arg);
536 Appends the QByteArray given by \a arg as \c{ARRAY of BYTE}
539 QStringList and QByteArray are the only two non-primitive types
540 that are supported directly by QDBusArgument because of their
541 widespread usage in Qt applications.
543 Other arrays are supported through compound types in QtDBus.
545 QDBusArgument &QDBusArgument::operator<<(const QByteArray &arg)
547 if (QDBusArgumentPrivate::checkWrite(d))
548 d->marshaller()->append(arg);
556 Appends the variant \a v.
560 void QDBusArgument::appendVariant(const QVariant &v)
562 if (QDBusArgumentPrivate::checkWrite(d))
563 d->marshaller()->appendVariantInternal(v);
568 Returns the type signature of the D-Bus type this QDBusArgument
569 object is currently pointing to.
571 QString QDBusArgument::currentSignature() const
575 if (d->direction == QDBusArgumentPrivate::Demarshalling)
576 return d->demarshaller()->currentSignature();
578 return d->marshaller()->currentSignature();
583 Returns the classification of the current element type. If an
584 error decoding the type occurs or if we're at the end of the
585 argument, this function returns QDBusArgument::UnknownType.
587 This function only makes sense when demarshalling arguments. If it
588 is used while marshalling, it will always return UnknownType.
590 QDBusArgument::ElementType QDBusArgument::currentType() const
594 if (d->direction == QDBusArgumentPrivate::Demarshalling)
595 return d->demarshaller()->currentType();
600 Extracts one D-BUS primitive argument of type \c{BYTE} from the
601 D-BUS stream and puts it into \a arg.
603 const QDBusArgument &QDBusArgument::operator>>(uchar &arg) const
605 if (QDBusArgumentPrivate::checkReadAndDetach(d))
606 arg = d->demarshaller()->toByte();
612 Extracts one D-Bus primitive argument of type \c{BOOLEAN} from the
615 const QDBusArgument &QDBusArgument::operator>>(bool &arg) const
617 if (QDBusArgumentPrivate::checkReadAndDetach(d))
618 arg = d->demarshaller()->toBool();
624 Extracts one D-Bus primitive argument of type \c{UINT16} from the
627 const QDBusArgument &QDBusArgument::operator>>(ushort &arg) const
629 if (QDBusArgumentPrivate::checkReadAndDetach(d))
630 arg = d->demarshaller()->toUShort();
636 Extracts one D-Bus primitive argument of type \c{INT16} from the
639 const QDBusArgument &QDBusArgument::operator>>(short &arg) const
641 if (QDBusArgumentPrivate::checkReadAndDetach(d))
642 arg = d->demarshaller()->toShort();
648 Extracts one D-Bus primitive argument of type \c{INT32} from the
651 const QDBusArgument &QDBusArgument::operator>>(int &arg) const
653 if (QDBusArgumentPrivate::checkReadAndDetach(d))
654 arg = d->demarshaller()->toInt();
660 Extracts one D-Bus primitive argument of type \c{UINT32} from the
663 const QDBusArgument &QDBusArgument::operator>>(uint &arg) const
665 if (QDBusArgumentPrivate::checkReadAndDetach(d))
666 arg = d->demarshaller()->toUInt();
672 Extracts one D-Bus primitive argument of type \c{INT64} from the
675 const QDBusArgument &QDBusArgument::operator>>(qlonglong &arg) const
677 if (QDBusArgumentPrivate::checkReadAndDetach(d))
678 arg = d->demarshaller()->toLongLong();
684 Extracts one D-Bus primitive argument of type \c{UINT64} from the
687 const QDBusArgument &QDBusArgument::operator>>(qulonglong &arg) const
689 if (QDBusArgumentPrivate::checkReadAndDetach(d))
690 arg = d->demarshaller()->toULongLong();
696 Extracts one D-Bus primitive argument of type \c{DOUBLE}
697 (double-precision floating pount) from the D-Bus stream.
699 const QDBusArgument &QDBusArgument::operator>>(double &arg) const
701 if (QDBusArgumentPrivate::checkReadAndDetach(d))
702 arg = d->demarshaller()->toDouble();
708 Extracts one D-Bus primitive argument of type \c{STRING} (Unicode
709 character string) from the D-Bus stream.
711 const QDBusArgument &QDBusArgument::operator>>(QString &arg) const
713 if (QDBusArgumentPrivate::checkReadAndDetach(d))
714 arg = d->demarshaller()->toString();
721 Extracts one D-Bus primitive argument of type \c{OBJECT_PATH}
722 (D-Bus path to an object) from the D-Bus stream.
724 const QDBusArgument &QDBusArgument::operator>>(QDBusObjectPath &arg) const
726 if (QDBusArgumentPrivate::checkReadAndDetach(d))
727 arg = d->demarshaller()->toObjectPath();
734 Extracts one D-Bus primitive argument of type \c{SIGNATURE} (D-Bus
735 type signature) from the D-Bus stream.
737 const QDBusArgument &QDBusArgument::operator>>(QDBusSignature &arg) const
739 if (QDBusArgumentPrivate::checkReadAndDetach(d))
740 arg = d->demarshaller()->toSignature();
748 Extracts one D-Bus primitive argument of type \c{UNIX_FILE_DESCRIPTOR}
749 (Unix file descriptor) from the D-Bus stream.
751 const QDBusArgument &QDBusArgument::operator>>(QDBusUnixFileDescriptor &arg) const
753 if (QDBusArgumentPrivate::checkReadAndDetach(d))
754 arg = d->demarshaller()->toUnixFileDescriptor();
760 Extracts one D-Bus primitive argument of type \c{VARIANT} from the
763 A D-Bus variant type can contain any type, including other
764 variants. It is similar to the Qt QVariant type.
766 In case the variant contains a type not directly supported by
767 QDBusArgument, the value of the returned QDBusVariant will contain
768 another QDBusArgument. It is your responsibility to further
769 demarshall it into another type.
771 const QDBusArgument &QDBusArgument::operator>>(QDBusVariant &arg) const
773 if (QDBusArgumentPrivate::checkReadAndDetach(d))
774 arg = d->demarshaller()->toVariant();
780 Extracts an array of strings from the D-Bus stream and return it
783 QStringList and QByteArray are the only two non-primitive types
784 that are supported directly by QDBusArgument because of their
785 widespread usage in Qt applications.
787 Other arrays are supported through compound types in QtDBus.
789 const QDBusArgument &QDBusArgument::operator>>(QStringList &arg) const
791 if (QDBusArgumentPrivate::checkReadAndDetach(d))
792 arg = d->demarshaller()->toStringList();
798 Extracts an array of bytes from the D-Bus stream and return it
801 QStringList and QByteArray are the only two non-primitive types
802 that are supported directly by QDBusArgument because of their
803 widespread usage in Qt applications.
805 Other arrays are supported through compound types in QtDBus.
807 const QDBusArgument &QDBusArgument::operator>>(QByteArray &arg) const
809 if (QDBusArgumentPrivate::checkReadAndDetach(d))
810 arg = d->demarshaller()->toByteArray();
815 Opens a new D-Bus structure suitable for appending new arguments.
817 This function is used usually in \c{operator<<} streaming
818 operators, as in the following example:
820 \snippet code/src_qdbus_qdbusargument.cpp 4
822 Structures can contain other structures, so the following code is
825 \snippet code/src_qdbus_qdbusargument.cpp 5
827 \sa endStructure(), beginArray(), beginMap()
829 void QDBusArgument::beginStructure()
831 if (QDBusArgumentPrivate::checkWrite(d))
832 d = d->marshaller()->beginStructure();
836 Closes a D-Bus structure opened with beginStructure(). This function must be called
837 same number of times that beginStructure() is called.
839 \sa beginStructure(), endArray(), endMap()
841 void QDBusArgument::endStructure()
843 if (QDBusArgumentPrivate::checkWrite(d))
844 d = d->marshaller()->endStructure();
848 Opens a new D-Bus array suitable for appending elements of meta-type \a id.
850 This function is used usually in \c{operator<<} streaming
851 operators, as in the following example:
853 \snippet code/src_qdbus_qdbusargument.cpp 6
855 If the type you want to marshall is a QList, QVector or any of the
856 Qt's \l {Container Classes} that take one template parameter,
857 you need not declare an \c{operator<<} function for it, since
858 QtDBus provides generic templates to do the job of marshalling
859 the data. The same applies for STL's sequence containers, such
860 as \c {std::list}, \c {std::vector}, etc.
862 \sa endArray(), beginStructure(), beginMap()
864 void QDBusArgument::beginArray(int id)
866 if (QDBusArgumentPrivate::checkWrite(d))
867 d = d->marshaller()->beginArray(id);
871 Closes a D-Bus array opened with beginArray(). This function must be called
872 same number of times that beginArray() is called.
874 \sa beginArray(), endStructure(), endMap()
876 void QDBusArgument::endArray()
878 if (QDBusArgumentPrivate::checkWrite(d))
879 d = d->marshaller()->endArray();
883 Opens a new D-Bus map suitable for
884 appending elements. Maps are containers that associate one entry
885 (the key) to another (the value), such as Qt's QMap or QHash. The
886 ids of the map's key and value meta types must be passed in \a kid
887 and \a vid respectively.
889 This function is used usually in \c{operator<<} streaming
890 operators, as in the following example:
892 \snippet code/src_qdbus_qdbusargument.cpp 7
894 If the type you want to marshall is a QMap or QHash, you need not
895 declare an \c{operator<<} function for it, since QtDBus provides
896 generic templates to do the job of marshalling the data.
898 \sa endMap(), beginStructure(), beginArray(), beginMapEntry()
900 void QDBusArgument::beginMap(int kid, int vid)
902 if (QDBusArgumentPrivate::checkWrite(d))
903 d = d->marshaller()->beginMap(kid, vid);
907 Closes a D-Bus map opened with beginMap(). This function must be called
908 same number of times that beginMap() is called.
910 \sa beginMap(), endStructure(), endArray()
912 void QDBusArgument::endMap()
914 if (QDBusArgumentPrivate::checkWrite(d))
915 d = d->marshaller()->endMap();
919 Opens a D-Bus map entry suitable for
920 appending the key and value entries. This function is only valid
921 when a map has been opened with beginMap().
923 See beginMap() for an example of usage of this function.
925 \sa endMapEntry(), beginMap()
927 void QDBusArgument::beginMapEntry()
929 if (QDBusArgumentPrivate::checkWrite(d))
930 d = d->marshaller()->beginMapEntry();
934 Closes a D-Bus map entry opened with beginMapEntry(). This function must be called
935 same number of times that beginMapEntry() is called.
939 void QDBusArgument::endMapEntry()
941 if (QDBusArgumentPrivate::checkWrite(d))
942 d = d->marshaller()->endMapEntry();
946 Opens a D-Bus structure suitable for extracting elements.
948 This function is used usually in \c{operator>>} streaming
949 operators, as in the following example:
951 \snippet code/src_qdbus_qdbusargument.cpp 8
953 \sa endStructure(), beginArray(), beginMap()
955 void QDBusArgument::beginStructure() const
957 if (QDBusArgumentPrivate::checkReadAndDetach(d))
958 d = d->demarshaller()->beginStructure();
962 Closes the D-Bus structure and allow extracting of the next element
967 void QDBusArgument::endStructure() const
969 if (QDBusArgumentPrivate::checkReadAndDetach(d))
970 d = d->demarshaller()->endStructure();
974 Recurses into the D-Bus array to allow extraction of
977 This function is used usually in \c{operator>>} streaming
978 operators, as in the following example:
980 \snippet code/src_qdbus_qdbusargument.cpp 9
982 If the type you want to demarshall is a QList, QVector or any of the
983 Qt's \l {Container Classes} that take one template parameter, you
984 need not declare an \c{operator>>} function for it, since QtDBus
985 provides generic templates to do the job of demarshalling the data.
986 The same applies for STL's sequence containers, such as \c {std::list},
987 \c {std::vector}, etc.
989 \sa atEnd(), beginStructure(), beginMap()
991 void QDBusArgument::beginArray() const
993 if (QDBusArgumentPrivate::checkReadAndDetach(d))
994 d = d->demarshaller()->beginArray();
998 Closes the D-Bus array and allow extracting of the next element
1003 void QDBusArgument::endArray() const
1005 if (QDBusArgumentPrivate::checkReadAndDetach(d))
1006 d = d->demarshaller()->endArray();
1010 Recurses into the D-Bus map to allow extraction of
1013 This function is used usually in \c{operator>>} streaming
1014 operators, as in the following example:
1016 \snippet code/src_qdbus_qdbusargument.cpp 10
1018 If the type you want to demarshall is a QMap or QHash, you need not
1019 declare an \c{operator>>} function for it, since QtDBus provides
1020 generic templates to do the job of demarshalling the data.
1022 \sa endMap(), beginStructure(), beginArray(), beginMapEntry()
1024 void QDBusArgument::beginMap() const
1026 if (QDBusArgumentPrivate::checkReadAndDetach(d))
1027 d = d->demarshaller()->beginMap();
1031 Closes the D-Bus map and allow extracting of the next element
1036 void QDBusArgument::endMap() const
1038 if (QDBusArgumentPrivate::checkReadAndDetach(d))
1039 d = d->demarshaller()->endMap();
1043 Recurses into the D-Bus map entry to allow extraction
1044 of the key and value pair.
1046 See beginMap() for an example of how this function is usually used.
1048 \sa endMapEntry(), beginMap()
1050 void QDBusArgument::beginMapEntry() const
1052 if (QDBusArgumentPrivate::checkReadAndDetach(d))
1053 d = d->demarshaller()->beginMapEntry();
1057 Closes the D-Bus map entry and allow extracting of the next element
1062 void QDBusArgument::endMapEntry() const
1064 if (QDBusArgumentPrivate::checkReadAndDetach(d))
1065 d = d->demarshaller()->endMapEntry();
1069 Returns true if there are no more elements to be extracted from
1070 this QDBusArgument. This function is usually used in QDBusArgument
1071 objects returned from beginMap() and beginArray().
1073 bool QDBusArgument::atEnd() const
1075 if (QDBusArgumentPrivate::checkRead(d))
1076 return d->demarshaller()->atEnd();
1078 return true; // at least, stop reading
1084 Returns the current argument in the form of a QVariant. Basic
1085 types will be decoded and returned in the QVariant, but for
1086 complex types, this function will return a QDBusArgument object in
1087 the QVariant. It is the caller's responsibility to decode the
1088 argument (for example, by calling asVariant() in it).
1090 For example, if the current argument is an INT32, this function
1091 will return a QVariant with an argument of type QVariant::Int. For
1092 an array of INT32, it will return a QVariant containing a
1095 If an error occurs or if there are no more arguments to decode
1096 (i.e., we are at the end of the argument list), this function will
1097 return an invalid QVariant.
1101 QVariant QDBusArgument::asVariant() const
1103 if (QDBusArgumentPrivate::checkRead(d))
1104 return d->demarshaller()->toVariantInternal();
1111 // for optimization purposes, we include the marshallers here
1112 #include "qdbusmarshaller.cpp"
1113 #include "qdbusdemarshaller.cpp"
1117 // QDBusArgument operators
1119 const QDBusArgument &operator>>(const QDBusArgument &a, QVariant &v)
1128 #ifndef QDBUS_NO_SPECIALTYPES
1129 const QDBusArgument &operator>>(const QDBusArgument &a, QDate &date)
1136 if (y != 0 && m != 0 && d != 0)
1137 date.setDate(y, m, d);
1143 QDBusArgument &operator<<(QDBusArgument &a, const QDate &date)
1147 a << date.year() << date.month() << date.day();
1154 const QDBusArgument &operator>>(const QDBusArgument &a, QTime &time)
1158 a >> h >> m >> s >> ms;
1164 time.setHMS(h, m, s, ms);
1168 QDBusArgument &operator<<(QDBusArgument &a, const QTime &time)
1172 a << time.hour() << time.minute() << time.second() << time.msec();
1174 a << -1 << -1 << -1 << -1;
1179 const QDBusArgument &operator>>(const QDBusArgument &a, QDateTime &dt)
1186 a >> date >> time >> timespec;
1189 dt = QDateTime(date, time, Qt::TimeSpec(timespec));
1193 QDBusArgument &operator<<(QDBusArgument &a, const QDateTime &dt)
1196 a << dt.date() << dt.time() << int(dt.timeSpec());
1201 const QDBusArgument &operator>>(const QDBusArgument &a, QRect &rect)
1203 int x, y, width, height;
1205 a >> x >> y >> width >> height;
1208 rect.setRect(x, y, width, height);
1212 QDBusArgument &operator<<(QDBusArgument &a, const QRect &rect)
1215 a << rect.x() << rect.y() << rect.width() << rect.height();
1221 const QDBusArgument &operator>>(const QDBusArgument &a, QRectF &rect)
1223 double x, y, width, height;
1225 a >> x >> y >> width >> height;
1228 rect.setRect(qreal(x), qreal(y), qreal(width), qreal(height));
1232 QDBusArgument &operator<<(QDBusArgument &a, const QRectF &rect)
1235 a << double(rect.x()) << double(rect.y()) << double(rect.width()) << double(rect.height());
1241 const QDBusArgument &operator>>(const QDBusArgument &a, QSize &size)
1244 a >> size.rwidth() >> size.rheight();
1250 QDBusArgument &operator<<(QDBusArgument &a, const QSize &size)
1253 a << size.width() << size.height();
1259 const QDBusArgument &operator>>(const QDBusArgument &a, QSizeF &size)
1261 double width, height;
1263 a >> width >> height;
1266 size.setWidth(qreal(width));
1267 size.setHeight(qreal(height));
1271 QDBusArgument &operator<<(QDBusArgument &a, const QSizeF &size)
1274 a << double(size.width()) << double(size.height());
1280 const QDBusArgument &operator>>(const QDBusArgument &a, QPoint &pt)
1283 a >> pt.rx() >> pt.ry();
1289 QDBusArgument &operator<<(QDBusArgument &a, const QPoint &pt)
1292 a << pt.x() << pt.y();
1298 const QDBusArgument &operator>>(const QDBusArgument &a, QPointF &pt)
1310 QDBusArgument &operator<<(QDBusArgument &a, const QPointF &pt)
1313 a << double(pt.x()) << double(pt.y());
1319 const QDBusArgument &operator>>(const QDBusArgument &a, QLine &line)
1326 line = QLine(p1, p2);
1330 QDBusArgument &operator<<(QDBusArgument &a, const QLine &line)
1333 a << line.p1() << line.p2();
1339 const QDBusArgument &operator>>(const QDBusArgument &a, QLineF &line)
1346 line = QLineF(p1, p2);
1350 QDBusArgument &operator<<(QDBusArgument &a, const QLineF &line)
1353 a << line.p1() << line.p2();
1362 #endif // QT_NO_DBUS