http_client

IHTTPClient is simple HTTP client.

File information

Functions

Helper functions

inline const char * HTTPShutdownReasonToStr(http_shutdown_reason_t reason)

Helper function to convert a http_shutdown_reason_t to a string. Helpful for debugging and logging purposes.

Classes

IHTTPClient

class IHTTPClient {
public:
    virtual ~IHTTPClient() {}
    static IHTTPClient * Create(class IIoMux * const iomux,
                                class ISocketProvider * const tcpSocketProvider,
                                class ISocketProvider * const tlsSocketProvider,
                                class UHTTPClient * const user,
                                class IInstanceLog * const log,
                                class IDns * const dns = nullptr,
                                class ISocketContext * const socketContext = nullptr);
    virtual void Connect(const char * address,
                         const char * user = NULL,
                         const char * pwd = NULL,
                         int authMethods = HTTP_AUTH_ALL) = 0;
    virtual void Recv(byte * buffer, size_t size, bool recvPartitial = false);
    virtual void Send(const byte * data = NULL, size_t size = 0, bool last = false);
    virtual void Shutdown();
    virtual void Reconnect();
    virtual void PassErrorToUser(http_error_t err);
    virtual void SendContentForAuthentication(bool doSend);
    virtual void SetRequestType(http_request_type_t reqType, const char * resourceName, size_t contentLength = 0, const char * contentType = "text/xml; charset=utf-8");
    virtual void SetCustomHeaderField(const char * field, const char * value);
    virtual http_result_t GetHTTPResult();
    virtual size_t GetContentLength(bool & chunked);
    virtual size_t GetHeaderFieldValueCount(const char * headerField);
    virtual const char * GetHeaderFieldValue(const char * headerField, size_t index = 0);

    virtual bool Connected();
};

This is the main class of the HTTP client functionality. Please note that IHTTPClient is not a fully-fledged HTTP client. For now only GET, PUT and POST requests can be used. However, the generally used authentication variants are supported by the Client (basic, digest and NTLM). Connections can be established by a TCP or a TLS socket. This depends on the address given to connect (HTTP for normal TCP connections, HTTPS for a TLS connection).

Public functions

UHTTPClient

class UHTTPClient {
public:
    ~UHTTPClient() {}
    virtual void HTTPClientConnectComplete(IHTTPClient * const httpClient);
    virtual void HTTPClientShutdown(IHTTPClient * const httpClient, http_shutdown_reason_t reason);
    virtual void HTTPClientSendResult(IHTTPClient * const httpClient);
    virtual void HTTPClientRecvResult(IHTTPClient * const httpClient, byte * buffer, size_t len, bool transferComplete);
    virtual void HTTPClientRecvCanceled(IHTTPClient * const httpClient, byte * buffer);
    virtual void HTTPClientRequestComplete(IHTTPClient * const httpClient);
};

This class is for receiving callbacks from the IHTTPClient. You must pass as subclass of UHTTPClient to an IHTTPClient as user.

Data types

Defines

#define HTTP_AUTH_NONE      0
#define HTTP_AUTH_NTLM      1
#define HTTP_AUTH_DIGEST    2
#define HTTP_AUTH_BASIC     4
#define HTTP_AUTH_ALL       HTTP_AUTH_NTLM | HTTP_AUTH_DIGEST | HTTP_AUTH_BASIC
#define HTTP_CLIENT_CHUNKED_TRANSFER    0xffffffff

http_request_type_t

typedef enum {
    HTTP_GET,
    HTTP_POST,
    HTTP_PUT
} http_request_type_t;

This enum defines the request types supported by the IHTTPClient. One of them must be given to IHTTP::SetRequestType(). The supported request types by the IHTTPClient are GET, POST and PUT.

http_shutdown_reason_t

typedef enum {
    HTTP_SHUTDOWN_NORMAL,
    HTTP_SOCKET_LOST,
    HTTP_ADDRESS_INVALID,
    HTTP_SOCKET_ERROR,
    HTTP_CONNECT_FAILED,
    HTTP_BYTE_STREAM_BROKEN,
    HTTP_UNHANDLED_HTTP_RESULT,
    HTTP_FAILURE,
    HTTP_AUTHENTICATION_FAILED,
    HTTP_NOT_FOUND,
    HTTP_BAD_REQUEST,
    HTTP_INTERNAL_SERVER_ERROR
} http_shutdown_reason_t;

This enum defines the reasons for a shutdown. The following reason can lead to a IHTTPClient shutdown:

http_result_t

typedef enum {
    HTTP_RESULT_OK,
    HTTP_RESULT_NOT_FOUND,
    HTTP_RESULT_BAD_REQUEST,
    HTTP_RESULT_INTERNAL_SERVER_ERROR
} http_result_t;

This enum defines the results of a HTTP request. That results can be get by calling IHTTPClient::GetHTTPResult(). The following results are supported by that function:

http_error_t

typedef enum {
    HTTP_CL_ERR_NOT_FOUND           = 0x0001,
    HTTP_CL_ERR_BAD_REQUEST         = 0x0002,
    HTTP_CL_ERR_INTERNAL_SERVER     = 0x0004
} http_error_t;

This enum defines the errors that should be passed to the UHTTPClient user. Instead of shutting down the IHTTPClient, the request will be accepted and UHTTPClient::HTTPClientRequestComplete() will be called. The user must check the error code (by calling IHTTPClient::GetHTTPResult()) and handle it properly. The flags of http_error_t can be combined to a bitfield by a binary or operator. The following flags are supported:

Code Example

app::app(IIoMux * iomux)
    : iomux(iomux)
{
    // you can optionally create a socketContext, if you e.g. want to disable sending of a client certificate
    class ISocketContext * socketContext = aTlsSocketProvider->CreateSocketContext(this);  
    socketContext->DisableClientCertificate();
    // create the httpClient instance
    this->httpClient = IHTTPClient::Create(iomux, aTcpSocketProvider, aTlsSocketProvider, this, this, nullptr, socketContext);
    this->httpClient->Connect("google.de");
}
void app::HTTPClientConnectComplete(IHTTPClient * const httpClient)
{
    this->httpClient->SetRequestType(HTTP_GET, "/index.html");
    this->httpClient->Send();
}
void app::HTTPClientSendResult(IHTTPClient * const httpClient)
{
    // for GET we can simply ignore the send result and wait for HTTPClientRequestComplete
}
void app::HTTPClientRequestComplete(IHTTPClient * const httpClient)
{
    this->httpClient->Recv((byte *)malloc(1024), 1024);
}
void app::HTTPClientRecvResult(IHTTPClient * const httpClient, byte * buffer, size_t len, bool transferComplete)
{
    printf("%.*s", len, (char *)buffer);
    if (transferComplete) {
        free(buffer);
        this->httpClient->Shutdown();
    }
    else
        this->httpClient->Recv(buffer, 1024);
}
void app::HTTPClientShutdown(IHTTPClient * const httpClient, http_shutdown_reason_t reason)
{
    delete this->httpClient;
}