NetServices: Initial implementation of BHttpResult
Incomplete class, but will provide the basis to start working on the internals of the BHttpSession. Change-Id: I3ca14b7bd823fc1b4a5a32f5784592d214c4e9a7
This commit is contained in:
Niels Sascha Reedijk
@@ -0,0 +1,293 @@
|
||||
/*
|
||||
* Copyright 2022 Haiku, Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* Niels Sascha Reedijk, [email protected]
|
||||
*
|
||||
* 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 {
|
||||
|
||||
|
||||
/*!
|
||||
\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
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\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 BNetServiceError 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::HasHeaders() const
|
||||
\brief Check if the headers are available.
|
||||
|
||||
\retval true The headers of the response is available using the \ref Headers() method.
|
||||
\retval false They are not yet available. Any call to \ref Headers() 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 BNetServicesError 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
|
||||
|
||||
Reference in New Issue
Block a user