1pappl-client(3) pappl client functions pappl-client(3)
2
6 pappl-client - pappl client functions
7
9 Printer Application Framework (libpappl, "pkg-config --cflags --libs
10 pappl")
11
14 #include <pappl/pappl.h>
15 typedef struct _pappl_client_s pappl_client_t;
17 char *
19 papplClientGetCSRFToken(pappl_client_t *client, char *buffer, size_t
20 bufsize);
21 char *
23 papplClientGetCookie(pappl_client_t *client, const char *name, char
24 *buffer, size_t bufsize);
25 int
27 papplClientGetForm(pappl_client_t *client, cups_option_t **form);
28 const char *
30 papplClientGetHostName(pappl_client_t *client);
31 int
33 papplClientGetHostPort(pappl_client_t *client);
34 http_t *
36 papplClientGetHTTP(pappl_client_t *client);
37 pappl_job_t *
39 papplClientGetJob(pappl_client_t *client);
40 http_state_t
42 papplClientGetMethod(pappl_client_t *client);
43 ipp_op_t
45 papplClientGetOperation(pappl_client_t *client);
46 const char *
48 papplClientGetOptions(pappl_client_t *client);
49 pappl_printer_t *
51 papplClientGetPrinter(pappl_client_t *client);
52 ipp_t *
54 papplClientGetRequest(pappl_client_t *client);
55 ipp_t *
57 papplClientGetResponse(pappl_client_t *client);
58 pappl_system_t *
60 papplClientGetSystem(pappl_client_t *client);
61 const char *
63 papplClientGetURI(pappl_client_t *client);
64 const char *
66 papplClientGetUsername(pappl_client_t *client);
67 bool
69 papplClientHTMLAuthorize(pappl_client_t *client);
70 void
72 papplClientHTMLEscape(pappl_client_t *client, const char *s, size_t
73 slen);
74 void
76 papplClientHTMLFooter(pappl_client_t *client);
77 void
79 papplClientHTMLHeader(pappl_client_t *client, const char *title, int
80 refresh);
81 void
83 papplClientHTMLPrintf(pappl_client_t *client, const char *format, ...);
84 void
86 papplClientHTMLPuts(pappl_client_t *client, const char *s);
87 void
89 papplClientHTMLStartForm(pappl_client_t *client, const char *action,
90 bool multipart);
91 http_status_t
93 papplClientIsAuthorized(pappl_client_t *client);
94 bool
96 papplClientRespond(pappl_client_t *client, http_status_t code, const
97 char *content_coding, const char *type, time_t last_modified, size_t
98 length);
99 ipp_t *
101 papplClientRespondIPP(pappl_client_t *client, ipp_status_t status,
102 const char *message, ...);
103 bool
105 papplClientRespondRedirect(pappl_client_t *client, http_status_t code,
106 const char *path);
107 void
109 papplClientSetCookie(pappl_client_t *client, const char * name, const
110 char *value, int expires);
111 bool
113 papplClientValidateForm(pappl_client_t *client, int num_form, cups_op‐
114 tion_t *form);
115
118 The PAPPL client functions provide access to client connections.
119 Client connections and the life cycle of the pappl_client_t objects are
120 managed automatically by the system object for the printer application.
121 The papplClientGet functions get the current values for various client-
123 supplied request data.
124
126 The papplClientRespond function starts a HTTP response to a client re‐
127 quest. The papplClientHTMLHeader and papplClientHTMLFooter functions
128 send standard HTML headers and footers for the printer application's
129 configured web interface while the papplClientHTMLEscape, papplClien‐
130 tHTMLPrintf, papplClientHTMLPuts, and papplClientHTMLStartForm func‐
131 tions send HTML messages or strings. Use the papplClientGetHTTP and
132 (CUPS) httpWrite2 functions to send arbitrary data in a client re‐
133 sponse. Cookies can be included in web browser requests using the pap‐
134 plClientSetCookie function.
135 The papplClientRespondIPP function starts an IPP response. Use the
137 various CUPS ippAdd functions to add attributes to the response mes‐
138 sage.
139 The papplClientRespondRedirect function sends a redirection response to
141 the client.
142
145 PAPPL provides the papplClientGetCSRFToken, papplClientGetForm, pap‐
146 plClientHTMLStartForm and papplClientValidateForm functions to securely
147 manage HTML forms.
148 The papplClientHTMLStartForm function starts a HTML form and inserts a
150 hidden variable containing a CSRF token that was generated by PAPPL
151 from a secure session key that is periodically updated. Upon receipt
152 of a follow-up form submission request, the papplClientGetForm and pap‐
153 plClientValidateForm functions can be used to securely read the form
154 data (including any file attachments) and validate the hidden CSRF to‐
155 ken.
156
159 PAPPL supports both user-based authentication using PAM modules and a
160 simple cookie-based password authentication mechanism that is used to
161 limit administrative access through the web interface.
162 The papplHTMLAuthorize function authorizes access to the web interface
164 and handles displaying an authentication form on the client's web
165 browser. The return value indicates whether the client is authorized
166 to access the web page.
167 The papplIsAuthorized function can be used to determine whether the
169 current client is authorized to perform administrative operations and
170 is normally only used for IPP clients. Local users are always autho‐
171 rized while remote users must provide credentials (typically a username
172 and password) for access. This function will return an HTTP status
173 code that can be provided to the httpClientSendResponse function. The
174 value HTTP_STATUS_CONTINUE indicates that authorization is granted and
175 the request should continue. The papplGetUsername function can be used
176 to obtain the authenticated user identity.
177
179 papplClientGetCSRFToken
180 Get a unique Cross-Site Request Forgery token string.
181 char * papplClientGetCSRFToken (
183 pappl_client_t *client,
184 char *buffer,
185 size_t bufsize
186 );
187 This function generates and returns a unique Cross-Site Request Forgery
189 token string to be used as the value of a hidden variable in all HTML
190 forms sent in the response and then compared when validating the form
191 data in the subsequent request.
192 The value is based on the current system session key and client address
194 in order to make replay attacks infeasible.
195 5 Note: The papplClientHTMLStartForm function automatically adds
197 the
198 5 hidden CSRF variable, and the papplClientIsValidForm function
200 5 validates the value.
202 papplClientGetCookie
204 Get a cookie from the client.
205 char * papplClientGetCookie (
207 pappl_client_t *client,
208 const char *name,
209 char *buffer,
210 size_t bufsize
211 );
212 This function gets a HTTP "cookie" value from the client request. NULL
214 is returned if no cookie has been set by a prior request, or if the
215 user has disabled or removed the cookie.
216 Use the papplClientSetCookie function to set a cookie in a response to
218 a request.
219 5 Note: Cookies set with papplClientSetCookie will not be avail‐
221 able to
222 5 this function until the following request.
224 papplClientGetForm
226 Get form data from the web client.
227 int papplClientGetForm (
229 pappl_client_t *client,
230 cups_option_t **form
231 );
232 For HTTP GET requests, the form data is collected from the request URI.
234 For HTTP POST requests, the form data is read from the client.
235 The returned form values must be freed using the cupsFreeOptions func‐
237 tion.
238 5 Note: Because the form data is read from the client connection,
240 this
241 5 function can only be called once per request.
243 papplClientGetHTTP
245 Get the HTTP connection associated with a client object.
246 http_t * papplClientGetHTTP (
248 pappl_client_t *client
249 );
250 This function returns the HTTP connection associated with the client
252 and is used when sending response data directly to the client using the
253 CUPS httpXxx functions.
254 papplClientGetHostName
256 Get the hostname from the client-supplied Host: field.
257 const char * papplClientGetHostName (
259 pappl_client_t *client
260 );
261 This function returns the hostname that was used in the request and
263 should be used in any URLs or URIs that you generate.
264 papplClientGetHostPort
266 Get the port from the client-supplied Host: field.
267 int papplClientGetHostPort (
269 pappl_client_t *client
270 );
271 This function returns the port number that was used in the request and
273 should be used in any URLs or URIs that you generate.
274 papplClientGetJob
276 Get the target job for an IPP request.
277 pappl_job_t * papplClientGetJob (
279 pappl_client_t *client
280 );
281 This function returns the job associated with the current IPP request.
283 NULL is returned if the request does not target a job.
284 papplClientGetMethod
286 Get the HTTP request method.
287 http_state_t papplClientGetMethod (
289 pappl_client_t *client
290 );
291 This function returns the HTTP request method that was used, for exam‐
293 ple HTTP_STATE_GET for a GET request or HTTP_STATE_POST for a POST re‐
294 quest.
295 papplClientGetOperation
297 Get the IPP operation code.
298 ipp_op_t papplClientGetOperation (
300 pappl_client_t *client
301 );
302 This function returns the IPP operation code associated with the cur‐
304 rent IPP request.
305 papplClientGetOptions
307 Get the options from the request URI.
308 const char * papplClientGetOptions (
310 pappl_client_t *client
311 );
312 This function returns any options that were passed in the HTTP request
314 URI. The options are the characters after the "?" character, for exam‐
315 ple a request URI of "/mypage?name=value" will have an options string
316 of "name=value".
317 NULL is returned if the request URI did not contain any options.
319 5 Note: HTTP GET form variables are normally accessed using the
321 5 papplClientGetForm function. This function should only be used
323 when
324 5 getting non-form data.
326 papplClientGetPrinter
328 Get the target printer for an IPP request.
329 pappl_printer_t * papplClientGetPrinter (
331 pappl_client_t *client
332 );
333 This function returns the printer associated with the current IPP re‐
335 quest. NULL is returned if the request does not target a printer.
336 papplClientGetRequest
338 Get the IPP request message.
339 ipp_t * papplClientGetRequest (
341 pappl_client_t *client
342 );
343 This function returns the attributes in the current IPP request, for
345 use with the CUPS ippFindAttribute, ippFindNextAttribute, ippFirstAt‐
346 tribute, and ippNextAttribute functions.
347 papplClientGetResponse
349 Get the IPP response message.
350 ipp_t * papplClientGetResponse (
352 pappl_client_t *client
353 );
354 This function returns the attributes in the current IPP response, for
356 use with the CUPS ippAddXxx and ippSetXxx functions. Use the pap‐
357 plClientRespondIPP function to set the status code and message, if any.
358 papplClientGetSystem
360 Get the containing system for the client.
361 pappl_system_t * papplClientGetSystem (
363 pappl_client_t *client
364 );
365 This function returns the system object that contains the client.
367 papplClientGetURI
369 Get the HTTP request URI.
370 const char * papplClientGetURI (
372 pappl_client_t *client
373 );
374 This function returns the URI that was sent in the current HTTP re‐
376 quest.
377 5 Note: Any options in the URI are removed and can be accessed
379 separately
380 5 using the papplClientGetOptions function.
382 papplClientGetUsername
384 Get the authenticated username, if any.
385 const char * papplClientGetUsername (
387 pappl_client_t *client
388 );
389 This function returns the current authenticated username, if any.
391 papplClientHTMLAuthorize
393 Handle authorization for the web interface.
394 bool papplClientHTMLAuthorize (
396 pappl_client_t *client
397 );
398 The web interface supports both authentication against user accounts
400 and authentication using a single administrative access password. This
401 function handles the details of authentication for the web interface
402 based on the system authentication service configuration (the
403 "auth_service" argument to papplSystemCreate).
404 5 Note: IPP operation callbacks needing to perform authorization
406 should use
407 5 the papplClientIsAuthorized function instead.
409 papplClientHTMLEscape
411 Send a string to a web browser client.
412 void papplClientHTMLEscape (
414 pappl_client_t *client,
415 const char *s,
416 size_t slen
417 );
418 This function sends the specified string to the web browser client and
420 escapes special characters as HTML entities as needed, for example "&"
421 is sent as &.
422 papplClientHTMLFooter
424 Show the web interface footer.
425 void papplClientHTMLFooter (
427 pappl_client_t *client
428 );
429 This function sends the standard web interface footer followed by a
431 trailing 0-length chunk to finish the current HTTP response. Use the
432 papplSystemSetFooterHTML function to add any custom HTML needed in the
433 footer.
434 papplClientHTMLHeader
436 Show the web interface header and title.
437 void papplClientHTMLHeader (
439 pappl_client_t *client,
440 const char *title,
441 int refresh
442 );
443 This function sends the standard web interface header and title. If
445 the "refresh" argument is greater than zero, the page will automati‐
446 cally reload after that many seconds.
447 Use the papplSystemAddLink function to add system-wide navigation links
449 to the header. Similarly, use papplPrinterAddLink to add printer-spe‐
450 cific links, which will appear in the web interface printer if the sys‐
451 tem is not configured to support multiple printers (the PAPPL_SOP‐
452 TIONS_MULTI_QUEUE option to papplSystemCreate).
453 papplClientHTMLPrinterFooter
455 Show the web interface footer for printers.
456 void papplClientHTMLPrinterFooter (
458 pappl_client_t *client
459 );
460 This function sends the standard web interface footer for a printer
462 followed by a trailing 0-length chunk to finish the current HTTP re‐
463 sponse. Use the papplSystemSetFooterHTML function to add any custom
464 HTML needed in the footer.
465 papplClientHTMLPrinterHeader
467 Show the web interface header and title for printers.
468 void papplClientHTMLPrinterHeader (
470 pappl_client_t *client,
471 pappl_printer_t *printer,
472 const char *title,
473 int refresh,
474 const char *label,
475 const char *path_or_url
476 );
477 This function sends the standard web interface header and title for a
479 printer. If the "refresh" argument is greater than zero, the page will
480 automatically reload after that many seconds.
481 If "label" and "path_or_url" are non-NULL strings, an additional navi‐
483 gation link is included with the title header - this is typically used
484 for an action button ("Change").
485 Use the papplSystemAddLink function to add system-wide navigation links
487 to the header. Similarly, use papplPrinterAddLink to add printer-spe‐
488 cific links, which will appear in the web interface printer if the sys‐
489 tem is not configured to support multiple printers (the PAPPL_SOP‐
490 TIONS_MULTI_QUEUE option to papplSystemCreate).
491 papplClientHTMLPrintf
493 Send formatted text to the web browser client, escaping as needed.
494 void papplClientHTMLPrintf (
496 pappl_client_t *client,
497 const char *format,
498 ...
499 );
500 This function sends formatted text to the web browser client using
502 printf-style formatting codes. The format string itself is not escaped
503 to allow for embedded HTML, however strings inserted using the '%c' or
504 %s codes are escaped properly for HTML - "&" is sent as &, etc.
505 papplClientHTMLPuts
507 Send a HTML string to the web browser client.
508 void papplClientHTMLPuts (
510 pappl_client_t *client,
511 const char *s
512 );
513 This function sends a HTML string to the client without performing any
515 escaping of special characters.
516 papplClientHTMLStartForm
518 Start a HTML form.
519 void papplClientHTMLStartForm (
521 pappl_client_t *client,
522 const char *action,
523 bool multipart
524 );
525 This function starts a HTML form with the specified "action" path and
527 includes the CSRF token as a hidden variable. If the "multipart" argu‐
528 ment is true, the form is annotated to support file attachments up to
529 2MiB in size.
530 papplClientIsAuthorized
532 Determine whether a client is authorized for administrative requests.
533 http_status_t papplClientIsAuthorized (
535 pappl_client_t *client
536 );
537 This function determines whether a client is authorized to submit an
539 administrative request.
540 The return value is HTTP_STATUS_CONTINUE if access is authorized,
542 HTTP_STATUS_FORBIDDEN if access is not allowed, HTTP_STATUS_UNAUTHO‐
543 RIZED if authorization is required, or HTTP_STATUS_UPGRADE_REQUIRED if
544 the connection needs to be encrypted. All of these values can be
545 passed to the papplClientRespond function.
546 papplClientIsValidForm
548 Validate HTML form variables.
549 bool papplClientIsValidForm (
551 pappl_client_t *client,
552 int num_form,
553 cups_option_t *form
554 );
555 This function validates the contents of a HTML form using the CSRF to‐
557 ken included as a hidden variable. When sending a HTML form you should
558 use the papplClientStartForm function to start the HTML form and insert
559 the CSRF token for later validation.
560 5 Note: Callers are expected to validate all other form variables.
562 papplClientRespond
564 Send a regular HTTP response.
565 bool papplClientRespond (
567 pappl_client_t *client,
568 http_status_t code,
569 const char *content_encoding,
570 const char *type,
571 time_t last_modified,
572 size_t length
573 );
574 This function sends all of the required HTTP fields and includes stan‐
576 dard messages for errors. The following values for "code" are explic‐
577 itly supported:
578 • HTTP_STATUS_OK: The request is successful.
580 • HTTP_STATUS_BAD_REQUEST: The client submitted a bad request.
582 • HTTP_STATUS_CONTINUE: An authentication challenge is not needed.
584 • HTTP_STATUS_FORBIDDEN: Authenticated but not allowed.
586 • HTTP_STATUS_METHOD_NOT_ALLOWED: The HTTP method is not supported
588 for the given URI.
589 • HTTP_STATUS_UNAUTHORIZED: Not authenticated.
591 • HTTP_STATUS_UPGRADE_REQUIRED: Redirects the client to a secure
593 page.
594 Use the papplClientRespondRedirect when you need to redirect the client
596 to another page.
597 papplClientRespondIPP
599 Send an IPP response.
600 ipp_t * papplClientRespondIPP (
602 pappl_client_t *client,
603 ipp_status_t status,
604 const char *message,
605 ...
606 );
607 This function sets the return status for an IPP request and returns the
609 current IPP response message. The "status" and "message" arguments re‐
610 place any existing status-code and "status-message" attribute value
611 that may be already present in the response.
612 5 Note: You should call this function prior to adding any response
614 5 attributes.
616 papplClientRespondIPPUnsupported
618 Respond with an unsupported IPP attribute.
619 void papplClientRespondIPPUnsupported (
621 pappl_client_t *client,
622 ipp_attribute_t *attr
623 );
624 This function returns a 'client-error-attributes-or-values-not-sup‐
626 ported' status code and adds the specified attribute to the unsupported
627 attributes group in the response.
628 papplClientRespondRedirect
630 Respond with a redirect to another page.
631 bool papplClientRespondRedirect (
633 pappl_client_t *client,
634 http_status_t code,
635 const char *path
636 );
637 This function sends a HTTP response that redirects the client to an‐
639 other page or URL. The most common "code" value to return is HTTP_STA‐
640 TUS_FOUND.
641 papplClientSetCookie
643 Set a cookie for the web browser client.
644 void papplClientSetCookie (
646 pappl_client_t *client,
647 const char *name,
648 const char *value,
649 int expires
650 );
651 This function sets the value of a cookie for the client by updating the
653 Set-Cookie header in the HTTP response that will be sent. The "name"
654 and "value" strings must contain only valid characters for a cookie and
655 its value as documented in RFC 6265, which basically means letters,
656 numbers, "@", "-", ".", and "_".
657 The "expires" argument specifies how long the cookie will remain active
659 in seconds, for example 3600 seconds is one hour and 86400 seconds is
660 one day. If the value is zero or less, a "session" cookie is created
661 instead which will expire as soon as the web browser is closed.
662
664 pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3),
665 pappl-mainline(3), pappl-makeresheader(1), pappl-printer(3), pappl-re‐
666 source(3), pappl-system(3), https://www.msweet.org/pappl
667
669 Copyright © 2019-2020 by Michael R Sweet.
670 PAPPL is licensed under the Apache License Version 2.0 with an (op‐
672 tional) exception to allow linking against GPL2/LGPL2 software (like
673 older versions of CUPS), so it can be used freely in any project you'd
674 like. See the files "LICENSE" and "NOTICE" in the source distribution
675 for more information.
6762021-02-15 pappl client functions pappl-client(3)