Represent a HTTP request. More...

Classes
struct	Body
	Describe the body for a network request. More...

Public Member Functions
Constructors and Destructor
	BHttpRequest ()
	Construct an empty HTTP request.

	BHttpRequest (const BUrl &url)
	Construct a HTTP request for an url.

	BHttpRequest (const BHttpRequest &other)=delete
	Copying is not allowed.

	BHttpRequest (BHttpRequest &&other) noexcept
	Move constructor.

	~BHttpRequest ()
	Destructor.

Assignment operators
BHttpRequest &	operator= (const BHttpRequest &other)=delete
	Copy assignment is not allowed.

BHttpRequest &	operator= (BHttpRequest &&) noexcept
	Move assignment.

Valid or empty
bool	IsEmpty () const noexcept
	Check if the request is valid or empty.

Current Options
const BHttpAuthentication *	Authentication () const noexcept
	Get the credentials for the authentication for the request.

const BHttpFields &	Fields () const noexcept
	Get the additional header fields set for the request.

uint8	MaxRedirections () const noexcept
	Get the current redirection options for this request.

const BHttpMethod &	Method () const noexcept
	Get the current method for the request.

const Body *	RequestBody () const noexcept
	Get the details of the custom body set for the request.

bool	StopOnError () const noexcept
	Is the request set to parse the full response on error.

bigtime_t	Timeout () const noexcept
	Get the current timeout for the server to respond.

const BUrl &	Url () const noexcept
	Get the current Url for the request.

Setting Options
void	SetAuthentication (const BHttpAuthentication &authentication)
	Set the credentials to enable basic authentication for the request.

void	SetFields (const BHttpFields &fields)
	Set additional header fields for this request.

void	SetMaxRedirections (uint8 maxRedirections)
	Set the redirection options for this request.

void	SetMethod (const BHttpMethod &method)
	Set the method for this request.

void	SetRequestBody (std::unique_ptr< BDataIO > input, BString mimeType, std::optional< off_t > size)
	Set a body for this request.

void	SetStopOnError (bool stopOnError)
	Set whether the entire response will be parsed on a client or server error.

void	SetTimeout (bigtime_t timeout)
	Set the maximum time waiting for the server to respond.

void	SetUrl (const BUrl &url)
	Set the url for this request.

Clearing options
void	ClearAuthentication () noexcept
	Clear any authentication details previously set with SetAuthentication().

std::unique_ptr< BDataIO >	ClearRequestBody () noexcept
	Clear any request body previously set with SetRequestBody().

Serialization
BString	HeaderToString () const
	Serialize the HTTP Header of this request to a string.

Detailed Description

Represent a HTTP request.

This class can be used to construct HTTP requests that can be executed by the Network Services Kit. A request has two states, either it is is a valid request, or it is an empty request. The criterium is whether or not the request has a URL. This class has all kinds of convenience methods set and retrieve particular options. Most options are wrapped in specialized container classes that do some form of validation.

The default options are:

Getter	Setter	Description	Default
Url()	SetUrl()	The URL. This must start with http or https.	Defaults to an empty BUrl
Fields()	SetFields()	Additional fields set in the request header.	Defaults with no additional fields
Method()	SetMethod()	The HTTP method for the request	Defaults to BHttpMethod::Get
MaxRedirections()	SetMaxRedirections()	How many redirections should be followed. Set to 0 to disable.	Defaults to 8 redirections per request
RequestBody()	SetRequestBody()	Body contents that is sent with the request.	Defaults to an empty body
StopOnError()	SetStopOnError()	Stop parsing the server response when there is a client or server error.	Defaults to false
Timeout()	SetTimeout()	The timeout determines how long is waited for the server to respond	`B_INFINITE_TIMEOUT`

Since: Haiku R1

Constructor & Destructor Documentation

◆ BHttpRequest() [1/4]

BPrivate::Network::BHttpRequest::BHttpRequest ( )

Construct an empty HTTP request.

Exceptions

std::bad_alloc This exception may be raised if it is impossible to allocate memory.

Since: Haiku R1

◆ BHttpRequest() [2/4]

BPrivate::Network::BHttpRequest::BHttpRequest ( const BUrl & url )

Construct a HTTP request for an url.

Parameters

url	A valid URL with the `http` or `https` protocol.

Exceptions

std::bad_alloc	This exception may be raised if it is impossible to allocate memory.
BUnsupportedProtocol	This exception is raised when the protocol of the URL cannot be handled.
BInvalidUrl	This exception is raised when the url is invalid.

Since: Haiku R1

◆ BHttpRequest() [3/4]

BPrivate::Network::BHttpRequest::BHttpRequest ( const BHttpRequest & other )

delete

Copying is not allowed.

Since: Haiku R1

◆ BHttpRequest() [4/4]

BPrivate::Network::BHttpRequest::BHttpRequest ( BHttpRequest && other )

noexcept

