File indexing completed on 2024-12-08 07:19:12

0001 /*
0002     SPDX-FileCopyrightText: 2018 Volker Krause <vkrause@kde.org>
0003 
0004     SPDX-License-Identifier: LGPL-2.0-or-later
0005 */
0006 
0007 #ifndef KPUBLICTRANSPORT_STOPOVERREQUEST_H
0008 #define KPUBLICTRANSPORT_STOPOVERREQUEST_H
0009 
0010 #include "kpublictransport_export.h"
0011 
0012 #include <KPublicTransport/Datatypes>
0013 #include <KPublicTransport/Line>
0014 
0015 #include <QMetaType>
0016 #include <QSharedDataPointer>
0017 
0018 #include <vector>
0019 
0020 class QDateTime;
0021 
0022 namespace KPublicTransport {
0023 
0024 class AbstractBackend;
0025 class Location;
0026 class RequestContext;
0027 class StopoverRequestPrivate;
0028 
0029 /** Describes an arrival or departure search.
0030  *  By default this search departures starting now, from the given Location.
0031  */
0032 class KPUBLICTRANSPORT_EXPORT StopoverRequest
0033 {
0034     KPUBLICTRANSPORT_GADGET(StopoverRequest)
0035 
0036     /** The location at which to search for departures/arrivals. */
0037     KPUBLICTRANSPORT_PROPERTY(KPublicTransport::Location, stop, setStop)
0038     /** Date/time at which the search should start.
0039      *  Default: now
0040      */
0041     KPUBLICTRANSPORT_PROPERTY(QDateTime, dateTime, setDateTime)
0042 
0043     /** Line modes. */
0044     Q_PROPERTY(QVariantList lineModes READ lineModesVariant WRITE setLineModesVariant)
0045 
0046 public:
0047     /** Query departures or arrivals? */
0048     enum Mode {
0049         QueryArrival, ///< Search for arrivals.
0050         QueryDeparture ///< Search for departures.
0051     };
0052     Q_ENUM(Mode)
0053 
0054     /** Controls whether to search for arrivals or departures.
0055      *  Default is QueryDeparture.
0056      */
0057     KPUBLICTRANSPORT_PROPERTY(Mode, mode, setMode)
0058 
0059     Q_PROPERTY(QStringList backends READ backendIds WRITE setBackendIds)
0060 
0061     /** Enable downloading of graphic assets such as line logos for the data requested here.
0062      *  Default: @c false
0063      */
0064     KPUBLICTRANSPORT_PROPERTY(bool, downloadAssets, setDownloadAssets)
0065 
0066     /** The maximum amount of expected results.
0067      *  @note This is only an optimization hint for backends, not a guarantee
0068      *  that all results comply with this constraint.
0069      */
0070     KPUBLICTRANSPORT_PROPERTY(int, maximumResults, setMaximumResults)
0071 
0072 public:
0073     /** Search for arrival/departures to/from @p stop. */
0074     explicit StopoverRequest(const Location &stop);
0075 
0076     /** Returns @c true if this is a valid request, ie. this is complete enough to perform a query. */
0077     bool isValid() const;
0078 
0079     /** Identifiers of the backends that should be queried.
0080      *  @see setBackendIds()
0081      */
0082     QStringList backendIds() const;
0083     /** Set identifiers of backends that should be queried.
0084      *  Settings this is only needed when you want explicit control over this, leaving
0085      *  this empty picks suitable backends automatically.
0086      */
0087     void setBackendIds(const QStringList &backendIds);
0088 
0089     /** Requested line modes.
0090      *  That is, the possible types of public transport lines to consider.
0091      *  Default: all
0092      */
0093     const std::vector<Line::Mode>& lineModes() const;
0094     /** Sets the requested line modes.
0095      *  An empty list is considered as all modes being allowed.
0096      *  @note This relies on backends actually supporting this and is thus does not
0097      *  provide any guarantee that the results wont contain other modes as well.
0098      */
0099     void setLineModes(std::vector <Line::Mode> &&modes);
0100 
0101     /** Unique string representation used for caching results. */
0102     QString cacheKey() const;
0103 
0104     ///@cond internal
0105     static QJsonObject toJson(const StopoverRequest &req);
0106     ///@endcond
0107 private:
0108     friend class AbstractBackend;
0109     friend class StopoverReply;
0110     friend class StopoverReplyPrivate;
0111     friend class Manager;
0112 
0113     Q_DECL_HIDDEN QVariantList lineModesVariant() const;
0114     Q_DECL_HIDDEN void setLineModesVariant(const QVariantList &modes);
0115 
0116     Q_DECL_HIDDEN RequestContext context(const AbstractBackend *backend) const;
0117     Q_DECL_HIDDEN const std::vector<RequestContext>& contexts() const;
0118     Q_DECL_HIDDEN void setContext(const AbstractBackend *backend, RequestContext &&context);
0119     Q_DECL_HIDDEN void purgeLoops(const StopoverRequest &baseRequest);
0120 };
0121 }
0122 
0123 Q_DECLARE_METATYPE(KPublicTransport::StopoverRequest)
0124 
0125 #endif // KPUBLICTRANSPORT_STOPOVERREQUEST_H