1/*
2 SPDX-FileCopyrightText: 2012 Vishesh Handa <me@vhanda.in>
3
4 SPDX-License-Identifier: LGPL-2.1-or-later
5*/
6
7
8#ifndef _KFILEMETADATA_EXTRACTOR_PLUGIN_H
9#define _KFILEMETADATA_EXTRACTOR_PLUGIN_H
10
11#include <QStringList>
12#include <QDateTime>
13
14#include "kfilemetadata_export.h"
15#include "extractionresult.h"
16
17namespace KFileMetaData
18{
19
20/*!
21 * \class KFileMetaData::ExtractorPlugin
22 * \inheaderfile KFileMetaData/ExtractorPlugin
23 * \inmodule KFileMetaData
24 *
25 * \brief The ExtractorPlugin is the base class for all file metadata
26 * extractors.
27 *
28 * It is responsible for extracting the metadata in a file.
29 *
30 * Plugins should derive from this class and implement the mimetypes()
31 * and extract() method.
32 *
33 * The plugin must also specify the implemented interface and provide
34 * sufficient metadata:
35 *
36 * \code
37 * class FooExtractor : public ExtractorPlugin
38 * {
39 * Q_OBJECT
40 * Q_PLUGIN_METADATA(IID kfilemetadata_extractor_iid
41 * FILE "fooextractor.json")
42 * Q_INTERFACES(KFileMetaData::ExtractorPlugin)
43 * ...
44 * };
45 * \endcode
46 * \badcode
47 * {
48 * "Name" : "FooExtractor",
49 * "Id" : "org.kde.fooextractor",
50 * "MimeTypes" : { "application/x-foo" : { "Version" : "0.0" } }
51 * }
52 * \endcode
53 *
54 */
55class KFILEMETADATA_EXPORT ExtractorPlugin : public QObject
56{
57 Q_OBJECT
58public:
59 /*!
60 *
61 */
62 explicit ExtractorPlugin(QObject* parent);
63 ~ExtractorPlugin() override;
64
65 /*!
66 * Provide a list of MIME types which are supported by this plugin.
67 * Only files with those MIME types will be provided to the plugin via
68 * the extract function.
69 *
70 * This can also contains partial MIME types like "text/", in that case
71 * this plugin will be chosen only if a better plugin does not exist.
72 *
73 * Returns a QStringList containing the MIME types.
74 * \sa extract
75 */
76 virtual QStringList mimetypes() const = 0;
77
78 /*!
79 * The main function of the plugin that is responsible for extracting
80 * the data and filling up the ExtractionResult
81 *
82 * The \a result provides the input URL and MIME type which
83 * can be used to identify the file.
84 *
85 * This function is synchronous and must be reentrant as it
86 * can be called by multiple threads.
87 */
88 virtual void extract(ExtractionResult* result) = 0;
89
90#if KFILEMETADATA_ENABLE_DEPRECATED_SINCE(6, 12)
91 //
92 // Helper functions
93 //
94
95 /*!
96 * Tries to extract a valid date time from the string provided.
97 * \deprecated[6.12]
98 */
99 static QDateTime dateTimeFromString(const QString& dateString);
100
101 /*!
102 * Tries to split the string into names. It cleans up any superfluous words
103 * and removes extra junk such as curly braces
104 * \deprecated[6.12]
105 */
106 static QStringList contactsFromString(const QString& string);
107#endif
108
109protected:
110 /*!
111 * Return the inherited MIME type which the extractor directly supports.
112 *
113 * The returned type is one of the types from mimetypes(),
114 * and is one of the ancestors of the input \a mimetype
115 * (including \a mimetype itself).
116 *
117 * In case the MIME type is not a subtype of the supported types,
118 * an empty QString() is returned.
119 *
120 * \sa ExtractorCollection::fetchExtractors
121 * \sa QMimeType::allAncestors
122 * \since 5.57
123 */
124 QString getSupportedMimeType(const QString& mimetype) const;
125
126private:
127 class ExtractorPluginPrivate;
128 ExtractorPluginPrivate *d_placeholder; // Placeholder for future binary compatible extensions
129};
130}
131
132#define kfilemetadata_extractor_iid "org.kde.kf5.kfilemetadata.ExtractorPlugin"
133Q_DECLARE_INTERFACE(KFileMetaData::ExtractorPlugin, kfilemetadata_extractor_iid)
134
135#endif // _KFILEMETADATA_EXTRACTOR_PLUGIN_H
136

source code of kfilemetadata/src/extractorplugin.h