pappl-system(3)

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

NAME

6       pappl-system - pappl system functions
7

LIBRARY

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

SYNOPSIS

13       #include <pappl/pappl.h>
14
15       typedef struct _pappl_system_s pappl_system_t;
16
17
18       bool
19       papplSystemAddListeners(pappl_system_t *system, const char *name);
20
21       void
22       papplSystemAddMIMEFilter(pappl_system_t *system, const  char  *srctype,
23       const char *dsttype, pappl_mime_filter_cb_t cb, void *data);
24
25       void
26       papplSystemCleanJobs(pappl_system_t *system);
27
28       pappl_system_t *
29       papplSystemCreate(pappl_soptions_t options, const char *name, int port,
30       const char  *subtypes,  const  char  *spooldir,  const  char  *logfile,
31       pappl_loglevel_t loglevel, const char *auth_service, bool tls_only);
32
33       void
34       papplSystemDelete(pappl_system_t *system);
35
36       pappl_printer_t     *
37       papplSystemFindPrinter(pappl_system_t  *system,  const  char *resource,
38       int printer_id, const char *device_uri);
39
40       char      *
41       papplSystemGetAdminGroup(pappl_system_t *system, char  *buffer,  size_t
42       bufsize);
43
44       const char     *
45       papplSystemGetAuthService(pappl_system_t *system);
46
47       pappl_contact_t     *
48       papplSystemGetContact(pappl_system_t   *system,  pappl_contact_t  *con‐
49       tact);
50
51       int
52       papplSystemGetDefaultPrinterID(pappl_system_t *system);
53
54       char      *
55       papplSystemGetDefaultPrintGroup(pappl_system_t *system,  char  *buffer,
56       size_t bufsize);
57
58       char      *
59       papplSystemGetDNSSDName(pappl_system_t  *system,  char  *buffer, size_t
60       bufsize);
61
62       const char     *
63       papplSystemGetFooterHTML(pappl_system_t *system);
64
65       char      *
66       papplSystemGetGeoLocation(pappl_system_t *system, char *buffer,  size_t
67       bufsize);
68
69       char      *
70       papplSystemGetHostname(pappl_system_t  *system,  char  *buffer,  size_t
71       bufsize);
72
73       char      *
74       papplSystemGetLocation(pappl_system_t  *system,  char  *buffer,  size_t
75       bufsize);
76
77       pappl_loglevel_t
78       papplSystemGetLogLevel(pappl_system_t *system);
79
80       size_t
81       papplSystemGetMaxLogSize(pappl_system_t *system);
82
83       char      *
84       papplSystemGetName(pappl_system_t  *system,  char  *buffer, size_t buf‐
85       size);
86
87       int
88       papplSystemGetNextPrinterID(pappl_system_t *system);
89
90       pappl_soptions_t
91       papplSystemGetOptions(pappl_system_t *system);
92
93       char      *
94       papplSystemGetOrganization(pappl_system_t *system, char *buffer, size_t
95       bufsize);
96
97       char      *
98       papplSystemGetOrganizationalUnit(pappl_system_t  *system, char *buffer,
99       size_t bufsize);
100
101       char      *
102       papplSystemGetPassword(pappl_system_t  *system,  char  *buffer,  size_t
103       bufsize);
104
105       int
106       papplSystemGetPort(pappl_system_t *system);
107
108       const char     *
109       papplSystemGetServerHeader(pappl_system_t *system);
110
111       char      *
112       papplSystemGetSessionKey(pappl_system_t  *system,  char *buffer, size_t
113       bufsize);
114
115       bool
116       papplSystemGetTLSOnly(pappl_system_t *system);
117
118       const char     *
119       papplSystemGetUUID(pappl_system_t *system);
120
121       int
122       papplSystemGetVersions(pappl_system_t   *system,   int    max_versions,
123       pappl_version_t *versions);
124
125       char      *
126       papplSystemHashPassword(pappl_system_t *system, const char *salt, const
127       char *password, char *buffer, size_t bufsize);
128
129       bool
130       papplSystemIsRunning(pappl_system_t *system);
131
132       bool
133       papplSystemIsShutdown(pappl_system_t *system);
134
135       void
136       papplSystemIteratePrinters(pappl_system_t  *system,  pappl_printer_cb_t
137       cb, void *data);
138
139       bool
140       papplSystemLoadState(pappl_system_t *system, const char *filename);
141
142       const char     *
143       papplSystemMatchDriver(pappl_system_t *system, const char *device_id);
144
145       void
146       papplSystemRemoveResource(pappl_system_t *system, const char *path);
147
148       void
149       papplSystemRun(pappl_system_t *system);
150
151       bool
152       papplSystemSaveState(pappl_system_t *system, const char *filename);
153
154
155       void
156       papplSystemSetAdminGroup(pappl_system_t *system, const char *value);
157
158       void
159       papplSystemSetContact(pappl_system_t   *system,  pappl_contact_t  *con‐
160       tact);
161
162       void
163       papplSystemSetDefaultPrinterID(pappl_system_t    *system,    int    de‐
164       fault_printer_id);
165
166       void
167       papplSystemSetDefaultPrintGroup(pappl_system_t   *system,   const  char
168       *value);
169
170       void
171       papplSystemSetDrivers(pappl_system_t    *system,    int    num_drivers,
172       pappl_driver_t *drivers, pappl_driver_cb_t cb, void *data);
173
174       void
175       papplSystemSetDNSSDName(pappl_system_t *system, const char *value);
176
177       void
178       papplSystemSetFooterHTML(pappl_system_t *system, const char *html);
179
180       void
181       papplSystemSetGeoLocation(pappl_system_t *system, const char *value);
182
183       void
184       papplSystemSetHostname(pappl_system_t *system, const char *value);
185
186       void
187       papplSystemSetLocation(pappl_system_t *system, const char *value);
188
189       void
190       papplSystemSetLogLevel(pappl_system_t     *system,     pappl_loglevel_t
191       loglevel);
192
193       void
194       papplSystemSetMaxLogSize(pappl_system_t *system, size_t maxSize);
195
196       void
197       papplSystemSetMIMECallback(pappl_system_t *system, pappl_mime_cb_t  cb,
198       void *data);
199
200       void
201       papplSystemSetNextPrinterID(pappl_system_t         *system,         int
202       next_printer_id);
203
204       void
205       papplSystemSetOperationCallback(pappl_system_t                 *system,
206       pappl_ipp_op_cb_t cb, void *data);
207
208       void
209       papplSystemSetOrganization(pappl_system_t *system, const char *value);
210
211       void
212       papplSystemSetOrganizationalUnit(pappl_system_t   *system,  const  char
213       *value);
214
215       void
216       papplSystemSetPassword(pappl_system_t *system, const char *hash);
217
218       void
219       papplSystemSetSaveCallback(pappl_system_t *system, pappl_save_cb_t  cb,
220       void *data);
221
222       void
223       papplSystemSetUUID(pappl_system_t *system, const char *value);
224
225       void
226       papplSystemSetVersions(pappl_system_t    *system,   int   num_versions,
227       pappl_version_t *versions);
228
229       void
230       papplSystemShutdown(pappl_system_t *system);
231
232

