1 | /* |
2 | This file is part of the KDE libraries |
3 | |
4 | SPDX-FileCopyrightText: 2005-2012 David Faure <faure@kde.org> |
5 | SPDX-FileCopyrightText: 2022 Harald Sitter <sitter@kde.org> |
6 | |
7 | SPDX-License-Identifier: LGPL-2.0-or-later |
8 | */ |
9 | |
10 | #ifndef KURLMIMEDATA_H |
11 | #define KURLMIMEDATA_H |
12 | |
13 | #include "kcoreaddons_export.h" |
14 | #include <QFlags> |
15 | #include <QMap> |
16 | #include <QUrl> |
17 | QT_BEGIN_NAMESPACE |
18 | class QMimeData; |
19 | QT_END_NAMESPACE |
20 | |
21 | /*! |
22 | * \namespace KUrlMimeData |
23 | * \inmodule KCoreAddons |
24 | * |
25 | * \brief Utility functions for using URLs in QMimeData. |
26 | * |
27 | * In addition to QMimeData::setUrls() and QMimeData::urls(), these functions allow to: |
28 | * \list |
29 | * \li Store two sets of URLs, the KDE-specific URLs and the equivalent local-file URLs |
30 | * for compatibility with non-KDE applications |
31 | * \li Store KIO metadata, such as the HTTP referrer for a given URL (some websites |
32 | * require it for downloading e.g. an image) |
33 | * \endlist |
34 | * |
35 | * \since 5.0 |
36 | */ |
37 | namespace KUrlMimeData |
38 | { |
39 | |
40 | /*! |
41 | * \typedef KUrlMimeData::MetaDataMap |
42 | * |
43 | * Alias for QMap<QString, QString> |
44 | */ |
45 | typedef QMap<QString, QString> MetaDataMap; |
46 | |
47 | /*! |
48 | * Adds URLs and KIO metadata into the given QMimeData. |
49 | * |
50 | * \warning do not call this method multiple times on the same mimedata object, |
51 | * you can add urls only once. But you can add other things, e.g. images, XML... |
52 | * |
53 | * \a mimeData the QMimeData instance used to drag or copy this URL |
54 | */ |
55 | KCOREADDONS_EXPORT void setUrls(const QList<QUrl> &urls, const QList<QUrl> &mostLocalUrls, QMimeData *mimeData); |
56 | |
57 | /*! |
58 | * Export URLs through the XDG Documents Portal to allow interaction from/with sandbox code. |
59 | * |
60 | * This implements the application/vnd.portal.filetransfer mimetype extension. |
61 | * |
62 | * When built without dbus support or the portal isn't installed on the target system, then this |
63 | * is no-op and returns false. |
64 | * |
65 | * Remote URLs are automatically mounted into the file system using kio-fuse |
66 | * |
67 | * Returns whether all URLS were exported through the portal |
68 | */ |
69 | KCOREADDONS_EXPORT bool exportUrlsToPortal(QMimeData *mimeData); |
70 | |
71 | /*! |
72 | * \a metaData KIO metadata shipped in the mime data, which is used for instance to |
73 | * set a correct HTTP referrer (some websites require it for downloading e.g. an image) |
74 | */ |
75 | KCOREADDONS_EXPORT void setMetaData(const MetaDataMap &metaData, QMimeData *mimeData); |
76 | |
77 | /*! |
78 | * Return the list of mimeTypes that can be decoded by urlsFromMimeData |
79 | */ |
80 | KCOREADDONS_EXPORT QStringList mimeDataTypes(); |
81 | |
82 | /*! |
83 | * Flags to be used in urlsFromMimeData. |
84 | * |
85 | * \value PreferKdeUrls |
86 | * When the mimedata contains both KDE-style URLs (eg: desktop:/foo) and |
87 | * the "most local" version of the URLs (eg: file:///home/dfaure/Desktop/foo), |
88 | * decode it as the KDE-style URL. Useful in DnD code e.g. when moving icons, |
89 | * and the kde-style url is used as identifier for the icons. |
90 | * |
91 | * \value PreferLocalUrls |
92 | * When the mimedata contains both KDE-style URLs (eg: desktop:/foo) and |
93 | * the "most local" version of the URLs (eg: file:///home/dfaure/Desktop/foo), |
94 | * decode it as local urls. Useful in paste/drop operations that end up calling KIO, |
95 | * so that urls from other users work as well. |
96 | * |
97 | */ |
98 | enum DecodeOption { |
99 | PreferKdeUrls = 0, |
100 | PreferLocalUrls = 1, |
101 | }; |
102 | Q_DECLARE_FLAGS(DecodeOptions, DecodeOption) |
103 | Q_DECLARE_OPERATORS_FOR_FLAGS(DecodeOptions) |
104 | |
105 | /*! |
106 | * Extract a list of urls from the contents of \a mimeData. |
107 | * |
108 | * Compared to QMimeData::urls(), this method has support for retrieving KDE-specific URLs |
109 | * when urls() would retrieve "most local URLs" instead as well as support for the XDG Documents Portal |
110 | * via the application/vnd.portal.filetransfer mimedata extension. |
111 | * |
112 | * Decoding will fail if \a mimeData does not contain any URLs, or if at |
113 | * least one extracted URL is not valid. |
114 | * |
115 | * When application/vnd.portal.filetransfer is set you'll only receive URLs retrieved from the XDG Documents Portal. |
116 | * When the portal is not available application/vnd.portal.filetransfer gets ignored. |
117 | * |
118 | * \a mimeData the mime data to extract from; cannot be 0 |
119 | * |
120 | * \a decodeOptions options for decoding |
121 | * |
122 | * \a metaData optional pointer to a map which will hold the metadata after this call |
123 | * |
124 | * Returns the list of urls |
125 | */ |
126 | KCOREADDONS_EXPORT QList<QUrl> urlsFromMimeData(const QMimeData *mimeData, DecodeOptions decodeOptions = PreferKdeUrls, MetaDataMap *metaData = nullptr); |
127 | } |
128 | |
129 | #endif /* KURLMIMEDATA_H */ |
130 | |