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
181 string.
182 char * papplClientGetCSRFToken (
184 pappl_client_t *client,
185 char *buffer,
186 size_t bufsize
187 );
188 This function generates and returns a unique Cross-Site Request Forgery
190 token string to be used as the value of a hidden variable in all HTML
191 forms sent in the response and then compared when validating the form
192 data in the subsequent request.
193 The value is based on the current system session key and client address
195 in order to make replay attacks infeasible.
196 5 Note: The papplClientHTMLStartForm function automatically adds
198 the
199 5 hidden CSRF variable, and the papplClientIsValidForm function
201 5 validates the value.
203 papplClientGetCookie
205 Get a cookie from the client.
206 char * papplClientGetCookie (
208 pappl_client_t *client,
209 const char *name,
210 char *buffer,
211 size_t bufsize
212 );
213 This function gets a HTTP "cookie" value from the client request. NULL
215 is returned if no cookie has been set by a prior request, or if the
216 user has disabled or removed the cookie.
217 Use the papplClientSetCookie function to set a cookie in a response to
219 a request.
220 5 Note: Cookies set with papplClientSetCookie will not be avail‐
222 able to
223 5 this function until the following request.
225 papplClientGetForm
227 Get form data from the web client.
228 int papplClientGetForm (
230 pappl_client_t *client,
231 cups_option_t **form
232 );
233 For HTTP GET requests, the form data is collected from the request URI.
235 For HTTP POST requests, the form data is read from the client.
236 The returned form values must be freed using the cupsFreeOptions func‐
238 tion.
239 5 Note: Because the form data is read from the client connection,
241 this
242 5 function can only be called once per request.
244 papplClientGetHTTP
246 Get the HTTP connection associated with a client
247 object.
248 http_t * papplClientGetHTTP (
250 pappl_client_t *client
251 );
252 This function returns the HTTP connection associated with the client
254 and is used when sending response data directly to the client using the
255 CUPS httpXxx functions.
256 papplClientGetHostName
258 Get the hostname from the client-supplied Host:
259 field.
260 const char * papplClientGetHostName (
262 pappl_client_t *client
263 );
264 This function returns the hostname that was used in the request and
266 should be used in any URLs or URIs that you generate.
267 papplClientGetHostPort
269 Get the port from the client-supplied Host:
270 field.
271 int papplClientGetHostPort (
273 pappl_client_t *client
274 );
275 This function returns the port number that was used in the request and
277 should be used in any URLs or URIs that you generate.
278 papplClientGetJob
280 Get the target job for an IPP request.
281 pappl_job_t * papplClientGetJob (
283 pappl_client_t *client
284 );
285 This function returns the job associated with the current IPP request.
287 NULL is returned if the request does not target a job.
288 papplClientGetLoc
290 Get the localization data for a client connection.
291 pappl_loc_t * papplClientGetLoc (
293 pappl_client_t *client
294 );
295 papplClientGetLocString
297 Get a localized string for the client.
298 const char * papplClientGetLocString (
300 pappl_client_t *client,
301 const char *s
302 );
303 papplClientGetMethod
305 Get the HTTP request method.
306 http_state_t papplClientGetMethod (
308 pappl_client_t *client
309 );
310 This function returns the HTTP request method that was used, for exam‐
312 ple HTTP_STATE_GET for a GET request or HTTP_STATE_POST for a POST re‐
313 quest.
314 papplClientGetOperation
316 Get the IPP operation code.
317 ipp_op_t papplClientGetOperation (
319 pappl_client_t *client
320 );
321 This function returns the IPP operation code associated with the cur‐
323 rent IPP request.
324 papplClientGetOptions
326 Get the options from the request URI.
327 const char * papplClientGetOptions (
329 pappl_client_t *client
330 );
331 This function returns any options that were passed in the HTTP request
333 URI. The options are the characters after the "?" character, for exam‐
334 ple a request URI of "/mypage?name=value" will have an options string
335 of "name=value".
336 NULL is returned if the request URI did not contain any options.
338 5 Note: HTTP GET form variables are normally accessed using the
340 5 papplClientGetForm function. This function should only be used
342 when
343 5 getting non-form data.
345 papplClientGetPrinter
347 Get the target printer for an IPP request.
348 pappl_printer_t * papplClientGetPrinter (
350 pappl_client_t *client
351 );
352 This function returns the printer associated with the current IPP re‐
354 quest. NULL is returned if the request does not target a printer.
355 papplClientGetRequest
357 Get the IPP request message.
358 ipp_t * papplClientGetRequest (
360 pappl_client_t *client
361 );
362 This function returns the attributes in the current IPP request, for
364 use with the CUPS ippFindAttribute, ippFindNextAttribute, ippFirstAt‐
365 tribute, and ippNextAttribute functions.
366 papplClientGetResponse
368 Get the IPP response message.
369 ipp_t * papplClientGetResponse (
371 pappl_client_t *client
372 );
373 This function returns the attributes in the current IPP response, for
375 use with the CUPS ippAddXxx and ippSetXxx functions. Use the pap‐
376 plClientRespondIPP function to set the status code and message, if any.
377 papplClientGetSystem
379 Get the containing system for the client.
380 pappl_system_t * papplClientGetSystem (
382 pappl_client_t *client
383 );
384 This function returns the system object that contains the client.
386 papplClientGetURI
388 Get the HTTP request URI.
389 const char * papplClientGetURI (
391 pappl_client_t *client
392 );
393 This function returns the URI that was sent in the current HTTP re‐
395 quest.
396 5 Note: Any options in the URI are removed and can be accessed
398 separately
399 5 using the papplClientGetOptions function.
401 papplClientGetUsername
403 Get the authenticated username, if any.
404 const char * papplClientGetUsername (
406 pappl_client_t *client
407 );
408 This function returns the current authenticated username, if any.
410 papplClientHTMLAuthorize
412 Handle authorization for the web interface.
413 bool papplClientHTMLAuthorize (
415 pappl_client_t *client
416 );
417 The web interface supports both authentication against user accounts
419 and authentication using a single administrative access password. This
420 function handles the details of authentication for the web interface
421 based on the system authentication service configuration = the
422 "auth_service" argument to papplSystemCreate and any callback set using
423 papplSystemSetAuthCallback.
424 5 Note: IPP operation callbacks needing to perform authorization
426 should use
427 5 the papplClientIsAuthorized function instead.
429 papplClientHTMLEscape
431 Send a string to a web browser client.
432 void papplClientHTMLEscape (
434 pappl_client_t *client,
435 const char *s,
436 size_t slen
437 );
438 This function sends the specified string to the web browser client and
440 escapes special characters as HTML entities as needed, for example "&"
441 is sent as &.
442 papplClientHTMLFooter
444 Show the web interface footer.
445 void papplClientHTMLFooter (
447 pappl_client_t *client
448 );
449 This function sends the standard web interface footer followed by a
451 trailing 0-length chunk to finish the current HTTP response. Use the
452 papplSystemSetFooterHTML function to add any custom HTML needed in the
453 footer.
454 papplClientHTMLHeader
456 Show the web interface header and title.
457 void papplClientHTMLHeader (
459 pappl_client_t *client,
460 const char *title,
461 int refresh
462 );
463 This function sends the standard web interface header and title. If
465 the "refresh" argument is greater than zero, the page will automati‐
466 cally reload after that many seconds.
467 Use the papplSystemAddLink function to add system-wide navigation links
469 to the header. Similarly, use papplPrinterAddLink to add printer-spe‐
470 cific links, which will appear in the web interface printer if the sys‐
471 tem is not configured to support multiple printers (the PAPPL_SOP‐
472 TIONS_MULTI_QUEUE option to papplSystemCreate).
473 papplClientHTMLPrinterFooter
475 Show the web interface footer for printers.
476 void papplClientHTMLPrinterFooter (
478 pappl_client_t *client
479 );
480 This function sends the standard web interface footer for a printer
482 followed by a trailing 0-length chunk to finish the current HTTP re‐
483 sponse. Use the papplSystemSetFooterHTML function to add any custom
484 HTML needed in the footer.
485 papplClientHTMLPrinterHeader
487 Show the web interface header and title
488 for printers.
489 void papplClientHTMLPrinterHeader (
491 pappl_client_t *client,
492 pappl_printer_t *printer,
493 const char *title,
494 int refresh,
495 const char *label,
496 const char *path_or_url
497 );
498 This function sends the standard web interface header and title for a
500 printer. If the "refresh" argument is greater than zero, the page will
501 automatically reload after that many seconds.
502 If "label" and "path_or_url" are non-NULL strings, an additional navi‐
504 gation link is included with the title header - this is typically used
505 for an action button ("Change").
506 Use the papplSystemAddLink function to add system-wide navigation links
508 to the header. Similarly, use papplPrinterAddLink to add printer-spe‐
509 cific links, which will appear in the web interface printer if the sys‐
510 tem is not configured to support multiple printers (the PAPPL_SOP‐
511 TIONS_MULTI_QUEUE option to papplSystemCreate).
512 papplClientHTMLPrintf
514 Send formatted text to the web browser client,
515 escaping as needed.
516 void papplClientHTMLPrintf (
518 pappl_client_t *client,
519 const char *format,
520 ...
521 );
522 This function sends formatted text to the web browser client using
524 printf-style formatting codes. The format string itself is not escaped
525 to allow for embedded HTML, however strings inserted using the '%c' or
526 %s codes are escaped properly for HTML - "&" is sent as &, etc.
527 papplClientHTMLPuts
529 Send a HTML string to the web browser client.
530 void papplClientHTMLPuts (
532 pappl_client_t *client,
533 const char *s
534 );
535 This function sends a HTML string to the client without performing any
537 escaping of special characters.
538 papplClientHTMLStartForm
540 Start a HTML form.
541 void papplClientHTMLStartForm (
543 pappl_client_t *client,
544 const char *action,
545 bool multipart
546 );
547 This function starts a HTML form with the specified "action" path and
549 includes the CSRF token as a hidden variable. If the "multipart" argu‐
550 ment is true, the form is annotated to support file attachments up to
551 2MiB in size.
552 papplClientIsAuthorized
554 Determine whether a client is authorized for
555 administrative requests.
556 http_status_t papplClientIsAuthorized (
558 pappl_client_t *client
559 );
560 This function determines whether a client is authorized to submit an
562 administrative request.
563 The return value is HTTP_STATUS_CONTINUE if access is authorized,
565 HTTP_STATUS_FORBIDDEN if access is not allowed, HTTP_STATUS_UNAUTHO‐
566 RIZED if authorization is required, or HTTP_STATUS_UPGRADE_REQUIRED if
567 the connection needs to be encrypted. All of these values can be
568 passed to the papplClientRespond function.
569 papplClientIsEncrypted
571 Return whether a Client connection is encrypted.
572 bool papplClientIsEncrypted (
574 pappl_client_t *client
575 );
576 This function returns a boolean value indicating whether a Client con‐
578 nection is encrypted with TLS.
579 papplClientIsValidForm
581 Validate HTML form variables.
582 bool papplClientIsValidForm (
584 pappl_client_t *client,
585 int num_form,
586 cups_option_t *form
587 );
588 This function validates the contents of a HTML form using the CSRF to‐
590 ken included as a hidden variable. When sending a HTML form you should
591 use the papplClientStartForm function to start the HTML form and insert
592 the CSRF token for later validation.
593 5 Note: Callers are expected to validate all other form variables.
595 papplClientRespond
597 Send a regular HTTP response.
598 bool papplClientRespond (
600 pappl_client_t *client,
601 http_status_t code,
602 const char *content_encoding,
603 const char *type,
604 time_t last_modified,
605 size_t length
606 );
607 This function sends all of the required HTTP fields and includes stan‐
609 dard messages for errors. The following values for "code" are explic‐
610 itly supported:
611 • HTTP_STATUS_OK: The request is successful.
613 • HTTP_STATUS_BAD_REQUEST: The client submitted a bad request.
615 • HTTP_STATUS_CONTINUE: An authentication challenge is not needed.
617 • HTTP_STATUS_FORBIDDEN: Authenticated but not allowed.
619 • HTTP_STATUS_METHOD_NOT_ALLOWED: The HTTP method is not supported
621 for the
622 given URI.
623 • HTTP_STATUS_UNAUTHORIZED: Not authenticated.
625 • HTTP_STATUS_UPGRADE_REQUIRED: Redirects the client to a secure
627 page.
628 Use the papplClientRespondRedirect when you need to redirect the client
630 to another page.
631 papplClientRespondIPP
633 Send an IPP response.
634 ipp_t * papplClientRespondIPP (
636 pappl_client_t *client,
637 ipp_status_t status,
638 const char *message,
639 ...
640 );
641 This function sets the return status for an IPP request and returns the
643 current IPP response message. The "status" and "message" arguments re‐
644 place any existing status-code and "status-message" attribute value
645 that may be already present in the response.
646 5 Note: You should call this function prior to adding any response
648 5 attributes.
650 papplClientRespondIPPUnsupported
652 Respond with an unsupported IPP attribute.
653 void papplClientRespondIPPUnsupported (
655 pappl_client_t *client,
656 ipp_attribute_t *attr
657 );
658 This function returns a 'client-error-attributes-or-values-not-sup‐
660 ported' status code and adds the specified attribute to the unsupported
661 attributes group in the response.
662 papplClientRespondRedirect
664 Respond with a redirect to another page.
665 bool papplClientRespondRedirect (
667 pappl_client_t *client,
668 http_status_t code,
669 const char *path
670 );
671 This function sends a HTTP response that redirects the client to an‐
673 other page or URL. The most common "code" value to return is HTTP_STA‐
674 TUS_FOUND.
675 papplClientSetCookie
677 Set a cookie for the web browser client.
678 void papplClientSetCookie (
680 pappl_client_t *client,
681 const char *name,
682 const char *value,
683 int expires
684 );
685 This function sets the value of a cookie for the client by updating the
687 Set-Cookie header in the HTTP response that will be sent. The "name"
688 and "value" strings must contain only valid characters for a cookie and
689 its value as documented in RFC 6265, which basically means letters,
690 numbers, "@", "-", ".", and "_".
691 The "expires" argument specifies how long the cookie will remain active
693 in seconds, for example 3600 seconds is one hour and 86400 seconds is
694 one day. If the value is zero or less, a "session" cookie is created
695 instead which will expire as soon as the web browser is closed.
696 papplClientSetUsername
698 Set the authenticated username, if any.
699 void papplClientSetUsername (
701 pappl_client_t *client,
702 const char *username
703 );
704 This function sets the current authenticated username, if any.
706
708 pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3),
709 pappl-mainline(3), pappl-makeresheader(1), pappl-printer(3), pappl-re‐
710 source(3), pappl-system(3), https://www.msweet.org/pappl
711
713 Copyright © 2019-2022 by Michael R Sweet.
714 PAPPL is licensed under the Apache License Version 2.0 with an (op‐
716 tional) exception to allow linking against GPL2/LGPL2 software (like
717 older versions of CUPS), so it can be used freely in any project you'd
718 like. See the files "LICENSE" and "NOTICE" in the source distribution
719 for more information.
7202023-10-06 pappl client functions pappl-client(3)