From d2c7d80544941100587c4bcf513cc64336da8126 Mon Sep 17 00:00:00 2001 From: Tobias Taschner Date: Sun, 14 Oct 2018 22:20:54 +0200 Subject: [PATCH] Add wxWebRequest documentation --- interface/wx/webrequest.h | 337 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 interface/wx/webrequest.h diff --git a/interface/wx/webrequest.h b/interface/wx/webrequest.h new file mode 100644 index 0000000000..4fa7f6fa9a --- /dev/null +++ b/interface/wx/webrequest.h @@ -0,0 +1,337 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: webrequest.h +// Created: 2018-10-14 +// Copyright: (c) 2018 wxWidgets development team +// Licence: wxWindows licence +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWebRequest + + This class allows for simple HTTP requests using the operating systems + components as implementation. + + The latest features of the operating system will be used if available + (e.g. HTTP/2, TLS 1.2). + System wide configuration like proxy and SSL certificates will be used + when possible. + + Instances of wxWebRequest are created by using + wxWebRequestSession::CreateRequest(). + + The requests are handled asynchronously and event handlers are used to + communicate the request status. + + Example usage: + + @code + // Create the request object + wxObjectDataPtr request( + wxWebRequestSession::GetDefault()->CreateRequest("https://www.wxwidgets.org/downloads/logos/blocks.png")); + + // Bind events + request->Bind(wxEVT_WEBREQUEST_READY, [](wxWebRequestEvent& evt) { + wxImage logoImage(evt->GetResponse()->GetStream()); + if (logoImage.IsOK()) + wxLogInfo("Image loaded"); + }); + request->Bind(wxEVT_WEBREQUEST_FAILED, [](wxWebRequestEvent& evt) { + wxLogError("Could not load logo: %s", evt.GetErrorDescription()); + }); + + // Start the request + request->Start(); + @endcode + + @section descriptions Implementation Descriptions + + The following APIs are used per platform, additional documentation + about supported features may be found in their documentation + + Available features by implementation and minimum version: + + + + + + + + + + + + + + + + + + + + + + + + + + +
Operating SystemAPIHTTPSHTTP/2
Windows + WinHTTP + YesWindows 10 1607
macOS + NSURLSession + macOS 10.9macOS 10.11
iOS + NSURLSession + iOS 7.0iOS 9.0
Linux + libcurl + Yes7.47.0
+ + @beginEventEmissionTable{wxWebRequestEvent} + @event{wxEVT_WEBREQUEST_READY(id, func)} + The response data is ready to be used. + @event{wxEVT_WEBREQUEST_FAILED(id, func)} + A network error has occured. This could be client side or server side. + Use wxWebRequestEvent::GetErrorDescription() to get more details. + @event{wxEVT_WEBREQUEST_AUTH_REQUIRED(id, func)} + The request needs additional authentication to continue. + @endEventTable + + @since 3.1.2 + + @library{wxnet} + @category{net} + + @see wxWebRequestResponse, wxWebRequestSession +*/ +class wxWebRequest: public wxEvtHandler, public wxRefCounter +{ +public: + /** + Adds a request header send by this request. + + @param name Name if the header + @param value String value of the header + */ + void AddHeader(const wxString& name, const wxString& value); + + /** + Set HTTP method. + + Set common + or expanded HTTP method. + + The default method is GET unless request data is provided in which + case POST is the default. + + @param method + HTTP method name, e.g. "GET". + */ + void SetMethod(const wxString& method); + + /** + Set the text to be posted to the server. + + After a successful call to this method, the request will use HTTP @c + POST instead of the default @c GET when it's executed. + + @param data + The data to post. + @param contentType + The value of HTTP "Content-Type" header, e.g. "text/html; + charset=UTF-8". + */ + void SetData(const wxString& data, const wxString& contentType); + + /** + Set the binary data to be posted to the server. + + The next request will + be an HTTP @c POST instead of the default HTTP @c GET and the given @a + data will be posted as the body of this request. + + @param dataStream + The data in this stream will be posted as the request body + @param contentType + The value of HTTP "Content-Type" header, e.g. "text/html; + charset=UTF-8". + */ + void SetData(const wxInputStream& dataStream, const wxString& contentType); + + /** + Instructs the request to ignore server error status codes. + + Per default server side errors (status code 500-599) will be send + a wxEVT_WEBREQUEST_FAILED event just like network errors, but + if the response is still required in this cases (e.g. to get more + details from the response body) this may be set to ignore these. + If ignored wxWebRequestResponse::GetStatus() has to be checked + from the wxEVT_WEBREQUEST_READY event handler. + */ + void SetIgnoreServerErrorStatus(bool ignore); + + /** + Send the request to the server asynchronously. + + Events will be triggered on success or failure + + @see Cancel() + */ + void Start(); + + /** + Cancel an active request + */ + void Cancel(); + + /** + Return a response object after a successful request. + */ + const wxWebRequestResponse* GetResponse() const; +}; + +/** + A wxWebRequestResponse allows access to the response sent by the server. + + @since 3.1.2 + + @library{wxnet} + @category{net} + + @see wxWebRequest +*/ +class wxWebRequestResponse +{ +public: + /** + Returns the final URL. + This URL might be different than the request URL when a redirection + occured. + */ + wxString GetURL() const; + + /** + Return a header from the response or an empty string if the header + could not be found. + + @param name Name of the header field + */ + wxString GetHeader(const wxString& name) const; + + /** + Returns the status code returned by the server + */ + int GetStatus() const; + + /** + Returns the response status text + */ + wxString GetStatusText() const; + + /** + Returns a stream which represents the response data sent by the server. + */ + wxInputStream& GetStream() const; + + /** + Returns all response data as a string. + + @param conv wxMBConv used to convert the response to a string. + If @c NULL the conversion will be determined by + response headers. Defaulting to UTF-8 + */ + wxString AsString(wxMBConv* conv = NULL) const; +}; + +/** + @class wxWebRequestSession + + This class handles session wide parameters and data used by wxWebRequest + instances. + + Usually the default session available via wxWebRequestSession::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.2 + + @library{wxnet} + @category{net} + + @see wxWebRequest +*/ +class wxWebRequestSession +{ +public: + /** + Constructor for the session + + All requests created by a call to CreateRequest() will use this session + for communication and to store cookies. + */ + wxWebRequestSession(); + + /** + Create a new request for the specified URL + + @param url + The URL of the HTTP resource for this request + @param id + Optional id send with events + */ + wxWebRequest* CreateRequest(const wxString& url, int id = wxID_ANY); + + + /** + Returns the default session + */ + static wxWebRequestSession* GetDefault(); + + /** + Adds a request header send by every wxWebRequest using this session. + + A good example for a session wide request header is the @c User-Agent + header. + + @param name Name if the header + @param value String value of the header + */ + void AddRequestHeader(const wxString& name, const wxString& value); +}; + +/** + @class wxWebRequestEvent + + A web request event send during or after server communication. + + @since 3.1.2 + + @library{wxnet} + @category{net} + + @see wxWebRequest +*/ +class wxWebRequestEvent : public wxEvent +{ +public: + wxWebViewEvent(); + wxWebViewEvent(wxEventType type, int id); + + /** + The response for a wxEVT_WEBREQUEST_READY event + */ + const wxWebRequestResponse* GetResponse() const; + + /** + A textual error description for a client side error + wxEVT_WEBREQUEST_FAILED + */ + const wxString& GetErrorDescription() const; +}; + +wxEventType wxEVT_WEBREQUEST_READY; +wxEventType wxEVT_WEBREQUEST_FAILED; +wxEventType wxEVT_WEBREQUEST_AUTH_REQUIRED;