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

STRUCTURES

1389   pappl_network_s
1390       Network interface information
1391
1392       struct pappl_network_s
1393       {
1394         http_addr_t addr4;
1395         http_addr_t addr6;
1396         pappl_netconf_t config4;
1397         pappl_netconf_t config6;
1398         http_addr_t dns[2];
1399         char domain[64];
1400         http_addr_t gateway4;
1401         http_addr_t gateway6;
1402         char ident[256];
1403         http_addr_t linkaddr6;
1404         http_addr_t mask4;
1405         char name[64];
1406         unsigned prefix6;
1407         bool up;
1408       };
1409
1410   pappl_pr_driver_s
1411       Printer driver information
1412
1413       struct pappl_pr_driver_s
1414       {
1415         const char *description;
1416         const char *device_id;
1417         void *extension;
1418         const char *name;
1419       };
1420
1421   pappl_version_s
1422       Firmware version information
1423
1424       struct pappl_version_s
1425       {
1426         char name[64];
1427         char patches[64];
1428         char sversion[64];
1429         unsigned short version[4];
1430       };
1431
1432   pappl_wifi_s
1433       Wi-Fi status/configuration information
1434
1435       struct pappl_wifi_s
1436       {
1437         char ssid[128];
1438         pappl_wifi_state_t state;
1439       };
1440

TYPES

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

COPYRIGHT

1563       Copyright © 2019-2022 by Michael R Sweet.
1564
1565       PAPPL  is  licensed  under  the Apache License Version 2.0 with an (op‐
1566       tional) exception to allow linking against  GPL2/LGPL2  software  (like
1567       older  versions of CUPS), so it can be used freely in any project you'd
1568       like.  See the files "LICENSE" and "NOTICE" in the source  distribution
1569       for more information.
1570
1571
1572
15732022-11-07                  pappl system functions             pappl-system(3)