Move constructor.

After a move, the other object is left in an empty state.

Parameters

other The request to move data from.

Since: Haiku R1

◆ ~BHttpRequest()

BPrivate::Network::BHttpRequest::~BHttpRequest ( )

Destructor.

Since: Haiku R1

Member Function Documentation

◆ Authentication()

const BHttpAuthentication * BPrivate::Network::BHttpRequest::Authentication ( ) const

noexcept

Get the credentials for the authentication for the request.

Returns: When no credentials are set for this request, the method returns a nullptr. Otherwise, it will return a pointer to the current BHttpAuthentication data set for this request.

Since: Haiku R1

◆ ClearAuthentication()

void BPrivate::Network::BHttpRequest::ClearAuthentication ( )

noexcept

Clear any authentication details previously set with SetAuthentication().

If there is no authentication data set, this method does nothing.

Since: Haiku R1

◆ ClearRequestBody()

std::unique_ptr< BDataIO > BPrivate::Network::BHttpRequest::ClearRequestBody ( )

noexcept

Clear any request body previously set with SetRequestBody().

Returns: Returns the previously set input BDataIO object. If there is no request body set, this method returns nullptr.

Since: Haiku R1

◆ Fields()

const BHttpFields & BPrivate::Network::BHttpRequest::Fields ( ) const

noexcept

Get the additional header fields set for the request.

The returned header fields may be empty if no additional header fields were set.

Since: Haiku R1

◆ HeaderToString()

BString BPrivate::Network::BHttpRequest::HeaderToString ( ) const

Serialize the HTTP Header of this request to a string.

The HTTP header consists of the request line, and the fields, serialized as text according to the HTTP specification.

This method can be used to debug requests.

Returns: A new string that represents the HTTP request.

Exceptions

std::bad_alloc In case it is not possible to allocate memory for the output string.

Since: Haiku R1

◆ IsEmpty()

bool BPrivate::Network::BHttpRequest::IsEmpty ( ) const

noexcept

Check if the request is valid or empty.

Return values

true	The request is empty.
false	The request is valid.

Since: Haiku R1

◆ MaxRedirections()

uint8 BPrivate::Network::BHttpRequest::MaxRedirections ( ) const

noexcept

Get the current redirection options for this request.

See also: BHttpRequest::SetMaxRedirections() for details on the options.

Since: Haiku R1

◆ Method()

const BHttpMethod & BPrivate::Network::BHttpRequest::Method ( ) const

noexcept

Get the current method for the request.

This will either return the custom value set for this request, or the default as is listed in the overview documentation of this class.

Since: Haiku R1

◆ operator=() [1/2]

BHttpRequest & BPrivate::Network::BHttpRequest::operator= ( BHttpRequest && other )

noexcept

Move assignment.

After a move, the other object is left in an empty state.

Parameters

other The request to move data from.

Since: Haiku R1

◆ operator=() [2/2]

BHttpRequest & BPrivate::Network::BHttpRequest::operator= ( const BHttpRequest & other )

delete

Copy assignment is not allowed.

Since: Haiku R1

◆ RequestBody()

const BHttpRequest::Body * BPrivate::Network::BHttpRequest::RequestBody ( ) const

noexcept

Get the details of the custom body set for the request.

Returns: When no body is set for this request, the method returns a nullptr. Otherwise, it will return a pointer to a struct that describes the current body.

Since: Haiku R1

◆ SetAuthentication()

void BPrivate::Network::BHttpRequest::SetAuthentication ( const BHttpAuthentication & authentication )

Set the credentials to enable basic authentication for the request.

The Basic authorization line is added to the request upon setting the request details. There is no support for other authentication schemes, like digest authentication.

Parameters

authentication The credentials to apply to the request.

Exceptions

std::bad_alloc This exception may be raised if it is impossible to allocate memory.

Since: Haiku R1

◆ SetFields()

void BPrivate::Network::BHttpRequest::SetFields ( const BHttpFields & fields )

Set additional header fields for this request.

There are a few reserved fields, which cannot be set as optional fields. These currently are: Host Accept-Encoding Connection Content-Type Content-Length

Parameters

fields Additional fields for the header of the request.

Exceptions

std::bad_alloc	This exception may be raised if it is impossible to allocate memory.
BHttpFields::InvalidData	This exception is raised when the fields contain reserved fields.

Since: Haiku R1

◆ SetMaxRedirections()

void BPrivate::Network::BHttpRequest::SetMaxRedirections ( uint8 maxRedirections )

Set the redirection options for this request.

The HTTP protocol allows the server to redirect requests if the resources have moved to a new location. For your convenience, you can instruct the network services kit to follow these redirections. You can set how many redirects should be followed. The maximum value is that of an unsigned 8 bit int, so maximum is 256 redirects. This prevents the request from staying stuck in a redirection loop.

If redirects are set to 0, or the maximum number of redirects have been processed, then the response will be set to the actual (last) received redirection response.

