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 papplClientGetLoc
286 Get the localization data for a client connection.
287 pappl_loc_t * papplClientGetLoc (
289 pappl_client_t *client
290 );
291 papplClientGetLocString
293 Get a localized string for the client.
294 const char * papplClientGetLocString (
296 pappl_client_t *client,
297 const char *s
298 );
299 papplClientGetMethod
301 Get the HTTP request method.
302 http_state_t papplClientGetMethod (
304 pappl_client_t *client
305 );
306 This function returns the HTTP request method that was used, for exam‐
308 ple HTTP_STATE_GET for a GET request or HTTP_STATE_POST for a POST re‐
309 quest.
310 papplClientGetOperation
312 Get the IPP operation code.
313 ipp_op_t papplClientGetOperation (
315 pappl_client_t *client
316 );
317 This function returns the IPP operation code associated with the cur‐
319 rent IPP request.
320 papplClientGetOptions
322 Get the options from the request URI.
323 const char * papplClientGetOptions (
325 pappl_client_t *client
326 );
327 This function returns any options that were passed in the HTTP request
329 URI. The options are the characters after the "?" character, for exam‐
330 ple a request URI of "/mypage?name=value" will have an options string
331 of "name=value".
332 NULL is returned if the request URI did not contain any options.
334 5 Note: HTTP GET form variables are normally accessed using the
336 5 papplClientGetForm function. This function should only be used
338 when
339 5 getting non-form data.
341 papplClientGetPrinter
343 Get the target printer for an IPP request.
344 pappl_printer_t * papplClientGetPrinter (
346 pappl_client_t *client
347 );
348 This function returns the printer associated with the current IPP re‐
350 quest. NULL is returned if the request does not target a printer.
351 papplClientGetRequest
353 Get the IPP request message.
354 ipp_t * papplClientGetRequest (
356 pappl_client_t *client
357 );
358 This function returns the attributes in the current IPP request, for
360 use with the CUPS ippFindAttribute, ippFindNextAttribute, ippFirstAt‐
361 tribute, and ippNextAttribute functions.
362 papplClientGetResponse
364 Get the IPP response message.
365 ipp_t * papplClientGetResponse (
367 pappl_client_t *client
368 );
369 This function returns the attributes in the current IPP response, for
371 use with the CUPS ippAddXxx and ippSetXxx functions. Use the pap‐
372 plClientRespondIPP function to set the status code and message, if any.
373 papplClientGetSystem
375 Get the containing system for the client.
376 pappl_system_t * papplClientGetSystem (
378 pappl_client_t *client
379 );
380 This function returns the system object that contains the client.
382 papplClientGetURI
384 Get the HTTP request URI.
385 const char * papplClientGetURI (
387 pappl_client_t *client
388 );
389 This function returns the URI that was sent in the current HTTP re‐
391 quest.
392 5 Note: Any options in the URI are removed and can be accessed
394 separately
395 5 using the papplClientGetOptions function.
397 papplClientGetUsername
399 Get the authenticated username, if any.
400 const char * papplClientGetUsername (
402 pappl_client_t *client
403 );
404 This function returns the current authenticated username, if any.
406 papplClientHTMLAuthorize
408 Handle authorization for the web interface.
409 bool papplClientHTMLAuthorize (
411 pappl_client_t *client
412 );
413 The web interface supports both authentication against user accounts
415 and authentication using a single administrative access password. This
416 function handles the details of authentication for the web interface
417 based on the system authentication service configuration = the
418 "auth_service" argument to papplSystemCreate and any callback set using
419 papplSystemSetAuthCallback.
420 5 Note: IPP operation callbacks needing to perform authorization
422 should use
423 5 the papplClientIsAuthorized function instead.
425 papplClientHTMLEscape
427 Send a string to a web browser client.
428 void papplClientHTMLEscape (
430 pappl_client_t *client,
431 const char *s,
432 size_t slen
433 );
434 This function sends the specified string to the web browser client and
436 escapes special characters as HTML entities as needed, for example "&"
437 is sent as &.
438 papplClientHTMLFooter
440 Show the web interface footer.
441 void papplClientHTMLFooter (
443 pappl_client_t *client
444 );
445 This function sends the standard web interface footer followed by a
447 trailing 0-length chunk to finish the current HTTP response. Use the
448 papplSystemSetFooterHTML function to add any custom HTML needed in the
449 footer.
450 papplClientHTMLHeader
452 Show the web interface header and title.
453 void papplClientHTMLHeader (
455 pappl_client_t *client,
456 const char *title,
457 int refresh
458 );
459 This function sends the standard web interface header and title. If
461 the "refresh" argument is greater than zero, the page will automati‐
462 cally reload after that many seconds.
463 Use the papplSystemAddLink function to add system-wide navigation links
465 to the header. Similarly, use papplPrinterAddLink to add printer-spe‐
466 cific links, which will appear in the web interface printer if the sys‐
467 tem is not configured to support multiple printers (the PAPPL_SOP‐
468 TIONS_MULTI_QUEUE option to papplSystemCreate).
469 papplClientHTMLPrinterFooter
471 Show the web interface footer for printers.
472 void papplClientHTMLPrinterFooter (
474 pappl_client_t *client
475 );
476 This function sends the standard web interface footer for a printer
478 followed by a trailing 0-length chunk to finish the current HTTP re‐
479 sponse. Use the papplSystemSetFooterHTML function to add any custom
480 HTML needed in the footer.
481 papplClientHTMLPrinterHeader
483 Show the web interface header and title for printers.
484 void papplClientHTMLPrinterHeader (
486 pappl_client_t *client,
487 pappl_printer_t *printer,
488 const char *title,
489 int refresh,
490 const char *label,
491 const char *path_or_url
492 );
493 This function sends the standard web interface header and title for a
495 printer. If the "refresh" argument is greater than zero, the page will
496 automatically reload after that many seconds.
497 If "label" and "path_or_url" are non-NULL strings, an additional navi‐
499 gation link is included with the title header - this is typically used
500 for an action button ("Change").
501 Use the papplSystemAddLink function to add system-wide navigation links
503 to the header. Similarly, use papplPrinterAddLink to add printer-spe‐
504 cific links, which will appear in the web interface printer if the sys‐
505 tem is not configured to support multiple printers (the PAPPL_SOP‐
506 TIONS_MULTI_QUEUE option to papplSystemCreate).
507 papplClientHTMLPrintf
509 Send formatted text to the web browser client, escaping as needed.
510 void papplClientHTMLPrintf (
512 pappl_client_t *client,
513 const char *format,
514 ...
515 );
516 This function sends formatted text to the web browser client using
518 printf-style formatting codes. The format string itself is not escaped
519 to allow for embedded HTML, however strings inserted using the '%c' or
520 %s codes are escaped properly for HTML - "&" is sent as &, etc.
521 papplClientHTMLPuts
523 Send a HTML string to the web browser client.
524 void papplClientHTMLPuts (
526 pappl_client_t *client,
527 const char *s
528 );
529 This function sends a HTML string to the client without performing any
531 escaping of special characters.
532 papplClientHTMLStartForm
534 Start a HTML form.
535 void papplClientHTMLStartForm (
537 pappl_client_t *client,
538 const char *action,
539 bool multipart
540 );
541 This function starts a HTML form with the specified "action" path and
543 includes the CSRF token as a hidden variable. If the "multipart" argu‐
544 ment is true, the form is annotated to support file attachments up to
545 2MiB in size.
546 papplClientIsAuthorized
548 Determine whether a client is authorized for administrative requests.
549 http_status_t papplClientIsAuthorized (
551 pappl_client_t *client
552 );
553 This function determines whether a client is authorized to submit an
555 administrative request.
556 The return value is HTTP_STATUS_CONTINUE if access is authorized,
558 HTTP_STATUS_FORBIDDEN if access is not allowed, HTTP_STATUS_UNAUTHO‐
559 RIZED if authorization is required, or HTTP_STATUS_UPGRADE_REQUIRED if
560 the connection needs to be encrypted. All of these values can be
561 passed to the papplClientRespond function.
562 papplClientIsValidForm
564 Validate HTML form variables.
565 bool papplClientIsValidForm (
567 pappl_client_t *client,
568 int num_form,
569 cups_option_t *form
570 );
571 This function validates the contents of a HTML form using the CSRF to‐
573 ken included as a hidden variable. When sending a HTML form you should
574 use the papplClientStartForm function to start the HTML form and insert
575 the CSRF token for later validation.
576 5 Note: Callers are expected to validate all other form variables.
578 papplClientRespond
580 Send a regular HTTP response.
581 bool papplClientRespond (
583 pappl_client_t *client,
584 http_status_t code,
585 const char *content_encoding,
586 const char *type,
587 time_t last_modified,
588 size_t length
589 );
590 This function sends all of the required HTTP fields and includes stan‐
592 dard messages for errors. The following values for "code" are explic‐
593 itly supported:
594 • HTTP_STATUS_OK: The request is successful.
596 • HTTP_STATUS_BAD_REQUEST: The client submitted a bad request.
598 • HTTP_STATUS_CONTINUE: An authentication challenge is not needed.
600 • HTTP_STATUS_FORBIDDEN: Authenticated but not allowed.
602 • HTTP_STATUS_METHOD_NOT_ALLOWED: The HTTP method is not supported
604 for the given URI.
605 • HTTP_STATUS_UNAUTHORIZED: Not authenticated.
607 • HTTP_STATUS_UPGRADE_REQUIRED: Redirects the client to a secure
609 page.
610 Use the papplClientRespondRedirect when you need to redirect the client
612 to another page.
613 papplClientRespondIPP
615 Send an IPP response.
616 ipp_t * papplClientRespondIPP (
618 pappl_client_t *client,
619 ipp_status_t status,
620 const char *message,
621 ...
622 );
623 This function sets the return status for an IPP request and returns the
625 current IPP response message. The "status" and "message" arguments re‐
626 place any existing status-code and "status-message" attribute value
627 that may be already present in the response.
628 5 Note: You should call this function prior to adding any response
630 5 attributes.
632 papplClientRespondIPPUnsupported
634 Respond with an unsupported IPP attribute.
635 void papplClientRespondIPPUnsupported (
637 pappl_client_t *client,
638 ipp_attribute_t *attr
639 );
640 This function returns a 'client-error-attributes-or-values-not-sup‐
642 ported' status code and adds the specified attribute to the unsupported
643 attributes group in the response.
644 papplClientRespondRedirect
646 Respond with a redirect to another page.
647 bool papplClientRespondRedirect (
649 pappl_client_t *client,
650 http_status_t code,
651 const char *path
652 );
653 This function sends a HTTP response that redirects the client to an‐
655 other page or URL. The most common "code" value to return is HTTP_STA‐
656 TUS_FOUND.
657 papplClientSetCookie
659 Set a cookie for the web browser client.
660 void papplClientSetCookie (
662 pappl_client_t *client,
663 const char *name,
664 const char *value,
665 int expires
666 );
667 This function sets the value of a cookie for the client by updating the
669 Set-Cookie header in the HTTP response that will be sent. The "name"
670 and "value" strings must contain only valid characters for a cookie and
671 its value as documented in RFC 6265, which basically means letters,
672 numbers, "@", "-", ".", and "_".
673 The "expires" argument specifies how long the cookie will remain active
675 in seconds, for example 3600 seconds is one hour and 86400 seconds is
676 one day. If the value is zero or less, a "session" cookie is created
677 instead which will expire as soon as the web browser is closed.
678 papplClientSetUsername
680 Set the authenticated username, if any.
681 void papplClientSetUsername (
683 pappl_client_t *client,
684 const char *username
685 );
686 This function sets the current authenticated username, if any.
688
690 pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3),
691 pappl-mainline(3), pappl-makeresheader(1), pappl-printer(3), pappl-re‐
692 source(3), pappl-system(3), https://www.msweet.org/pappl
693
695 Copyright © 2019-2022 by Michael R Sweet.
696 PAPPL is licensed under the Apache License Version 2.0 with an (op‐
698 tional) exception to allow linking against GPL2/LGPL2 software (like
699 older versions of CUPS), so it can be used freely in any project you'd
700 like. See the files "LICENSE" and "NOTICE" in the source distribution
701 for more information.
7022022-05-10 pappl client functions pappl-client(3)