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 
25 class Request;
26 class Response;
27 class Connection;
28 
29 using RequestID = int;
30 
31 using HeaderList = std::vector<std::pair<std::string, std::string>>;
32 using SuccessCallback =
33     base::Callback<void(RequestID, std::unique_ptr<Response>)>;
34 using ErrorCallback = base::Callback<void(RequestID, const brillo::Error*)>;
35 
36 ///////////////////////////////////////////////////////////////////////////////
37 // Transport is a base class for specific implementation of HTTP communication.
38 // This class (and its underlying implementation) is used by http::Request and
39 // http::Response classes to provide HTTP functionality to the clients.
40 ///////////////////////////////////////////////////////////////////////////////
41 class BRILLO_EXPORT Transport : public std::enable_shared_from_this<Transport> {
42  public:
43   Transport() = default;
44   virtual ~Transport() = default;
45 
46   // Creates a connection object and initializes it with the specified data.
47   // |transport| is a shared pointer to this transport object instance,
48   // used to maintain the object alive as long as the connection exists.
49   // The |url| here is the full URL specified in the request. It is passed
50   // to the underlying transport (e.g. CURL) to establish the connection.
51   virtual std::shared_ptr<Connection> CreateConnection(
52       const std::string& url,
53       const std::string& method,
54       const HeaderList& headers,
55       const std::string& user_agent,
56       const std::string& referer,
57       brillo::ErrorPtr* error) = 0;
58 
59   // Runs |callback| on the task runner (message loop) associated with the
60   // transport. For transports that do not contain references to real message
61   // loops (e.g. a fake transport), calls the callback immediately.
62   virtual void RunCallbackAsync(const tracked_objects::Location& from_here,
63                                 const base::Closure& callback) = 0;
64 
65   // Initiates an asynchronous transfer on the given |connection|.
66   // The actual implementation of an async I/O is transport-specific.
67   // Returns a request ID which can be used to cancel the request.
68   virtual RequestID StartAsyncTransfer(
69       Connection* connection,
70       const SuccessCallback& success_callback,
71       const ErrorCallback& error_callback) = 0;
72 
73   // Cancels a pending asynchronous request. This will cancel a pending request
74   // scheduled by the transport while the I/O operations are still in progress.
75   // As soon as all I/O completes for the request/response, or when an error
76   // occurs, the success/error callbacks are invoked and the request is
77   // considered complete and can no longer be canceled.
78   // Returns false if pending request with |request_id| is not found (e.g. it
79   // has already completed/its callbacks are dispatched).
80   virtual bool CancelRequest(RequestID request_id) = 0;
81 
82   // Set the default timeout of requests made.
83   virtual void SetDefaultTimeout(base::TimeDelta timeout) = 0;
84 
85   // Creates a default http::Transport (currently, using http::curl::Transport).
86   static std::shared_ptr<Transport> CreateDefault();
87 
88  private:
89   DISALLOW_COPY_AND_ASSIGN(Transport);
90 };
91 
92 }  // namespace http
93 }  // namespace brillo
94 
95 #endif  // LIBBRILLO_BRILLO_HTTP_HTTP_TRANSPORT_H_
96