1/*
2 This file is part of the KDE libraries
3
4 SPDX-FileCopyrightText: 2005-2012 David Faure <[email protected]>
5 SPDX-FileCopyrightText: 2022 Harald Sitter <[email protected]>
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>
17QT_BEGIN_NAMESPACE
18class QMimeData;
19QT_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 */
37namespace KUrlMimeData
38{
39
40/*!
41 * \typedef KUrlMimeData::MetaDataMap
42 *
43 * Alias for QMap<QString, QString>
44 */
45typedef 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 */
55KCOREADDONS_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 */
69KCOREADDONS_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 */
75KCOREADDONS_EXPORT void setMetaData(const MetaDataMap &metaData, QMimeData *mimeData);
76
77/*!
78 * Return the list of mimeTypes that can be decoded by urlsFromMimeData
79 */
80KCOREADDONS_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 */
98enum DecodeOption {
99 PreferKdeUrls = 0,
100 PreferLocalUrls = 1,
101};
102Q_DECLARE_FLAGS(DecodeOptions, DecodeOption)
103Q_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 */
126KCOREADDONS_EXPORT QList<QUrl> urlsFromMimeData(const QMimeData *mimeData, DecodeOptions decodeOptions = PreferKdeUrls, MetaDataMap *metaData = nullptr);
127}
128
129#endif /* KURLMIMEDATA_H */
130

source code of kcoreaddons/src/lib/io/kurlmimedata.h