Public Member Functions | List of all members
BPrivate::Network::BHttpSession Class Reference

Schedule, execute and manage HTTP requests. More...

Public Member Functions

 BHttpSession ()
 Construct a new object. More...
 
 BHttpSession (BHttpSession &&) noexcept=delete
 Move is disabled. More...
 
 BHttpSession (const BHttpSession &) noexcept
 Create a new BHttpSession object that shares a state with another. More...
 
 ~BHttpSession () noexcept
 Destructor. More...
 
void Cancel (const BHttpResult &request)
 Cancel a running request. More...
 
void Cancel (int32 identifier)
 Cancel a running request. More...
 
BHttpResult Execute (BHttpRequest &&request, BBorrow< BDataIO > target=nullptr, BMessenger observer=BMessenger())
 Schedule and execute a request. More...
 
BHttpSessionoperator= (BHttpSession &&) noexcept=delete
 Move is disabled. More...
 
BHttpSessionoperator= (const BHttpSession &) noexcept
 Copy and use the shared state from another session. More...
 
void SetMaxConnectionsPerHost (size_t maxConnections)
 Set the maximum number of connections per host. More...
 
void SetMaxHosts (size_t maxConnections)
 Set the maximum number of concurrent hosts that can be connected to. More...
 

Detailed Description

Schedule, execute and manage HTTP requests.

All requests start from a `BHttpSession`. This class has the following jobs:

Objects of the `BHttpSession` class can be shared between different parts of the application. They should be copied, rather than shared using pointers. This is because they have an inner state that is shared between the various objects.

// Creating and sharing a session
auto session = BHttpSession();
// A copy is passed to window1 and window2, which share the same session data
auto window1 = new WindowWithSession(session);
auto window2 = new WindowWithSession(session);
// Add a cookie to the session, this cookie will be used in window1 and window2
BNetworkCookie cookie("key", "value", BUrl("https://example.com/"));
session.AddCookie(std::move(cookie));
// The session data persists, even if the original session goes out of scope

There are specific scenarios for having more than one session, most notably if an application provides services over HTTP whereby a user is identified by cookies, and the application wants to support more than one user account. But in most cases, there will be one instance of the BHttpSession that is shared between various segments of the application.

Since
Haiku R1

Constructor & Destructor Documentation

◆ BHttpSession() [1/3]

BPrivate::Network::BHttpSession::BHttpSession ( )

Construct a new object.

Each newly constructed object will have their own queue for HTTP requests, as well as their own cookies and certificate store.

Exceptions
std::bad_allocUnable to allocate resources for the object.
BRuntimeErrorUnable to create semaphores or threads.
Since
Haiku R1

◆ BHttpSession() [2/3]

BPrivate::Network::BHttpSession::BHttpSession ( const BHttpSession )
noexcept

Create a new BHttpSession object that shares a state with another.

The internal HTTP queue and context can be shared among multiple objects. You can use the copy constructor to create a new object.

Since
Haiku R1

◆ BHttpSession() [3/3]

BPrivate::Network::BHttpSession::BHttpSession ( BHttpSession &&  )
deletenoexcept

Move is disabled.

BHttpSession objects cannot be moved. Because it has a shared internal state, making copies is cheap and it is the only supported method of creating multiple scoped objects with a shared lifetime.

Since
Haiku R1

◆ ~BHttpSession()

BPrivate::Network::BHttpSession::~BHttpSession ( )
noexcept

Destructor.

The destructor releases the shared internal state of the session object. If there are no more sessions using the shared state, the state is cleaned up.

Since
Haiku R1

Member Function Documentation

◆ Cancel() [1/2]

void BPrivate::Network::BHttpSession::Cancel ( const BHttpResult request)

Cancel a running request.

See the BHttpSession::Cancel(int32 identifier) method for more details on how this method works.

Exceptions
std::bad_allocError in case memory cannot be allocated.
Since
Haiku R1

◆ Cancel() [2/2]