DESCRIPTION

234       The PAPPL system functions provide access to the system object.  System
235       are created and deleted by the printer application while the life cycle
236       of the pappl_system_t object is managed automatically for  the  printer
237       application.  The papplSystemCreate function creates a new system while
238       the papplSystemDelete function deletes a system.
239
240       The papplSystemRun function starts a system while the  papplSystemShut‐
241       down function stops a running system.
242
243       The  papplSystemGet  functions get the current values associated with a
244       system while the papplSystemSet functions set the current values  asso‐
245       ciated with a system.
246

ENUMERATIONS

248   pappl_netconf_e
249       Network configuration mode
250
251       PAPPL_NETCONF_DHCP
252            Full DHCP
253
254       PAPPL_NETCONF_DHCP_MANUAL
255            DHCP with manual IP address
256
257       PAPPL_NETCONF_MANUAL
258            Manual IP, netmask, and router
259
260       PAPPL_NETCONF_OFF
261            Turn network interface off
262
263   pappl_soptions_e
264       System option bits
265
266       PAPPL_SOPTIONS_DNSSD_HOST
267            Use hostname in DNS-SD service names instead of serial number/UUID
268
269       PAPPL_SOPTIONS_MULTI_QUEUE
270            Support multiple printers
271
272       PAPPL_SOPTIONS_NONE
273            No options
274
275       PAPPL_SOPTIONS_NO_TLS
276            Disable TLS support
277
278       PAPPL_SOPTIONS_RAW_SOCKET
279            Accept jobs via raw sockets
280
281       PAPPL_SOPTIONS_USB_PRINTER
282            Accept jobs via USB for default printer (embedded Linux only)
283
284       PAPPL_SOPTIONS_WEB_INTERFACE
285            Enable the standard web pages
286
287       PAPPL_SOPTIONS_WEB_LOG
288            Enable the log file page
289
290       PAPPL_SOPTIONS_WEB_NETWORK
291            Enable the network settings page
292
293       PAPPL_SOPTIONS_WEB_REMOTE
294            Allow remote queue management (vs. localhost only)
295
296       PAPPL_SOPTIONS_WEB_SECURITY
297            Enable the user/password settings page
298
299       PAPPL_SOPTIONS_WEB_TLS
300            Enable the TLS settings page
301
302   pappl_wifi_state_e
303       "printer-wifi-state" values
304
305       PAPPL_WIFI_STATE_CANNOT_JOIN
306            ´cannot-join'
307
308       PAPPL_WIFI_STATE_JOINING
309            ´joining'
310
311       PAPPL_WIFI_STATE_NOT_CONFIGURED
312            ´not-configured'
313
314       PAPPL_WIFI_STATE_NOT_VISIBLE
315            ´not-visible'
316
317       PAPPL_WIFI_STATE_OFF
318            ´off'
319
320       PAPPL_WIFI_STATE_ON
321            ´on'
322

FUNCTIONS

