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_RAW_SOCKET
261            Accept jobs via raw sockets
262
263       PAPPL_SOPTIONS_USB_PRINTER
264            Accept jobs via USB for default printer (embedded Linux only)
265
266       PAPPL_SOPTIONS_WEB_INTERFACE
267            Enable the standard web pages
268
269       PAPPL_SOPTIONS_WEB_LOG
270            Enable the log file page
271
272       PAPPL_SOPTIONS_WEB_NETWORK
273            Enable the network settings page
274
275       PAPPL_SOPTIONS_WEB_REMOTE
276            Allow remote queue management (vs. localhost only)
277
278       PAPPL_SOPTIONS_WEB_SECURITY
279            Enable the user/password settings page
280
281       PAPPL_SOPTIONS_WEB_TLS
282            Enable the TLS settings page
283

FUNCTIONS

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

STRUCTURES

1120   pappl_pr_driver_s
1121       Printer driver information
1122
1123       struct pappl_pr_driver_s
1124       {
1125         const char *description;
1126         const char *device_id;
1127         void *extension;
1128         const char *name;
1129       };
1130
1131   pappl_version_s
1132       Firmware version information
1133
1134       struct pappl_version_s
1135       {
1136         char name[64];
1137         char patches[64];
1138         char sversion[64];
1139         unsigned short version[4];
1140       };
1141

TYPES

1143   pappl_ipp_op_cb_t
1144       IPP operation callback function
1145
1146       typedef bool (*pappl_ipp_op_cb_t)(pappl_client_t *client, void *data);
1147
1148   pappl_mime_cb_t
1149       MIME typing callback function
1150
1151       typedef const char * (*pappl_mime_cb_t)(const unsigned char *header, size_t headersize, void *data);
1152
1153   pappl_mime_filter_cb_t
1154       Filter callback function
1155
1156       typedef bool (*pappl_mime_filter_cb_t)(pappl_job_t *job, pappl_device_t *device, void *data);
1157
1158   pappl_pr_autoadd_cb_t
1159       Auto-add callback
1160
1161       typedef const char * (*pappl_pr_autoadd_cb_t)(const char *device_info, const char *device_uri, const char *device_id, void *data);
1162
1163   pappl_pr_create_cb_t
1164       Printer creation callback
1165
1166       typedef void (*pappl_pr_create_cb_t)(pappl_printer_t *printer, void *data);
1167
1168   pappl_pr_driver_cb_t
1169       Driver callback function
1170
1171       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);
1172
1173   pappl_pr_driver_t
1174       Printer driver information
1175
1176       typedef struct pappl_pr_driver_s pappl_pr_driver_t;
1177
1178   pappl_printer_cb_t
1179       Printer iterator callback function
1180
1181       typedef void (*pappl_printer_cb_t)(pappl_printer_t *printer, void *data);
1182
1183   pappl_resource_cb_t
1184       Dynamic resource callback function
1185
1186       typedef bool (*pappl_resource_cb_t)(pappl_client_t *client, void *data);
1187
1188   pappl_save_cb_t
1189       Save callback function
1190
1191       typedef bool (*pappl_save_cb_t)(pappl_system_t *system, void *data);
1192
1193   pappl_soptions_t
1194       Bitfield for system options
1195
1196       typedef unsigned pappl_soptions_t;
1197
1198   pappl_version_t
1199       Firmware version information
1200
1201       typedef struct pappl_version_s pappl_version_t;
1202

COPYRIGHT

1209       Copyright © 2019-2020 by Michael R Sweet.
1210
1211       PAPPL  is  licensed  under  the Apache License Version 2.0 with an (op‐
1212       tional) exception to allow linking against  GPL2/LGPL2  software  (like
1213       older  versions of CUPS), so it can be used freely in any project you'd
1214       like.  See the files "LICENSE" and "NOTICE" in the source  distribution
1215       for more information.
1216
1217
1218
12192021-02-15                  pappl system functions             pappl-system(3)