1 // Copyright 2014 The Chromium OS Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef LIBBRILLO_BRILLO_HTTP_HTTP_TRANSPORT_H_ 6 #define LIBBRILLO_BRILLO_HTTP_HTTP_TRANSPORT_H_ 7 8 #include <memory> 9 #include <string> 10 #include <utility> 11 #include <vector> 12 13 #include <base/callback_forward.h> 14 #include <base/location.h> 15 #include <base/macros.h> 16 #include <base/time/time.h> 17 #include <brillo/brillo_export.h> 18 #include <brillo/errors/error.h> 19 20 namespace brillo { 21 namespace http { 22 23 BRILLO_EXPORT extern const char kErrorDomain[]; 24 // Constant referring to 'direct' proxy which implies no proxy server. 25 BRILLO_EXPORT extern const char kDirectProxy[]; // direct:// 26 27 class Request; 28 class Response; 29 class Connection; 30 31 using RequestID = int; 32 33 using HeaderList = std::vector<std::pair<std::string, std::string>>; 34 using SuccessCallback = 35 base::Callback<void(RequestID, std::unique_ptr<Response>)>; 36 using ErrorCallback = base::Callback<void(RequestID, const brillo::Error*)>; 37 38 /////////////////////////////////////////////////////////////////////////////// 39 // Transport is a base class for specific implementation of HTTP communication. 40 // This class (and its underlying implementation) is used by http::Request and 41 // http::Response classes to provide HTTP functionality to the clients. 42 /////////////////////////////////////////////////////////////////////////////// 43 class BRILLO_EXPORT Transport : public std::enable_shared_from_this<Transport> { 44 public: 45 Transport() = default; 46 virtual ~Transport() = default; 47 48 // Creates a connection object and initializes it with the specified data. 49 // |transport| is a shared pointer to this transport object instance, 50 // used to maintain the object alive as long as the connection exists. 51 // The |url| here is the full URL specified in the request. It is passed 52 // to the underlying transport (e.g. CURL) to establish the connection. 53 virtual std::shared_ptr<Connection> CreateConnection( 54 const std::string& url, 55 const std::string& method, 56 const HeaderList& headers, 57 const std::string& user_agent, 58 const std::string& referer, 59 brillo::ErrorPtr* error) = 0; 60 61 // Runs |callback| on the task runner (message loop) associated with the 62 // transport. For transports that do not contain references to real message 63 // loops (e.g. a fake transport), calls the callback immediately. 64 virtual void RunCallbackAsync(const base::Location& from_here, 65 const base::Closure& callback) = 0; 66 67 // Initiates an asynchronous transfer on the given |connection|. 68 // The actual implementation of an async I/O is transport-specific. 69 // Returns a request ID which can be used to cancel the request. 70 virtual RequestID StartAsyncTransfer( 71 Connection* connection, 72 const SuccessCallback& success_callback, 73 const ErrorCallback& error_callback) = 0; 74 75 // Cancels a pending asynchronous request. This will cancel a pending request 76 // scheduled by the transport while the I/O operations are still in progress. 77 // As soon as all I/O completes for the request/response, or when an error 78 // occurs, the success/error callbacks are invoked and the request is 79 // considered complete and can no longer be canceled. 80 // Returns false if pending request with |request_id| is not found (e.g. it 81 // has already completed/its callbacks are dispatched). 82 virtual bool CancelRequest(RequestID request_id) = 0; 83 84 // Set the default timeout of requests made. 85 virtual void SetDefaultTimeout(base::TimeDelta timeout) = 0; 86 87 // Set the local IP address of requests 88 virtual void SetLocalIpAddress(const std::string& ip_address) = 0; 89 90 // Creates a default http::Transport (currently, using http::curl::Transport). 91 static std::shared_ptr<Transport> CreateDefault(); 92 93 // Creates a default http::Transport that will utilize the passed in proxy 94 // server (currently, using a http::curl::Transport). |proxy| should be of the 95 // form scheme://[user:pass@]host:port or may be the empty string or the 96 // string kDirectProxy (i.e. direct://) to indicate no proxy. 97 static std::shared_ptr<Transport> CreateDefaultWithProxy( 98 const std::string& proxy); 99 100 private: 101 DISALLOW_COPY_AND_ASSIGN(Transport); 102 }; 103 104 } // namespace http 105 } // namespace brillo 106 107 #endif // LIBBRILLO_BRILLO_HTTP_HTTP_TRANSPORT_H_ 108