httplib

The HTTPlib is a collection of classes to handle HTTP Headers (reading / creating them). They are used by the webserver, so normally there is no need to use them as long as you don't use IWebserverPassthrough. There it could become in handy using the HTTPlib classes to handle the HTTP header stuff. After setting the version number and the HTTP result (or the HTTP request method), the header is prepared to be send. You can set what ever field you want to and send that header directly by getting the buffer to the byte-stream and the size of it. So there is no need for any other function to prepare a http header. Just set the version, the request or result, what ever field you want to set more (it will always be a good idea to set at least the content length, even if it will be 0) and send the header.

File information

Classes

HTTPLib

class HTTPLib {
public:
    static inline const char * GetHTTPRequestMethodName(http_request_method_t method);
    inline static const http_result_t * HTTPResultFromStatusNumber(int number);
    inline static const http_result_t * HTTPResultFromStatusNumberStr(const char * numStr);

};

This class actually is only for wrapping the types and constants used by the HTTP lib (beside the one helper function described here). The other parts of that class are described in the data types section of this document (see below).

Public functions

HTTPHeader

class HTTPHeader {
public:
    HTTPHeader();
    ~HTTPHeader();

    void SetHTTPVersion(int major, int minor);
    void SetHTTPResult(const HTTPLib::http_result_t * result);
    void SetContentSize(ulong64 size);
    void SetContentRange(ulong64 start, ulong64 end, ulong64 completeSize);
    void SetContentType(const char * contentType);
    void SetEncoding(HTTPLib::http_encoding_t enc);
    void SetETag(const char * etag);
    void SetConnection(HTTPLib::http_connection_t connection);
    void SetUpgrade(HTTPLib::http_upgrade_t upgrade);
    void SetWebsocketAcceptKey(const char * key);
    void SetCustomField(const char * field);
    void SetCustomField(const char * field, const char * value);
    void SetDate();
    void SetRequest(HTTPLib::http_request_method_t req, const char * resource);

    const char * GetHeaderData() { return buffer; }
    size_t GetHeaderSize() { return contentSize; }
};

This class is used for creating an HTTP header asresponse or request. If you want to parse an HTTP Header, HTTPParser must be used.

Public functions

HTTPParser

class HTTPParser {
public:
    typedef enum {
        HTTP_PARSE_DONE,
        HTTP_PARSE_NEED_DATA,
        HTTP_PARSE_CANCEL,
        HTTP_PARSE_ERROR
    } parseresult_t;

    HTTPParser();
    ~HTTPParser();

    size_t ParseData(char * data, size_t len, UHTTPParser * user = nullptr);

    parseresult_t GetParseResult() const { return (parseresult_t)parseResult; }
    HTTPLib::http_encoding_t GetAcceptEncoding() const { return acceptEncoding; }
    HTTPLib::http_request_method_t GetRequestMethod() const { return reqMethod; }
    const char * GetRequestTarget() const { return requestTarget; }
    const char * GetRequestParameters() const { return requestParameters; }
    int GetMajorVersion() const { return httpVersion >> 8; }
    int GetMinorVersion() const { return httpVersion & 0x00FF; }
    int GetVersion() const { return httpVersion; }
    const HTTPHeaderField * GetHeaderField(const char * fieldName)  const;

    ulong64 GetContentLength() const { return contentLength; }
    bool IsConnectionType(HTTPLib::http_connection_t ct) const { return (connectionType & ct) != 0; }
    bool IsChunkedTransfer();
    const char * GetCookie() const { return cookie; }
    const char * GetETag() const { return etag; }
    const char * GetContentType() const { return contentType; }
    const char * GetHost() const { return host; }
    HTTPLib::http_upgrade_t GetUpgrade() const { return upgradeType; }
    const HTTPRange * GetRange() const { return rangeListStart; }
    size_t GetRangeCount() const { return rangeCount; }
    HTTPLib::http_encoding_t GetEncoding() const { return encoding; }

    const char * GetWebsocketKey() const { return websocketKey; }
    int GetWebsocketVersion() const { return websocketVersion; }
    const char * GetOrigin() const { return origin; }

    const HTTPLib::http_result_t * GetHTTPResultCode() const { return httpResultCode; }

    size_t GetHeaderSize() const { return 0; }
    char * MakeHeaderCopy() const { return nullptr; };
    void GetFieldListCopy(byte * & buffer, size_t & bufferSize) const;
};

This class will be used to parse a byte stream for a HTTP header and extract the fields / data from the header. Note that the byte stream must begin with a valid HTTP header, or an error will be returned.

Public functions

UHTTPParser

class UHTTPParser {
public:
    virtual ~UHTTPParser() {}
    virtual bool HTTPParserValidateRequest(class HTTPParser * httpParser) = 0;
};

This class is for passing a user to HTTPParser::ParseData(). After parsing the request line, UHTTPParser::HTTPParserValidateRequest() will be called. The app can check the request and validate it the HTTPParser continues with parsing the rest of the header. This can be done by checking the values of the given HTTPParser instance. Note that only the request type and the requested resource will be available at this point, but no header fields.

Public functions

HTTPHeaderField

class HTTPHeaderField {
public:
    const char * GetValue(size_t idx) const { return values[idx]; }
    size_t GetValueCount() const { return valueCount; }
};

Represents a HTTP header field and its values. Even if a field can have more values (that means, that field appears mutltiple times in the header), there also can be multiple values set, seperated by ';'. Those will be handled as one value only, so an app must seperate them if needed. An header field can be obtained by calling HTTPParser::GetHeaderField().

Public functions

HTTPRange

class HTTPRange {
public:
    HTTPRange() { this->next = NULL; }
    virtual ~HTTPRange() {}

