LIBRARY
Printer Application Framework (libpappl, "pkg-config --cflags --libs pappl")

SYNOPSIS
#include <pappl/pappl.h>

typedef struct _pappl_client_s pappl_client_t;

char *
papplClientGetCSRFToken(pappl_client_t *client, char *buffer, size_t bufsize);

char *
papplClientGetCookie(pappl_client_t *client, const char *name, char *buffer, size_t bufsize);

int
papplClientGetForm(pappl_client_t *client, cups_option_t **form);

const char *
papplClientGetHostName(pappl_client_t *client);

int
papplClientGetHostPort(pappl_client_t *client);

http_t *
papplClientGetHTTP(pappl_client_t *client);

pappl_job_t *
papplClientGetJob(pappl_client_t *client);

http_state_t
papplClientGetMethod(pappl_client_t *client);

ipp_op_t
papplClientGetOperation(pappl_client_t *client);

const char *
papplClientGetOptions(pappl_client_t *client);

pappl_printer_t *
papplClientGetPrinter(pappl_client_t *client);

ipp_t *
papplClientGetRequest(pappl_client_t *client);

ipp_t *
papplClientGetResponse(pappl_client_t *client);

pappl_system_t *
papplClientGetSystem(pappl_client_t *client);

const char *
papplClientGetURI(pappl_client_t *client);

const char *
papplClientGetUsername(pappl_client_t *client);

bool
papplClientHTMLAuthorize(pappl_client_t *client);

void
papplClientHTMLEscape(pappl_client_t *client, const char *s, size_t slen);

void
papplClientHTMLFooter(pappl_client_t *client);

void
papplClientHTMLHeader(pappl_client_t *client, const char *title, int refresh);

void
papplClientHTMLPrintf(pappl_client_t *client, const char *format, ...);

void
papplClientHTMLPuts(pappl_client_t *client, const char *s);

void
papplClientHTMLStartForm(pappl_client_t *client, const char *action, bool multipart);

http_status_t
papplClientIsAuthorized(pappl_client_t *client);

bool
papplClientRespond(pappl_client_t *client, http_status_t code, const char *content_coding, const char *type, time_t last_modified, size_t length);

ipp_t *
papplClientRespondIPP(pappl_client_t *client, ipp_status_t status, const char *message, ...);

bool
papplClientRespondRedirect(pappl_client_t *client, http_status_t code, const char *path);

void
papplClientSetCookie(pappl_client_t *client, const char * name, const char *value, int expires);

bool
papplClientValidateForm(pappl_client_t *client, int num_form, cups_option_t *form);

DESCRIPTION
The PAPPL client functions provide access to client connections. Client connections and the life cycle of the pappl_client_t objects are managed automatically by the system object for the printer application.

The papplClientGet functions get the current values for various client-supplied request data.

RESPONDING TO CLIENT REQUESTS
The papplClientRespond function starts a HTTP response to a client request. The papplClientHTMLHeader and papplClientHTMLFooter functions send standard HTML headers and footers for the printer application's configured web interface while the papplClientHTMLEscape, papplClientHTMLPrintf, papplClientHTMLPuts, and papplClientHTMLStartForm functions send HTML messages or strings. Use the papplClientGetHTTP and (CUPS) httpWrite2 functions to send arbitrary data in a client response. Cookies can be included in web browser requests using the papplClientSetCookie function.

The papplClientRespondIPP function starts an IPP response. Use the various CUPS ippAdd functions to add attributes to the response message.

The papplClientRespondRedirect function sends a redirection response to the client.

HTML FORMS
PAPPL provides the papplClientGetCSRFToken, papplClientGetForm, papplClientHTMLStartForm and papplClientValidateForm functions to securely manage HTML forms.

The papplClientHTMLStartForm function starts a HTML form and inserts a hidden variable containing a CSRF token that was generated by PAPPL from a secure session key that is periodically updated. Upon receipt of a follow-up form submission request, the papplClientGetForm and papplClientValidateForm functions can be used to securely read the form data (including any file attachments) and validate the hidden CSRF token.

AUTHENTICATION AND AUTHORIZATION
PAPPL supports both user-based authentication using PAM modules and a simple cookie-based password authentication mechanism that is used to limit administrative access through the web interface.

The papplHTMLAuthorize function authorizes access to the web interface and handles displaying an authentication form on the client's web browser. The return value indicates whether the client is authorized to access the web page.

The papplIsAuthorized function can be used to determine whether the current client is authorized to perform administrative operations and is normally only used for IPP clients. Local users are always authorized while remote users must provide credentials (typically a username and password) for access. This function will return an HTTP status code that can be provided to the httpClientSendResponse function. The value HTTP_STATUS_CONTINUE indicates that authorization is granted and the request should continue. The papplGetUsername function can be used to obtain the authenticated user identity.