NAME

khttp_body, khttp_body_compress — close the HTTP header sequence for kcgi

LIBRARY

library “libkcgi”

SYNOPSIS

#include <sys/types.h>
#include <stdarg.h>
#include <stdint.h>
#include <kcgi.h>

enum kcgi_err
khttp_body(struct kreq *req);

enum kcgi_err
khttp_body_compress(struct kreq *req, int compress);

DESCRIPTION

The khttp_body() and khttp_body_compress() functions terminate the zero or more khttp_head(3) calls for a kcgi(3) context req. After these functions, invoking khttp_head(3) or invoking khttp_body() or khttp_body_compress() again results in undefined behaviour.

The khttp_body() function checks whether compression should be enabled by examining request headers. If applicable, it emits the appropriate content encoding header and enables compressed output for subsequent khttp_write(3) calls.

The khttp_body_compress() function accepts the compress argument which, if zero, disables compressed output for subsequent khttp_write(3) calls. This is appropriate for caller-managed compression, such as when sending pre-compressed files. If non-zero, compressed output is enabled. In either case, content encoding headers must be managed by the caller.

RETURN VALUES

The khttp_body() and khttp_body_compress() functions return an enum kcgi_err indicating the error state.

KCGI_OK: Success (not an error).
KCGI_ENOMEM: Internal memory allocation failure.
KCGI_SYSTEM: Internal system error writing to the output stream.
KCGI_HUP: The output connection has been terminated. For FastCGI connections, the current connection should be released with khttp_free(3) and parse loop reentered.
KCGI_FORM: Returned by khttp_body_compress() if compression was requested but is not provided by the operating system.

EXAMPLES

Write out an HTTP header sequence and text content with automatic compression detection. Assume that r is a pointer to a struct kreq successfully initialised by khttp_parse(3).

khttp_head(r, kresps[KRESP_STATUS],
  "%s", khttps[KHTTP_200]);
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
  "%s", kmimetypes[KMIME_TEXT_PLAIN]);
khttp_body(r);
khttp_puts(r, "Hello, world!\n");

To explicitly disable compression:

khttp_head(r, kresps[KRESP_STATUS],
  "%s", khttps[KHTTP_200]);
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
  "%s", kmimetypes[KMIME_TEXT_PLAIN]);
khttp_body_compress(r, 0);
khttp_puts(r, "Hello, world!\n");

To disable compression, but emit a compressed file:

khttp_head(r, kresps[KRESP_STATUS],
  "%s", khttps[KHTTP_200]);
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
  "%s", kmimetypes[KMIME_TEXT_PLAIN]);
khttp_head(r, kresps[KRESP_CONTENT_ENCODING],
  "%s", "gzip");
khttp_body_compress(r, 0);
khttp_template(r, NULL, "compressed.txt.gz");

AUTHORS

The khttp_body() function was written by Kristaps Dzonsons <kristaps@bsd.lv>.