| 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 | * 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 | */ |
|---|
| 32 | namespace KUrlMimeData |
|---|
| 33 | { |
|---|
| 34 | typedef 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 | */ |
|---|
| 44 | KCOREADDONS_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 | */ |
|---|
| 54 | KCOREADDONS_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 | */ |
|---|
| 60 | KCOREADDONS_EXPORT void setMetaData(const MetaDataMap &metaData, QMimeData *mimeData); |
|---|
| 61 | |
|---|
| 62 | /** |
|---|
| 63 | * Return the list of mimeTypes that can be decoded by urlsFromMimeData |
|---|
| 64 | */ |
|---|
| 65 | KCOREADDONS_EXPORT QStringList mimeDataTypes(); |
|---|
| 66 | |
|---|
| 67 | /** |
|---|
| 68 | * Flags to be used in urlsFromMimeData. |
|---|
| 69 | */ |
|---|
| 70 | enum 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 | }; |
|---|
| 86 | Q_DECLARE_FLAGS(DecodeOptions, DecodeOption) |
|---|
| 87 | Q_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 | */ |
|---|
| 107 | KCOREADDONS_EXPORT QList<QUrl> urlsFromMimeData(const QMimeData *mimeData, DecodeOptions decodeOptions = PreferKdeUrls, MetaDataMap *metaData = nullptr); |
|---|
| 108 | } |
|---|
| 109 | |
|---|
| 110 | #endif /* KURLMIMEDATA_H */ |
|---|
| 111 | |
|---|