324   papplSystemAddEvent
325       Add a notification event.
326
327       void papplSystemAddEvent (
328           pappl_system_t *system,
329           pappl_printer_t *printer,
330           pappl_job_t *job,
331           pappl_event_t event,
332           const char *message,
333           ...
334       );
335
336   papplSystemAddListeners
337       Add network or domain socket listeners.
338
339       bool  papplSystemAddListeners (
340           pappl_system_t *system,
341           const char *name
342       );
343
344       This  function  adds  socket listeners.  The "name" parameter specifies
345       the listener address.  Names starting with a slash (/) specify  a  UNIX
346       domain  socket path, otherwise the name is treated as a fully-qualified
347       domain name or numeric IPv4 or IPv6 address.   If  name  is  NULL,  the
348       "any" addresses are used ("0.0.0.0" and "[::]").
349
350       Listeners cannot be added after papplSystemRun is called.
351
352   papplSystemAddMIMEFilter
353       Add a file filter to the system.
354
355       void papplSystemAddMIMEFilter (
356           pappl_system_t *system,
357           const char *srctype,
358           const char *dsttype,
359           pappl_mime_filter_cb_t cb,
360           void *data
361       );
362
363       This  function adds a file filter to the system to be used for process‐
364       ing different kinds of document data in print jobs.  The "srctype"  and
365       "dsttype" arguments specify the source and destination MIME media types
366       as constant strings.  A destination  MIME  media  type  of  "image/pwg-
367       raster"  specifies  a  filter  that uses the driver's raster interface.
368       Other destination types imply direct submission to  the  output  device
369       using the papplDeviceXxx functions.
370
371       5      Note:  This  function may not be called while the system is run‐
372              ning.
373
374   papplSystemAddTimerCallback
375       Add a timer callback to a system.
376
377       bool  papplSystemAddTimerCallback (
378           pappl_system_t *system,
379           time_t start,
380           int interval,
381           pappl_timer_cb_t cb,
382           void *cb_data
383       );
384
385       This function schedules a function that will be called on the main  run
386       loop  thread at the specified time and optionally every "interval" sec‐
387       onds thereafter.  The timimg accuracy is typically within  a  few  mil‐
388       liseconds but is not guaranteed.  Since the callback is run on the main
389       run loop thread, functions should create a new thread for any long-run‐
390       ning operations.
391
392       The  callback function receives the "system" and "cb_data" pointers and
393       returns true to repeat the timer or false to remove it:
394
395           bool my_timer_cb(pappl_system_t *system, void *cb_data)
396           {
397             ... do periodic task ...
398             return (true); // repeat the timer
399           }
400
401
402
403   papplSystemCreate
404       Create a system object.
405
406       pappl_system_t * papplSystemCreate (
407           pappl_soptions_t options,
408           const char *name,
409           int port,
410           const char *subtypes,
411           const char *spooldir,
412           const char *logfile,
413           pappl_loglevel_t loglevel,
414           const char *auth_service,
415           bool tls_only
416       );
417
418       This function creates a new system object,  which  is  responsible  for
419       managing  all the printers, jobs, and resources used by the printer ap‐
420       plication.
421
422       The "options" argument specifies which  options  are  enabled  for  the
423       server:
424
425       •    PAPPL_SOPTIONS_NONE: No options.
426
427       •    PAPPL_SOPTIONS_DNSSD_HOST: When resolving DNS-SD service name col‐
428            lisions,
429              use the DNS-SD hostname instead of a serial number or UUID.
430
431       •    PAPPL_SOPTIONS_WEB_LOG: Include the log file web page.
432
433       •    PAPPL_SOPTIONS_MULTI_QUEUE: Support multiple printers.
434
435       •    PAPPL_SOPTIONS_WEB_NETWORK: Include the network settings web page.
436
437       •    PAPPL_SOPTIONS_RAW_SOCKET: Accept jobs via raw sockets starting on
438            port
439              9100.
440
441       •    PAPPL_SOPTIONS_WEB_REMOTE: Allow remote queue management.
442
443       •    PAPPL_SOPTIONS_WEB_SECURITY:  Include  the  security  settings web
444            page.
445
446       •    PAPPL_SOPTIONS_WEB_INTERFACE: Include the standard printer and job
447            monitoring
448              web pages.
449
450       •    PAPPL_SOPTIONS_WEB_TLS: Include the TLS settings page.
451
452       •    PAPPL_SOPTIONS_USB_PRINTER:  Accept  jobs  via USB for the default
453            printer
454              (embedded Linux only).
455
456       The "name" argument specifies a human-readable name for the system.
457
458       The "port" argument specifies the port number to bind to.  A value of 0
459       will  cause an available port number to be assigned when the first lis‐
460       tener is added with the papplSystemAddListeners function.
461
462       The "subtypes" argument specifies one or  more  comma-delimited  DNS-SD
463       service sub-types such as "_print" and "_universal".
464
465       The  "spooldir" argument specifies the location of job files.  If NULL,
466       a temporary directory is created.
467
468       The "logfile" argument specifies where to send log messages.  If  NULL,
469       the log messages are written to a temporary file.
470
471       The "loglevel" argument specifies the initial logging level.
472
473       The  "auth_service"  argument  specifies  a  PAM authentication service
474       name.  If NULL, no user authentication will be provided.
475
476       The "tls_only" argument controls whether the printer  application  will
477       accept  unencrypted  connections.  In general, this argument should al‐
478       ways be false (allow unencrypted connections)  since  not  all  clients
479       support encrypted printing.
480
481   papplSystemCreatePrinters
482       Create newly discovered printers.
483
484       bool  papplSystemCreatePrinters (
485           pappl_system_t *system,
486           pappl_devtype_t types,
487           pappl_pr_create_cb_t cb,
488           void *cb_data
489       );
490
491       This  function  lists  all devices specified by "types" and attempts to
492       add any new printers that are found.  The callback function "cb" is in‐
493       voked for each printer that is added.
494
495   papplSystemDelete
496       Delete a system object.
497
498       void papplSystemDelete (
499           pappl_system_t *system
500       );
501
502       5      Note: A system object cannot be deleted while the system is run‐
503              ning.
504
505   papplSystemFindLoc
506       Find a localization for the given printer and language.
507
508       pappl_loc_t * papplSystemFindLoc (
509           pappl_system_t *system,
510           const char *language
511       );
512
513   papplSystemFindPrinter
514       Find a printer by resource, ID, or device URI.
515
516       pappl_printer_t * papplSystemFindPrinter (
517           pappl_system_t *system,
518           const char *resource,
519           int printer_id,
520           const char *device_uri
521       );
522
523       This function finds a printer contained in the  system  using  its  re‐
524       source  path,  unique  integer  identifier,  or device URI.  If none of
525       these is specified, the current default printer is returned.
526
527   papplSystemFindSubscription
528       Find a subscription.
529
530       pappl_subscription_t * papplSystemFindSubscription (
531           pappl_system_t *system,
532           int sub_id
533       );
534
535       This function finds the numbered event notification subscription  on  a
536       system.
537
538   papplSystemGetAdminGroup
539       Get the current administrative group, if any.
540
541       char * papplSystemGetAdminGroup (
542           pappl_system_t *system,
543           char *buffer,
544           size_t bufsize
545       );
546
547       This  function  copies the current administrative group, if any, to the
548       specified buffer.
549
550   papplSystemGetAuthService
551       Get the PAM authorization service, if any.
552
553       const char * papplSystemGetAuthService (
554           pappl_system_t *system
555       );
556
557       This function returns the PAM authorization service being used  by  the
558       system for authentication, if any.
559
560   papplSystemGetContact
561       Get the "system-contact" value.
562
563       pappl_contact_t * papplSystemGetContact (
564           pappl_system_t *system,
565           pappl_contact_t *contact
566       );
567
568       This  function  copies  the  current  system contact information to the
569       specified buffer.
570
571   papplSystemGetDNSSDName
572       Get the current DNS-SD service name.
573
574       char * papplSystemGetDNSSDName (
575           pappl_system_t *system,
576           char *buffer,
577           size_t bufsize
578       );
579
580       This function copies the current DNS-SD service name of the system,  if
581       any, to the specified buffer.
582
583   papplSystemGetDefaultPrintGroup
584       Get the default print group, if any.
585
586       char * papplSystemGetDefaultPrintGroup (
587           pappl_system_t *system,
588           char *buffer,
589           size_t bufsize
590       );
591
592       This  function  copies  the current default print group, if any, to the
593       specified buffer.
594
595   papplSystemGetDefaultPrinterID
596       Get the current "default-printer-id" value.
597
598       int  papplSystemGetDefaultPrinterID (
599           pappl_system_t *system
600       );
601
602       This function returns the positive integer identifier for  the  current
603       default printer or 0 if there is no default printer.
604
605   papplSystemGetFooterHTML
606       Get the footer HTML for the web interface, if any.
607
608       const char * papplSystemGetFooterHTML (
609           pappl_system_t *system
610       );
611
612       This  function  returns  the HTML for the web page footer, if any.  The
613       footer HTML can be set using the papplSystemSetFooterHTML function.
614
615   papplSystemGetGeoLocation
616       Get the system geo-location string, if any.
617
618       char * papplSystemGetGeoLocation (
619           pappl_system_t *system,
620           char *buffer,
621           size_t bufsize
622       );
623
624       This function copies the current system geographic location as a "geo:"
625       URI to the specified buffer.
626
627   papplSystemGetHostName
628       Get the system hostname.
629
630       char * papplSystemGetHostName (
631           pappl_system_t *system,
632           char *buffer,
633           size_t bufsize
634       );
635
636       This  function copies the current system hostname to the specified buf‐
637       fer.
638
639   papplSystemGetHostPort
640       Get the port number for network connections to
641                                    the system.
642
643       int  papplSystemGetHostPort (
644           pappl_system_t *system
645       );
646
647       This function returns the port number that is used for network  connec‐
648       tions to the system.
649
650   papplSystemGetLocation
651       Get the system location string, if any.
652
653       char * papplSystemGetLocation (
654           pappl_system_t *system,
655           char *buffer,
656           size_t bufsize
657       );
658
659       This  function  copies  the current human-readable location, if any, to
660       the specified buffer.
661
662   papplSystemGetLogLevel
663       Get the system log level.
664
665       pappl_loglevel_t  papplSystemGetLogLevel (
666           pappl_system_t *system
667       );
668
669       This function returns the current system log level as an enumeration.
670
671   papplSystemGetMaxClients
672       Get the maximum number of clients.
673
674       int  papplSystemGetMaxClients (
675           pappl_system_t *system
676       );
677
678       This function gets the maximum number of simultaneous clients that  are
679       allowed by the system.
680
681   papplSystemGetMaxImageSize
682       Get the maximum supported size for images.
683
684       size_t  papplSystemGetMaxImageSize (
685           pappl_system_t *system,
686           int *max_width,
687           int *max_height
688       );
689
690       This  function retrieves the image size limits in bytes (uncompressed),
691       columns, and lines.
692
693   papplSystemGetMaxLogSize
694       Get the maximum log file size.
695
696       size_t  papplSystemGetMaxLogSize (
697           pappl_system_t *system
698       );
699
700       This function gets the maximum log file size, which is only  used  when
701       logging directly to a file.  When the limit is reached, the current log
702       file is renamed to "filename.O" and a new log file is created.  Set the
703       maximum size to 0 to disable log file rotation.
704
705       The default maximum log file size is 1MiB or 1048576 bytes.
706
707   papplSystemGetMaxSubscriptions
708       Get the maximum number of event subscriptions.
709
710       size_t  papplSystemGetMaxSubscriptions (
711           pappl_system_t *system
712       );
713
714       This  function  gets the maximum number of event subscriptions that are
715       allowed.  A maximum of 0 means there is no limit.
716
717       The default maximum number of event subscriptions is 100.
718
719   papplSystemGetName
720       Get the system name.
721
722       char * papplSystemGetName (
723           pappl_system_t *system,
724           char *buffer,
725           size_t bufsize
726       );
727
728       This function copies the current system name to the specified buffer.
729
730   papplSystemGetNextPrinterID
731       Get the next "printer-id" value.
732
733       int  papplSystemGetNextPrinterID (
734           pappl_system_t *system
735       );
736
737       This function returns the positive integer identifier that will be used
738       for the next printer that is created.
739
740   papplSystemGetOptions
741       Get the system options.
742
743       pappl_soptions_t  papplSystemGetOptions (
744           pappl_system_t *system
745       );
746
747       This function returns the system options as a bitfield.
748
749   papplSystemGetOrganization
750       Get the system organization string, if any.
751
752       char * papplSystemGetOrganization (
753           pappl_system_t *system,
754           char *buffer,
755           size_t bufsize
756       );
757
758       This  function  copies  the  current  organization name, if any, to the
759       specified buffer.
760
761   papplSystemGetOrganizationalUnit
762       Get the system organizational unit string, if any.
763
764       char * papplSystemGetOrganizationalUnit (
765           pappl_system_t *system,
766           char *buffer,
767           size_t bufsize
768       );
769
770       This function copies the current organizational unit name, if  any,  to
771       the specified buffer.
772
773   papplSystemGetPassword
774       Get the current web site access password.
775
776       char * papplSystemGetPassword (
777           pappl_system_t *system,
778           char *buffer,
779           size_t bufsize
780       );
781
782       This function copies the current web site password hash, if any, to the
783       specified buffer.
784
785       Note: The access password is only used when the PAM authentication ser‐
786       vice is not set.
787
788   papplSystemGetServerHeader
789       Get the Server: header for HTTP responses.
790
791       const char * papplSystemGetServerHeader (
792           pappl_system_t *system
793       );
794
795       This  function  returns  the value of the HTTP "Server:" header that is
796       used by the system.
797
798   papplSystemGetSessionKey
799       Get the current session key.
800
801       char * papplSystemGetSessionKey (
802           pappl_system_t *system,
803           char *buffer,
804           size_t bufsize
805       );
806
807       This function copies the current session key to the  specified  buffer.
808       The session key is used for web interface forms to provide CSRF protec‐
809       tion and is refreshed periodically.
810
811   papplSystemGetTLSOnly
812       Get the TLS-only state of the system.
813
814       bool  papplSystemGetTLSOnly (
815           pappl_system_t *system
816       );
817
818       This function returns whether the system  will  only  accept  encrypted
819       connections.
820
821   papplSystemGetUUID
822       Get the "system-uuid" value.
823
824       const char * papplSystemGetUUID (
825           pappl_system_t *system
826       );
827
828       This function returns the system's UUID value.
829
830   papplSystemGetVersions
831       Get the firmware names and versions.
832
833       int  papplSystemGetVersions (
834           pappl_system_t *system,
835           int max_versions,
836           pappl_version_t *versions
837       );
838
839       This  function  copies the system firmware information to the specified
840       buffer.  The return value is always the  number  of  firmware  versions
841       that  have  been set using the papplSystemSetVersions function, regard‐
842       less of the value of the "max_versions" argument.
843
844   papplSystemHashPassword
845       Generate a password hash using salt and password strings.
846
847       char * papplSystemHashPassword (
848           pappl_system_t *system,
849           const char *salt,
850           const char *password,
851           char *buffer,
852           size_t bufsize
853       );
854
855       This function generates a password hash using the "salt" and "password"
856       strings.   The  "salt" string should be NULL to generate a new password
857       hash or the value of an existing password hash to verify that  a  given
858       plaintext "password" string matches the password hash.
859
860       5      Note: Hashed access passwords are only used when the PAM authen‐
861              tication
862
863       5      service is not set.
864
865   papplSystemIsRunning
866       Return whether the system is running.
867
868       bool  papplSystemIsRunning (
869           pappl_system_t *system
870       );
871
872       This function returns whether the system is running.
873
874   papplSystemIsShutdown
875       Return whether the system has been shutdown.
876
877       bool  papplSystemIsShutdown (
878           pappl_system_t *system
879       );
880
881       This function returns whether the system is shutdown  or  scheduled  to
882       shutdown.
883
884   papplSystemIteratePrinters
885       Iterate all of the printers.
886
887       void papplSystemIteratePrinters (
888           pappl_system_t *system,
889           pappl_printer_cb_t cb,
890           void *data
891       );
892
893       This function iterates each of the printers managed by the system.  The
894       "cb" function is called once per printer with the "system"  and  "data"
895       values.
896
897   papplSystemLoadState
898       Load the previous system state.
899
900       bool  papplSystemLoadState (
901           pappl_system_t *system,
902           const char *filename
903       );
904
905       This  function  loads  the previous system state from a file created by
906       the papplSystemSaveState function.  The system state  contains  all  of
907       the  system  object values, the list of printers, and the jobs for each
908       printer.
909
910       When loading a printer definition, if the  printer  cannot  be  created
911       (e.g.,  because  the  driver name is no longer valid) then that printer
912       and all of its job history will be lost.  In the case of a  bad  driver
913       name, a printer application's driver callback can perform any necessary
914       mapping of the driver name, including the use its auto-add callback  to
915       find a compatible new driver.
916
917       5      Note: This function must be called prior to papplSystemRun.
918
919   papplSystemMatchDriver
920       const char * papplSystemMatchDriver (
921           pappl_system_t *system,
922           const char *device_id
923       );
924
925   papplSystemRemoveTimerCallback
926       Remove a timer callback.
927
928       void papplSystemRemoveTimerCallback (
929           pappl_system_t *system,
930           pappl_timer_cb_t cb,
931           void *cb_data
932       );
933
934       This  function  removes all matching timer callbacks from the specified
935       system.  Both the callback function and data must  match  to  remove  a
936       timer.
937
938   papplSystemRun
939       Run the printer application.
940
941       void papplSystemRun (
942           pappl_system_t *system
943       );
944
945       This  function runs the printer application, accepting new connections,
946       handling requests, and processing jobs as needed.  It returns once  the
947       system is shutdown, either through an IPP request or SIGTERM.
948
949   papplSystemSaveState
950       Save the current system state.
951
952       bool  papplSystemSaveState (
953           pappl_system_t *system,
954           const char *filename
955       );
956
957       This  function  saves  the current system state to a file.  It is typi‐
958       cally used with the papplSystemSetSaveCallback function to periodically
959       save the state:
960
961           papplSystemSetSaveCallback(system, (pappl_save_cb_t)papplSystemSaveState,
962               (void *)filename);
963
964
965
966   papplSystemSetAdminGroup
967       Set the administrative group.
968
969       void papplSystemSetAdminGroup (
970           pappl_system_t *system,
971           const char *value
972       );
973
974       This function sets the group name used for administrative requests such
975       as adding or deleting a printer.
976
977       5      Note: The administrative group is only used when the PAM  autho‐
978              rization
979
980       5      service is also set when the system is created.
981
982   papplSystemSetAuthCallback
983       Set an authentication callback for the specified scheme.
984
985       void papplSystemSetAuthCallback (
986           pappl_system_t *system,
987           const char *auth_scheme,
988           pappl_auth_cb_t auth_cb,
989           void *auth_cbdata
990       );
991
992       This  function sets the authentication callback that is used for Client
993       requests.  The authentication callback is used for every Client request
994       containing  the  WWW-Authenticate header (HTTP_FIELD_WWW_AUTHENTICATE).
995       The callback returns one of the following status codes:
996
997       •    HTTP_STATUS_CONTINUE if the authentication succeeded,
998
999       •    HTTP_STATUS_UNAUTHORIZED if the authentication failed, or
1000
1001       •    HTTP_STATUS_FORBIDDEN if the authentication succeeded but the user
1002            is
1003              not part of the specified group.</li> </ul>
1004
1005   papplSystemSetContact
1006       Set the "system-contact" value.
1007
1008       void papplSystemSetContact (
1009           pappl_system_t *system,
1010           pappl_contact_t *contact
1011       );
1012
1013       This function sets the system contact value.
1014
1015   papplSystemSetDNSSDName
1016       Set the DNS-SD service name.
1017
1018       void papplSystemSetDNSSDName (
1019           pappl_system_t *system,
1020           const char *value
1021       );
1022
1023       This function sets the DNS-SD service name of the system.  If NULL, the
1024       DNS-SD registration is removed.
1025
1026   papplSystemSetDefaultPrintGroup
1027       Set the default print group.
1028
1029       void papplSystemSetDefaultPrintGroup (
1030           pappl_system_t *system,
1031           const char *value
1032       );
1033
1034       This function sets the default group name used for print requests.
1035
1036       5      Note: The default print group is only used when the  PAM  autho‐
1037              rization
1038
1039       5      service is also set when the system is created.
1040
1041   papplSystemSetDefaultPrinterID
1042       Set the "default-printer-id" value.
1043
1044       void papplSystemSetDefaultPrinterID (
1045           pappl_system_t *system,
1046           int default_printer_id
1047       );
1048
1049       This  function sets the default printer using its unique positive inte‐
1050       ger identifier.
1051
1052   papplSystemSetEventCallback
1053       Set a callback for monitoring system events.
1054
1055       void papplSystemSetEventCallback (
1056           pappl_system_t *system,
1057           pappl_event_cb_t event_cb,
1058           void *event_data
1059       );
1060
1061       This function sets a callback function to receive  event  notifications
1062       from the system.
1063
1064   papplSystemSetFooterHTML
1065       Set the footer HTML for the web interface.
1066
1067       void papplSystemSetFooterHTML (
1068           pappl_system_t *system,
1069           const char *html
1070       );
1071
1072       This function sets the footer HTML for the web interface.
1073
1074       5      Note: The footer HTML can only be set prior to calling
1075
1076       5      papplSystemRun.
1077
1078   papplSystemSetGeoLocation
1079       Set the geographic location string.
1080
1081       void papplSystemSetGeoLocation (
1082           pappl_system_t *system,
1083           const char *value
1084       );
1085
1086       This  function  sets  the geographic location of the system as a "geo:"
1087       URI.  If NULL, the location is cleared.
1088
1089   papplSystemSetHostName
1090       Set the system hostname.
1091
1092       void papplSystemSetHostName (
1093           pappl_system_t *system,
1094           const char *value
1095       );
1096
1097       This function sets the system hostname.  If NULL, the default  hostname
1098       is used.
1099
1100   papplSystemSetLocation
1101       Set the system location string, if any.
1102
1103       void papplSystemSetLocation (
1104           pappl_system_t *system,
1105           const char *value
1106       );
1107
1108       This function sets the human-readable location of the system.  If NULL,
1109       the location is cleared.
1110
1111   papplSystemSetLogLevel
1112       Set the system log level
1113
1114       void papplSystemSetLogLevel (
1115           pappl_system_t *system,
1116           pappl_loglevel_t loglevel
1117       );
1118
1119       This function sets the log level as an enumeration.
1120
1121   papplSystemSetMIMECallback
1122       Set the MIME typing callback for the system.
1123
1124       void papplSystemSetMIMECallback (
1125           pappl_system_t *system,
1126           pappl_mime_cb_t cb,
1127           void *data
1128       );
1129
1130       This function sets a custom MIME typing callback for the  system.   The
1131       MIME typing callback extends the built-in MIME typing support for other
1132       media types that are supported by  the  application,  typically  vendor
1133       print formats.
1134
1135       The callback function receives a buffer containing the initial bytes of
1136       the document data, the length of the buffer, and the callback data.  It
1137       can  then  return  NULL  if the content is not recognized or a constant
1138       string containing the MIME media type, for example "application/vnd.hp-
1139       pcl" for HP PCL print data.
1140
1141   papplSystemSetMaxClients
1142       Set the maximum number of clients.
1143
1144       void papplSystemSetMaxClients (
1145           pappl_system_t *system,
1146           int max_clients
1147       );
1148
1149       This  function sets the maximum number of simultaneous clients that are
1150       allowed by the system from 0 (auto) to 32768 (half of the available TCP
1151       port numbers).
1152
1153       The  default maximum number of clients is based on available system re‐
1154       sources.
1155
1156   papplSystemSetMaxImageSize
1157       Set the maximum allowed JPEG/PNG image sizes.
1158
1159       void papplSystemSetMaxImageSize (
1160           pappl_system_t *system,
1161           size_t max_size,
1162           int max_width,
1163           int max_height
1164       );
1165
1166       This function sets the maximum size allowed for JPEG  and  PNG  images.
1167       The  default  limits  are 16384x16384 and 1/10th the maximum memory the
1168       current process can use or 1GiB, whichever is less.
1169
1170   papplSystemSetMaxLogSize
1171       Set the maximum log file size in bytes.
1172
1173       void papplSystemSetMaxLogSize (
1174           pappl_system_t *system,
1175           size_t maxsize
1176       );
1177
1178       This function sets the maximum log file size in bytes,  which  is  only
1179       used  when  logging directly to a file.  When the limit is reached, the
1180       current log file is renamed to "filename.O" and a new log file is  cre‐
1181       ated.  Set the maximum size to 0 to disable log file rotation.
1182
1183       The default maximum log file size is 1MiB or 1048576 bytes.
1184
1185   papplSystemSetMaxSubscriptions
1186       Set the maximum number of event subscriptions.
1187
1188       void papplSystemSetMaxSubscriptions (
1189           pappl_system_t *system,
1190           size_t max_subscriptions
1191       );
1192
1193       This  function  Sets the maximum number of event subscriptions that are
1194       allowed.  A maximum of 0 means there is no limit.
1195
1196       The default maximum number of event subscriptions is 100.
1197
1198   papplSystemSetNetworkCallbacks
1199       Set the network configuration callbacks.
1200
1201       void papplSystemSetNetworkCallbacks (
1202           pappl_system_t *system,
1203           pappl_network_get_cb_t get_cb,
1204           pappl_network_set_cb_t set_cb,
1205           void *cb_data
1206       );
1207
1208       This function sets the network configuration callbacks  for  a  system.
1209       The  "get"  callback  reads the configuration of all network interfaces
1210       and stores them in an  array  of  pappl_network_t  structures  that  is
1211       passed to the callback.  The "set" callback writes the configuration of
1212       all network interfaces and returns a boolean value  indicating  whether
1213       the configuration has been written successfully.
1214
1215   papplSystemSetNextPrinterID
1216       Set the next "printer-id" value.
1217
1218       void papplSystemSetNextPrinterID (
1219           pappl_system_t *system,
1220           int next_printer_id
1221       );
1222
1223       This  function sets the unique positive integer identifier that will be
1224       used for the next printer that is created.  It is typically only called
1225       as part of restoring the state of a system.
1226
1227       5      Note: The next printer ID can only be set prior to calling
1228
1229       5      papplSystemRun.
1230
1231   papplSystemSetOperationCallback
1232       Set the IPP operation callback.
1233
1234       void papplSystemSetOperationCallback (
1235           pappl_system_t *system,
1236           pappl_ipp_op_cb_t cb,
1237           void *data
1238       );
1239
1240       This  function  sets a custom IPP operation handler for the system that
1241       is called for any IPP operations that are not handled by  the  built-in
1242       IPP services.
1243
1244       5      Note: The operation callback can only be set prior to calling
1245
1246       5      papplSystemRun.
1247
1248   papplSystemSetOrganization
1249       Set the system organization string, if any.
1250
1251       void papplSystemSetOrganization (
1252           pappl_system_t *system,
1253           const char *value
1254       );
1255
1256       This  function sets the organization name for the system.  If NULL, the
1257       name is cleared.
1258
1259   papplSystemSetOrganizationalUnit
1260       Set the system organizational unit
1261                                              string, if any.
1262
1263       void papplSystemSetOrganizationalUnit (
1264           pappl_system_t *system,
1265           const char *value
1266       );
1267
1268       This function sets the organizational unit name  for  the  system.   If
1269       NULL, the name is cleared.
1270
1271   papplSystemSetPassword
1272       Set the access password hash string.
1273
1274       void papplSystemSetPassword (
1275           pappl_system_t *system,
1276           const char *hash
1277       );
1278
1279       This  function  sets  the  hash  for the web access password.  The hash
1280       string is generated using the papplSystemHashPassword function.
1281
1282       5      Note: The access password is only used when the PAM  authentica‐
1283              tion service
1284
1285       5      is not set.
1286
1287   papplSystemSetPrinterDrivers
1288       Set the list of drivers and the driver
1289                                          callbacks.
1290
1291       void papplSystemSetPrinterDrivers (
1292           pappl_system_t *system,
1293           int num_drivers,
1294           pappl_pr_driver_t *drivers,
1295           pappl_pr_autoadd_cb_t autoadd_cb,
1296           pappl_pr_create_cb_t create_cb,
1297           pappl_pr_driver_cb_t driver_cb,
1298           void *data
1299       );
1300
1301       This  function sets the lists of printer drivers, the optional auto-add
1302       callback function, the optional creation  callback,  and  the  required
1303       driver initialization callback function.
1304
1305       The auto-add callback ("autoadd_cb") finds a compatible driver name for
1306       the specified printer.  It is used when the client  or  user  specifies
1307       the  "auto" driver name, and for the "autoadd" sub-command for the pap‐
1308       plMainloop API.
1309
1310       The creation callback ("create_cb") is called at  the  end  of  printer
1311       creation  to make any common changes or additions to a new printer.  It
1312       is typically used to add extra web pages, add  per-printer  static  re‐
1313       sources, and/or initialize the contact and location information.
1314
1315       The  driver initialization callback ("driver_cb") is called to initial‐
1316       ize the pappl_pr_driver_data_t structure, which  provides  all  of  the
1317       printer capabilities and callbacks for printing.
1318
1319   papplSystemSetSaveCallback
1320       Set the save callback.
1321
1322       void papplSystemSetSaveCallback (
1323           pappl_system_t *system,
1324           pappl_save_cb_t cb,
1325           void *data
1326       );
1327
1328       This  function  sets  a  callback that is used to periodically save the
1329       current system state.  Typically the callback function ("cb")  is  pap‐
1330       plSystemSaveState  and  the  callback  data ("data") is the name of the
1331       state file:
1332
1333           papplSystemSetSaveCallback(system, (pappl_save_cb_t)papplSystemSaveState,
1334               (void *)filename);
1335
1336
1337
1338       5      Note: The save callback can only be set prior to calling
1339
1340       5      papplSystemRun.
1341
1342   papplSystemSetUUID
1343       Set the system UUID.
1344
1345       void papplSystemSetUUID (
1346           pappl_system_t *system,
1347           const char *value
1348       );
1349
1350       This function sets the system UUID value, overriding the default  (gen‐
1351       erated) value.  It is typically used when restoring the state of a pre‐
1352       vious incarnation of the system.
1353
1354       5      Note: The UUID can only be set prior to calling papplSystemRun.
1355
1356   papplSystemSetVersions
1357       Set the firmware names and versions.
1358
1359       void papplSystemSetVersions (
1360           pappl_system_t *system,
1361           int num_versions,
1362           pappl_version_t *versions
1363       );
1364
1365       This function sets the names and  versions  of  each  firmware/software
1366       component of the printer application.
1367
1368   papplSystemSetWiFiCallbacks
1369       Set Wi-Fi callbacks.
1370
1371       void papplSystemSetWiFiCallbacks (
1372           pappl_system_t *system,
1373           pappl_wifi_join_cb_t join_cb,
1374           pappl_wifi_list_cb_t list_cb,
1375           pappl_wifi_status_cb_t status_cb,
1376           void *data
1377       );
1378
1379       This function sets the 802.11 Wi-Fi interface callbacks for the system.
1380       The "join_cb" is used to join a Wi-Fi network, the "list_cb" is used to
1381       list  available networks, and the "status_cb" is used to query the cur‐
1382       rent Wi-Fi network connection status and Secure Set Identifier  (SSID).
1383       The "join_cb" and "status_cb" functions are used to support getting and
1384       setting  the   IPP   "printer-wifi-state",   "printer-wifi-ssid",   and
1385       "printer-wifi-password"  attributes,  while  the "list_cb" function en‐
1386       ables changing the Wi-Fi network from the network web interface, if en‐
1387       abled.
1388
1389       Note: The Wi-Fi callbacks can only be set prior to calling papplSystem‐
1390       Run.
1391
1392   papplSystemShutdown
1393       Shutdown the system.
1394
1395       void papplSystemShutdown (
1396           pappl_system_t *system
1397       );
1398
1399       This function tells the system to perform an orderly  shutdown  of  all
1400       printers and to terminate the main loop.
1401

