BPrivate::Network::BHttpSession Class Reference

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

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

Detailed Description

Schedule, execute and manage HTTP requests.

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

• Store data used between various HTTP calls
  • Proxies
  • Cookies
  • Additional SSL certificates
  • Authentication Data
• Manage the scheduling and execution of HTTP requests.

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_alloc	Unable to allocate resources for the object.
BRuntimeError	Unable 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_alloc

Error 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

identifier

The identifier for the request to cancel.

Exceptions

std::bad_alloc

Error 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

request	The (valid) request to move from.
target	An 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.
observer	An 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
BHttpSession session1 = BHttpSession();
    // Creates a new session, including an entirely new (expensive) state
BHttpSession session2 = BHttpSession();
    // 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 session1 = BHttpSession();
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

maxConnections

The maximum number of connections per host. This value must between 1 and INT32_MAX.

Exceptions

BRuntimeError

In 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

maxConnections

The maximum number of hosts. The value must be at least 1.

Exceptions

BRuntimeError

In case the maxConnections is 0.

Since

Haiku R1