Experimental API to do higher level network requests. More...

Files
file	ErrorsExt.h
	Defines advanced error types and error functions for the Network Services API.

file	ExclusiveBorrow.h
	Provides the BExclusiveBorrow smart pointer.

file	HttpFields.h
	Provides the BHttpFields class.

file	HttpRequest.h
	Provides the classes and tools to build HTTP Requests.

file	HttpResult.h
	Provides classes and tools to handle HTTP responses.

file	HttpSession.h
	Provides classes and tools to schedule and execute HTTP requests.

file	HttpTime.h
	Provides tools to parse and format HTTP dates.

file	NetServicesDefs.h
	Various standardized error and notification types used by multiple protocols of the Network Services Kit.

Classes
class	BPrivate::Network::BBorrow< T >
	Smart pointer that borrows an object from a BExclusiveBorrow owner. More...

class	BPrivate::Network::BBorrowError
	Error while handling a BExclusiveBorrow or BBorrow object. More...

class	BPrivate::Network::BError
	Abstract base class for advanced error objects. More...

class	BPrivate::Network::BExclusiveBorrow< T >
	Smart pointer that allows shared ownership of an object with exclusive access. More...

struct	BPrivate::Network::BHttpAuthentication
	Describe username and password for basic authentication for the request. More...

struct	BPrivate::Network::BHttpBody
	Represents a HTTP response body. More...

class	BPrivate::Network::BHttpFields
	Represents the field section of a HTTP header. More...

class	BPrivate::Network::BHttpMethod
	Represent a HTTP method. More...

class	BPrivate::Network::BHttpRequest
	Represent a HTTP request. More...

class	BPrivate::Network::BHttpResult
	Unique object to wait for and access a HTTP response data. More...

class	BPrivate::Network::BHttpSession
	Schedule, execute and manage HTTP requests. More...

struct	BPrivate::Network::BHttpStatus
	Represents the HTTP status code and status text of an incoming response. More...

class	BPrivate::Network::BHttpTime
	Utility class that can parse and format HTTP Date strings. More...

class	BPrivate::Network::BInvalidUrl
	Error that indicates that the URL is not valid. More...

class	BPrivate::Network::BNetworkRequestError
	Error that indicates there was an issue executing the network request. More...

struct	BPrivate::Network::BHttpRequest::Body
	Describe the body for a network request. More...

class	BPrivate::Network::BRuntimeError
	Advanced error object for runtime errors. More...

class	BPrivate::Network::BSystemError
	Advanced error object that wrap low-level system errors. More...

class	BPrivate::Network::BUnsupportedProtocol
	Error that indicates that the protocol is not supported. More...

class	BPrivate::Network::BHttpFields::Field
	Represents a HTTP header field. More...

class	BPrivate::Network::BHttpFields::FieldName
	Representation of a HTTP header name. More...

class	BPrivate::Network::BHttpTime::InvalidInput
	Error that indicates that a string cannot be parsed as a valid HTTP timestamp. More...

class	BPrivate::Network::BHttpFields::InvalidInput
	Error that represents when a string input contains characters that are incompatible with the HTTP specification. More...

class	BPrivate::Network::BHttpMethod::InvalidMethod
	Error that represents when a custom method does not conform to the HTTP standard. More...

Enumerations
enum	BPrivate::Network::BNetworkRequestError::ErrorType { BPrivate::Network::BNetworkRequestError::HostnameError, BPrivate::Network::BNetworkRequestError::NetworkError, BPrivate::Network::BNetworkRequestError::ProtocolError, BPrivate::Network::BNetworkRequestError::SystemError, BPrivate::Network::BNetworkRequestError::Canceled }
	A list of errors that can occur while executing a network request. More...

enum	BPrivate::Network::BHttpMethod::Verb { BPrivate::Network::BHttpMethod::Get, BPrivate::Network::BHttpMethod::Head, BPrivate::Network::BHttpMethod::Post, BPrivate::Network::BHttpMethod::Put, BPrivate::Network::BHttpMethod::Delete, BPrivate::Network::BHttpMethod::Connect, BPrivate::Network::BHttpMethod::Options, BPrivate::Network::BHttpMethod::Trace }
	A list of standard HTTP methods. More...

Functions
template<class T , class... _Args>
BExclusiveBorrow< T >	BPrivate::Network::make_exclusive_borrow (_Args &&... __args)
	Create a new object that is managed by a BExclusiveBorrow smart pointer. More...

Detailed Description

Experimental API to do higher level network requests.

This API currently is marked as experimental. It is part of the BPrivate::Network namespace, the header files are found at headers\private\netservices2, and you have to link your application to libnetservices2.a. The new API is only available for modern platforms (x86 and x86_64), and not for the legacy platform (x86_gcc2). The compiler needs to support C++17 or higher.

Asynchronous handling of the result.

In GUI applications, networking operations are often triggered by a user action. For example, downloading a file will be initiated by the user clicking a button. When you initiate that action in the window's thread, and you block the message loop until the request is finished, the user will be left with a non-responsive UI. That is why one would usually run a network request asynchronously. And instead of checking the status every few CPU cycles, you'd want to be proactively informed when something important happens, like the progress of the download or a signal when the request is finished.