STRUCTURES

1403   pappl_network_s
1404       Network interface information
1405
1406       struct pappl_network_s
1407       {
1408         http_addr_t addr4;
1409         http_addr_t addr6;
1410         pappl_netconf_t config4;
1411         pappl_netconf_t config6;
1412         http_addr_t dns[2];
1413         char domain[64];
1414         http_addr_t gateway4;
1415         http_addr_t gateway6;
1416         char ident[256];
1417         http_addr_t linkaddr6;
1418         http_addr_t mask4;
1419         char name[64];
1420         unsigned prefix6;
1421         bool up;
1422       };
1423
1424   pappl_pr_driver_s
1425       Printer driver information
1426
1427       struct pappl_pr_driver_s
1428       {
1429         const char *description;
1430         const char *device_id;
1431         void *extension;
1432         const char *name;
1433       };
1434
1435   pappl_version_s
1436       Firmware version information
1437
1438       struct pappl_version_s
1439       {
1440         char name[64];
1441         char patches[64];
1442         char sversion[64];
1443         unsigned short version[4];
1444       };
1445
1446   pappl_wifi_s
1447       Wi-Fi status/configuration information
1448
1449       struct pappl_wifi_s
1450       {
1451         char ssid[128];
1452         pappl_wifi_state_t state;
1453       };
1454

