Add wxWebRequest documentation
This commit is contained in:
Tobias Taschner
parent
251561172a
commit
d2c7d80544
337
interface/wx/webrequest.h
Normal file
337
interface/wx/webrequest.h
Normal file
@ -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<wxWebRequest> 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:
|
||||
<table>
|
||||
<tr><th>Operating System</th><th>API</th><th>HTTPS</th><th>HTTP/2</th></tr>
|
||||
<tr>
|
||||
<td>Windows</td>
|
||||
<td>
|
||||
<a target=_new href="https://docs.microsoft.com/en-us/windows/desktop/WinHttp/about-winhttp">WinHTTP</a>
|
||||
</td>
|
||||
<td>Yes</td>
|
||||
<td>Windows 10 1607</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>macOS</td>
|
||||
<td>
|
||||
<a target=_new href="https://developer.apple.com/documentation/foundation/urlsession">NSURLSession</a>
|
||||
</td>
|
||||
<td>macOS 10.9</td>
|
||||
<td>macOS 10.11</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>iOS</td>
|
||||
<td>
|
||||
<a target=_new href="https://developer.apple.com/documentation/foundation/urlsession">NSURLSession</a>
|
||||
</td>
|
||||
<td>iOS 7.0</td>
|
||||
<td>iOS 9.0</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Linux</td>
|
||||
<td>
|
||||
<a target=_new href="https://curl.haxx.se/libcurl/">libcurl</a>
|
||||
</td>
|
||||
<td>Yes</td>
|
||||
<td>7.47.0</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@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 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html">common</a>
|
||||
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 <b>must not</b> 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;
|
||||
Loading…
Reference in New Issue
Block a user