1/* 2 * Copyright 2021 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Niels Sascha Reedijk, niels.reedijk@gmail.com 7 * 8 * Corresponds to: 9 * headers/private/netservices2/HttpSession.h hrev????? 10 * src/kits/network/libnetservices2/HttpSession.cpp hrev????? 11 */ 12 13 14#if __cplusplus >= 201703L 15 16 17/*! 18 \file HttpSession.h 19 \ingroup netservices 20 \brief Provides classes and tools to schedule and execute HTTP requests. 21 22 \since Haiku R1 23*/ 24 25 26namespace BPrivate { 27 28namespace Network { 29 30 31/*! 32 \class BHttpSession 33 \ingroup netservices 34 \brief Schedule, execute and manage HTTP requests 35 36 All requests start from a `BHttpSession`. This class has the following jobs: 37 - Store data used between various HTTP calls 38 - Proxies 39 - Cookies 40 - Additional SSL certificates 41 - Authentication Data 42 - Manage the scheduling and execution of HTTP requests. 43 44 Objects of the `BHttpSession` class can be shared between different parts 45 of the application. They should be copied, rather than shared using 46 pointers. This is because they have an inner state that is shared between 47 the various objects. 48 49 \code 50 // Creating and sharing a session 51 auto session = BHttpSession(); 52 53 // A copy is passed to window1 and window2, which share the same session data 54 auto window1 = new WindowWithSession(session); 55 auto window2 = new WindowWithSession(session); 56 57 // Add a cookie to the session, this cookie will be used in window1 and window2 58 BNetworkCookie cookie("key", "value", BUrl("https://example.com/")); 59 session.AddCookie(std::move(cookie)); 60 61 // The session data persists, even if the original session goes out of scope 62 \endcode 63 64 There are specific scenarios for having more than one session, most notably 65 if an application provides services over HTTP whereby a user is identified 66 by cookies, and the application wants to support more than one user 67 account. But in most cases, there will be one instance of the BHttpSession 68 that is shared between various segments of the application. 69 70 \since Haiku R1 71*/ 72 73 74/*! 75 \fn BHttpSession::BHttpSession() 76 \brief Construct a new object. 77 78 Each newly constructed object will have their own queue for HTTP requests, 79 as well as their own cookies and certificate store. 80 81 \exception std::bad_alloc Unable to allocate resources for the object. 82 \exception BRuntimeError Unable to create semaphores or threads. 83 84 \since Haiku R1 85*/ 86 87 88/*! 89 \fn BHttpSession::BHttpSession(const BHttpSession&) noexcept 90 \brief Create a new BHttpSession object that shares a state with another. 91 92 The internal HTTP queue and context can be shared among multiple objects. 93 You can use the copy constructor to create a new object. 94 95 \since Haiku R1 96*/ 97 98 99/*! 100 \fn BHttpSession::BHttpSession(BHttpSession&&) noexcept 101 \brief Move is disabled. 102 103 BHttpSession objects cannot be moved. Because it has a shared internal 104 state, making copies is cheap and it is the only supported method of 105 creating multiple scoped objects with a shared lifetime. 106 107 \since Haiku R1 108*/ 109 110 111/*! 112 \fn BHttpSession::~BHttpSession() noexcept 113 \brief Destructor 114 115 The destructor releases the shared internal state of the session object. 116 If there are no more sessions using the shared state, the state is 117 cleaned up. 118 119 \since Haiku R1 120*/ 121 122 123/*! 124 \fn BHttpSession& BHttpSession::operator=(const BHttpSession&) noexcept 125 \brief Copy and use the shared state from another session. 126 127 The internal HTTP queue and context can be shared among multiple objects. 128 You can use the copy constructor to create a new copy. 129 130 This copy assignment operator should be used in very specific instances 131 only, where there is a particular reason to replace an existing session 132 internal session with another. It should not be used in the following case: 133 134 \code 135 // Bad example 136 BHttpSession session1 = BHttpSession(); 137 // Creates a new session, including an entirely new (expensive) state 138 BHttpSession session2 = BHttpSession(); 139 // Creates another new session, including internal state 140 session2 = session1; 141 // At this stage, the internal state of session2 would 142 // have to be cleaned up just after it was created. 143 144 // Instead do this 145 BHttpSession session1 = BHttpSession(); 146 BHttpSession session2(session1); 147 // Now session2 directly shares the state with session 1 148 \endcode 149 150 \since Haiku R1 151*/ 152 153 154/*! 155 \fn BHttpSession& BHttpSession::operator=(BHttpSession&&) noexcept 156 \brief Move is disabled. 157 158 BHttpSession objects cannot be moved. Because it has a shared internal 159 state, making copies is cheap and it is the only supported method of 160 creating multiple scoped objects with a shared lifetime. 161 162 \since Haiku R1 163*/ 164 165 166/*! 167 \fn BHttpResult BHttpSession::Execute(BHttpRequest &&request, 168 BBorrow< BDataIO > target=nullptr, BMessenger observer=BMessenger()) 169 \brief Schedule and execute a \a request. 170 171 \param request The (valid) request to move from. 172 \param target An optional data buffer to write the incoming body of the request to. This can be 173 \c nullptr if you want to use the default internal storage. If you provide a buffer, it 174 must be wrapped in a \ref BBorrow object. This means that you exclusively borrow the 175 target to this session object. After the request is finished, you can regain usage of the 176 object through the matching \ref BExclusiveBorrow object. Use the \ref BHttpResult::Body() 177 method to synchronize when the target is available again. 178 \param observer An optional observer that will receive the progress and status messages for 179 this request. 180 181 \return The \ref BHttpResult object that corresponds to this request, and that can be used to 182 monitor the progress. 183 184 \since Haiku R1 185*/ 186 187 188/*! 189 \fn void BHttpSession::Cancel(int32 identifier) 190 \brief Cancel a running request. 191 192 When a request that is scheduled or running is cancelled, its \ref BHttpResult object will 193 be set to the \ref BNetworkRequestError exception with the \c Cancelled type. 194 195 There are three possible outcomes: 196 1. If the request is not yet scheduled, then it will never start. The result will be set to 197 the cancelled error state. 198 2. If the request was started, then processing it will be terminated. The result will be set to 199 the cancelled error state. 200 3. If the request was already finished, then nothing happens. The result will keep the value it 201 had assigned. The same if the request identifier is invalid. 202 203 \param identifier The identifier for the request to cancel. 204 205 \exception std::bad_alloc Error in case memory cannot be allocated. 206 207 \since Haiku R1 208*/ 209 210 211/*! 212 \fn void BHttpSession::Cancel(const BHttpResult& request) 213 \brief Cancel a running \a request. 214 215 See the \ref BHttpSession::Cancel(int32 identifier) method for more details on how this method 216 works. 217 218 \exception std::bad_alloc Error in case memory cannot be allocated. 219 220 \since Haiku R1 221*/ 222 223 224/*! 225 \fn void BHttpSession::SetMaxConnectionsPerHost(size_t maxConnections) 226 \brief Set the maximum number of connections per host. 227 228 A host is identified by the domain name and the port. You can limit the number of concurrent 229 connections to a host by tweaking this value. 230 231 The default value is 2 connections per host. 232 233 If the value is decreased, any requests that already started will not be affected. The new 234 value will only be applied when any new requests are added. 235 236 \param maxConnections The maximum number of connections per host. This value must between 1 237 and \c INT32_MAX. 238 239 \exception BRuntimeError In case the \a maxConnections is invalid. 240 241 \since Haiku R1 242*/ 243 244 245/*! 246 \fn void BPrivate::Network::BHttpSession::SetMaxHosts(size_t maxConnections) 247 \brief Set the maximum number of concurrent hosts that can be connected to. 248 249 A host is identified by the domain name and the port. You can limit the number of concurrent 250 hosts by tweaking this value. 251 252 The default value is 10 concurrent hosts. 253 254 If the value is decreased, any requests that already started will not be affected. The new 255 value will only be applied when any new requests are added. 256 257 \param maxConnections The maximum number of hosts. The value must be at least 1. 258 259 \exception BRuntimeError In case the \a maxConnections is 0. 260 261 \since Haiku R1 262*/ 263 264 265/*! 266 \var UrlEvent::HttpStatus 267 \brief The HTTP status code has been received, and can be accessed through the result object. 268 269 \since Haiku R1 270*/ 271 272 273/*! 274 \var UrlEvent::HttpFields 275 \brief The HTTP header block has been received, and the status and fields can be accessed 276 through the result object. 277 278 \since Haiku R1 279*/ 280 281 282/*! 283 \var UrlEvent::CertificateError 284 \brief There was an error communicating with the server because of an SSL certificate issue. 285 286 \since Haiku R1 287*/ 288 289 290/*! 291 \var UrlEvent::HttpRedirect 292 \brief The Http request was redirected, and this redirect was handled by the kit. 293 294 \since Haiku R1 295*/ 296 297 298/*! 299 \var const char* UrlEventData::HttpStatusCode 300 \brief An \c int16 value that contains the HTTP status code for this request. 301 302 \since Haiku R1 303*/ 304 305 306/*! 307 \var const char* UrlEventData::SSLCertificate 308 \brief The SSL certificate that causes the issue. 309 310 \since Haiku R1 311*/ 312 313 314/*! 315 \var const char* UrlEventData::SSLMessage 316 \brief A \ref BString message about the error while processing the SSL certificate. 317 318 \since Haiku R1 319*/ 320 321 322/*! 323 \var const char* UrlEventData::HttpRedirectUrl 324 \brief A \ref BString with the URL that the HTTP request was redirected to. 325 326 \since Haiku R1 327*/ 328 329 330} // namespace Network 331 332} // namespace BPrivate 333 334#endif 335