TYPES

1456   pappl_auth_cb_t
1457       Authentication callback
1458
1459       typedef http_status_t (*pappl_auth_cb_t)(pappl_client_t *client, const char *group, gid_t groupid, void *cb_data);
1460
1461   pappl_ipp_op_cb_t
1462       IPP operation callback function
1463
1464       typedef bool (*pappl_ipp_op_cb_t)(pappl_client_t *client, void *data);
1465
1466   pappl_mime_cb_t
1467       MIME typing callback function
1468
1469       typedef const char * (*pappl_mime_cb_t)(const unsigned char *header, size_t headersize, void *data);
1470
1471   pappl_mime_filter_cb_t
1472       Filter callback function
1473
1474       typedef bool (*pappl_mime_filter_cb_t)(pappl_job_t *job, pappl_device_t *device, void *data);
1475
1476   pappl_netconf_t
1477       Network configuration mode
1478
1479       typedef enum pappl_netconf_e pappl_netconf_t;
1480
1481   pappl_network_get_cb_t
1482       Get networks callback
1483
1484       typedef size_t (*pappl_network_get_cb_t)(pappl_system_t *system, void *cb_data, size_t max_networks, pappl_network_t *networks);
1485
1486   pappl_network_set_cb_t
1487       Set networks callback
1488
1489       typedef bool (*pappl_network_set_cb_t)(pappl_system_t *system, void *cb_data, size_t num_networks, pappl_network_t *networks);
1490
1491   pappl_network_t
1492       Network interface information
1493
1494       typedef struct pappl_network_s pappl_network_t;
1495
1496   pappl_pr_autoadd_cb_t
1497       Auto-add callback
1498
1499       typedef const char * (*pappl_pr_autoadd_cb_t)(const char *device_info, const char *device_uri, const char *device_id, void *data);
1500
1501   pappl_pr_create_cb_t
1502       Printer creation callback
1503
1504       typedef void (*pappl_pr_create_cb_t)(pappl_printer_t *printer, void *data);
1505
1506   pappl_pr_driver_cb_t
1507       Driver callback function
1508
1509       typedef bool (*pappl_pr_driver_cb_t)(pappl_system_t *system, const char *driver_name, const char *device_uri, const char *device_id, pappl_pr_driver_data_t *driver_data, ipp_t **driver_attrs, void *data);
1510
1511   pappl_pr_driver_t
1512       Printer driver information
1513
1514       typedef struct pappl_pr_driver_s pappl_pr_driver_t;
1515
1516   pappl_printer_cb_t
1517       Printer iterator callback function
1518
1519       typedef void (*pappl_printer_cb_t)(pappl_printer_t *printer, void *data);
1520
1521   pappl_resource_cb_t
1522       Dynamic resource callback function
1523
1524       typedef bool (*pappl_resource_cb_t)(pappl_client_t *client, void *data);
1525
1526   pappl_save_cb_t
1527       Save callback function
1528
1529       typedef bool (*pappl_save_cb_t)(pappl_system_t *system, void *data);
1530
1531   pappl_soptions_t
1532       Bitfield for system options
1533
1534       typedef unsigned pappl_soptions_t;
1535
1536   pappl_timer_cb_t
1537       Timer callback function
1538
1539       typedef bool (*pappl_timer_cb_t)(pappl_system_t *system, void *cb_data);
1540
1541   pappl_version_t
1542       Firmware version information
1543
1544       typedef struct pappl_version_s pappl_version_t;
1545
1546   pappl_wifi_join_cb_t
1547       Wi-Fi join callback
1548
1549       typedef bool (*pappl_wifi_join_cb_t)(pappl_system_t *system, void *data, const char *ssid, const char *psk);
1550
1551   pappl_wifi_list_cb_t
1552       Wi-Fi list callback
1553
1554       typedef int (*pappl_wifi_list_cb_t)(pappl_system_t *system, void *data, cups_dest_t **ssids);
1555
1556   pappl_wifi_state_t
1557       "printer-wifi-state" values
1558
1559       typedef enum pappl_wifi_state_e pappl_wifi_state_t;
1560
1561   pappl_wifi_status_cb_t
1562       Wi-Fi status callback
1563
1564       typedef pappl_wifi_t * (*pappl_wifi_status_cb_t)(pappl_system_t *system, void *data, pappl_wifi_t *wifi_data);
1565
1566   pappl_wifi_t
1567       Wi-Fi status/configuration information
1568
1569       typedef struct pappl_wifi_s pappl_wifi_t;
1570

COPYRIGHT

1577       Copyright © 2019-2022 by Michael R Sweet.
1578
1579       PAPPL  is  licensed  under  the Apache License Version 2.0 with an (op‐
1580       tional) exception to allow linking against  GPL2/LGPL2  software  (like
1581       older  versions of CUPS), so it can be used freely in any project you'd
1582       like.  See the files "LICENSE" and "NOTICE" in the source  distribution
1583       for more information.
1584
1585
1586
15872023-10-06                  pappl system functions             pappl-system(3)