Provided by: libpappl-dev_1.3.1-2.1build3_amd64 
NAME
pappl-client - pappl client functions
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.
FUNCTIONS
papplClientGetCSRFToken
Get a unique Cross-Site Request Forgery token
string.
char * papplClientGetCSRFToken (
pappl_client_t *client,
char *buffer,
size_t bufsize
);
This function generates and returns a unique Cross-Site Request Forgery token string to be used as the
value of a hidden variable in all HTML forms sent in the response and then compared when validating the
form data in the subsequent request.
The value is based on the current system session key and client address in order to make replay attacks
infeasible.
5 Note: The papplClientHTMLStartForm function automatically adds the
5 hidden CSRF variable, and the papplClientIsValidForm function
5 validates the value.
papplClientGetCookie
Get a cookie from the client.
char * papplClientGetCookie (
pappl_client_t *client,
const char *name,
char *buffer,
size_t bufsize
);
This function gets a HTTP "cookie" value from the client request. NULL is returned if no cookie has been
set by a prior request, or if the user has disabled or removed the cookie.
Use the papplClientSetCookie function to set a cookie in a response to a request.
5 Note: Cookies set with papplClientSetCookie will not be available to
5 this function until the following request.
papplClientGetForm
Get form data from the web client.
int papplClientGetForm (
pappl_client_t *client,
cups_option_t **form
);
For HTTP GET requests, the form data is collected from the request URI. For HTTP POST requests, the form
data is read from the client.
The returned form values must be freed using the cupsFreeOptions function.
5 Note: Because the form data is read from the client connection, this
5 function can only be called once per request.
papplClientGetHTTP
Get the HTTP connection associated with a client
object.
http_t * papplClientGetHTTP (
pappl_client_t *client
);
This function returns the HTTP connection associated with the client and is used when sending response
data directly to the client using the CUPS httpXxx functions.
papplClientGetHostName
Get the hostname from the client-supplied Host:
field.
const char * papplClientGetHostName (
pappl_client_t *client
);
This function returns the hostname that was used in the request and should be used in any URLs or URIs
that you generate.
papplClientGetHostPort
Get the port from the client-supplied Host:
field.
int papplClientGetHostPort (
pappl_client_t *client
);
This function returns the port number that was used in the request and should be used in any URLs or URIs
that you generate.
papplClientGetJob
Get the target job for an IPP request.
pappl_job_t * papplClientGetJob (
pappl_client_t *client
);
This function returns the job associated with the current IPP request. NULL is returned if the request
does not target a job.
papplClientGetLoc
Get the localization data for a client connection.
pappl_loc_t * papplClientGetLoc (
pappl_client_t *client
);
papplClientGetLocString
Get a localized string for the client.
const char * papplClientGetLocString (
pappl_client_t *client,
const char *s
);
papplClientGetMethod
Get the HTTP request method.
http_state_t papplClientGetMethod (
pappl_client_t *client
);
This function returns the HTTP request method that was used, for example HTTP_STATE_GET for a GET request
or HTTP_STATE_POST for a POST request.
papplClientGetOperation
Get the IPP operation code.
ipp_op_t papplClientGetOperation (
pappl_client_t *client
);
This function returns the IPP operation code associated with the current IPP request.
papplClientGetOptions
Get the options from the request URI.
const char * papplClientGetOptions (
pappl_client_t *client
);
This function returns any options that were passed in the HTTP request URI. The options are the
characters after the "?" character, for example a request URI of "/mypage?name=value" will have an
options string of "name=value".
NULL is returned if the request URI did not contain any options.
5 Note: HTTP GET form variables are normally accessed using the
5 papplClientGetForm function. This function should only be used when
5 getting non-form data.
papplClientGetPrinter
Get the target printer for an IPP request.
pappl_printer_t * papplClientGetPrinter (
pappl_client_t *client
);
This function returns the printer associated with the current IPP request. NULL is returned if the
request does not target a printer.
papplClientGetRequest
Get the IPP request message.
ipp_t * papplClientGetRequest (
pappl_client_t *client
);
This function returns the attributes in the current IPP request, for use with the CUPS ippFindAttribute,
ippFindNextAttribute, ippFirstAttribute, and ippNextAttribute functions.
papplClientGetResponse
Get the IPP response message.
ipp_t * papplClientGetResponse (
pappl_client_t *client
);
This function returns the attributes in the current IPP response, for use with the CUPS ippAddXxx and
ippSetXxx functions. Use the papplClientRespondIPP function to set the status code and message, if any.
papplClientGetSystem
Get the containing system for the client.
pappl_system_t * papplClientGetSystem (
pappl_client_t *client
);
This function returns the system object that contains the client.
papplClientGetURI
Get the HTTP request URI.
const char * papplClientGetURI (
pappl_client_t *client
);
This function returns the URI that was sent in the current HTTP request.
5 Note: Any options in the URI are removed and can be accessed separately
5 using the papplClientGetOptions function.
papplClientGetUsername
Get the authenticated username, if any.
const char * papplClientGetUsername (
pappl_client_t *client
);
This function returns the current authenticated username, if any.
papplClientHTMLAuthorize
Handle authorization for the web interface.
bool papplClientHTMLAuthorize (
pappl_client_t *client
);
The web interface supports both authentication against user accounts and authentication using a single
administrative access password. This function handles the details of authentication for the web
interface based on the system authentication service configuration = the "auth_service" argument to
papplSystemCreate and any callback set using papplSystemSetAuthCallback.
5 Note: IPP operation callbacks needing to perform authorization should use
5 the papplClientIsAuthorized function instead.
papplClientHTMLEscape
Send a string to a web browser client.
void papplClientHTMLEscape (
pappl_client_t *client,
const char *s,
size_t slen
);
This function sends the specified string to the web browser client and escapes special characters as HTML
entities as needed, for example "&" is sent as &.
papplClientHTMLFooter
Show the web interface footer.
void papplClientHTMLFooter (
pappl_client_t *client
);
This function sends the standard web interface footer followed by a trailing 0-length chunk to finish the
current HTTP response. Use the papplSystemSetFooterHTML function to add any custom HTML needed in the
footer.
papplClientHTMLHeader
Show the web interface header and title.
void papplClientHTMLHeader (
pappl_client_t *client,
const char *title,
int refresh
);
This function sends the standard web interface header and title. If the "refresh" argument is greater
than zero, the page will automatically reload after that many seconds.
Use the papplSystemAddLink function to add system-wide navigation links to the header. Similarly, use
papplPrinterAddLink to add printer-specific links, which will appear in the web interface printer if the
system is not configured to support multiple printers (the PAPPL_SOPTIONS_MULTI_QUEUE option to
papplSystemCreate).
papplClientHTMLPrinterFooter
Show the web interface footer for printers.
void papplClientHTMLPrinterFooter (
pappl_client_t *client
);
This function sends the standard web interface footer for a printer followed by a trailing 0-length chunk
to finish the current HTTP response. Use the papplSystemSetFooterHTML function to add any custom HTML
needed in the footer.
papplClientHTMLPrinterHeader
Show the web interface header and title
for printers.
void papplClientHTMLPrinterHeader (
pappl_client_t *client,
pappl_printer_t *printer,
const char *title,
int refresh,
const char *label,
const char *path_or_url
);
This function sends the standard web interface header and title for a printer. If the "refresh" argument
is greater than zero, the page will automatically reload after that many seconds.
If "label" and "path_or_url" are non-NULL strings, an additional navigation link is included with the
title header - this is typically used for an action button ("Change").
Use the papplSystemAddLink function to add system-wide navigation links to the header. Similarly, use
papplPrinterAddLink to add printer-specific links, which will appear in the web interface printer if the
system is not configured to support multiple printers (the PAPPL_SOPTIONS_MULTI_QUEUE option to
papplSystemCreate).
papplClientHTMLPrintf
Send formatted text to the web browser client,
escaping as needed.
void papplClientHTMLPrintf (
pappl_client_t *client,
const char *format,
...
);
This function sends formatted text to the web browser client using printf-style formatting codes. The
format string itself is not escaped to allow for embedded HTML, however strings inserted using the '%c'
or %s codes are escaped properly for HTML - "&" is sent as &, etc.
papplClientHTMLPuts
Send a HTML string to the web browser client.
void papplClientHTMLPuts (
pappl_client_t *client,
const char *s
);
This function sends a HTML string to the client without performing any escaping of special characters.
papplClientHTMLStartForm
Start a HTML form.
void papplClientHTMLStartForm (
pappl_client_t *client,
const char *action,
bool multipart
);
This function starts a HTML form with the specified "action" path and includes the CSRF token as a hidden
variable. If the "multipart" argument is true, the form is annotated to support file attachments up to
2MiB in size.
papplClientIsAuthorized
Determine whether a client is authorized for
administrative requests.
http_status_t papplClientIsAuthorized (
pappl_client_t *client
);
This function determines whether a client is authorized to submit an administrative request.
The return value is HTTP_STATUS_CONTINUE if access is authorized, HTTP_STATUS_FORBIDDEN if access is not
allowed, HTTP_STATUS_UNAUTHORIZED if authorization is required, or HTTP_STATUS_UPGRADE_REQUIRED if the
connection needs to be encrypted. All of these values can be passed to the papplClientRespond function.
papplClientIsEncrypted
Return whether a Client connection is encrypted.
bool papplClientIsEncrypted (
pappl_client_t *client
);
This function returns a boolean value indicating whether a Client connection is encrypted with TLS.
papplClientIsValidForm
Validate HTML form variables.
bool papplClientIsValidForm (
pappl_client_t *client,
int num_form,
cups_option_t *form
);
This function validates the contents of a HTML form using the CSRF token included as a hidden variable.
When sending a HTML form you should use the papplClientStartForm function to start the HTML form and
insert the CSRF token for later validation.
5 Note: Callers are expected to validate all other form variables.
papplClientRespond
Send a regular HTTP response.
bool papplClientRespond (
pappl_client_t *client,
http_status_t code,
const char *content_encoding,
const char *type,
time_t last_modified,
size_t length
);
This function sends all of the required HTTP fields and includes standard messages for errors. The
following values for "code" are explicitly supported:
• HTTP_STATUS_OK: The request is successful.
• HTTP_STATUS_BAD_REQUEST: The client submitted a bad request.
• HTTP_STATUS_CONTINUE: An authentication challenge is not needed.
• HTTP_STATUS_FORBIDDEN: Authenticated but not allowed.
• HTTP_STATUS_METHOD_NOT_ALLOWED: The HTTP method is not supported for the
given URI.
• HTTP_STATUS_UNAUTHORIZED: Not authenticated.
• HTTP_STATUS_UPGRADE_REQUIRED: Redirects the client to a secure page.
Use the papplClientRespondRedirect when you need to redirect the client to another page.
papplClientRespondIPP
Send an IPP response.
ipp_t * papplClientRespondIPP (
pappl_client_t *client,
ipp_status_t status,
const char *message,
...
);
This function sets the return status for an IPP request and returns the current IPP response message.
The "status" and "message" arguments replace any existing status-code and "status-message" attribute
value that may be already present in the response.
5 Note: You should call this function prior to adding any response
5 attributes.
papplClientRespondIPPUnsupported
Respond with an unsupported IPP attribute.
void papplClientRespondIPPUnsupported (
pappl_client_t *client,
ipp_attribute_t *attr
);
This function returns a 'client-error-attributes-or-values-not-supported' status code and adds the
specified attribute to the unsupported attributes group in the response.
papplClientRespondRedirect
Respond with a redirect to another page.
bool papplClientRespondRedirect (
pappl_client_t *client,
http_status_t code,
const char *path
);
This function sends a HTTP response that redirects the client to another page or URL. The most common
"code" value to return is HTTP_STATUS_FOUND.
papplClientSetCookie
Set a cookie for the web browser client.
void papplClientSetCookie (
pappl_client_t *client,
const char *name,
const char *value,
int expires
);
This function sets the value of a cookie for the client by updating the Set-Cookie header in the HTTP
response that will be sent. The "name" and "value" strings must contain only valid characters for a
cookie and its value as documented in RFC 6265, which basically means letters, numbers, "@", "-", ".",
and "_".
The "expires" argument specifies how long the cookie will remain active in seconds, for example 3600
seconds is one hour and 86400 seconds is one day. If the value is zero or less, a "session" cookie is
created instead which will expire as soon as the web browser is closed.
papplClientSetUsername
Set the authenticated username, if any.
void papplClientSetUsername (
pappl_client_t *client,
const char *username
);
This function sets the current authenticated username, if any.
SEE ALSO
pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3), pappl-mainline(3), pappl-
makeresheader(1), pappl-printer(3), pappl-resource(3), pappl-system(3), https://www.msweet.org/pappl
COPYRIGHT
Copyright © 2019-2022 by Michael R Sweet.
PAPPL is licensed under the Apache License Version 2.0 with an (optional) exception to allow linking
against GPL2/LGPL2 software (like older versions of CUPS), so it can be used freely in any project you'd
like. See the files "LICENSE" and "NOTICE" in the source distribution for more information.
2022-11-07 pappl client functions pappl-client(3)