HTTP Message Functions

gxsHTTPMessage holds an HTTP/1.1 request or response. The read and write functions work over any gxsTLSConnection, client or server.

Contents

Overview
gxsHTTPMessage Functions
Read and Write Functions

Overview

A gxsHTTPMessage has a request line (method, target) or a status line (status, reason), headers, and a body. Header names are matched without regard to case. The read functions handle Content-Length and chunked bodies and limit header and body sizes; the write functions set Content-Length from the body and refuse CR or LF in header names and values (header injection).

The HTTPS client gxsHTTPClient uses these functions, and so does the example HTTPS server in examples/tls/https_server.cpp:

gxsHTTPMessage req, resp;
if(gxsHTTPReadRequest(conn, req) == 0) {
  resp.status = 200;
  resp.SetHeader("Content-Type", "text/plain");
  resp.body = "Hello over HTTPS\n";
  gxsHTTPWriteResponse(conn, resp);
}

gxsHTTPMessage Functions

std::string gxsHTTPMessage::Header(std::string_view name) const

Value of the first header with this name, or an empty string.

bool gxsHTTPMessage::HasHeader(std::string_view name) const

True if the header is present.

void gxsHTTPMessage::SetHeader(std::string_view name, std::string_view value)

Replaces any headers with this name.

void gxsHTTPMessage::AddHeader(std::string_view name, std::string_view value)

Adds a header, keeping existing ones (for Set-Cookie and similar).

void gxsHTTPMessage::RemoveHeader(std::string_view name)

Removes every header with this name.

void gxsHTTPMessage::Clear()

Resets the message.

Read and Write Functions

int gxsHTTPWriteRequest(gxsTLSConnection &conn, gxsHTTPMessage &msg)

Writes a request. Returns 0 if successful.

int gxsHTTPWriteResponse(gxsTLSConnection &conn, gxsHTTPMessage &msg)

Writes a response. An empty body keeps a Content-Length the caller set, as a response to HEAD needs.

int gxsHTTPReadRequest(gxsTLSConnection &conn, gxsHTTPMessage &msg, std::size_t max_body = 16*1024*1024)

Reads a request and its body.

int gxsHTTPReadResponse(gxsTLSConnection &conn, gxsHTTPMessage &msg, bool head_request = false, std::size_t max_body = 1024*1024*1024)

Reads a response, skipping 1xx responses. Pass head_request for a response to HEAD, which has no body.

const char *gxsHTTPStatusCodeMessage(int status)

Standard reason phrase for a status code.