Classes | List of all members
BPrivate::Network::BHttpRequest Class Reference

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. More...
 
 BHttpRequest (const BUrl &url)
 Construct a HTTP request for an url. More...
 
 BHttpRequest (const BHttpRequest &other)=delete
 Copying is not allowed. More...
 
 BHttpRequest (BHttpRequest &&other) noexcept
 Move constructor. More...
 
 ~BHttpRequest ()
 Destructor. More...
 
Assignment operators
BHttpRequestoperator= (const BHttpRequest &other)=delete
 Copy assignment is not allowed. More...
 
BHttpRequestoperator= (BHttpRequest &&) noexcept
 Move assignment. More...
 
Valid or empty
bool IsEmpty () const noexcept
 Check if the request is valid or empty. More...
 
Current Options
const BHttpAuthenticationAuthentication () const noexcept
 Get the credentials for the authentication for the request. More...
 
const BHttpFieldsFields () const noexcept
 Get the additional header fields set for the request. More...
 
uint8 MaxRedirections () const noexcept
 Get the current redirection options for this request. More...
 
const BHttpMethodMethod () const noexcept
 Get the current method for the request. More...
 
const BodyRequestBody () const noexcept
 Get the details of the custom body set for the request. More...
 
bool StopOnError () const noexcept
 Is the request set to parse the full response on error. More...
 
bigtime_t Timeout () const noexcept
 Get the current timeout for the server to respond. More...
 
const BUrlUrl () const noexcept
 Get the current Url for the request. More...
 
Setting Options
void SetAuthentication (const BHttpAuthentication &authentication)
 Set the credentials to enable basic authentication for the request. More...
 
void SetFields (const BHttpFields &fields)
 Set additional header fields for this request. More...
 
void SetMaxRedirections (uint8 maxRedirections)
 Set the redirection options for this request. More...
 
void SetMethod (const BHttpMethod &method)
 Set the method for this request. More...
 
void SetRequestBody (std::unique_ptr< BDataIO > input, BString mimeType, std::optional< off_t > size)
 Set a body for this request. More...
 
void SetStopOnError (bool stopOnError)
 Set whether the entire response will be parsed on a client or server error. More...
 
void SetTimeout (bigtime_t timeout)
 Set the maximum time waiting for the server to respond. More...
 
void SetUrl (const BUrl &url)
 Set the url for this request. More...
 
Clearing options
void ClearAuthentication () noexcept
 Clear any authentication details previously set with SetAuthentication(). More...
 
std::unique_ptr< BDataIOClearRequestBody () noexcept
 Clear any request body previously set with SetRequestBody(). More...
 
Serialization
BString HeaderToString () const
 Serialize the HTTP Header of this request to a string. More...
 

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:

GetterSetterDescriptionDefault
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_allocThis 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
urlA valid URL with the http or https protocol.
Exceptions
std::bad_allocThis exception may be raised if it is impossible to allocate memory.
BUnsupportedProtocolThis exception is raised when the protocol of the URL cannot be handled.
BInvalidUrlThis 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
otherThe 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_allocIn 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
trueThe request is empty.
falseThe 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
otherThe 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
authenticationThe credentials to apply to the request.
Exceptions
std::bad_allocThis 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
fieldsAdditional fields for the header of the request.
Exceptions
std::bad_allocThis exception may be raised if it is impossible to allocate memory.
BHttpFields::InvalidDataThis 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
maxRedirectionsThe number of redirections to follow. Set to 0 to disable.
Exceptions
std::bad_allocThis 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
methodThe method to use for the request.
Exceptions
std::bad_allocThis 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
inputThe 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.
mimeTypeA valid mimetype, with a class and a subtype. For example text/plain is a valid mime type.
sizeWhen 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_allocThis exception may be raised if it is impossible to allocate memory.
std::invalid_argumentThis 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
stopOnErrorSet to true to stop parsing the HTTP response when a client error or server error occurs.
Exceptions
std::bad_allocThis 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
timeoutThe timeout in milliseconds.
Exceptions
std::bad_allocThis 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
urlA valid URL with the http or https protocol.
Exceptions
std::bad_allocThis exception may be raised if it is impossible to allocate memory.
BUnsupportedProtocolThis exception is raised when the protocol of the URL cannot be handled.
BInvalidUrlThis 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
trueWhen encountering a HTTP status of the client error class (4xx) or server error class (5xx), then the response will not be parsed.
falseThe 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