zypp/zyppng/media/network/request.h

   1 #ifndef ZYPP_NG_MEDIA_CURL_REQUEST_H_INCLUDED
   2 #define ZYPP_NG_MEDIA_CURL_REQUEST_H_INCLUDED
   3
   4 #include <zypp/zyppng/media/network/networkrequesterror.h>
   5 #include <zypp/zyppng/media/network/TransferSettings>
   6 #include <zypp/zyppng/base/Base>
   7 #include <zypp/zyppng/core/Url>
   8 #include <zypp/zyppng/base/zyppglobal.h>
   9 #include <zypp/zyppng/base/signals.h>
  10 #include <zypp/base/Flags.h>
  11 #include <vector>
  12
  13 namespace zypp {
  14   class Digest;
  15
  16   namespace media {
  17     class AuthData;
  18   }
  19 }
  20
  21 namespace zyppng {
  22
  23   using AuthData = zypp::media::AuthData;
  24
  25   class NetworkRequestDispatcher;
  26   class NetworkRequestPrivate;
  27
  28   /*!
  29    * Represents a (http/https/ftp) request. This is the low level API for the
  30    * \sa zyppng::Downloader , usually it makes more sense to use the Downloader for the
  31    * more features it supports.
  32    * After creating a NetworkRequest and changing the required settings is enqueued
  33    * to the \sa zyppng::NetworkRequestDispatcher.
  34    */
  35   class LIBZYPP_NG_EXPORT NetworkRequest : public Base
  36   {
  37   public:
  38
  39     using Ptr = std::shared_ptr<NetworkRequest>;
  40     using WeakPtr = std::weak_ptr<NetworkRequest>;
  41
  42     enum State {
  43       Pending,    //< waiting to be dispatched
  44       Running,    //< currently running
  45       Finished,   //< finished successfully
  46       Error,      //< Error, use error function to figure out the issue
  47     };
  48
  49     enum Priority {
  50       Normal, //< Requests with normal priority will be enqueued at the end
  51       High    //< Request with high priority will be moved to the front of the queue
  52     };
  53
  54     enum FileMode {
  55       WriteExclusive, //< the request will create its own file, overwriting anything that already exists
  56       WriteShared     //< the request will create or open the file in shared mode and only write between \a start and \a len
  57     };
  58
  59     enum OptionBits {
  60       HeadRequest = 0x01 //< only request the header part of the file
  61     };
  62     ZYPP_DECLARE_FLAGS(Options, OptionBits);
  63
  64     /*!
  65      * \param url The source URL of the download
  66      * \param targetFile The path where the file should be stored
  67      * \param start File offset, if set this will create a range download request
  68      * \param len File range length
  69      * \param fMode The mode in which the file is opened in.
  70      */
  71     NetworkRequest( Url url, zypp::Pathname targetFile, off_t start = -1, off_t len = 0, FileMode fMode = WriteExclusive );
  72     virtual ~NetworkRequest();
  73
  74     /*!
  75      * Sets the priority of the NetworkRequest, this will affect where
  76      * the \sa NetworkRequestDispatcher puts the Request in the Queue.
  77      * \note changing this makes only sense before enqueueing the request
  78      */
  79     void setPriority ( Priority prio );
  80
  81     /*!
  82      * Returns the requested priority of the NetworkRequest
  83      */
  84     Priority priority ( ) const;
  85
  86     /*!
  87      * Change request options, currently only the \sa OptionBits::HeadRequest option is supported
  88      *
  89      * \note changing this makes only sense before the request was started
  90      */
  91     void setOptions ( Options opt );
  92
  93     /*!
  94      * Returns the currently set options
  95      */
  96     Options options () const;
  97
  98     /*!
  99      * Sets the range description
 100      * \note This will not change a running download
 101      * \param start
 102      * \param len
 103      */
 104     void setRequestRange ( off_t start = -1, off_t len = 0 );
 105
 106     /*!
 107      * Returns the last redirect information from the headers.
 108      */
 109     const std::string &lastRedirectInfo() const;
 110
 111     /*!
 112      * Returns a pointer to the native CURL easy handle
 113      *
 114      * \note consider adding the functionality here instead of using the Handle directly.
 115      *       In case we ever decide to switch out the CURL backend your code will break
 116      */
 117     void *nativeHandle () const;
 118
 119     /*!
 120      * Will return the data at \a offset with length \a count.
 121      * If there is not yet enough data a empty vector will be returned
 122      */
 123     std::vector<char> peekData ( off_t offset, size_t count ) const;
 124
 125     /*!
 126      * Returns the request URL
 127      */
 128     Url url () const;
 129
 130     /**
 131      * This will change the URL of the request.
 132      * \note calling this on a currently running request has no impact
 133      */
 134     void setUrl ( const Url & url );
 135
 136     /**
 137      * Returns the target filename path
 138      */
 139     const zypp::Pathname & targetFilePath () const;
 140
 141     /**
 142      * Returns the content type as reported from the server
 143      * \note can only return a valid value if the download has started already
 144      */
 145     std::string contentType () const;
 146
 147     /**
 148      * Returns the requested start offset
 149      */
 150     off_t downloadOffset () const;
 151
 152     /**
 153      * Returns the number of bytes that are reported from the backend as the full download size, those can
 154      * be 0 even when the download is already running.
 155      */
 156     off_t reportedByteCount   () const;
 157
 158     /**
 159      * Returns the expected byte count that was passed to the constructor, zero if
 160      * none was given
 161      */
 162     off_t expectedByteCount   () const;
 163
 164     /**
 165      * Returns the number of already downloaded bytes as reported by the backend
 166      */
 167     off_t downloadedByteCount () const;
 168
 169     /**
 170      * Set a \sa zypp::Digest that is updated when data is written, can be used to
 171      * validate the file contents with a checksum
 172      */
 173     void setDigest ( std::shared_ptr<zypp::Digest> dig );
 174
 175     /**
 176      * Returns the currently used \sa zypp::Digest, null if non was set.
 177      */
 178     std::shared_ptr<zypp::Digest> digest () const;
 179
 180     /**
 181      * Enables automated checking of downloaded contents against a checksum.
 182      * Only makes a difference if a \sa zypp::Digest was with with \sa setDigest.
 183      *
 184      * \note expects checksum in byte NOT in string format
 185      */
 186     void setExpectedChecksum (std::vector<unsigned char> checksum );
 187
 188
 189     /*!
 190      * Returns a writeable reference to the internal \sa zyppng::TransferSettings.
 191      * \note calling this on a already running request has no impact
 192      */
 193     TransferSettings &transferSettings ();
 194
 195     /**
 196      * Returns the current state the \a HttpDownloadRequest is in
 197      */
 198     State state () const;
 199
 200     /**
 201      * Returns the last set Error
 202      */
 203     const NetworkRequestError &error () const;
 204
 205     /**
 206      * In some cases curl can provide extended error informations collected at
 207      * runtime. In those cases its possible to query that information.
 208      */
 209     std::string extendedErrorString() const;
 210
 211     /**
 212      * Checks if there was a error with the request
 213      */
 214     bool hasError () const;
 215
 216     /*!
 217      * Adds a raw header to the request data. Use this to send custom headers
 218      * to the server.
 219      */
 220     bool addRequestHeader(const std::string &header );
 221
 222     /**
 223      * Signals that the dispatcher dequeued the request and actually starts downloading data
 224      */
 225     SignalProxy<void ( NetworkRequest &req )> sigStarted  ();
 226
 227     /**
 228      * Signals if there was data read from the download
 229      */
 230     SignalProxy<void ( NetworkRequest &req, off_t dltotal, off_t dlnow, off_t ultotal, off_t ulnow )> sigProgress ();
 231
 232     /**
 233      * Signals that the download finished.
 234      *
 235      * \note After this signal was emitted the Curl handle is reset,
 236      *       so all queries to it need to be done in a Slot connected to this signal
 237      */
 238     SignalProxy<void ( NetworkRequest &req, const NetworkRequestError &err)> sigFinished ( );
 239
 240   private:
 241     friend class NetworkRequestDispatcher;
 242     friend class NetworkRequestDispatcherPrivate;
 243     ZYPP_DECLARE_PRIVATE( NetworkRequest )
 244   };
 245
 246 }
 247 ZYPP_DECLARE_OPERATORS_FOR_FLAGS(zyppng::NetworkRequest::Options);
 248
 249 #endif