KHTTP_BODY(3)

NAME
khttp_body, khttp_body_compress - close the HTTP header sequence for kcgi

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");

SEE ALSO
kcgi(3), khttp_head(3), zlib(3)

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