| Version: 3.3.1

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

`#include <wx/webrequest.h>`

## Detailed Description

Session allows creating wxWebRequestSync objects used for the synchronous HTTP requests.

This class is similar to wxWebSession but is used for synchronous requests only. Please see wxWebSession description for more details.

Since
  3.3.0

##

Library: wxNet
Category: Networking

See also
  wxWebRequestSync

## Public Member Functions
wxWebRequestSync | CreateRequest (const wxString &url)
| Create a new synchronous 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 wxWebRequestSync 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...
void | 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 wxWebSessionSync & | GetDefault ()
| Returns the default session. More...
static wxWebSessionSync | New (const wxString &backend=wxString())
| Creates a new wxWebSessionSync 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 wxWebSessionSync::AddCommonHeader | ( | const wxString & | name,
|  | const wxString & | value
| ) |  |

Sets a request header in every wxWebRequestSync 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 wxWebSessionSync::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()

wxWebRequestSync wxWebSessionSync::CreateRequest | ( | const wxString & | url | ) |

Create a new synchronous request for the specified URL.

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

  url | The URL of the HTTP resource for this request

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

## ◆ EnablePersistentStorage()

bool wxWebSessionSync::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.

## ◆ GetDefault()

static wxWebSessionSync& wxWebSessionSync::GetDefault | ( |  | ) |
| static

Returns the default session.

## ◆ GetLibraryVersionInfo()

virtual wxVersionInfo wxWebSessionSync::GetLibraryVersionInfo | ( |  | ) | const
| virtual

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

## ◆ GetNativeHandle()

wxWebSessionHandle wxWebSessionSync::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 wxWebSessionSync::GetTempDir | ( |  | ) | const

Returns the current temporary directory.

See also
  SetTempDir()

## ◆ IsBackendAvailable()

static bool wxWebSessionSync::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 wxWebSessionSync::IsOpened | ( |  | ) | const

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

## ◆ New()

static wxWebSessionSync wxWebSessionSync::New | ( | const wxString & | backend = `wxString()` | ) |
| static

Creates a new wxWebSessionSync 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 wxWebSessionSync

## ◆ SetBaseURL()

bool wxWebSessionSync::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).

## ◆ SetProxy()

void wxWebSessionSync::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.

Since
  3.3.0

## ◆ SetTempDir()

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

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