1/* 2 * Copyright 2022 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/HttpResult.h hrev????? 10 * src/kits/network/libnetservices2/HttpResult.cpp hrev????? 11 */ 12 13 14#if __cplusplus >= 201703L 15 16 17/*! 18 \file HttpResult.h 19 \ingroup netservices 20 \brief Provides classes and tools to handle HTTP responses. 21 22 \since Haiku R1 23*/ 24 25 26namespace BPrivate { 27 28namespace Network { 29 30 31/*! 32 \enum BHttpStatusClass 33 \brief Category of the HTTP response status code. 34*/ 35 36 37/*! 38 \enum BHttpStatusCode 39 \brief Enumeration of standardized HTTP status codes. 40*/ 41 42 43/*! 44 \struct BHttpStatus 45 \ingroup netservices 46 \brief Represents the HTTP status code and status text of an incoming response. 47 48 The HTTP Standard specifies that each response should include a 49 <a href="https://datatracker.ietf.org/doc/html/rfc7230#section-3.1.2">three digit status 50 code</a> and a phrase that describes the status code. When processing the response status, you 51 should ignore the textual representation and only look at the status code. 52 53 Instances of this class provide a representation of the actual status information in the 54 response. There is no additional validation done, other than that the structure of the 55 status line is in compliance with the HTTP specification. 56 57 \since Haiku R1 58*/ 59 60 61/*! 62 \var int16 BHttpStatus::code 63 \brief The three digit status code 64 65 This code represents the result of how the server is processing or has processed a request. 66 Common codes are \c 200 indicating success, or \c 404 indicating that the requested resource is 67 not found. 68 69 See <a href="https://datatracker.ietf.org/doc/html/rfc7231#page-48">RFC7231 and its 70 references</a> for more information. 71 72 \since Haiku R1 73*/ 74 75 76/*! 77 \var BString BHttpStatus::text 78 \brief A textual representation of the result status. 79 80 As defined in the 81 <a href="https://datatracker.ietf.org/doc/html/rfc7230#section-3.1.2">specification</a>, the 82 status text should only be taken as informative. Only the \ref BHttpStatus::code should be used 83 for further processing. 84 85 \since Haiku R1 86*/ 87 88 89/*! 90 \fn BHttpStatusClass BHttpStatus::StatusClass() const noexcept 91 \brief Map the \ref code value to a \ref BHttpStatusClass value 92 93 \return One of the valid values of \ref BHttpStatusClass, or \c BHttpStatusClass::Invalid if 94 the return code cannot be maped. 95 96 \since Haiku R1 97*/ 98 99 100/*! 101 \fn BHttpStatusCode BHttpStatus::StatusCode() const noexcept 102 \brief Map the \ref code value to a \ref BHttpStatusCode value 103 104 \return One of the valid values of \ref BHttpStatusCode, or \c BHttpStatusCode::Unknown if 105 the return code cannot be maped. 106 107 \since Haiku R1 108*/ 109 110 111/*! 112 \struct BHttpBody 113 \ingroup netservices 114 \brief Represents a HTTP response body. 115 116 The HTTP response body is captured in this object. The body is either stored into a 117 target, or into a \ref text variable, depending on how you called the 118 \ref BHttpSession::Execute() method. 119 120 You will usually get a reference to this object through the \ref BHttpResult::Body() method. 121 If you want to keep the contents of the body beyond the lifetime of the BHttpResult object, 122 you should move the data into owned objects of your own. 123 124 \since Haiku R1 125*/ 126 127 128/*! 129 \var std::optional<BString> BHttpBody::text 130 \brief A string containing the body of the HTTP request. 131 132 The value of this class variable is set to \c std::nullopt if the target body was written to 133 a specified target. Otherwise, the response body is stored in this string. If the response 134 body was empty, then this will be an empty string. 135 136 \since Haiku R1 137*/ 138 139 140/*! 141 \class BHttpResult 142 \ingroup netservices 143 \brief Unique object to wait for and access a HTTP response data. 144 145 Once you have scheduled a HTTP request in a HTTP session, you will get an object of this type 146 as a return value. This object allows you to track the progress of receiving the response, and 147 to inspect the status, the headers and the data as the response is received from the server. 148 149 The object is a future type, meaning that eventually it will contain the data or an error. 150 The \ref Status(), \ref Fields() and \ref Body() methods will yield the respective data. If it 151 is not yet received, they will block until it is available. You can also use the non-blocking 152 methods to check if data is available yet. 153 154 The result can either be a partial or completed HTTP Response, or an error. The partial aspect 155 is represented by the fact that the status line, the fields and the body are loaded 156 progressively and can be accessed as soon as they have been received. The meaning of a HTTP 157 response is defined by the HTTP standards. For example, a GET request can return a response 158 with a 200 status code, a set of headers and a body. But it can also return a 404 response, 159 indicating that the resource was not found at the location. It is important to note that both 160 responses are valid HTTP responses within the context of this API. This means that you can 161 still use the access methods of this class to access data from the 404 response without raising 162 an exception. 163 164 When there are errors during the request that lead to the situation where there is no valid 165 response according to the HTTP specification, then this object goes into an error state. This 166 means that the access methods of this object will throw an exception of the 167 \ref BNetworkRequestError type. 168 169 A special property of this object is that it is unique. This means it cannot be copied, only 170 moved. Objects that have moved from, are in an invalid state, and will always raise a 171 \ref BRuntimeError exception when they are used. 172 173 \since Haiku R1 174*/ 175 176 177/*! 178 \name Constructors, assignment operators and destructor 179*/ 180 181 182//! @{ 183 184 185/*! 186 \fn BHttpResult::BHttpResult(BHttpResult &&other) noexcept 187 \brief Move constructor. 188 189 \param other The object to move from. The \a other object will be in an invalid state and will 190 always throw exceptions when it is used. 191 192 \since Haiku R1 193*/ 194 195 196/*! 197 \fn BHttpResult::BHttpResult(const BHttpResult &other)=delete 198 \brief Copy constructor is disabled. 199 200 These objects cannot be copied. 201 202 \since Haiku R1 203*/ 204 205 206/*! 207 \fn BHttpResult& BHttpResult::operator=(BHttpResult &&other) noexcept 208 \brief Move operator. 209 210 \param other The object to move from. The \a other object will be in an invalid state and will 211 always throw exceptions when it is used. 212 213 \since Haiku R1 214*/ 215 216 217/*! 218 \fn BHttpResult& BHttpResult::operator=(const BHttpResult &other)=delete 219 \brief Copy assignment is disabled. 220 221 These objects cannot be copied. 222 223 \since Haiku R1 224*/ 225 226 227/*! 228 \fn BHttpResult::~BHttpResult() 229 \brief Destructor 230 231 \since Haiku R1 232*/ 233 234 235//! @} 236 237 238/*! 239 \name Non-blocking status functions 240*/ 241 242 243//! @{ 244 245 246/*! 247 \fn int32 BHttpResult::Identity() const 248 \brief Unique identifier for the response. 249 250 The identifier can be used to cancel requests in a BHttpSession. It can also be uses to check 251 incoming asynchronous event messages against the response. 252 253 \return A unique identifier that associates this response with an active or completed request. 254 255 \exception BRuntimeException This exception is raised when the object has been moved from and 256 is thus no longer valid. 257 258 \since Haiku R1 259*/ 260 261 262/*! 263 \fn bool BHttpResult::HasStatus() const 264 \brief Check if the status is available. 265 266 \retval true The status line of the response is available using the \ref Status() method. 267 \retval false The line is not yet available. Any call to \ref Status() will block. 268 269 \exception BRuntimeException This exception is raised when the object has been moved from and 270 is thus no longer valid. 271 272 \since Haiku R1 273*/ 274 275 276/*! 277 \fn bool BPrivate::Network::BHttpResult::HasFields() const 278 \brief Check if the header fields are available. 279 280 \retval true The header fields of the response is available using the \ref Fields() method. 281 \retval false They are not yet available. Any call to \ref Fields() will block. 282 283 \exception BRuntimeException This exception is raised when the object has been moved from and 284 is thus no longer valid. 285 286 \since Haiku R1 287*/ 288 289 290/*! 291 \fn bool BPrivate::Network::BHttpResult::HasBody() const 292 \brief Check if the body is available. 293 294 \retval true The body of the response is available using the \ref Body() method. 295 \retval false The body is not yet available. Any call to \ref Body() will block. 296 297 \exception BRuntimeException This exception is raised when the object has been moved from and 298 is thus no longer valid. 299 300 \since Haiku R1 301*/ 302 303 304/*! 305 \fn bool BPrivate::Network::BHttpResult::IsCompleted() const 306 \brief Check if the request is completed. 307 308 A request is completed when the status, headers and body have been received, or an error was 309 raised while receiving the data. 310 311 \exception BRuntimeException This exception is raised when the object has been moved from and 312 is thus no longer valid. 313 314 \since Haiku R1 315*/ 316 317 318//! @} 319 320 321/*! 322 \name Blocking Data Access 323*/ 324 325 326//! @{ 327 328 329/*! 330 \fn const BHttpStatus& BHttpResult::Status() const 331 \brief Retrieve the status line of the HTTP response. 332 333 If the status line is not yet available, then this method call will block until it is. You can 334 use the \ref HasStatus() method to do a non-blocking check if the status is available. 335 336 \returns A const reference to the \ref BHttpStatus object that describes the status of the 337 response. 338 339 \exception BRuntimeException This exception is raised when the object has been moved from and 340 is thus no longer valid. 341 \exception BNetworkRequestError This exception is raised when there was an error that prevented 342 completely retrieving and parsing the HTTP response. 343 344 \since Haiku R1 345*/ 346 347 348/*! 349 \fn const BHttpFields& BHttpResult::Fields() const 350 \brief Retrieve the header fields of the HTTP response. 351 352 If the header fields are not yet available, then this method call will block until it is. You 353 can use the \ref HasFields() method to do a non-blocking check if the fields are available. 354 355 \returns A const reference to the \ref BHttpFields object that describes the header fields of 356 the response. 357 358 \exception BRuntimeException This exception is raised when the object has been moved from and 359 is thus no longer valid. 360 \exception BNetworkRequestError This exception is raised when there was an error that prevented 361 completely retrieving and parsing the HTTP response. 362 363 \since Haiku R1 364*/ 365 366 367/*! 368 \fn BHttpBody& BHttpResult::Body() const 369 \brief Retrieve the body of the HTTP response. 370 371 If the body is not yet available, then this method call will block until it is. You can 372 use the \ref HasBody() method to do a non-blocking check if the status is available. 373 374 The lifetime of the body is tied to the lifetime of this response result object. If you want to 375 keep the body beyond that time, you can copy or move the data from the \ref BHttpBody object. 376 377 \returns A reference to the \ref BHttpBody object that contains the body. 378 379 \exception BRuntimeException This exception is raised when the object has been moved from and 380 is thus no longer valid. 381 \exception BNetworkRequestError This exception is raised when there was an error that prevented 382 completely retrieving and parsing the HTTP response. 383 384 \since Haiku R1 385*/ 386 387 388//! @} 389 390 391} // namespace BPrivate 392 393} // namespace Network 394 395#endif 396