KItinerary

file.h
1/*
2 SPDX-FileCopyrightText: 2019 Volker Krause <vkrause@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "kitinerary_export.h"
10
11#include <QList>
12
13#include <memory>
14
15namespace KPkPass {
16class Pass;
17}
18
19class QIODevice;
20class QString;
21class QVariant;
22
23namespace KItinerary {
24
25class FilePrivate;
26
27/** A file containing a bundle of reservations and associated documents.
28 * This is used to export or transfer a set of reservation-related documents
29 * while keeping the associations between them.
30 *
31 * A KItinerary::File can contain the following elements:
32 * - JSON-LD reservation objects (see KItinerary::Reservation). Each reservation has a UUID.
33 * - PkPass files. Their identifier is determined by their pass type identifier and their serial number.
34 * - JSON-LD document objects (see KItinerary::CreativeWork) and their associated file content. Each document has a UUID.
35 * - Application-specific data in custom namespaces.
36 */
37class KITINERARY_EXPORT File
38{
39public:
40 explicit File();
41 /** Create a File instance for the file named @p fileName. */
42 explicit File(const QString &fileName);
43 /** Create a File instance for the given i/o device. */
44 explicit File(QIODevice *device);
45 File(const File&) = delete;
46 File(File&&) noexcept;
47 ~File();
48 File& operator=(const File&) = delete;
49 File& operator=(File&&) noexcept;
50
51 /** Sets the file name. Needs to be done before calling open(). */
52 void setFileName(const QString &fileName);
53
54 enum OpenMode { Read, Write };
55 /** Open the file for reading or writing. A filename needs to be set before calling this.
56 * All read/write operations require the file to be open as a precondition.
57 */
58 [[nodiscard]] bool open(OpenMode mode) const;
59 /** Error message in case opening the file failed. */
60 [[nodiscard]] QString errorString() const;
61 /** Save and close the file. Automatically called from the dtor. */
62 void close();
63
64 /** Lists the identifiers of all reservations in this file. */
65 [[nodiscard]] QList<QString> reservations() const;
66 /** Loads the reservation with the given identifier. */
67 [[nodiscard]] QVariant reservation(const QString &resId) const;
68 /** Add a reservation to this file. A new unique identifier will be generated for the reservation. */
69 void addReservation(const QVariant &res);
70 /** Add a reservation to this file. The given identifier will be used. */
71 void addReservation(const QString &id, const QVariant &res);
72
73 /** Returns the pass identifier used in here for @p pass. */
74 [[nodiscard]] static QString passId(const KPkPass::Pass *pass);
75 [[nodiscard]] static QString passId(const QString &passTypeIdenfier, const QString &serialNumber);
76 /** Decodes an identifier returned by passId() again. */
78 QString passTypeIdenfier;
79 QString serialNumber;
80 };
81 [[nodiscard]] static PkPassIdentifier decodePassId(QStringView);
82
83 /** Lists all pkpass files in this file. */
84 [[nodiscard]] QList<QString> passes() const;
85 /** Pass data for the given pass id. */
86 [[nodiscard]] QByteArray passData(const QString &passId) const;
87 /** Add a pkpass file to this file. */
88 void addPass(KPkPass::Pass *pass, const QByteArray &rawData);
89 /** Add a pkpass file with the given pass id. */
90 void addPass(const QString &passId, const QByteArray &rawData);
91
92 /** Makes sure the resulting file name is something that can safely be used without messing up the
93 * file system or archive structure.
94 */
95 [[nodiscard]] static QString normalizeDocumentFileName(const QString &name);
96
97 /** Lists all document identifiers. */
98 [[nodiscard]] QList<QString> documents() const;
99 /** Loads the document meta data of document @p id. */
100 [[nodiscard]] QVariant documentInfo(const QString &id) const;
101 /** Loads the content of document @p id. */
102 [[nodiscard]] QByteArray documentData(const QString &id) const;
103 /** Adds a document and associated meta data to the file. */
104 void addDocument(const QString &id, const QVariant &docInfo, const QByteArray &docData);
105
106 /** List custom data in the given namespace. */
107 [[nodiscard]] QList<QString> listCustomData(QStringView scope) const;
108 /** Returns @c true if custom data with the given id exists in @p scope. */
109 [[nodiscard]] bool hasCustomData(QStringView scope, const QString &id) const;
110 /** Returns the custom data in the given namespace and with the given id. */
111 [[nodiscard]] QByteArray customData(QStringView scope, const QString &id) const;
112 /** Adds a custom data element with identifier @p id in to namespace @p scope. */
113 void addCustomData(QStringView scope, const QString &id, const QByteArray &data);
114
115private:
116 std::unique_ptr<FilePrivate> d;
117};
118
119}
120
void addDocument(const QString &id, const QVariant &docInfo, const QByteArray &docData)
Adds a document and associated meta data to the file.
Definition file.cpp:322
QByteArray passData(const QString &passId) const
Pass data for the given pass id.
Definition file.cpp:211
static QString passId(const KPkPass::Pass *pass)
Returns the pass identifier used in here for pass.
Definition file.cpp:160
static QString normalizeDocumentFileName(const QString &name)
Makes sure the resulting file name is something that can safely be used without messing up the file s...
Definition file.cpp:304
QList< QString > reservations() const
Lists the identifiers of all reservations in this file.
Definition file.cpp:100
bool open(OpenMode mode) const
Open the file for reading or writing.
Definition file.cpp:68
QVariant reservation(const QString &resId) const
Loads the reservation with the given identifier.
Definition file.cpp:120
void addPass(KPkPass::Pass *pass, const QByteArray &rawData)
Add a pkpass file to this file.
Definition file.cpp:227
void addReservation(const QVariant &res)
Add a reservation to this file.
Definition file.cpp:149
QString errorString() const
Error message in case opening the file failed.
Definition file.cpp:84
bool hasCustomData(QStringView scope, const QString &id) const
Returns true if custom data with the given id exists in scope.
Definition file.cpp:357
void close()
Save and close the file.
Definition file.cpp:92
QByteArray customData(QStringView scope, const QString &id) const
Returns the custom data in the given namespace and with the given id.
Definition file.cpp:368
QVariant documentInfo(const QString &id) const
Loads the document meta data of document id.
Definition file.cpp:257
QList< QString > documents() const
Lists all document identifiers.
Definition file.cpp:238
QList< QString > passes() const
Lists all pkpass files in this file.
Definition file.cpp:184
void setFileName(const QString &fileName)
Sets the file name.
Definition file.cpp:63
QByteArray documentData(const QString &id) const
Loads the content of document id.
Definition file.cpp:286
QList< QString > listCustomData(QStringView scope) const
List custom data in the given namespace.
Definition file.cpp:342
void addCustomData(QStringView scope, const QString &id, const QByteArray &data)
Adds a custom data element with identifier id in to namespace scope.
Definition file.cpp:384
Classes for reservation/travel data models, data extraction and data augmentation.
Definition berelement.h:17
Decodes an identifier returned by passId() again.
Definition file.h:77
This file is part of the KDE documentation.
Documentation copyright © 1996-2025 The KDE developers.
Generated on Fri Jan 31 2025 12:00:18 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.