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_soptions_e
249       System option bits
250
251       PAPPL_SOPTIONS_DNSSD_HOST
252            Use hostname in DNS-SD service names instead of serial number/UUID
253
254       PAPPL_SOPTIONS_MULTI_QUEUE
255            Support multiple printers
256
257       PAPPL_SOPTIONS_NONE
258            No options
259
260       PAPPL_SOPTIONS_NO_TLS
261            Disable TLS support
262
263       PAPPL_SOPTIONS_RAW_SOCKET
264            Accept jobs via raw sockets
265
266       PAPPL_SOPTIONS_USB_PRINTER
267            Accept jobs via USB for default printer (embedded Linux only)
268
269       PAPPL_SOPTIONS_WEB_INTERFACE
270            Enable the standard web pages
271
272       PAPPL_SOPTIONS_WEB_LOG
273            Enable the log file page
274
275       PAPPL_SOPTIONS_WEB_NETWORK
276            Enable the network settings page
277
278       PAPPL_SOPTIONS_WEB_REMOTE
279            Allow remote queue management (vs. localhost only)
280
281       PAPPL_SOPTIONS_WEB_SECURITY
282            Enable the user/password settings page
283
284       PAPPL_SOPTIONS_WEB_TLS
285            Enable the TLS settings page
286
287   pappl_wifi_state_e
288       "printer-wifi-state" values
289
290       PAPPL_WIFI_STATE_CANNOT_JOIN
291            ´cannot-join'
292
293       PAPPL_WIFI_STATE_JOINING
294            ´joining'
295
296       PAPPL_WIFI_STATE_NOT_CONFIGURED
297            ´not-configured'
298
299       PAPPL_WIFI_STATE_NOT_VISIBLE
300            ´not-visible'
301
302       PAPPL_WIFI_STATE_OFF
303            ´off'
304
305       PAPPL_WIFI_STATE_ON
306            ´on'
307

FUNCTIONS

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

STRUCTURES

1287   pappl_pr_driver_s
1288       Printer driver information
1289
1290       struct pappl_pr_driver_s
1291       {
1292         const char *description;
1293         const char *device_id;
1294         void *extension;
1295         const char *name;
1296       };
1297
1298   pappl_version_s
1299       Firmware version information
1300
1301       struct pappl_version_s
1302       {
1303         char name[64];
1304         char patches[64];
1305         char sversion[64];
1306         unsigned short version[4];
1307       };
1308
1309   pappl_wifi_s
1310       Wi-Fi status/configuration information
1311
1312       struct pappl_wifi_s
1313       {
1314         char ssid[128];
1315         pappl_wifi_state_t state;
1316       };
1317

TYPES

1319   pappl_auth_cb_t
1320       Authentication callback
1321
1322       typedef http_status_t (*pappl_auth_cb_t)(pappl_client_t *client, const char *group, gid_t groupid, void *cb_data);
1323
1324   pappl_ipp_op_cb_t
1325       IPP operation callback function
1326
1327       typedef bool (*pappl_ipp_op_cb_t)(pappl_client_t *client, void *data);
1328
1329   pappl_mime_cb_t
1330       MIME typing callback function
1331
1332       typedef const char * (*pappl_mime_cb_t)(const unsigned char *header, size_t headersize, void *data);
1333
1334   pappl_mime_filter_cb_t
1335       Filter callback function
1336
1337       typedef bool (*pappl_mime_filter_cb_t)(pappl_job_t *job, pappl_device_t *device, void *data);
1338
1339   pappl_pr_autoadd_cb_t
1340       Auto-add callback
1341
1342       typedef const char * (*pappl_pr_autoadd_cb_t)(const char *device_info, const char *device_uri, const char *device_id, void *data);
1343
1344   pappl_pr_create_cb_t
1345       Printer creation callback
1346
1347       typedef void (*pappl_pr_create_cb_t)(pappl_printer_t *printer, void *data);
1348
1349   pappl_pr_driver_cb_t
1350       Driver callback function
1351
1352       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);
1353
1354   pappl_pr_driver_t
1355       Printer driver information
1356
1357       typedef struct pappl_pr_driver_s pappl_pr_driver_t;
1358
1359   pappl_printer_cb_t
1360       Printer iterator callback function
1361
1362       typedef void (*pappl_printer_cb_t)(pappl_printer_t *printer, void *data);
1363
1364   pappl_resource_cb_t
1365       Dynamic resource callback function
1366
1367       typedef bool (*pappl_resource_cb_t)(pappl_client_t *client, void *data);
1368
1369   pappl_save_cb_t
1370       Save callback function
1371
1372       typedef bool (*pappl_save_cb_t)(pappl_system_t *system, void *data);
1373
1374   pappl_soptions_t
1375       Bitfield for system options
1376
1377       typedef unsigned pappl_soptions_t;
1378
1379   pappl_version_t
1380       Firmware version information
1381
1382       typedef struct pappl_version_s pappl_version_t;
1383
1384   pappl_wifi_join_cb_t
1385       Wi-Fi join callback
1386
1387       typedef bool (*pappl_wifi_join_cb_t)(pappl_system_t *system, void *data, const char *ssid, const char *psk);
1388
1389   pappl_wifi_list_cb_t
1390       Wi-Fi list callback
1391
1392       typedef int (*pappl_wifi_list_cb_t)(pappl_system_t *system, void *data, cups_dest_t **ssids);
1393
1394   pappl_wifi_state_t
1395       "printer-wifi-state" values
1396
1397       typedef enum pappl_wifi_state_e pappl_wifi_state_t;
1398
1399   pappl_wifi_status_cb_t
1400       Wi-Fi status callback
1401
1402       typedef pappl_wifi_t * (*pappl_wifi_status_cb_t)(pappl_system_t *system, void *data, pappl_wifi_t *wifi_data);
1403
1404   pappl_wifi_t
1405       Wi-Fi status/configuration information
1406
1407       typedef struct pappl_wifi_s pappl_wifi_t;
1408

COPYRIGHT

1415       Copyright © 2019-2022 by Michael R Sweet.
1416
1417       PAPPL is licensed under the Apache License Version  2.0  with  an  (op‐
1418       tional)  exception  to  allow linking against GPL2/LGPL2 software (like
1419       older versions of CUPS), so it can be used freely in any project  you'd
1420       like.   See the files "LICENSE" and "NOTICE" in the source distribution
1421       for more information.
1422
1423
1424
14252022-05-10                  pappl system functions             pappl-system(3)