The Network Services kit support using the Haiku API's Looper and Handler system to keep you up to date about relevant events that happen to the requests.

The following messages are available for all requests (HTTP and other). The messages below are in the order that they will arrive (when applicable).

Message Constant	Description	Applies to	Additional Data
UrlEvent::HostNameResolved	The hostname has been resolved. This message is even sent when you set an IP-address in the URL object	All protocols that use network connections.	UrlEventData::Id `int32` UrlEventData::HostName BString
UrlEvent::ConnectionOpened	The connection to the remote server is opened. After this event, data will be written.	All protocols that use network connections.	UrlEventData::Id `int32`
UrlEvent::UploadProgress	If there is a request body to be sent, this informs you of the progress. When the total size of the request body is known, this will be part of the message.	All protocols that use network connections and support writing data to the server (like HTTP(S)).	UrlEventData::Id `int32` UrlEventData::NumBytes `int64` UrlEventData::TotalBytes `int64` (optional)
UrlEvent::ResponseStarted	The server has started transmitting the response.	All Protocols	UrlEventData::Id `int32`
UrlEvent::HttpRedirect	The network services kit is handling a HTTP redirect. The request will be repeated for a new URL.	HTTP/HTTPS	UrlEventData::Id `int32` UrlEventData::HttpRedirectUrl BString
UrlEvent::HttpStatus	The response status is available. This means it can also be accessed through BHttpResult::Status() without blocking the system.	HTTP/HTTPS	UrlEventData::Id `int32` UrlEventData::HttpStatusCode `int16`
UrlEvent::HttpFields	The HTTP header block has been fully received, and the HTTP fields can be accessed using BHttpResult::Fields() without blocking the system.	HTTP/HTTPS	UrlEventData::Id `int32`
UrlEvent::DownloadProgress	If there is a response body to be received, this informs you of the progress. If the total size of the body is known, this will be included in the message as well.	All protocols that use network connections.	UrlEventData::Id `int32` UrlEventData::NumBytes `int64` UrlEventData::TotalBytes `int64` (optional)
UrlEvent::BytesWritten	An interim update on how many bytes have been written to the target. This message is only sent when you supplied a custom target to store the body of the request in. Note that the number of bytes written to the target may differ from the network transfer size, due to compression in the protocol.	All protocols.	UrlEventData::Id `int32` UrlEventData::NumBytes `int64`
UrlEvent::RequestCompleted	The request is completed and all the data is written to the target, or there was an error.	All protocols.	UrlEventData::Id `int32` UrlEventData::Success `bool`
UrlEvent::DebugMessage	Additional debug information on the request. This is enabled or disabled per request. See the details in the protocol description.	All protocols.	UrlEventData::Id `int32` UrlEventData::DebugType `uint32` UrlEventData::DebugMessage BString

Enumeration Type Documentation

◆ ErrorType

enum BPrivate::Network::BNetworkRequestError::ErrorType

A list of errors that can occur while executing a network request.

Since: Haiku R1

Enumerator
HostnameError	Error resolving the hostname. ErrorCode() will be set to contain the underlying error code. Since Haiku R1
NetworkError	The request was interrupted due to a network error. This may occur when reading or writing fails due to an underlying network error, like an unexpected closed connection. ErrorCode() will be set to contain the underlying error code. Since Haiku R1
ProtocolError	The request did not complete because the response did not conform to the protocol. The server gave an unexpected or incorrect response. The network request could not complete because of this. There will not be any ErrorCode() set. Since Haiku R1
SystemError	Other internal error while handling the request. There could have been issues initializing buffers or decompression engines. ErrorCode() will be set to contain the underlying error code. Since Haiku R1
Canceled	The request was canceled before it was completed. This could either have been done through the API, or because the session that schedules and executes the requests was destroyed. There will not be any ErrorCode() set. Since Haiku R1

◆ Verb

enum BPrivate::Network::BHttpMethod::Verb

A list of standard HTTP methods.

Since: Haiku R1

Enumerator
Get	Represents the `GET` method. Since Haiku R1
Head	Represents the `HEAD` method. Since Haiku R1
Post	Represents the `POST` method. Since Haiku R1
Put	Represents the `PUT` method. Since Haiku R1
Delete	Represents the `DELETE` method. Since Haiku R1
Connect	Represents the `CONNECT` method. Since Haiku R1
Options	Represents the `OPTIONS` method. Since Haiku R1
Trace	Represents the `TRACE` method. Since Haiku R1

Function Documentation

◆ make_exclusive_borrow()

template<class T , class... _Args>

BExclusiveBorrow< T > BPrivate::Network::make_exclusive_borrow ( _Args &&... __args )

Create a new object that is managed by a BExclusiveBorrow smart pointer.

This is a convenience template function to the likes of std::make_unique(). It allows you to directly create the BExclusiveBorrow smart pointer around a newly allocated object.

Template Parameters

T	The type of the object that will be created.
_Args	Arguments to be passed to the constructor of T.

Exceptions

std::bad_alloc	In case there are issues allocating the new object.
...	Any other exception that is thrown by the constructor of the object T.

Since: Haiku R1

Files

Classes

Enumerations