wxWidgets: wxWebSession Class Reference

| Version: 3.2.7

Public Member Functions | Static Public Member Functions | List of all members
wxWebSession Class Reference
Class List by Category » Networking

`#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

## 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 ()
| 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...
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...
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...

## 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.

## ◆ 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.

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.

## ◆ GetDefault()

static wxWebSession& wxWebSession::GetDefault | ( |  | ) |
| static

Returns the default session.

## ◆ GetLibraryVersionInfo()

virtual wxVersionInfo wxWebSession::GetLibraryVersionInfo | ( |  | ) |
| 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

## ◆ SetTempDir()

void wxWebSession::SetTempDir | ( | const wxString & | dir | ) |

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