UrlClient.h

Go to the documentation of this file.

 
// UrlClient.h
 
// Declares the cUrlClient class for high-level URL interaction
 
/*
Options that can be set via the Options parameter to the cUrlClient calls:
"MaxRedirects":       The maximum number of allowed redirects before the client refuses a redirect with an error
"OwnCert":            The client certificate to use, if requested by the server. Any string that can be parsed by cX509Cert.
"OwnPrivKey":         The private key appropriate for OwnCert. Any string that can be parsed by cCryptoKey.
"OwnPrivKeyPassword": The password for OwnPrivKey. If not present or empty, no password is assumed.
"TrustedRootCAs":     The trusted root CA certificates (\n-delimited concatenated PEM format) to be used for peer cert verification. If not present, peer cert is not verified.
 
Behavior:
- If a redirect is received, and redirection is allowed, the redirection is reported via OnRedirecting() callback
and the request is restarted at the redirect URL, without reporting any of the redirect's headers nor body
- If a redirect is received and redirection is not allowed (maximum redirection attempts have been reached),
the OnRedirecting() callback is called with the redirect URL and then the request terminates with an OnError() callback,
without reporting the redirect's headers nor body.
*/
 
 
 
 
 
#pragma once
 
#include "../OSSupport/Network.h"
 
 
 
 
 
class cUrlClient
{
public:
    class cCallbacks
    {
    public:
        // Force a virtual destructor in descendants:
        virtual ~cCallbacks() {}
 
        virtual void OnConnected(cTCPLink & a_Link) {}
 
        virtual bool OnCertificateReceived() { return true; }
 
        virtual void OnTlsHandshakeCompleted() { }
 
        virtual void OnRequestSent() {}
 
        virtual void OnStatusLine(const AString & a_HttpVersion, int a_StatusCode, const AString & a_Rest) {}
 
        virtual void OnHeader(const AString & a_Key, const AString & a_Value) {}
 
        virtual void OnHeadersFinished() {}
 
        virtual void OnBodyData(const void * a_Data, size_t a_Size) {}
 
        virtual void OnBodyFinished() {}
 
        virtual void OnError(const AString & a_ErrorMsg) {}
 
        virtual void OnRedirecting(const AString & a_NewLocation) {}
    };
    using cCallbacksPtr = std::shared_ptr<cCallbacks>;
 
 
    enum eHTTPStatus
    {
        HTTP_STATUS_OK                 = 200,
        HTTP_STATUS_MULTIPLE_CHOICES   = 300,  // MAY have a redirect using the "Location" header
        HTTP_STATUS_MOVED_PERMANENTLY  = 301,  // redirect using the "Location" header
        HTTP_STATUS_FOUND              = 302,  // redirect using the "Location" header
        HTTP_STATUS_SEE_OTHER          = 303,  // redirect using the "Location" header
        HTTP_STATUS_TEMPORARY_REDIRECT = 307,  // redirect using the "Location" header
    };
 
 
    static std::pair<bool, AString> Request(
        const AString & a_Method,
        const AString & a_URL,
        cCallbacksPtr && a_Callbacks,
        AStringMap && a_Headers,
        const AString & a_Body,
        const AStringMap & a_Options
    );
 
    static std::pair<bool, AString> Get(
        const AString & a_URL,
        cCallbacksPtr && a_Callbacks,
        AStringMap && a_Headers = {},
        const AString & a_Body = {},
        const AStringMap & a_Options = {}
    );
 
    static std::pair<bool, AString> Post(
        const AString & a_URL,
        cCallbacksPtr && a_Callbacks,
        AStringMap && a_Headers,
        const AString & a_Body,
        const AStringMap & a_Options = {}
    );
 
    static std::pair<bool, AString> Put(
        const AString & a_URL,
        cCallbacksPtr && a_Callbacks,
        AStringMap && a_Headers,
        const AString & a_Body,
        const AStringMap & a_Options = {}
    );
 
    static std::pair<bool, AString> BlockingRequest(
        const AString & a_Method,
        const AString & a_URL,
        AStringMap && a_Headers = {},
        const AString & a_Body = {},
        const AStringMap & a_Options = {}
    );
 
    static std::pair<bool, AString> BlockingGet(
        const AString & a_URL,
        AStringMap a_Headers = {},
        const AString & a_Body = {},
        const AStringMap & a_Options = {}
    );
 
    static std::pair<bool, AString> BlockingPost(
        const AString & a_URL,
        AStringMap && a_Headers,
        const AString & a_Body,
        const AStringMap & a_Options = {}
    );
 
    static std::pair<bool, AString> BlockingPut(
        const AString & a_URL,
        AStringMap && a_Headers,
        const AString & a_Body,
        const AStringMap & a_Options = {}
    );
};