1pappl-client(3)             pappl client functions             pappl-client(3)
2
3
4

NAME

6       pappl-client - pappl client functions
7

LIBRARY

9       Printer  Application  Framework  (libpappl, "pkg-config --cflags --libs
10       pappl")
11
12

SYNOPSIS

14       #include <pappl/pappl.h>
15
16       typedef struct _pappl_client_s pappl_client_t;
17
18       char *
19       papplClientGetCSRFToken(pappl_client_t *client,  char  *buffer,  size_t
20       bufsize);
21
22       char *
23       papplClientGetCookie(pappl_client_t  *client,  const  char  *name, char
24       *buffer, size_t bufsize);
25
26       int
27       papplClientGetForm(pappl_client_t *client, cups_option_t **form);
28
29       const char *
30       papplClientGetHostName(pappl_client_t *client);
31
32       int
33       papplClientGetHostPort(pappl_client_t *client);
34
35       http_t *
36       papplClientGetHTTP(pappl_client_t *client);
37
38       pappl_job_t *
39       papplClientGetJob(pappl_client_t *client);
40
41       http_state_t
42       papplClientGetMethod(pappl_client_t *client);
43
44       ipp_op_t
45       papplClientGetOperation(pappl_client_t *client);
46
47       const char *
48       papplClientGetOptions(pappl_client_t *client);
49
50       pappl_printer_t *
51       papplClientGetPrinter(pappl_client_t *client);
52
53       ipp_t *
54       papplClientGetRequest(pappl_client_t *client);
55
56       ipp_t *
57       papplClientGetResponse(pappl_client_t *client);
58
59       pappl_system_t *
60       papplClientGetSystem(pappl_client_t *client);
61
62       const char *
63       papplClientGetURI(pappl_client_t *client);
64
65       const char *
66       papplClientGetUsername(pappl_client_t *client);
67
68       bool
69       papplClientHTMLAuthorize(pappl_client_t *client);
70
71       void
72       papplClientHTMLEscape(pappl_client_t *client,  const  char  *s,  size_t
73       slen);
74
75       void
76       papplClientHTMLFooter(pappl_client_t *client);
77
78       void
79       papplClientHTMLHeader(pappl_client_t  *client,  const  char *title, int
80       refresh);
81
82       void
83       papplClientHTMLPrintf(pappl_client_t *client, const char *format, ...);
84
85       void
86       papplClientHTMLPuts(pappl_client_t *client, const char *s);
87
88       void
89       papplClientHTMLStartForm(pappl_client_t *client,  const  char  *action,
90       bool multipart);
91
92       http_status_t
93       papplClientIsAuthorized(pappl_client_t *client);
94
95       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
100       ipp_t *
101       papplClientRespondIPP(pappl_client_t   *client,   ipp_status_t  status,
102       const char *message, ...);
103
104       bool
105       papplClientRespondRedirect(pappl_client_t *client, http_status_t  code,
106       const char *path);
107
108       void
109       papplClientSetCookie(pappl_client_t  *client,  const char * name, const
110       char *value, int expires);
111
112       bool
113       papplClientValidateForm(pappl_client_t *client, int num_form,  cups_op‐
114       tion_t *form);
115
116

DESCRIPTION

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
122       The papplClientGet functions get the current values for various client-
123       supplied request data.
124

RESPONDING TO CLIENT REQUESTS

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
136       The papplClientRespondIPP function starts an  IPP  response.   Use  the
137       various  CUPS  ippAdd  functions to add attributes to the response mes‐
138       sage.
139
140       The papplClientRespondRedirect function sends a redirection response to
141       the client.
142
143

HTML FORMS

145       PAPPL  provides  the  papplClientGetCSRFToken, papplClientGetForm, pap‐
146       plClientHTMLStartForm and papplClientValidateForm functions to securely
147       manage HTML forms.
148
149       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
157

AUTHENTICATION AND AUTHORIZATION

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
163       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
168       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

FUNCTIONS

179   papplClientGetCSRFToken
180       Get a unique Cross-Site Request Forgery token
181                                     string.
182
183       char * papplClientGetCSRFToken (
184           pappl_client_t *client,
185           char *buffer,
186           size_t bufsize
187       );
188
189       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
194       The value is based on the current system session key and client address
195       in order to make replay attacks infeasible.
196
197       5      Note: The papplClientHTMLStartForm function  automatically  adds
198              the
199
200       5      hidden CSRF variable, and the papplClientIsValidForm function
201
202       5      validates the value.
203
204   papplClientGetCookie
205       Get a cookie from the client.
206
207       char * papplClientGetCookie (
208           pappl_client_t *client,
209           const char *name,
210           char *buffer,
211           size_t bufsize
212       );
213
214       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
218       Use  the papplClientSetCookie function to set a cookie in a response to
219       a request.
220
221       5      Note: Cookies set with papplClientSetCookie will not  be  avail‐
222              able to
223
224       5      this function until the following request.
225
226   papplClientGetForm
227       Get form data from the web client.
228
229       int  papplClientGetForm (
230           pappl_client_t *client,
231           cups_option_t **form
232       );
233
234       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
237       The returned form values must be freed using the cupsFreeOptions  func‐
238       tion.
239
240       5      Note:  Because the form data is read from the client connection,
241              this
242
243       5      function can only be called once per request.
244
245   papplClientGetHTTP
246       Get the HTTP connection associated with a client
247                                object.
248
249       http_t * papplClientGetHTTP (
250           pappl_client_t *client
251       );
252
253       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
257   papplClientGetHostName
258       Get the hostname from the client-supplied Host:
259                                    field.
260
261       const char * papplClientGetHostName (
262           pappl_client_t *client
263       );
264
265       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
268   papplClientGetHostPort
269       Get the port from the client-supplied Host:
270                                    field.
271
272       int  papplClientGetHostPort (
273           pappl_client_t *client
274       );
275
276       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
279   papplClientGetJob
280       Get the target job for an IPP request.
281
282       pappl_job_t * papplClientGetJob (
283           pappl_client_t *client
284       );
285
286       This function returns the job associated with the current IPP  request.
287       NULL is returned if the request does not target a job.
288
289   papplClientGetLoc
290       Get the localization data for a client connection.
291
292       pappl_loc_t * papplClientGetLoc (
293           pappl_client_t *client
294       );
295
296   papplClientGetLocString
297       Get a localized string for the client.
298
299       const char * papplClientGetLocString (
300           pappl_client_t *client,
301           const char *s
302       );
303
304   papplClientGetMethod
305       Get the HTTP request method.
306
307       http_state_t  papplClientGetMethod (
308           pappl_client_t *client
309       );
310
311       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
315   papplClientGetOperation
316       Get the IPP operation code.
317
318       ipp_op_t  papplClientGetOperation (
319           pappl_client_t *client
320       );
321
322       This  function  returns the IPP operation code associated with the cur‐
323       rent IPP request.
324
325   papplClientGetOptions
326       Get the options from the request URI.
327
328       const char * papplClientGetOptions (
329           pappl_client_t *client
330       );
331
332       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
337       NULL is returned if the request URI did not contain any options.
338
339       5      Note: HTTP GET form variables are normally accessed using the
340
341       5      papplClientGetForm  function.  This function should only be used
342              when
343
344       5      getting non-form data.
345
346   papplClientGetPrinter
347       Get the target printer for an IPP request.
348
349       pappl_printer_t * papplClientGetPrinter (
350           pappl_client_t *client
351       );
352
353       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
356   papplClientGetRequest
357       Get the IPP request message.
358
359       ipp_t * papplClientGetRequest (
360           pappl_client_t *client
361       );
362
363       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
367   papplClientGetResponse
368       Get the IPP response message.
369
370       ipp_t * papplClientGetResponse (
371           pappl_client_t *client
372       );
373
374       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
378   papplClientGetSystem
379       Get the containing system for the client.
380
381       pappl_system_t * papplClientGetSystem (
382           pappl_client_t *client
383       );
384
385       This function returns the system object that contains the client.
386
387   papplClientGetURI
388       Get the HTTP request URI.
389
390       const char * papplClientGetURI (
391           pappl_client_t *client
392       );
393
394       This  function  returns  the  URI that was sent in the current HTTP re‐
395       quest.
396
397       5      Note: Any options in the URI are removed  and  can  be  accessed
398              separately
399
400       5      using the papplClientGetOptions function.
401
402   papplClientGetUsername
403       Get the authenticated username, if any.
404
405       const char * papplClientGetUsername (
406           pappl_client_t *client
407       );
408
409       This function returns the current authenticated username, if any.
410
411   papplClientHTMLAuthorize
412       Handle authorization for the web interface.
413
414       bool  papplClientHTMLAuthorize (
415           pappl_client_t *client
416       );
417
418       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
425       5      Note: IPP operation callbacks needing to  perform  authorization
426              should use
427
428       5      the papplClientIsAuthorized function instead.
429
430   papplClientHTMLEscape
431       Send a string to a web browser client.
432
433       void papplClientHTMLEscape (
434           pappl_client_t *client,
435           const char *s,
436           size_t slen
437       );
438
439       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 &amp;.
442
443   papplClientHTMLFooter
444       Show the web interface footer.
445
446       void papplClientHTMLFooter (
447           pappl_client_t *client
448       );
449
450       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
455   papplClientHTMLHeader
456       Show the web interface header and title.
457
458       void papplClientHTMLHeader (
459           pappl_client_t *client,
460           const char *title,
461           int refresh
462       );
463
464       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
468       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
474   papplClientHTMLPrinterFooter
475       Show the web interface footer for printers.
476
477       void papplClientHTMLPrinterFooter (
478           pappl_client_t *client
479       );
480
481       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
486   papplClientHTMLPrinterHeader
487       Show the web interface header and title
488                                          for printers.
489
490       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
499       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
503       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
507       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
513   papplClientHTMLPrintf
514       Send formatted text to the web browser client,
515                                   escaping as needed.
516
517       void papplClientHTMLPrintf (
518           pappl_client_t *client,
519           const char *format,
520           ...
521       );
522
523       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 &amp;, etc.
527
528   papplClientHTMLPuts
529       Send a HTML string to the web browser client.
530
531       void papplClientHTMLPuts (
532           pappl_client_t *client,
533           const char *s
534       );
535
536       This function sends a HTML string to the client without performing  any
537       escaping of special characters.
538
539   papplClientHTMLStartForm
540       Start a HTML form.
541
542       void papplClientHTMLStartForm (
543           pappl_client_t *client,
544           const char *action,
545           bool multipart
546       );
547
548       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
553   papplClientIsAuthorized
554       Determine whether a client is authorized for
555                                     administrative requests.
556
557       http_status_t  papplClientIsAuthorized (
558           pappl_client_t *client
559       );
560
561       This function determines whether a client is authorized  to  submit  an
562       administrative request.
563
564       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
570   papplClientIsEncrypted
571       Return whether a Client connection is encrypted.
572
573       bool  papplClientIsEncrypted (
574           pappl_client_t *client
575       );
576
577       This  function returns a boolean value indicating whether a Client con‐
578       nection is encrypted with TLS.
579
580   papplClientIsValidForm
581       Validate HTML form variables.
582
583       bool  papplClientIsValidForm (
584           pappl_client_t *client,
585           int num_form,
586           cups_option_t *form
587       );
588
589       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
594       5      Note: Callers are expected to validate all other form variables.
595
596   papplClientRespond
597       Send a regular HTTP response.
598
599       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
608       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
612HTTP_STATUS_OK: The request is successful.
613
614HTTP_STATUS_BAD_REQUEST: The client submitted a bad request.
615
616HTTP_STATUS_CONTINUE: An authentication challenge is not needed.
617
618HTTP_STATUS_FORBIDDEN: Authenticated but not allowed.
619
620HTTP_STATUS_METHOD_NOT_ALLOWED:  The  HTTP method is not supported
621            for the
622              given URI.
623
624HTTP_STATUS_UNAUTHORIZED: Not authenticated.
625
626HTTP_STATUS_UPGRADE_REQUIRED: Redirects the  client  to  a  secure
627            page.
628
629       Use the papplClientRespondRedirect when you need to redirect the client
630       to another page.
631
632   papplClientRespondIPP
633       Send an IPP response.
634
635       ipp_t * papplClientRespondIPP (
636           pappl_client_t *client,
637           ipp_status_t status,
638           const char *message,
639           ...
640       );
641
642       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
647       5      Note: You should call this function prior to adding any response
648
649       5      attributes.
650
651   papplClientRespondIPPUnsupported
652       Respond with an unsupported IPP attribute.
653
654       void papplClientRespondIPPUnsupported (
655           pappl_client_t *client,
656           ipp_attribute_t *attr
657       );
658
659       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
663   papplClientRespondRedirect
664       Respond with a redirect to another page.
665
666       bool  papplClientRespondRedirect (
667           pappl_client_t *client,
668           http_status_t code,
669           const char *path
670       );
671
672       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
676   papplClientSetCookie
677       Set a cookie for the web browser client.
678
679       void papplClientSetCookie (
680           pappl_client_t *client,
681           const char *name,
682           const char *value,
683           int expires
684       );
685
686       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
692       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
697   papplClientSetUsername
698       Set the authenticated username, if any.
699
700       void papplClientSetUsername (
701           pappl_client_t *client,
702           const char *username
703       );
704
705       This function sets the current authenticated username, if any.
706

SEE ALSO

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
715       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.
720
721
722
7232022-11-07                  pappl client functions             pappl-client(3)
Impressum