13bfff7be3
The user of the API can set whether redirects should be followed, and if so, how many. This is part of the BHttpRequest API. The BHttpSession then follows those instructions, and executes the maximum number of redirects the user would like to follow. As part of this commit, the BHttpStatusClass and BHttpStatusCodes helper enums have been added, to give a friendlier access to HTTP status codes and status classes. Change-Id: Ic8c9e3fda158e2cce549c8f1d360951f7ac83311
401 lines
11 KiB
Plaintext
401 lines
11 KiB
Plaintext
/*
|
|
* Copyright 2022 Haiku, Inc. All rights reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* Niels Sascha Reedijk, niels.reedijk@gmail.com
|
|
*
|
|
* Corresponds to:
|
|
* headers/private/netservices2/HttpResult.h hrev?????
|
|
* src/kits/network/libnetservices2/HttpResult.cpp hrev?????
|
|
*/
|
|
|
|
|
|
#if __cplusplus >= 201703L
|
|
|
|
|
|
/*!
|
|
\file HttpResult.h
|
|
\ingroup netservices
|
|
\brief Provides classes and tools to handle HTTP responses.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
namespace BPrivate {
|
|
|
|
namespace Network {
|
|
|
|
|
|
/*!
|
|
\enum BHttpStatusClass
|
|
\brief Category of the HTTP response status code.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\enum BHttpStatusCode
|
|
\brief Enumeration of standardized HTTP status codes.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\struct BHttpStatus
|
|
\ingroup netservices
|
|
\brief Represents the HTTP status code and status text of an incoming response.
|
|
|
|
The HTTP Standard specifies that each response should include a
|
|
<a href="https://datatracker.ietf.org/doc/html/rfc7230#section-3.1.2">three digit status
|
|
code</a> and a phrase that describes the status code. When processing the response status, you
|
|
should ignore the textual representation and only look at the status code.
|
|
|
|
Instances of this class provide a representation of the actual status information in the
|
|
response. There is no additional validation done, other than that the structure of the
|
|
status line is in compliance with the HTTP specification.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var int16 BHttpStatus::code
|
|
\brief The three digit status code
|
|
|
|
This code represents the result of how the server is processing or has processed a request.
|
|
Common codes are \c 200 indicating success, or \c 404 indicating that the requested resource is
|
|
not found.
|
|
|
|
See <a href="https://datatracker.ietf.org/doc/html/rfc7231#page-48">RFC7231 and its
|
|
references</a> for more information.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BString BHttpStatus::text
|
|
\brief A textual representation of the result status.
|
|
|
|
As defined in the
|
|
<a href="https://datatracker.ietf.org/doc/html/rfc7230#section-3.1.2">specification</a>, the
|
|
status text should only be taken as informative. Only the \ref BHttpStatus::code should be used
|
|
for further processing.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BHttpStatusClass BHttpStatus::StatusClass() const noexcept
|
|
\brief Map the \ref code value to a \ref BHttpStatusClass value
|
|
|
|
\return One of the valid values of \ref BHttpStatusClass, or \c BHttpStatusClass::Invalid if
|
|
the return code cannot be maped.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BHttpStatusCode BHttpStatus::StatusCode() const noexcept
|
|
\brief Map the \ref code value to a \ref BHttpStatusCode value
|
|
|
|
\return One of the valid values of \ref BHttpStatusCode, or \c BHttpStatusCode::Unknown if
|
|
the return code cannot be maped.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\struct BHttpBody
|
|
\ingroup netservices
|
|
\brief Represents a HTTP response body.
|
|
|
|
The HTTP response body is captured in this object. The body is either stored into a
|
|
\ref target, or into a \a text variable, depending on how you called the
|
|
\ref BHttpSession::Execute() method. If there is a \a target, the body will be empty,
|
|
and vice versa.
|
|
|
|
You will usually get a reference to this object through the \ref BHttpResult::Body() method.
|
|
If you want to keep the contents of the body beyond the lifetime of the BHttpResult object,
|
|
you should move the data into owned objects of your own.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var std::unique_ptr<BDataIO> BHttpBody::target
|
|
\brief An owned pointer to where the body has been written.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BString BHttpBody::text
|
|
\brief A string containing the body of the HTTP request.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\class BHttpResult
|
|
\ingroup netservices
|
|
\brief Unique object to wait for and access a HTTP response data.
|
|
|
|
Once you have scheduled a HTTP request in a HTTP session, you will get an object of this type
|
|
as a return value. This object allows you to track the progress of receiving the response, and
|
|
to inspect the status, the headers and the data as the response is received from the server.
|
|
|
|
The object is a future type, meaning that eventually it will contain the data or an error.
|
|
The \ref Status(), \ref Fields() and \ref Body() methods will yield the respective data. If it
|
|
is not yet received, they will block until it is available. You can also use the non-blocking
|
|
methods to check if data is available yet.
|
|
|
|
The result can either be a partial or completed HTTP Response, or an error. The partial aspect
|
|
is represented by the fact that the status line, the fields and the body are loaded
|
|
progressively and can be accessed as soon as they have been received. The meaning of a HTTP
|
|
response is defined by the HTTP standards. For example, a GET request can return a response
|
|
with a 200 status code, a set of headers and a body. But it can also return a 404 response,
|
|
indicating that the resource was not found at the location. It is important to note that both
|
|
responses are valid HTTP responses within the context of this API. This means that you can
|
|
still use the access methods of this class to access data from the 404 response without raising
|
|
an exception.
|
|
|
|
When there are errors during the request that lead to the situation where there is no valid
|
|
response according to the HTTP specification, then this object goes into an error state. This
|
|
means that the access methods of this object will throw an exception of the
|
|
\ref BNetworkRequestError type.
|
|
|
|
A special property of this object is that it is unique. This means it cannot be copied, only
|
|
moved. Objects that have moved from, are in an invalid state, and will always raise a
|
|
\ref BRuntimeError exception when they are used.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\name Constructors, assignment operators and destructor
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BHttpResult::BHttpResult(BHttpResult &&other) noexcept
|
|
\brief Move constructor.
|
|
|
|
\param other The object to move from. The \a other object will be in an invalid state and will
|
|
always throw exceptions when it is used.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BHttpResult::BHttpResult(const BHttpResult &other)=delete
|
|
\brief Copy constructor is disabled.
|
|
|
|
These objects cannot be copied.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BHttpResult& BHttpResult::operator=(BHttpResult &&other) noexcept
|
|
\brief Move operator.
|
|
|
|
\param other The object to move from. The \a other object will be in an invalid state and will
|
|
always throw exceptions when it is used.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BHttpResult& BHttpResult::operator=(const BHttpResult &other)=delete
|
|
\brief Copy assignment is disabled.
|
|
|
|
These objects cannot be copied.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BHttpResult::~BHttpResult()
|
|
\brief Destructor
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Non-blocking status functions
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn int32 BHttpResult::Identity() const
|
|
\brief Unique identifier for the response.
|
|
|
|
The identifier can be used to cancel requests in a BHttpSession. It can also be uses to check
|
|
incoming asynchronous event messages against the response.
|
|
|
|
\return A unique identifier that associates this response with an active or completed request.
|
|
|
|
\exception BRuntimeException This exception is raised when the object has been moved from and
|
|
is thus no longer valid.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BHttpResult::HasStatus() const
|
|
\brief Check if the status is available.
|
|
|
|
\retval true The status line of the response is available using the \ref Status() method.
|
|
\retval false The line is not yet available. Any call to \ref Status() will block.
|
|
|
|
\exception BRuntimeException This exception is raised when the object has been moved from and
|
|
is thus no longer valid.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BPrivate::Network::BHttpResult::HasFields() const
|
|
\brief Check if the header fields are available.
|
|
|
|
\retval true The header fields of the response is available using the \ref Fields() method.
|
|
\retval false They are not yet available. Any call to \ref Fields() will block.
|
|
|
|
\exception BRuntimeException This exception is raised when the object has been moved from and
|
|
is thus no longer valid.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BPrivate::Network::BHttpResult::HasBody() const
|
|
\brief Check if the body is available.
|
|
|
|
\retval true The body of the response is available using the \ref Body() method.
|
|
\retval false The body is not yet available. Any call to \ref Body() will block.
|
|
|
|
\exception BRuntimeException This exception is raised when the object has been moved from and
|
|
is thus no longer valid.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BPrivate::Network::BHttpResult::IsCompleted() const
|
|
\brief Check if the request is completed.
|
|
|
|
A request is completed when the status, headers and body have been received, or an error was
|
|
raised while receiving the data.
|
|
|
|
\exception BRuntimeException This exception is raised when the object has been moved from and
|
|
is thus no longer valid.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Blocking Data Access
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn const BHttpStatus& BHttpResult::Status() const
|
|
\brief Retrieve the status line of the HTTP response.
|
|
|
|
If the status line is not yet available, then this method call will block until it is. You can
|
|
use the \ref HasStatus() method to do a non-blocking check if the status is available.
|
|
|
|
\returns A const reference to the \ref BHttpStatus object that describes the status of the
|
|
response.
|
|
|
|
\exception BRuntimeException This exception is raised when the object has been moved from and
|
|
is thus no longer valid.
|
|
\exception BNetworkRequestError This exception is raised when there was an error that prevented
|
|
completely retrieving and parsing the HTTP response.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn const BHttpFields& BHttpResult::Fields() const
|
|
\brief Retrieve the header fields of the HTTP response.
|
|
|
|
If the header fields are not yet available, then this method call will block until it is. You
|
|
can use the \ref HasFields() method to do a non-blocking check if the fields are available.
|
|
|
|
\returns A const reference to the \ref BHttpFields object that describes the header fields of
|
|
the response.
|
|
|
|
\exception BRuntimeException This exception is raised when the object has been moved from and
|
|
is thus no longer valid.
|
|
\exception BNetworkRequestError This exception is raised when there was an error that prevented
|
|
completely retrieving and parsing the HTTP response.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BHttpBody& BHttpResult::Body() const
|
|
\brief Retrieve the body of the HTTP response.
|
|
|
|
If the body is not yet available, then this method call will block until it is. You can
|
|
use the \ref HasBody() method to do a non-blocking check if the status is available.
|
|
|
|
The lifetime of the body is tied to the lifetime of this response result object. If you want to
|
|
keep the body beyond that time, you can copy or move the data from the \ref BHttpBody object.
|
|
|
|
\returns A reference to the \ref BHttpBody object that contains the body.
|
|
|
|
\exception BRuntimeException This exception is raised when the object has been moved from and
|
|
is thus no longer valid.
|
|
\exception BNetworkRequestError This exception is raised when there was an error that prevented
|
|
completely retrieving and parsing the HTTP response.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
} // namespace BPrivate
|
|
|
|
} // namespace Network
|
|
|
|
#endif
|