File indexing completed on 2024-07-21 04:35:15

0001 /*
0002     SPDX-FileCopyrightText: 2004 Ace Jones acejones @users.sourceforge.net
0003     SPDX-FileCopyrightText: 2018 Ralf Habacker ralf.habacker @freenet.de
0004     SPDX-FileCopyrightText: 2020 Thomas Baumgart <tbaumgart@kde.org>
0005 
0006     This file is part of libalkimia.
0007 
0008     SPDX-License-Identifier: GPL-2.0-or-later
0009 */
0010 
0011 #ifndef ALKONLINEQUOTE_H
0012 #define ALKONLINEQUOTE_H
0013 
0014 #include <alkimia/alkvalue.h>
0015 
0016 #include <QObject>
0017 #include <QDateTime>
0018 #include <QString>
0019 #include <QMap>
0020 
0021 class AlkOnlineQuoteSource;
0022 class AlkOnlineQuotesProfile;
0023 
0024 typedef QMap<QDate, AlkValue> AlkDatePriceMap;
0025 
0026 /**
0027 Retrieves a price quote from a web-based quote source
0028 
0029 @author Ace Jones acejones @users.sourceforge.net
0030 */
0031 class ALK_EXPORT AlkOnlineQuote : public QObject
0032 {
0033     Q_OBJECT
0034 public:
0035     explicit AlkOnlineQuote(AlkOnlineQuotesProfile *profile = 0, QObject * = 0);
0036     ~AlkOnlineQuote();
0037 
0038     /**
0039      * Hold errors reported from price quote fetching and parsing
0040      *
0041      * The implementation provides a type safe way to use
0042      * bit operations like '|=' for combining values and '&'
0043      * for checking value presence.
0044      */
0045     class ALK_EXPORT Errors
0046     {
0047     public:
0048         enum Type {
0049             None,
0050             Data,
0051             Date,
0052             DateFormat,
0053             Price,
0054             Script,
0055             Source,
0056             Symbol,
0057             Success,
0058             Timeout,
0059             URL,
0060         };
0061 
0062         Errors();
0063         Errors(Type type);
0064         Errors& operator|=(Type t);
0065         bool operator &(Type t) const;
0066 
0067     protected:
0068         QList<Type> m_type;
0069     };
0070 
0071     AlkOnlineQuotesProfile *profile();
0072     void setProfile(AlkOnlineQuotesProfile *profile);
0073 
0074     /**
0075      * Set accepted language the online quote should be returned for
0076      *
0077      * @param language accepted language to set
0078      */
0079     void setAcceptLanguage(const QString &language);
0080 
0081     /**
0082      * Return actual used timeout for fetching online quotes
0083      * If the returned value is -1, no timeout has been set.
0084      * @return timeout
0085      */
0086     int timeout() const;
0087 
0088     /**
0089      * Set timeout for fetching online quotes
0090      * If the timeout is != -1, a request to retrieve online quotes will be aborted
0091      * if the time set with this function has been exceeded.
0092      * @param newTimeout timeout in millseconds
0093      */
0094     void setTimeout(int newTimeout);
0095 
0096     /**
0097      * Defines a date range within which the data is to be retrieved.
0098      * This range is only taken into account for data in CSV format and
0099      * provides online quotes via the `quotes` signal.
0100      * @param from first date to include the online quote
0101      * @param to last date to include the online quote
0102      */
0103     void setDateRange(const QDate &from, const QDate &to);
0104 
0105     /**
0106      * Always use signal `quote`.
0107      * For online sources in CSV data format (see AlkOnlineQuoteSource::DataFormat),
0108      * the quotes found are normally returned via the `quotes` signal,
0109      * which can be changed to the `quote` signal using this method.
0110      *
0111      * This means that sources in CSV format can be processed via the
0112      * same interface as other formats.
0113      * @param state Enable or disable use of the `quote` signal
0114      */
0115     void setUseSingleQuoteSignal(bool state);
0116 
0117     /**
0118      * Returns the status of whether the `quote` signal is always used
0119      * @return current state
0120      */
0121     bool useSingleQuoteSignal();
0122 
0123     const AlkOnlineQuoteSource &source() const;
0124 
0125 public Q_SLOTS:
0126     /**
0127       * This launches a web-based quote update for the given @p _symbol.
0128       * When the quote is received back from the web source, it will be
0129       * emitted on the 'quote' signal.
0130       *
0131       * If services do not provide a date, parsing of the date can be disabled
0132       * by specifying an empty date attribute of the given online source.
0133       *
0134       * If a timeout is set with @ref setTimeout() and the web source does not
0135       * return the requested data, the update will be aborted after this time.
0136       *
0137       * @param _symbol the trading symbol of the stock to fetch a price for
0138       * @param _id an arbitrary identifier, which will be emitted in the quote
0139       *                signal when a price is sent back.
0140       * @param _source the source of the quote (must be a valid value returned
0141       *                by quoteSources().  Send QString() to use the default
0142       *                source.
0143       * @return bool Whether the quote fetch process was launched successfully
0144       *              In case of failures it returns false and @ref errors()
0145       *              could be used to get error details.
0146       */
0147     bool launch(const QString &_symbol, const QString &_id, const QString &_source = QString());
0148 
0149     /**
0150       * If @ref launch() returns false, this method can be used to get details
0151       * about the errors that occurred.
0152       *
0153       * @return bit map of errors, see class @ref Errors for details
0154      */
0155     const AlkOnlineQuote::Errors &errors();
0156 
0157 Q_SIGNALS:
0158     void quote(QString id, QString symbol, QDate date, double price);
0159     void quotes(const QString &id, const QString &symbol, const AlkDatePriceMap &prices);
0160     void failed(QString id, QString symbol);
0161     void status(QString s);
0162     void error(QString s);
0163 
0164 private:
0165     class Private;
0166     Private *const d;
0167 
0168 protected:
0169     Private &d_ptr();
0170 
0171     friend class AlkOnlineQuotePrivateTest;
0172 };
0173 
0174 #endif // ALKONLINEQUOTE_H