haiku/docs/user/netservices/HttpResult.dox

/*
 * 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 {


/*!
	\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