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. | |
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.
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 |
A list of errors that can occur while executing a network request.
| Enumerator | |
|---|---|
| HostnameError | Error resolving the hostname. ErrorCode() will be set to contain the underlying error code.
|
| 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.
|
| 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.
|
| 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.
|
| 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.
|
A list of standard HTTP methods.
| 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.
| T | The type of the object that will be created. |
| _Args | Arguments to be passed to the constructor of T. |
| 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. |