Parameters

maxRedirections The number of redirections to follow. Set to 0 to disable.

Exceptions

std::bad_alloc This exception may be raised if it is impossible to allocate memory.

Since: Haiku R1

◆ SetMethod()

void BPrivate::Network::BHttpRequest::SetMethod ( const BHttpMethod & method )

Set the method for this request.

Note that there currently is no additional validation done on any semantical incompatibilities. This means that it is currently allowed to do a GET or HEAD request with data, while that is forbidden by the standard.

Parameters

method The method to use for the request.

Exceptions

std::bad_alloc This exception may be raised if it is impossible to allocate memory.

Since: Haiku R1

◆ SetRequestBody()

void BPrivate::Network::BHttpRequest::SetRequestBody	(	std::unique_ptr< BDataIO >	input,
		BString	mimeType,
		std::optional< off_t >	size
	)

Set a body for this request.

When the requests needs a body, this method can be used to set the contents of that body.

Parameters

input	The input is an owned pointer to an input. The lifetime of the input is guaranteed up to the point that the request is sent for execution.
mimeType	A valid mimetype, with a class and a subtype. For example `text/plain` is a valid mime type.
size	When the content size is set, the request will have a `Content-Length` header field. If the input has less data in the buffer, this will cause the request to error out. However, if the input has more data, it is only read up to size. If the actual size of the data is unknown, this can be made optional. The request body will then be sent as a so-called chunked transfer, sending data until the input is at the end.

Exceptions

std::bad_alloc	This exception may be raised if it is impossible to allocate memory.
std::invalid_argument	This exception is raised when the mimeType is invalid or when input is a `nullptr`.

Since: Haiku R1

◆ SetStopOnError()

void BPrivate::Network::BHttpRequest::SetStopOnError ( bool stopOnError )

Set whether the entire response will be parsed on a client or server error.

When the server encounters an error processing a request, it may respond with an error code. Error responses can be either an error with the request, like the 404 Not Found error, or errors on the server side, like a 500 Internal Server Error. Error responses may still have header fields and bodies.

If your application is not interested in the rest of the response in case a client error or a server error occurs, you can set this option to stop parsing. This will allow you to use the BHttpResult object as normal, but the response fields will be empty, and there will be no body data.

Parameters

stopOnError Set to true to stop parsing the HTTP response when a client error or server error occurs.

Exceptions

std::bad_alloc This exception may be raised if it is impossible to allocate memory.

Since: Haiku R1

◆ SetTimeout()

void BPrivate::Network::BHttpRequest::SetTimeout ( bigtime_t timeout )

Set the maximum time waiting for the server to respond.

If the request times out, then the response will hold the BNetworkRequestError of the NetworkError type. By default, the request does not time out.

Parameters

timeout The timeout in milliseconds.

Exceptions

std::bad_alloc This exception may be raised if it is impossible to allocate memory.

Since: Haiku R1

◆ SetUrl()

void BPrivate::Network::BHttpRequest::SetUrl ( const BUrl & url )

Set the url for this request.

Parameters

url	A valid URL with the `http` or `https` protocol.

Exceptions

std::bad_alloc	This exception may be raised if it is impossible to allocate memory.
BUnsupportedProtocol	This exception is raised when the protocol of the URL cannot be handled.
BInvalidUrl	This exception is raised when the url is invalid.

Since: Haiku R1

◆ StopOnError()

bool BPrivate::Network::BHttpRequest::StopOnError ( ) const

noexcept

Is the request set to parse the full response on error.

Return values

true	When encountering a HTTP status of the client error class (4xx) or server error class (5xx), then the response will not be parsed.
false	The full response will be parsed, even with an error status code.

Since: Haiku R1

◆ Timeout()

bigtime_t BPrivate::Network::BHttpRequest::Timeout ( ) const

noexcept

Get the current timeout for the server to respond.

Since: Haiku R1

◆ Url()

const BUrl & BPrivate::Network::BHttpRequest::Url ( ) const

noexcept

Get the current Url for the request.

This will either return the custom value set for this request, or the default as is listed in the overview documentation of this class.

Since: Haiku R1

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BHttpRequest() [1/4]

◆ BHttpRequest() [2/4]

◆ BHttpRequest() [3/4]

◆ BHttpRequest() [4/4]

◆ ~BHttpRequest()

Member Function Documentation

◆ Authentication()

◆ ClearAuthentication()

◆ ClearRequestBody()

◆ Fields()

◆ HeaderToString()

◆ IsEmpty()

◆ MaxRedirections()

◆ Method()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ RequestBody()

◆ SetAuthentication()

◆ SetFields()

◆ SetMaxRedirections()

◆ SetMethod()

◆ SetRequestBody()

◆ SetStopOnError()

◆ SetTimeout()

◆ SetUrl()

◆ StopOnError()

◆ Timeout()

◆ Url()