#include <wx/webrequest.h>

Detailed Description

Session allows creating wxWebRequest objects used for the actual HTTP requests.

It also handles session-wide parameters and data used by wxWebRequest instances.

Usually the default session available via wxWebSession::GetDefault() should be used. Additional instances might be useful if session separation is required. Instances must not be deleted before every active web request has finished.

Every wxWebRequest sharing the same session object will use the same cookies. Additionally, an underlying network connection might be kept alive to achieve faster additional responses.

Since: 3.1.5

Library: wxNet

Category: Networking

See also: wxWebRequest, wxWebSessionSync

Public Member Functions
wxWebRequest	CreateRequest (wxEvtHandler *handler, const wxString &url, int id=wxID_ANY)
	Create a new request for the specified URL. More...

virtual wxVersionInfo	GetLibraryVersionInfo () const
	Retrieve the version information about the implementation library used by this session. More...

void	AddCommonHeader (const wxString &name, const wxString &value)
	Sets a request header in every wxWebRequest created from this session after is has been set. More...

bool	SetBaseURL (const wxString &url)
	Sets the base URL for all requests using non-absolute URLs. More...

void	SetTempDir (const wxString &dir)
	Override the default temporary directory that may be used by the session implementation, when required. More...

wxString	GetTempDir () const
	Returns the current temporary directory. More...

bool	SetProxy (const wxWebProxy &proxy)
	Set the proxy to use for all requests initiated by this session. More...

wxWebSessionHandle	GetNativeHandle () const
	Return the native handle corresponding to this session object. More...

bool	IsOpened () const
	Return true if the session was successfully opened and can be used. More...

void	Close ()
	Close the session. More...

bool	EnablePersistentStorage (bool enable)
	Allows to enable persistent storage for the session. More...

Static Public Member Functions
static wxWebSession &	GetDefault ()
	Returns the default session. More...

static wxWebSession	New (const wxString &backend=wxString())
	Creates a new wxWebSession object. More...

static bool	IsBackendAvailable (const wxString &backend)
	Allows to check if the specified backend is available at runtime. More...

Member Function Documentation

◆ AddCommonHeader()

void wxWebSession::AddCommonHeader	(	const wxString &	name,
		const wxString &	value
	)

Sets a request header in every wxWebRequest created from this session after is has been set.

A good example for a session-wide request header is the User-Agent header.

Calling this function with the same header name again replaces the previously used value.

Parameters

name	Name of the header
value	String value of the header

◆ Close()

void wxWebSession::Close ( )

Close the session.

This frees any resources associated with the session and puts it in an invalid state. Another session object can be assigned to it later to allow using this object again.

Note that this is usually unnecessary to call this function explicitly, it will be done by the destructor of the object when it is destroyed in any case. Also note that the session object resources will remain allocated as long as there are any wxWebRequest objects using it still in existence.

◆ CreateRequest()

wxWebRequest wxWebSession::CreateRequest	(	wxEvtHandler *	handler,
		const wxString &	url,
		int	id = `wxID_ANY`
	)

Create a new request for the specified URL.

The specified objects will be notified via wxWebRequestEvent objects when the request state changes, e.g. when it is completed. It must be specified and its lifetime must be long enough to last until the request is completed. In particular, if the handler is a top-level window, the request must be cancelled before the window can be closed and destroyed.

If SetBaseURL() had been called before this function, the url can be relative, e.g. with https://foo.com/api as the base URL, passing the following values would result in using these full URLs:

get would become https://foo.com/api/get
/root would become https://foo.com/root
https://bar.org/ would remain unchanged

Parameters

handler	The handler object to notify, must be non-null.
url	The URL of the HTTP resource for this request
id	Optional id sent with events

Returns: The new request object, use wxWebRequest::IsOk() to check if its creation has succeeded.

◆ EnablePersistentStorage()

bool wxWebSession::EnablePersistentStorage ( bool enable )

Allows to enable persistent storage for the session.

