1/* This file is part of the KDE libraries
2
3 Copyright (c) 2001,2002 Carsten Pfeiffer <pfeiffer@kde.org>
4 2007 Jos van den Oever <jos@vandenoever.info>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License (LGPL) as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21#ifndef KFILEMETAINFO_H
22#define KFILEMETAINFO_H
23
24#include "predicateproperties.h"
25#include "kfilemetainfoitem.h"
26#include <QtCore/QList>
27#include <QtCore/QStringList>
28class KUrl;
29
30typedef QList<KFileMetaInfoItem> KFileMetaInfoItemList;
31
32class KFileMetaInfoGroupPrivate;
33class KIO_EXPORT KFileMetaInfoGroup {
34public:
35 KFileMetaInfoGroup();
36 KFileMetaInfoGroup(const KFileMetaInfoGroup&);
37 ~KFileMetaInfoGroup();
38 const KFileMetaInfoGroup& operator=(const KFileMetaInfoGroup&);
39 KFileMetaInfoItemList items() const;
40 const QString& name() const;
41 const QStringList& keys() const;
42private:
43 QSharedDataPointer<KFileMetaInfoGroupPrivate> d;
44};
45
46typedef QList<KFileMetaInfoGroup> KFileMetaInfoGroupList;
47
48class KFileMetaInfoPrivate;
49/**
50 * KFileMetaInfo provides metadata extracted from a file or other resource.
51 *
52 * When instantiating an instance of this class, the metadata related to it
53 * will be retrieved and stored in the instance. The data can be inspected
54 * through KFileMetaInfoItem objects.
55 **/
56class KIO_EXPORT KFileMetaInfo {
57public:
58 /**
59 * This is used to specify what a KFileMetaInfo object should read, so
60 * you can specify if you want to read "expensive" items or not.
61 * This is like a preset which can be customized by passing additional
62 * parameters to constructors.
63 */
64 enum What
65 {
66 Fastest = 0x1, /**< do the fastest possible read and omit all items
67 that might need a significantly longer time
68 than the others */
69// Deprecated
70// DontCare = 0x2, ///< let the plugin decide what to read.
71
72 TechnicalInfo = 0x4, /**< extract technical details about the file, like
73 e.g. play time, resolution or a compressioni
74 type */
75 ContentInfo = 0x8, /**< read information about the content of the file
76 like comments or id3 tags */
77 ExternalSources = 0x10, /**<read external metadata sources such as
78 filesystem based extended attributes if
79 they are supported for the filesystem;
80 RDF storages etc */
81 Thumbnail = 0x20, /**< only read the file's thumbnail, if it contains
82 one */
83// Deprecated
84// Preferred = 0x40, ///< get at least the preferred items
85 LinkedData = 0x80, //< extract linked/related files like html links, source #include etc
86 Everything = 0xffff ///< read everything, even if it might take a while
87
88 };
89 Q_DECLARE_FLAGS(WhatFlags, What)
90
91 /**
92 * @brief Construct a KFileMetaInfo that contains metainformation about
93 * the resource pointed to by @p path.
94 *
95 * When w is not Everything, a limit of 64kbytes is imposed on the file size.
96 **/
97 explicit KFileMetaInfo(const QString& path, const QString& mimetype = QString(),
98 WhatFlags w = Everything);
99 /**
100 * @brief Construct a KFileMetaInfo that contains metainformation about
101 * the resource pointed to by @p url.
102 * @note that c'tor is not thread-safe
103 **/
104 KFileMetaInfo(const KUrl& url);
105 /**
106 * @brief Construct an empty, invalid KFileMetaInfo instance.
107 **/
108 KFileMetaInfo();
109 /**
110 * @brief Construct a KFileMetaInfo instance from another one.
111 **/
112 KFileMetaInfo(const KFileMetaInfo&);
113 /**
114 * @brief Destructor.
115 **/
116 ~KFileMetaInfo();
117 /**
118 * @brief Copy a KFileMetaInfo instance from another one.
119 **/
120 KFileMetaInfo& operator=(KFileMetaInfo const& kfmi);
121 /**
122 * @brief Save the changes made to this KFileMetaInfo instance.
123 */
124 bool applyChanges();
125 /**
126 * @brief Retrieve all the items.
127 **/
128 const QHash<QString, KFileMetaInfoItem>& items() const;
129 KFileMetaInfoItem& item(const QString& key);
130 const KFileMetaInfoItem& item(const QString& key) const;
131 bool isValid() const;
132 /**
133 * Deprecated
134 **/
135 QStringList preferredKeys() const;
136 /**
137 * Deprecated
138 **/
139 QStringList supportedKeys() const;
140 KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfo& )
141;
142 KIO_EXPORT friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfo&);
143 /**
144 * Deprecated
145 **/
146#ifndef KDE_NO_DEPRECATED
147 KDE_DEPRECATED KFileMetaInfoGroupList preferredGroups() const;
148#endif
149 /**
150 * Deprecated
151 **/
152#ifndef KDE_NO_DEPRECATED
153 KDE_DEPRECATED KFileMetaInfoGroupList supportedGroups() const;
154#endif
155 KFileMetaInfoGroupList groups() const;
156 QStringList keys() const;
157 const KUrl& url() const;
158
159private:
160 QSharedDataPointer<KFileMetaInfoPrivate> d;
161};
162
163Q_DECLARE_OPERATORS_FOR_FLAGS(KFileMetaInfo::WhatFlags)
164
165
166#endif
167