/** Copyright 2021 Haiku, Inc. All rights reserved.* Distributed under the terms of the MIT License.** Authors:* Niels Sascha Reedijk, niels.reedijk@gmail.com** Corresponds to:* headers/private/netservices2/HttpSession.h hrev?????* src/kits/network/libnetservices2/HttpSession.cpp hrev?????*/#if __cplusplus >= 201703L/*!\file HttpSession.h\ingroup netservices\brief Provides classes and tools to schedule and execute HTTP requests.\since Haiku R1*/namespace BPrivate {namespace Network {/*!\class BHttpSession\ingroup netservices\brief Schedule, execute and manage HTTP requestsAll 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 partsof the application. They should be copied, rather than shared usingpointers. This is because they have an inner state that is shared betweenthe various objects.\code// Creating and sharing a sessionauto session = BHttpSession();// A copy is passed to window1 and window2, which share the same session dataauto window1 = new WindowWithSession(session);auto window2 = new WindowWithSession(session);// Add a cookie to the session, this cookie will be used in window1 and window2BNetworkCookie 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\endcodeThere are specific scenarios for having more than one session, most notablyif an application provides services over HTTP whereby a user is identifiedby cookies, and the application wants to support more than one useraccount. But in most cases, there will be one instance of the BHttpSessionthat is shared between various segments of the application.\since Haiku R1*//*!\fn BHttpSession::BHttpSession()\brief 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.\exception std::bad_alloc Unable to allocate resources for the object.\exception BRuntimeError Unable to create semaphores or threads.\since Haiku R1*//*!\fn BHttpSession::BHttpSession(const BHttpSession&) noexcept\brief 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*//*!\fn BHttpSession::BHttpSession(BHttpSession&&) noexcept\brief Move is disabled.BHttpSession objects cannot be moved. Because it has a shared internalstate, making copies is cheap and it is the only supported method ofcreating multiple scoped objects with a shared lifetime.\since Haiku R1*//*!\fn BHttpSession::~BHttpSession() noexcept\brief DestructorThe destructor releases the shared internal state of the session object.If there are no more sessions using the shared state, the state iscleaned up.\since Haiku R1*//*!\fn BHttpSession& BHttpSession::operator=(const BHttpSession&) noexcept\brief 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 instancesonly, where there is a particular reason to replace an existing sessioninternal session with another. It should not be used in the following case:\code// Bad exampleBHttpSession session1 = BHttpSession();// Creates a new session, including an entirely new (expensive) stateBHttpSession session2 = BHttpSession();// Creates another new session, including internal statesession2 = session1;// At this stage, the internal state of session2 would// have to be cleaned up just after it was created.// Instead do thisBHttpSession session1 = BHttpSession();BHttpSession session2(session1);// Now session2 directly shares the state with session 1\endcode\since Haiku R1*//*!\fn BHttpSession& BHttpSession::operator=(BHttpSession&&) noexcept\brief Move is disabled.BHttpSession objects cannot be moved. Because it has a shared internalstate, making copies is cheap and it is the only supported method ofcreating multiple scoped objects with a shared lifetime.\since Haiku R1*//*!\fn BHttpResult BHttpSession::Execute(BHttpRequest &&request,BBorrow< BDataIO > target=nullptr, BMessenger observer=BMessenger())\brief Schedule and execute a \a request.\param request The (valid) request to move from.\param target An optional data buffer to write the incoming body of the request to. This can be\c nullptr if you want to use the default internal storage. If you provide a buffer, itmust be wrapped in a \ref BBorrow object. This means that you exclusively borrow thetarget to this session object. After the request is finished, you can regain usage of theobject through the matching \ref BExclusiveBorrow object. Use the \ref BHttpResult::Body()method to synchronize when the target is available again.\param observer An optional observer that will receive the progress and status messages forthis request.\return The \ref BHttpResult object that corresponds to this request, and that can be used tomonitor the progress.\since Haiku R1*//*!\fn void BHttpSession::Cancel(int32 identifier)\brief Cancel a running request.When a request that is scheduled or running is cancelled, its \ref BHttpResult object willbe set to the \ref BNetworkRequestError exception with the \c 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 tothe cancelled error state.2. If the request was started, then processing it will be terminated. The result will be set tothe cancelled error state.3. If the request was already finished, then nothing happens. The result will keep the value ithad assigned. The same if the request identifier is invalid.\param identifier The identifier for the request to cancel.\exception std::bad_alloc Error in case memory cannot be allocated.\since Haiku R1*//*!\fn void BHttpSession::Cancel(const BHttpResult& request)\brief Cancel a running \a request.See the \ref BHttpSession::Cancel(int32 identifier) method for more details on how this methodworks.\exception std::bad_alloc Error in case memory cannot be allocated.\since Haiku R1*//*!\fn void BHttpSession::SetMaxConnectionsPerHost(size_t maxConnections)\brief 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 concurrentconnections 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 newvalue will only be applied when any new requests are added.\param maxConnections The maximum number of connections per host. This value must between 1and \c INT32_MAX.\exception BRuntimeError In case the \a maxConnections is invalid.\since Haiku R1*//*!\fn void BPrivate::Network::BHttpSession::SetMaxHosts(size_t maxConnections)\brief 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 concurrenthosts 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 newvalue will only be applied when any new requests are added.\param maxConnections The maximum number of hosts. The value must be at least 1.\exception BRuntimeError In case the \a maxConnections is 0.\since Haiku R1*//*!\var UrlEvent::HttpStatus\brief The HTTP status code has been received, and can be accessed through the result object.\since Haiku R1*//*!\var UrlEvent::HttpFields\brief The HTTP header block has been received, and the status and fields can be accessedthrough the result object.\since Haiku R1*//*!\var UrlEvent::CertificateError\brief There was an error communicating with the server because of an SSL certificate issue.\since Haiku R1*//*!\var UrlEvent::HttpRedirect\brief The Http request was redirected, and this redirect was handled by the kit.\since Haiku R1*//*!\var const char* UrlEventData::HttpStatusCode\brief An \c int16 value that contains the HTTP status code for this request.\since Haiku R1*//*!\var const char* UrlEventData::SSLCertificate\brief The SSL certificate that causes the issue.\since Haiku R1*//*!\var const char* UrlEventData::SSLMessage\brief A \ref BString message about the error while processing the SSL certificate.\since Haiku R1*//*!\var const char* UrlEventData::HttpRedirectUrl\brief A \ref BString with the URL that the HTTP request was redirected to.\since Haiku R1*/} // namespace Network} // namespace BPrivate#endif