Files | Classes | Enumerations | Functions
Experimental Network Services Support

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

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

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
TThe type of the object that will be created.
_ArgsArguments to be passed to the constructor of T.
Exceptions
std::bad_allocIn case there are issues allocating the new object.
...Any other exception that is thrown by the constructor of the object T.
Since
Haiku R1