Persistent storage is disabled by default, but this function can be called to enable it before the first request is created. Note that it can't be called any more after creating the first request in this session.

When persistent storage is enabled, the session will store cookies and other data between sessions.

Returns: true if the backend supports to modify this setting. false if the setting is not supported by the backend.

Note: This is only implemented in the macOS backend.

Since: 3.3.0

◆ GetDefault()

static wxWebSession& wxWebSession::GetDefault ( )

static

Returns the default session.

◆ GetLibraryVersionInfo()

virtual wxVersionInfo wxWebSession::GetLibraryVersionInfo ( ) const

virtual

Retrieve the version information about the implementation library used by this session.

◆ GetNativeHandle()

wxWebSessionHandle wxWebSession::GetNativeHandle ( ) const

Return the native handle corresponding to this session object.

wxWebSessionHandle is an opaque type containing a value of the following type according to the backend being used:

For WinHTTP backend, this is HINTERNET session handle.
For CURL backend, this is a CURLM struct pointer.
For macOS backend, this is NSURLSession object pointer.

See also: wxWebRequest::GetNativeHandle()

◆ GetTempDir()

wxString wxWebSession::GetTempDir ( ) const

Returns the current temporary directory.

See also: SetTempDir()

◆ IsBackendAvailable()

static bool wxWebSession::IsBackendAvailable ( const wxString & backend )

static

Allows to check if the specified backend is available at runtime.

Usually the default backend should always be available, but e.g. macOS before 10.9 does not have the NSURLSession implementation available.

◆ IsOpened()

bool wxWebSession::IsOpened ( ) const

Return true if the session was successfully opened and can be used.

◆ New()

static wxWebSession wxWebSession::New ( const wxString & backend = wxString() )

static

Creates a new wxWebSession object.

backend may be specified explicitly by using of the predefined wxWebSessionBackendWinHTTP, wxWebSessionBackendURLSession or wxWebSessionBackendCURL constants to select the corresponding backend or left empty to select the default backend. The default depends on the current platform: WinHTTP-based implementation is used under MSW, NSURLSession-based one under macOS and libcurl-based otherwise.

Further, if WXWEBREQUEST_BACKEND environment variable is defined, it overrides the default backend selection, allowing to force the use of libcurl-based implementation by default under MSW or macOS platforms, for example.

Use IsOpened() to check if the session creation succeeded.

Parameters

backend The backend web session implementation to use or empty to use the default implementation as described above.

Returns: The created wxWebSession

◆ SetBaseURL()

bool wxWebSession::SetBaseURL ( const wxString & url )

Sets the base URL for all requests using non-absolute URLs.

If this function is called and returns true, the url will be used as the base for all the requests created by the subsequent calls to CreateRequest() with relative URLs. This is especially useful when using some web API which typically uses a common root URL for all its endpoints.

Parameters

url	An absolute URL, i.e. including the scheme and the host.

Returns: true if the base URL was set successfully, false otherwise (this happens if the URL couldn't be parsed successfully or was not an absolute one).

Since: 3.3.0

◆ SetProxy()

bool wxWebSession::SetProxy ( const wxWebProxy & proxy )

Set the proxy to use for all requests initiated by this session.

By default, the system default proxy settings are used but this function can be called before creating the first request to override them.

Returns: true if the proxy was set successfully, false otherwise (this may indicate unsupported URL schema or that the function was called after creating the first request).

Since: 3.3.0

◆ SetTempDir()

void wxWebSession::SetTempDir ( const wxString & dir )

Override the default temporary directory that may be used by the session implementation, when required.

Detailed Description

Public Member Functions

Static Public Member Functions

Member Function Documentation

◆ AddCommonHeader()

◆ Close()

◆ CreateRequest()

◆ EnablePersistentStorage()

◆ GetDefault()

◆ GetLibraryVersionInfo()

◆ GetNativeHandle()

◆ GetTempDir()

◆ IsBackendAvailable()

◆ IsOpened()

◆ New()

◆ SetBaseURL()

◆ SetProxy()

◆ SetTempDir()