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_CONNECTION_H_ 6 #define LIBBRILLO_BRILLO_HTTP_HTTP_CONNECTION_H_ 7 8 #include <memory> 9 #include <string> 10 #include <vector> 11 12 #include <base/callback_forward.h> 13 #include <base/macros.h> 14 #include <brillo/brillo_export.h> 15 #include <brillo/errors/error.h> 16 #include <brillo/http/http_transport.h> 17 #include <brillo/streams/stream.h> 18 19 namespace brillo { 20 namespace http { 21 22 class Response; 23 24 /////////////////////////////////////////////////////////////////////////////// 25 // Connection class is the base class for HTTP communication session. 26 // It abstracts the implementation of underlying transport library (ex libcurl). 27 // When the Connection-derived class is constructed, it is pre-set up with 28 // basic initialization information necessary to initiate the server request 29 // connection (such as the URL, request method, etc - see 30 // Transport::CreateConnection() for more details). But most implementations 31 // would not probably initiate the physical connection until SendHeaders 32 // is called. 33 // You normally shouldn't worry about using this class directly. 34 // http::Request and http::Response classes use it for communication. 35 // Effectively this class is the interface for the request/response objects to 36 // the transport-specific instance of the communication channel with the 37 // destination server. It is created by Transport as part of initiating 38 // the connection to the destination URI and is shared between the request and 39 // response object until all the data is sent to the server and the response 40 // is received. The class does NOT represent a persistent TCP connection though 41 // (e.g. in keep-alive scenarios). 42 /////////////////////////////////////////////////////////////////////////////// 43 class BRILLO_EXPORT Connection 44 : public std::enable_shared_from_this<Connection> { 45 public: Connection(const std::shared_ptr<Transport> & transport)46 explicit Connection(const std::shared_ptr<Transport>& transport) 47 : transport_(transport) {} 48 virtual ~Connection() = default; 49 50 // The following methods are used by http::Request object to initiate the 51 // communication with the server, send the request data and receive the 52 // response. 53 54 // Called by http::Request to initiate the connection with the server. 55 // This normally opens the socket and sends the request headers. 56 virtual bool SendHeaders(const HeaderList& headers, 57 brillo::ErrorPtr* error) = 0; 58 // If needed, this function can be called to send the request body data. 59 virtual bool SetRequestData(StreamPtr stream, brillo::ErrorPtr* error) = 0; 60 // If needed, this function can be called to customize where the response 61 // data is streamed to. 62 virtual void SetResponseData(StreamPtr stream) = 0; 63 // This function is called when all the data is sent off and it's time 64 // to receive the response data. The method will block until the whole 65 // response message is received, or if an error occur in which case the 66 // function will return false and fill the error details in |error| object. 67 virtual bool FinishRequest(brillo::ErrorPtr* error) = 0; 68 // Send the request asynchronously and invoke the callback with the response 69 // received. Returns the ID of the pending async request. 70 virtual RequestID FinishRequestAsync(const SuccessCallback& success_callback, 71 const ErrorCallback& error_callback) = 0; 72 73 // The following methods are used by http::Response object to obtain the 74 // response data. They are used only after the response data has been received 75 // since the http::Response object is not constructed until 76 // Request::GetResponse()/Request::GetResponseAndBlock() methods are called. 77 78 // Returns the HTTP status code (e.g. 200 for success). 79 virtual int GetResponseStatusCode() const = 0; 80 // Returns the status text (e.g. for error 403 it could be "NOT AUTHORIZED"). 81 virtual std::string GetResponseStatusText() const = 0; 82 // Returns the HTTP protocol version (e.g. "HTTP/1.1"). 83 virtual std::string GetProtocolVersion() const = 0; 84 // Returns the value of particular response header, or empty string if the 85 // headers wasn't received. 86 virtual std::string GetResponseHeader( 87 const std::string& header_name) const = 0; 88 // Returns the response data stream. This function can be called only once 89 // as it transfers ownership of the data stream to the caller. Subsequent 90 // calls will fail with "Stream closed" error. 91 // Returns empty stream on failure and fills in the error information in 92 // |error| object. 93 virtual StreamPtr ExtractDataStream(brillo::ErrorPtr* error) = 0; 94 95 protected: 96 // |transport_| is mainly used to keep the object alive as long as the 97 // connection exists. But some implementations of Connection could use 98 // the Transport-derived class for their own needs as well. 99 std::shared_ptr<Transport> transport_; 100 101 private: 102 DISALLOW_COPY_AND_ASSIGN(Connection); 103 }; 104 105 } // namespace http 106 } // namespace brillo 107 108 #endif // LIBBRILLO_BRILLO_HTTP_HTTP_CONNECTION_H_ 109