    enum {
        RANGE_NONE        = 0x00,
        RANGE_START_END   = 0x01,
        RANGE_START_ONLY  = 0x02,
        RANGE_LAST_BYTES  = 0x03
    } rangeType;
    size_t start;
    size_t end;
    HTTPRange * next;
};

Represents the values of ranges send with an HTTP header. An instance of HTTPRange will be returned by HTTPParser::GetRange(). The retunred instance is the start of a linked list. So you must not call delete on it! HTTPParser itself will take care of releasing the objects when needed. The class itself has no functions. You have access directly to the fields of the class.

Data types

Defines / Statics

#define CLRF                 "\r\n"

#define HTTP_GET_KEY         "GET"       
#define HTTP_HEAD_KEY        "HEAD"      
#define HTTP_POST_KEY        "POST"      
#define HTTP_PUT_KEY         "PUT"       
#define HTTP_CONNECT_KEY     "CONNECT"   
#define HTTP_OPTIONS_KEY     "OPTIONS"   
#define HTTP_TRACE_KEY       "TRACE"     
#define HTTP_PROPFIND_KEY    "PROPFIND"
#define HTTP_MKCOL_KEY       "MKCOL"
#define HTTP_COPY_KEY        "COPY"
#define HTTP_MOVE_KEY        "MOVE"
#define HTTP_DELETE_KEY      "DELETE"
#define HTTP_LOCK_KEY        "LOCK"
#define HTTP_UNLOCK_KEY      "UNLOCK"
#define HTTP_PROPPATCH_KEY   "PROPPATCH"
#define HTTP_SYSCLIENT_KEY   "SYSCLIENT"

#define HTTP_VERSION_1_0    0x0100
#define HTTP_VERSION_1_1    0x0101

http_request_method_t

typedef enum {
    HTTP_NONE,
    HTTP_GET,
    HTTP_HEAD,
    HTTP_POST,
    HTTP_PUT,
    HTTP_CONNECT,
    HTTP_OPTIONS,
    HTTP_TRACE,
    HTTP_PROPFIND,
    HTTP_MKCOL,
    HTTP_COPY,
    HTTP_MOVE,
    HTTP_DELETE,
    HTTP_LOCK,
    HTTP_UNLOCK,
    HTTP_PROPPATCH,
    HTTP_SYSCLIENT
} http_request_method_t;

This enum is used to define the method to use for a HTTP request and must be one of the following:

http_connection_t

typedef enum {
    HTTP_CONNECTION_NONE = 0x00,
    HTTP_CONNECTION_KEEP_ALIVE = 0x01,
    HTTP_CONNECTION_CLOSE = 0x02,
    HTTP_CONNECTION_UPGRADE = 0x04
} http_connection_t;

This enum describes the type of a connection and must be one of the following:

http_upgrade_t

typedef enum {
    HTTP_UPGRADE_NONE,
    HTTP_UPGRADE_WEBSOCKET
} http_upgrade_t;

These are the upgrades the a request can define.

http_encoding_t

typedef enum {
    HTTP_ENCODING_NONE,      // Default
    HTTP_ENCODING_GZIP
} http_encoding_t;

These are the encoding types for a HTTP connection (the moment, only gzip is supported as special encoding).

http_result_t

typedef struct {
    int code;
    const char * description;
    size_t descLen;
} http_result_t;

This structure holds an HTTP result code in three parts: an integer value (easier to use for checking inside the code), a descroption string (actualle the one tha must be put to the header) and the length of the description. The HTTPLib defines constants for most of the result codes (see below). That constans can be used to pass to functions loke HTTPHeader::SetHTTPResult(). For more information about the resturn codes see RFC 7231, Page 41.

Code examples

// This example shows how to use the HTTP library to response to an incomming HTTP request.
// The class itself is a subclass of USocket (for receiving data) and UHTTPParser
// (to check the request and only accept GET requests).

void MyApp::SocketRecvResult(ISocket * const socket, void * buf, size_t len) {
    // parser is an HTTPParser instance of the object the function here is part of.
    this->parser->ParseData(buf, len, this);

    switch (this->parser->GetParseResult())
    {
        case HTTPParser::HTTP_PARSE_NEED_DATA:
            // More data need for the header. Note that we must make a partial Recv() call here.
            socket->Recv(buffer, 8192, true);
            break;

        case HTTPParser::HTTP_PARSE_ERROR:
            debug->printf("Error while parsing the HTTP header.");
            socket->Shutdown();
            break;

        case HTTPParser::HTTP_PARSE_CANCEL: // Unsupported request - see below
            debug->printf("Parsing canceled.");
            socket->Shutdown();
            break;

        case HTTPParser::HTTP_PARSE_DONE:
            this->ResponseGETRequest(socket);
            break;
    }
}


// The callback function from UHTTPParser. We only accept GET requests...
bool MyApp::HTTPParserValidateRequest(class HTTPParser * httpParser)
{
    if (httpParser->GetRequestMethod()) == HTTPLib::HTTP_GET) return true;
    
    debug->printf("Only GET requests are supported.");
    return false;
}


void MyApp::ResponseGETRequest(ISocket * socket)
{
    const char * responseData = "<!DOCTYPE html><html xmlns=\"http://www.w3.org/1999/xhtml\"><body>Hello World</body></html>"
    size_t responseLen = strlen(responseData);
    
    // Use the object on the stack - no need to delete it later.
    HTTPHeader header;
    header.SetHTTPVersion(this->parser->GetMajorVersion(), this->parser->GetMinorVersion());
    header.SetHTTPResult(&HTTPLib::HTTP_200);
    header.SetContentSize(responseLen);
    
    // Finally - send everything.
    socket->Send(header.GetHeaderData(), header.GetHeaderSize());
    socket->Send(responseData, responseLen);
}