KPublicTransport

journeyrequest.h
1/*
2 SPDX-FileCopyrightText: 2018 Volker Krause <vkrause@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KPUBLICTRANSPORT_JOURNEYREQUEST_H
8#define KPUBLICTRANSPORT_JOURNEYREQUEST_H
9
10#include "kpublictransport_export.h"
11
12#include <KPublicTransport/Datatypes>
13#include <KPublicTransport/IndividualTransport>
14#include <KPublicTransport/Journey>
15
16#include <QMetaType>
17#include <QSharedDataPointer>
18#include <QVariant>
19
20#include <vector>
21
22class QDateTime;
23
24namespace KPublicTransport {
25
26class AbstractBackend;
27class JourneyReply;
28class JourneyRequestPrivate;
29class Location;
30class Manager;
31class RequestContext;
32
33/** Describes a journey search.
34 * By default journeys departing now are searched.
35 */
36class KPUBLICTRANSPORT_EXPORT JourneyRequest
37{
38 KPUBLICTRANSPORT_GADGET(JourneyRequest)
39
40 /** The starting point of the journey search. */
41 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Location, from, setFrom)
42 /** The journey destination. */
43 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Location, to, setTo)
44 /** Date/time at which the journey should start/end. */
45 KPUBLICTRANSPORT_PROPERTY(QDateTime, dateTime, setDateTime)
46
47 /** Modes of transportation that should be considered for this query.
48 * Only transit modes matter (public transport, rented vehicles, etc),
49 * values for tranfers/waits/etc are ignored.
50 */
51 KPUBLICTRANSPORT_PROPERTY(KPublicTransport::JourneySection::Modes, modes, setModes)
52 /** The maximum amount of expected results.
53 * @note This is only an optimization hint for backends, not a guarantee
54 * that all results comply with this constraint.
55 */
56 KPUBLICTRANSPORT_PROPERTY(int, maximumResults, setMaximumResults)
57 /** Retrieve intermediate stops for the queried journeys as well.
58 * @note This is only an optimization hint for backends, not a guarantee
59 * that all results will contain this information.
60 */
61 KPUBLICTRANSPORT_PROPERTY(bool, includeIntermediateStops, setIncludeIntermediateStops)
62 /** Retrieve path details for the journeys.
63 * @note This is only an optimization hint for backends, not a guarantee
64 * that all results will contain this information.
65 */
66 KPUBLICTRANSPORT_PROPERTY(bool, includePaths, setIncludePaths)
67
68 /** Access modes. */
69 Q_PROPERTY(QVariantList accessModes READ accessModesVariant WRITE setAccessModesVariant)
70 /** Egress modes. */
71 Q_PROPERTY(QVariantList egressModes READ egressModesVariant WRITE setEgressModesVariant)
72
73 /** Line modes. */
74 Q_PROPERTY(QVariantList lineModes READ lineModesVariant WRITE setLineModesVariant)
75
76 /** Individual transport modes for direct connections.
77 * Only considered when, modes contains JourneySection::IndividualTransport.
78 */
79 Q_PROPERTY(QVariantList individualTransportModes READ individualTransportModesVariant WRITE setIndividualTransportModesVariant)
80public:
82 Arrival, ///< dateTime() represents the desired arriva time.
83 Departure ///< dateTime() represents the desired departure time.
84 };
85 Q_ENUM(DateTimeMode)
86 /** Controls whether to search for journeys starting or ending at the given time. */
87 KPUBLICTRANSPORT_PROPERTY(DateTimeMode, dateTimeMode, setDateTimeMode)
88
89 Q_PROPERTY(QStringList backends READ backendIds WRITE setBackendIds)
90
91 /** Download graphic assets such as line logos for the data requested here.
92 * Default: @c false
93 */
94 KPUBLICTRANSPORT_PROPERTY(bool, downloadAssets, setDownloadAssets)
95
96public:
97 /** Search a journey from @p from to @p to. */
98 JourneyRequest(const Location &from, const Location &to);
99
100 /** Returns @c true if this is a valid request, that is, it has enough parameters set to perform a query. */
101 [[nodiscard]] bool isValid() const;
102
103 /** Set the desired departure time.
104 * This is mutually exclusive to setting a desired arrival time.
105 */
106 void setDepartureTime(const QDateTime &dt);
107 /** Sets the desired arrival time.
108 * This is mutually exclusive to setting a desired departure time.
109 */
110 void setArrivalTime(const QDateTime &dt);
111
112 /** Identifiers of the backends that should be queried.
113 * @see setBackendIds()
114 */
115 [[nodiscard]] QStringList backendIds() const;
116 /** Set identifiers of backends that should be queried.
117 * Settings this is only needed when you want explicit control over this, leaving
118 * this empty picks suitable backends automatically.
119 */
120 void setBackendIds(const QStringList &backendIds);
121
122 /** Requested access modes.
123 * That is individual transport modes on the first (access) leg of the journey.
124 * Default: walking
125 */
126 [[nodiscard]] const std::vector<IndividualTransport>& accessModes() const;
127 /** Sets the requested access modes. */
128 void setAccessModes(std::vector<IndividualTransport> &&accessModes);
129
130 /** Requested egress modes.
131 * That is, individual transport modes for the last (egress) leg of the journey.
132 * Default: walking
133 */
134 [[nodiscard]] const std::vector<IndividualTransport>& egressModes() const;
135 /** Sets the requested egress modes. */
136 void setEgressModes(std::vector<IndividualTransport> &&egressModes);
137
138 /** Returns @c true if the specified access/egress modes require bike
139 * transportation on public transport.
140 */
141 [[nodiscard]] bool requiresBikeTransport() const;
142
143 /** Requested line modes.
144 * That is, the possible types of public transport lines to consider for public
145 * transports sections of the journey.
146 * Default: all
147 */
148 [[nodiscard]] const std::vector<Line::Mode>& lineModes() const;
149 /** Sets the requested line modes.
150 * An empty list is considered as all modes being allowed.
151 * @note This relies on backends actually supporting this and is thus does not
152 * provide any guarantee that the results wont contain other modes as well.
153 */
154 void setLineModes(std::vector <Line::Mode> &&modes);
155
156 /** Requested individual transport modes.
157 * Individual transport modes for direct journeys.
158 */
159 [[nodiscard]] const std::vector<IndividualTransport>& individualTransportModes() const;
160 /** Sets individual transport modes considered for direct journeys. */
161 void setIndividualTransportModes(std::vector<IndividualTransport> &&modes);
162
163 /** Unique string representation used for caching results. */
164 [[nodiscard]] QString cacheKey() const;
165
166 ///@cond internal
167 [[nodiscard]] static QJsonObject toJson(const JourneyRequest &req);
168 ///@endcond
169private:
170 friend class AbstractBackend;
171 friend class JourneyReply;
172 friend class JourneyReplyPrivate;
173 friend class Manager;
174 friend class JourneyRequestTest;
175
176 [[nodiscard]] Q_DECL_HIDDEN QVariantList accessModesVariant() const;
177 Q_DECL_HIDDEN void setAccessModesVariant(const QVariantList &accessModesVariant);
178 [[nodiscard]] Q_DECL_HIDDEN QVariantList egressModesVariant() const;
179 Q_DECL_HIDDEN void setEgressModesVariant(const QVariantList &egressModesVariant);
180 [[nodiscard]] Q_DECL_HIDDEN QVariantList lineModesVariant() const;
181 Q_DECL_HIDDEN void setLineModesVariant(const QVariantList &modes);
182 [[nodiscard]] Q_DECL_HIDDEN QVariantList individualTransportModesVariant() const;
183 Q_DECL_HIDDEN void setIndividualTransportModesVariant(const QVariantList &modes);
184
185 [[nodiscard]] Q_DECL_HIDDEN RequestContext context(const AbstractBackend *backend) const;
186 [[nodiscard]] Q_DECL_HIDDEN const std::vector<RequestContext>& contexts() const;
187 Q_DECL_HIDDEN void setContext(const AbstractBackend *backend, RequestContext &&context);
188 Q_DECL_HIDDEN void purgeLoops(const JourneyRequest &baseRequest);
189
190 /** Check that the given request parameters are semantically sane, and fix that if needed. */
191 void validate() const;
192};
193
194}
195
196Q_DECLARE_METATYPE(KPublicTransport::JourneyRequest)
197
198#endif // KPUBLICTRANSPORT_JOURNEYREQUEST_H
Individual transport mode details for a journey section, and for specifying journey requests.
Journey query response.
Describes a journey search.
@ Arrival
dateTime() represents the desired arriva time.
A segment of a journey plan.
Definition journey.h:32
A public transport line.
Definition line.h:20
Entry point for starting public transport queries.
Definition manager.h:42
Query operations and data types for accessing realtime public transport information from online servi...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 29 2024 11:57:19 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.