void BPrivate::Network::BHttpSession::Cancel ( int32  identifier)

Cancel a running request.

When a request that is scheduled or running is cancelled, its BHttpResult object will be set to the BNetworkRequestError exception with the Cancelled type.

There are three possible outcomes: 1. If the request is not yet scheduled, then it will never start. The result will be set to the cancelled error state. 2. If the request was started, then processing it will be terminated. The result will be set to the cancelled error state. 3. If the request was already finished, then nothing happens. The result will keep the value it had assigned. The same if the request identifier is invalid.

Parameters
identifierThe identifier for the request to cancel.
Exceptions
std::bad_allocError in case memory cannot be allocated.
Since
Haiku R1

◆ Execute()

BHttpResult BPrivate::Network::BHttpSession::Execute ( BHttpRequest &&  request,
BBorrow< BDataIO target = nullptr,
BMessenger  observer = BMessenger() 
)

Schedule and execute a request.

Parameters
requestThe (valid) request to move from.
targetAn optional data buffer to write the incoming body of the request to. This can be nullptr if you want to use the default internal storage. If you provide a buffer, it must be wrapped in a BBorrow object. This means that you exclusively borrow the target to this session object. After the request is finished, you can regain usage of the object through the matching BExclusiveBorrow object. Use the BHttpResult::Body() method to synchronize when the target is available again.
observerAn optional observer that will receive the progress and status messages for this request.
Returns
The BHttpResult object that corresponds to this request, and that can be used to monitor the progress.
Since
Haiku R1

◆ operator=() [1/2]

BHttpSession & BPrivate::Network::BHttpSession::operator= ( BHttpSession &&  )
deletenoexcept

Move is disabled.

BHttpSession objects cannot be moved. Because it has a shared internal state, making copies is cheap and it is the only supported method of creating multiple scoped objects with a shared lifetime.

Since
Haiku R1

◆ operator=() [2/2]

BHttpSession & BPrivate::Network::BHttpSession::operator= ( const BHttpSession )
noexcept

Copy and use the shared state from another session.

The internal HTTP queue and context can be shared among multiple objects. You can use the copy constructor to create a new copy.

This copy assignment operator should be used in very specific instances only, where there is a particular reason to replace an existing session internal session with another. It should not be used in the following case:

// Bad example
// Creates a new session, including an entirely new (expensive) state
// Creates another new session, including internal state
session2 = session1;
// At this stage, the internal state of session2 would
// have to be cleaned up just after it was created.
// Instead do this
BHttpSession session2(session1);
// Now session2 directly shares the state with session 1
Since
Haiku R1

◆ SetMaxConnectionsPerHost()

void BPrivate::Network::BHttpSession::SetMaxConnectionsPerHost ( size_t  maxConnections)

Set the maximum number of connections per host.

A host is identified by the domain name and the port. You can limit the number of concurrent connections to a host by tweaking this value.

The default value is 2 connections per host.

If the value is decreased, any requests that already started will not be affected. The new value will only be applied when any new requests are added.

Parameters
maxConnectionsThe maximum number of connections per host. This value must between 1 and INT32_MAX.
Exceptions
BRuntimeErrorIn case the maxConnections is invalid.
Since
Haiku R1

◆ SetMaxHosts()

void BPrivate::Network::BHttpSession::SetMaxHosts ( size_t  maxConnections)

Set the maximum number of concurrent hosts that can be connected to.

A host is identified by the domain name and the port. You can limit the number of concurrent hosts by tweaking this value.

The default value is 10 concurrent hosts.

If the value is decreased, any requests that already started will not be affected. The new value will only be applied when any new requests are added.

Parameters
maxConnectionsThe maximum number of hosts. The value must be at least 1.
Exceptions
BRuntimeErrorIn case the maxConnections is 0.
Since
Haiku R1
BUrl
Represents and manipulates an URL (Uniform Resource Locator).
Definition: Url.h:15
BPrivate::Network::BHttpSession::BHttpSession
BHttpSession()
Construct a new object.