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

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