KPublicTransport

journeyrequest.h
1 /*
2  SPDX-FileCopyrightText: 2018 Volker Krause <[email protected]>
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 
22 class QDateTime;
23 
24 namespace KPublicTransport {
25 
26 class AbstractBackend;
27 class JourneyReply;
28 class JourneyRequestPrivate;
29 class Location;
30 class Manager;
31 class RequestContext;
32 
33 /** Describes a journey search.
34  * By default journeys departing now are searched.
35  */
36 class 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 setAccessModes)
70  /** Egress modes. */
71  Q_PROPERTY(QVariantList egressModes READ egressModesVariant WRITE setEgressModes)
72 
73 public:
74  enum DateTimeMode {
75  Arrival, ///< dateTime() represents the desired arriva time.
76  Departure ///< dateTime() represents the desired departure time.
77  };
78  Q_ENUM(DateTimeMode)
79  /** Controls whether to search for journeys starting or ending at the given time. */
80  KPUBLICTRANSPORT_PROPERTY(DateTimeMode, dateTimeMode, setDateTimeMode)
81 
82  Q_PROPERTY(QStringList backends READ backendIds WRITE setBackendIds)
83 
84  /** Download graphic assets such as line logos for the data requested here.
85  * Default: @c false
86  */
87  KPUBLICTRANSPORT_PROPERTY(bool, downloadAssets, setDownloadAssets)
88 
89 public:
90  /** Search a journey from @p from to @p to. */
91  JourneyRequest(const Location &from, const Location &to);
92 
93  /** Returns @c true if this is a valid request, that is, it has enough parameters set to perform a query. */
94  bool isValid() const;
95 
96  /** Set the desired departure time.
97  * This is mutually exclusive to setting a desired arrival time.
98  */
99  void setDepartureTime(const QDateTime &dt);
100  /** Sets the desired arrival time.
101  * This is mutually exclusive to setting a desired departure time.
102  */
103  void setArrivalTime(const QDateTime &dt);
104 
105  /** Identifiers of the backends that should be queried.
106  * @see setBackendIds()
107  */
108  QStringList backendIds() const;
109  /** Set identifiers of backends that should be queried.
110  * Settings this is only needed when you want explicit control over this, leaving
111  * this empty picks suitable backends automatically.
112  */
113  void setBackendIds(const QStringList &backendIds);
114 
115  /** Requested access modes.
116  * That is individual transport modes on the first (access) leg of the journey.
117  * Default: walking
118  */
119  const std::vector<IndividualTransport>& accessModes() const;
120  /** Sets the requested access modes. */
121  void setAccessModes(std::vector<IndividualTransport> &&accessModes);
122 
123  /** Requested egress modes.
124  * That is, individual transport modes for the last (egress) leg of the journey.
125  * Default: walking
126  */
127  const std::vector<IndividualTransport>& egressModes() const;
128  /** Sets the requested egress modes. */
129  void setEgressModes(std::vector<IndividualTransport> &&egressModes);
130 
131  /** Unique string representation used for caching results. */
132  QString cacheKey() const;
133 
134  ///@cond internal
135  static QJsonObject toJson(const JourneyRequest &req);
136  ///@endcond
137 private:
138  friend class AbstractBackend;
139  friend class JourneyReply;
140  friend class JourneyReplyPrivate;
141  friend class Manager;
142  friend class JourneyRequestTest;
143 
144  Q_DECL_HIDDEN QVariantList accessModesVariant() const;
145  Q_DECL_HIDDEN void setAccessModes(const QVariantList &accessModesVariant);
146  Q_DECL_HIDDEN QVariantList egressModesVariant() const;
147  Q_DECL_HIDDEN void setEgressModes(const QVariantList &egressModesVariant);
148 
149  Q_DECL_HIDDEN RequestContext context(const AbstractBackend *backend) const;
150  Q_DECL_HIDDEN const std::vector<RequestContext>& contexts() const;
151  Q_DECL_HIDDEN void setContext(const AbstractBackend *backend, RequestContext &&context);
152  Q_DECL_HIDDEN void purgeLoops(const JourneyRequest &baseRequest);
153 
154  /** Check that the given request parameters are semantically sane, and fix that if needed. */
155  void validate() const;
156 };
157 
158 }
159 
160 Q_DECLARE_METATYPE(KPublicTransport::JourneyRequest)
161 
162 #endif // KPUBLICTRANSPORT_JOURNEYREQUEST_H
Query operations and data types for accessing realtime public transport information from online servi...
Definition: attribution.cpp:16
Individual transport mode details for a journey section, and for specifying journey requests...
A segment of a journey plan.
Definition: journey.h:31
Journey query response.
Definition: journeyreply.h:21
Information about an arrival and/or departure of a vehicle at a stop area.
Definition: stopover.h:25
dateTime() represents the desired arriva time.
Describes a journey search.
Entry point for starting public transport queries.
Definition: manager.h:41
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Oct 23 2021 23:05:21 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.