NAME

Http — Encode and decode various parts of the HTTP protocol.

SYNOPSIS

#include <Http.h>

const char *
HttpStatusToString(const HttpStatus);

HttpRequestMethod
HttpRequestMethodFromString(const char *);

const char *
HttpRequestMethodToString(const HttpRequestMethod);

char *
HttpUrlEncode(char *);

char *
HttpUrlDecode(char *);

HashMap *
HttpParamDecode(char *);

char *
HttpParamEncode(HashMap *);

DESCRIPTION

Http is a collection of utility functions that are useful for dealing with HTTP. HTTP is not a complex protocol, but this API makes it a lot easier to work with.

HttpStatusToString() takes an HttpStatus and converts it into a string description of the status, which is to be used in an HTTP response. For example, calling HttpStatusToString(HTTP_GATEWAY_TIMEOUT) produces the string "Gateway Timeout".

HttpStatus is an enumeration that corresponds to the actual integer values of the valid HTTP response codes. For example, calling HttpStatusToString(504) produces the same output. HttpStatus is defined as follows:

typedef enum HttpStatus
{
    /* Informational responses */
    HTTP_CONTINUE = 100,
    HTTP_SWITCHING_PROTOCOLS = 101,
    HTTP_EARLY_HINTS = 103,

    /* Successful responses */
    HTTP_OK = 200,
    HTTP_CREATED = 201,
    HTTP_ACCEPTED = 202,
    HTTP_NON_AUTHORITATIVE_INFORMATION = 203,
    HTTP_NO_CONTENT = 204,
    HTTP_RESET_CONTENT = 205,
    HTTP_PARTIAL_CONTENT = 206,

    /* Redirection messages */
    HTTP_MULTIPLE_CHOICES = 300,
    HTTP_MOVED_PERMANENTLY = 301,
    HTTP_FOUND = 302,
    HTTP_SEE_OTHER = 303,
    HTTP_NOT_MODIFIED = 304,
    HTTP_TEMPORARY_REDIRECT = 307,
    HTTP_PERMANENT_REDIRECT = 308,

    /* Client error messages */
    HTTP_BAD_REQUEST = 400,
    HTTP_UNAUTHORIZED = 401,
    HTTP_FORBIDDEN = 403,
    HTTP_NOT_FOUND = 404,
    HTTP_METHOD_NOT_ALLOWED = 405,
    HTTP_NOT_ACCEPTABLE = 406,
    HTTP_PROXY_AUTH_REQUIRED = 407,
    HTTP_REQUEST_TIMEOUT = 408,
    HTTP_CONFLICT = 409,
    HTTP_GONE = 410,
    HTTP_LENGTH_REQUIRED = 411,
    HTTP_PRECONDITION_FAILED = 412,
    HTTP_PAYLOAD_TOO_LARGE = 413,
    HTTP_URI_TOO_LONG = 414,
    HTTP_UNSUPPORTED_MEDIA_TYPE = 415,
    HTTP_RANGE_NOT_SATISFIABLE = 416,
    HTTP_EXPECTATION_FAILED = 417,
    HTTP_TEAPOT = 418,
    HTTP_UPGRADE_REQUIRED = 426,
    HTTP_PRECONDITION_REQUIRED = 428,
    HTTP_TOO_MANY_REQUESTS = 429,
    HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = 431,
    HTTP_UNAVAILABLE_FOR_LEGAL_REASONS = 451,

    /* Server error responses */
    HTTP_INTERNAL_SERVER_ERROR = 500,
    HTTP_NOT_IMPLEMENTED = 501,
    HTTP_BAD_GATEWAY = 502,
    HTTP_SERVICE_UNAVAILABLE = 503,
    HTTP_GATEWAY_TIMEOUT = 504,
    HTTP_VERSION_NOT_SUPPORTED = 505,
    HTTP_VARIANT_ALSO_NEGOTIATES = 506,
    HTTP_NOT_EXTENDED = 510,
    HTTP_NETWORK_AUTH_REQUIRED = 511
} HttpStatus;

HttpRequestMethodFromString() and HttpRequestMethodToString() convert an HttpRequestMethod enumeration value from and to a string, respectively. The HttpRequestMethod enumeration is defined as follows:

typedef enum HttpRequestMethod
{
	HTTP_METHOD_UNKNOWN,
	HTTP_GET,
	HTTP_HEAD,
	HTTP_POST,
	HTTP_PUT,
	HTTP_DELETE,
	HTTP_CONNECT,
	HTTP_OPTIONS,
	HTTP_TRACE,
	HTTP_PATCH
} HttpRequestMethod;

These can be used for parsing a request method and then storing it efficiently; it doesn't have be stored as a string, and it's much nicer to work with enumeration values than it is with strings in C. The very first enumeration value is not to be passed to HttpRequestMethodToString(), rather it may be returned by HttpRequestMethodFromString() if it cannot identify the request method string passed to it.

HttpUrlEncode() and HttpUrlDecode() deal with URL-safe strings. HttpUrlEncode() encodes a C string such that it can appear in a URL, and HttpUrlDecode() does the opposite; it decodes a URL string into the actual bytes it is supposed to represent.

HttpParamDecode() and HttpParamEncode() convert HTTP parameters in the form of "param=value&param2=val2" to and from a hash map for easy parsing, manipulation, and encoding.

RETURN VALUES

HttpStatusToString() and HttpRequestMethodToString() both return constant strings; they are not to be manipulated because doing so would result in a segmentation fault, as these strings are stored in the data segment of the program.

HttpUrlEncode(), HttpUrlDecode(), HttpParamDecode(), and HttpParamEncode() all return strings that were allocated on the heap using the Memory API, or NULL if there was an error allocating memory. Thee strings returned can be manipulated at will, and must be freed using the Memory API when they're no longer needed.

SEE ALSO

HashMap(3), Memory(3)