Provided by: libpappl-dev_1.3.1-2_amd64 bug

NAME

       pappl-system - pappl system functions

LIBRARY

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

SYNOPSIS

       #include <pappl/pappl.h>

       typedef struct _pappl_system_s pappl_system_t;

       bool
       papplSystemAddListeners(pappl_system_t *system, const char *name);

       void
       papplSystemAddMIMEFilter(pappl_system_t *system, const char *srctype, const char *dsttype,
       pappl_mime_filter_cb_t cb, void *data);

       void
       papplSystemCleanJobs(pappl_system_t *system);

       pappl_system_t *
       papplSystemCreate(pappl_soptions_t  options,  const  char  *name,  int  port,  const  char
       *subtypes,  const  char  *spooldir,  const char *logfile, pappl_loglevel_t loglevel, const
       char *auth_service, bool tls_only);

       void
       papplSystemDelete(pappl_system_t *system);

       pappl_printer_t     *
       papplSystemFindPrinter(pappl_system_t *system, const char *resource, int printer_id, const
       char *device_uri);

       char      *
       papplSystemGetAdminGroup(pappl_system_t *system, char *buffer, size_t bufsize);

       const char     *
       papplSystemGetAuthService(pappl_system_t *system);

       pappl_contact_t     *
       papplSystemGetContact(pappl_system_t *system, pappl_contact_t *contact);

       int
       papplSystemGetDefaultPrinterID(pappl_system_t *system);

       char      *
       papplSystemGetDefaultPrintGroup(pappl_system_t *system, char *buffer, size_t bufsize);

       char      *
       papplSystemGetDNSSDName(pappl_system_t *system, char *buffer, size_t bufsize);

       const char     *
       papplSystemGetFooterHTML(pappl_system_t *system);

       char      *
       papplSystemGetGeoLocation(pappl_system_t *system, char *buffer, size_t bufsize);

       char      *
       papplSystemGetHostname(pappl_system_t *system, char *buffer, size_t bufsize);

       char      *
       papplSystemGetLocation(pappl_system_t *system, char *buffer, size_t bufsize);

       pappl_loglevel_t
       papplSystemGetLogLevel(pappl_system_t *system);

       size_t
       papplSystemGetMaxLogSize(pappl_system_t *system);

       char      *
       papplSystemGetName(pappl_system_t *system, char *buffer, size_t bufsize);

       int
       papplSystemGetNextPrinterID(pappl_system_t *system);

       pappl_soptions_t
       papplSystemGetOptions(pappl_system_t *system);

       char      *
       papplSystemGetOrganization(pappl_system_t *system, char *buffer, size_t bufsize);

       char      *
       papplSystemGetOrganizationalUnit(pappl_system_t *system, char *buffer, size_t bufsize);

       char      *
       papplSystemGetPassword(pappl_system_t *system, char *buffer, size_t bufsize);

       int
       papplSystemGetPort(pappl_system_t *system);

       const char     *
       papplSystemGetServerHeader(pappl_system_t *system);

       char      *
       papplSystemGetSessionKey(pappl_system_t *system, char *buffer, size_t bufsize);

       bool
       papplSystemGetTLSOnly(pappl_system_t *system);

       const char     *
       papplSystemGetUUID(pappl_system_t *system);

       int
       papplSystemGetVersions(pappl_system_t    *system,    int   max_versions,   pappl_version_t
       *versions);

       char      *
       papplSystemHashPassword(pappl_system_t *system, const char *salt,  const  char  *password,
       char *buffer, size_t bufsize);

       bool
       papplSystemIsRunning(pappl_system_t *system);

       bool
       papplSystemIsShutdown(pappl_system_t *system);

       void
       papplSystemIteratePrinters(pappl_system_t *system, pappl_printer_cb_t cb, void *data);

       bool
       papplSystemLoadState(pappl_system_t *system, const char *filename);

       const char     *
       papplSystemMatchDriver(pappl_system_t *system, const char *device_id);

       void
       papplSystemRemoveResource(pappl_system_t *system, const char *path);

       void
       papplSystemRun(pappl_system_t *system);

       bool
       papplSystemSaveState(pappl_system_t *system, const char *filename);

       void
       papplSystemSetAdminGroup(pappl_system_t *system, const char *value);

       void
       papplSystemSetContact(pappl_system_t *system, pappl_contact_t *contact);

       void
       papplSystemSetDefaultPrinterID(pappl_system_t *system, int default_printer_id);

       void
       papplSystemSetDefaultPrintGroup(pappl_system_t *system, const char *value);

       void
       papplSystemSetDrivers(pappl_system_t  *system,  int  num_drivers, pappl_driver_t *drivers,
       pappl_driver_cb_t cb, void *data);

       void
       papplSystemSetDNSSDName(pappl_system_t *system, const char *value);

       void
       papplSystemSetFooterHTML(pappl_system_t *system, const char *html);

       void
       papplSystemSetGeoLocation(pappl_system_t *system, const char *value);

       void
       papplSystemSetHostname(pappl_system_t *system, const char *value);

       void
       papplSystemSetLocation(pappl_system_t *system, const char *value);

       void
       papplSystemSetLogLevel(pappl_system_t *system, pappl_loglevel_t loglevel);

       void
       papplSystemSetMaxLogSize(pappl_system_t *system, size_t maxSize);

       void
       papplSystemSetMIMECallback(pappl_system_t *system, pappl_mime_cb_t cb, void *data);

       void
       papplSystemSetNextPrinterID(pappl_system_t *system, int next_printer_id);

       void
       papplSystemSetOperationCallback(pappl_system_t *system, pappl_ipp_op_cb_t cb, void *data);

       void
       papplSystemSetOrganization(pappl_system_t *system, const char *value);

       void
       papplSystemSetOrganizationalUnit(pappl_system_t *system, const char *value);

       void
       papplSystemSetPassword(pappl_system_t *system, const char *hash);

       void
       papplSystemSetSaveCallback(pappl_system_t *system, pappl_save_cb_t cb, void *data);

       void
       papplSystemSetUUID(pappl_system_t *system, const char *value);

       void
       papplSystemSetVersions(pappl_system_t   *system,   int    num_versions,    pappl_version_t
       *versions);

       void
       papplSystemShutdown(pappl_system_t *system);

DESCRIPTION

       The  PAPPL  system  functions provide access to the system object.  System are created and
       deleted by the printer application while the life cycle of the  pappl_system_t  object  is
       managed automatically for the printer application.  The papplSystemCreate function creates
       a new system while the papplSystemDelete function deletes a system.

       The papplSystemRun function starts a system while the papplSystemShutdown function stops a
       running system.

       The  papplSystemGet  functions  get  the current values associated with a system while the
       papplSystemSet functions set the current values associated with a system.

ENUMERATIONS

   pappl_netconf_e
       Network configuration mode

       PAPPL_NETCONF_DHCP
            Full DHCP

       PAPPL_NETCONF_DHCP_MANUAL
            DHCP with manual IP address

       PAPPL_NETCONF_MANUAL
            Manual IP, netmask, and router

       PAPPL_NETCONF_OFF
            Turn network interface off

   pappl_soptions_e
       System option bits

       PAPPL_SOPTIONS_DNSSD_HOST
            Use hostname in DNS-SD service names instead of serial number/UUID

       PAPPL_SOPTIONS_MULTI_QUEUE
            Support multiple printers

       PAPPL_SOPTIONS_NONE
            No options

       PAPPL_SOPTIONS_NO_TLS
            Disable TLS support

       PAPPL_SOPTIONS_RAW_SOCKET
            Accept jobs via raw sockets

       PAPPL_SOPTIONS_USB_PRINTER
            Accept jobs via USB for default printer (embedded Linux only)

       PAPPL_SOPTIONS_WEB_INTERFACE
            Enable the standard web pages

       PAPPL_SOPTIONS_WEB_LOG
            Enable the log file page

       PAPPL_SOPTIONS_WEB_NETWORK
            Enable the network settings page

       PAPPL_SOPTIONS_WEB_REMOTE
            Allow remote queue management (vs. localhost only)

       PAPPL_SOPTIONS_WEB_SECURITY
            Enable the user/password settings page

       PAPPL_SOPTIONS_WEB_TLS
            Enable the TLS settings page

   pappl_wifi_state_e
       "printer-wifi-state" values

       PAPPL_WIFI_STATE_CANNOT_JOIN
            ´cannot-join'

       PAPPL_WIFI_STATE_JOINING
            ´joining'

       PAPPL_WIFI_STATE_NOT_CONFIGURED
            ´not-configured'

       PAPPL_WIFI_STATE_NOT_VISIBLE
            ´not-visible'

       PAPPL_WIFI_STATE_OFF
            ´off'

       PAPPL_WIFI_STATE_ON
            ´on'

FUNCTIONS

   papplSystemAddEvent
       Add a notification event.

       void papplSystemAddEvent (
           pappl_system_t *system,
           pappl_printer_t *printer,
           pappl_job_t *job,
           pappl_event_t event,
           const char *message,
           ...
       );

   papplSystemAddListeners
       Add network or domain socket listeners.

       bool  papplSystemAddListeners (
           pappl_system_t *system,
           const char *name
       );

       This function adds socket listeners.  The "name" parameter specifies the listener address.
       Names  starting  with a slash (/) specify a UNIX domain socket path, otherwise the name is
       treated as a fully-qualified domain name or numeric IPv4 or  IPv6  address.   If  name  is
       NULL, the "any" addresses are used ("0.0.0.0" and "[::]").

       Listeners cannot be added after papplSystemRun is called.

   papplSystemAddMIMEFilter
       Add a file filter to the system.

       void papplSystemAddMIMEFilter (
           pappl_system_t *system,
           const char *srctype,
           const char *dsttype,
           pappl_mime_filter_cb_t cb,
           void *data
       );

       This  function  adds a file filter to the system to be used for processing different kinds
       of document data in print jobs.  The "srctype" and "dsttype" arguments specify the  source
       and  destination  MIME  media types as constant strings.  A destination MIME media type of
       "image/pwg-raster" specifies a filter that uses  the  driver's  raster  interface.   Other
       destination  types  imply  direct submission to the output device using the papplDeviceXxx
       functions.

       5      Note: This function may not be called while the system is running.

   papplSystemAddTimerCallback
       Add a timer callback to a system.

       bool  papplSystemAddTimerCallback (
           pappl_system_t *system,
           time_t start,
           int interval,
           pappl_timer_cb_t cb,
           void *cb_data
       );

       This function schedules a function that will be called on the main run loop thread at  the
       specified time and optionally every "interval" seconds thereafter.  The timimg accuracy is
       typically within a few milliseconds but is not guaranteed.  Since the callback is  run  on
       the  main  run  loop  thread,  functions  should  create a new thread for any long-running
       operations.

       The callback function receives the "system" and "cb_data" pointers  and  returns  true  to
       repeat the timer or false to remove it:

           bool my_timer_cb(pappl_system_t *system, void *cb_data)
           {
             ... do periodic task ...
             return (true); // repeat the timer
           }

   papplSystemCreate
       Create a system object.

       pappl_system_t * papplSystemCreate (
           pappl_soptions_t options,
           const char *name,
           int port,
           const char *subtypes,
           const char *spooldir,
           const char *logfile,
           pappl_loglevel_t loglevel,
           const char *auth_service,
           bool tls_only
       );

       This  function  creates  a  new  system  object, which is responsible for managing all the
       printers, jobs, and resources used by the printer application.

       The "options" argument specifies which options are enabled for the server:

       •    PAPPL_SOPTIONS_NONE: No options.

       •    PAPPL_SOPTIONS_DNSSD_HOST: When resolving DNS-SD service name collisions,
              use the DNS-SD hostname instead of a serial number or UUID.

       •    PAPPL_SOPTIONS_WEB_LOG: Include the log file web page.

       •    PAPPL_SOPTIONS_MULTI_QUEUE: Support multiple printers.

       •    PAPPL_SOPTIONS_WEB_NETWORK: Include the network settings web page.

       •    PAPPL_SOPTIONS_RAW_SOCKET: Accept jobs via raw sockets starting on port
              9100.

       •    PAPPL_SOPTIONS_WEB_REMOTE: Allow remote queue management.

       •    PAPPL_SOPTIONS_WEB_SECURITY: Include the security settings web page.

       •    PAPPL_SOPTIONS_WEB_INTERFACE: Include the standard printer and job monitoring
              web pages.

       •    PAPPL_SOPTIONS_WEB_TLS: Include the TLS settings page.

       •    PAPPL_SOPTIONS_USB_PRINTER: Accept jobs via USB for the default printer
              (embedded Linux only).

       The "name" argument specifies a human-readable name for the system.

       The "port" argument specifies the port number to bind to.  A value  of  0  will  cause  an
       available  port  number  to  be  assigned  when  the  first  listener  is  added  with the
       papplSystemAddListeners function.

       The "subtypes" argument specifies one or more  comma-delimited  DNS-SD  service  sub-types
       such as "_print" and "_universal".

       The  "spooldir"  argument  specifies  the  location  of  job  files.  If NULL, a temporary
       directory is created.

       The "logfile" argument specifies where to send log messages.  If NULL,  the  log  messages
       are written to a temporary file.

       The "loglevel" argument specifies the initial logging level.

       The "auth_service" argument specifies a PAM authentication service name.  If NULL, no user
       authentication will be provided.

       The "tls_only" argument controls whether the printer application will  accept  unencrypted
       connections.   In  general,  this  argument  should  always  be  false  (allow unencrypted
       connections) since not all clients support encrypted printing.

   papplSystemDelete
       Delete a system object.

       void papplSystemDelete (
           pappl_system_t *system
       );

       5      Note: A system object cannot be deleted while the system is running.

   papplSystemFindLoc
       Find a localization for the given printer and language.

       pappl_loc_t * papplSystemFindLoc (
           pappl_system_t *system,
           const char *language
       );

   papplSystemFindPrinter
       Find a printer by resource, ID, or device URI.

       pappl_printer_t * papplSystemFindPrinter (
           pappl_system_t *system,
           const char *resource,
           int printer_id,
           const char *device_uri
       );

       This function finds a printer contained in the system  using  its  resource  path,  unique
       integer  identifier,  or  device  URI.  If none of these is specified, the current default
       printer is returned.

   papplSystemFindSubscription
       Find a subscription.

       pappl_subscription_t * papplSystemFindSubscription (
           pappl_system_t *system,
           int sub_id
       );

       This function finds the numbered event notification subscription on a system.

   papplSystemGetAdminGroup
       Get the current administrative group, if any.

       char * papplSystemGetAdminGroup (
           pappl_system_t *system,
           char *buffer,
           size_t bufsize
       );

       This function copies the current administrative group, if any, to the specified buffer.

   papplSystemGetAuthService
       Get the PAM authorization service, if any.

       const char * papplSystemGetAuthService (
           pappl_system_t *system
       );

       This function returns  the  PAM  authorization  service  being  used  by  the  system  for
       authentication, if any.

   papplSystemGetContact
       Get the "system-contact" value.

       pappl_contact_t * papplSystemGetContact (
           pappl_system_t *system,
           pappl_contact_t *contact
       );

       This function copies the current system contact information to the specified buffer.

   papplSystemGetDNSSDName
       Get the current DNS-SD service name.

       char * papplSystemGetDNSSDName (
           pappl_system_t *system,
           char *buffer,
           size_t bufsize
       );

       This  function  copies  the  current  DNS-SD  service  name  of the system, if any, to the
       specified buffer.

   papplSystemGetDefaultPrintGroup
       Get the default print group, if any.

       char * papplSystemGetDefaultPrintGroup (
           pappl_system_t *system,
           char *buffer,
           size_t bufsize
       );

       This function copies the current default print group, if any, to the specified buffer.

   papplSystemGetDefaultPrinterID
       Get the current "default-printer-id" value.

       int  papplSystemGetDefaultPrinterID (
           pappl_system_t *system
       );

       This function returns the positive integer identifier for the current default printer or 0
       if there is no default printer.

   papplSystemGetFooterHTML
       Get the footer HTML for the web interface, if any.

       const char * papplSystemGetFooterHTML (
           pappl_system_t *system
       );

       This  function  returns  the HTML for the web page footer, if any.  The footer HTML can be
       set using the papplSystemSetFooterHTML function.

   papplSystemGetGeoLocation
       Get the system geo-location string, if any.

       char * papplSystemGetGeoLocation (
           pappl_system_t *system,
           char *buffer,
           size_t bufsize
       );

       This function copies the current system  geographic  location  as  a  "geo:"  URI  to  the
       specified buffer.

   papplSystemGetHostName
       Get the system hostname.

       char * papplSystemGetHostName (
           pappl_system_t *system,
           char *buffer,
           size_t bufsize
       );

       This function copies the current system hostname to the specified buffer.

   papplSystemGetHostPort
       Get the port number for network connections to
                                    the system.

       int  papplSystemGetHostPort (
           pappl_system_t *system
       );

       This function returns the port number that is used for network connections to the system.

   papplSystemGetLocation
       Get the system location string, if any.

       char * papplSystemGetLocation (
           pappl_system_t *system,
           char *buffer,
           size_t bufsize
       );

       This function copies the current human-readable location, if any, to the specified buffer.

   papplSystemGetLogLevel
       Get the system log level.

       pappl_loglevel_t  papplSystemGetLogLevel (
           pappl_system_t *system
       );

       This function returns the current system log level as an enumeration.

   papplSystemGetMaxClients
       Get the maximum number of clients.

       int  papplSystemGetMaxClients (
           pappl_system_t *system
       );

       This  function  gets  the  maximum  number of simultaneous clients that are allowed by the
       system.

   papplSystemGetMaxImageSize
       Get the maximum supported size for images.

       size_t  papplSystemGetMaxImageSize (
           pappl_system_t *system,
           int *max_width,
           int *max_height
       );

       This function retrieves the image size limits in bytes (uncompressed), columns, and lines.

   papplSystemGetMaxLogSize
       Get the maximum log file size.

       size_t  papplSystemGetMaxLogSize (
           pappl_system_t *system
       );

       This function gets the maximum log file size, which is only used when logging directly  to
       a  file.  When the limit is reached, the current log file is renamed to "filename.O" and a
       new log file is created.  Set the maximum size to 0 to disable log file rotation.

       The default maximum log file size is 1MiB or 1048576 bytes.

   papplSystemGetMaxSubscriptions
       Get the maximum number of event subscriptions.

       size_t  papplSystemGetMaxSubscriptions (
           pappl_system_t *system
       );

       This function gets the maximum number of event subscriptions that are allowed.  A  maximum
       of 0 means there is no limit.

       The default maximum number of event subscriptions is 100.

   papplSystemGetName
       Get the system name.

       char * papplSystemGetName (
           pappl_system_t *system,
           char *buffer,
           size_t bufsize
       );

       This function copies the current system name to the specified buffer.

   papplSystemGetNextPrinterID
       Get the next "printer-id" value.

       int  papplSystemGetNextPrinterID (
           pappl_system_t *system
       );

       This  function  returns  the  positive  integer  identifier that will be used for the next
       printer that is created.

   papplSystemGetOptions
       Get the system options.

       pappl_soptions_t  papplSystemGetOptions (
           pappl_system_t *system
       );

       This function returns the system options as a bitfield.

   papplSystemGetOrganization
       Get the system organization string, if any.

       char * papplSystemGetOrganization (
           pappl_system_t *system,
           char *buffer,
           size_t bufsize
       );

       This function copies the current organization name, if any, to the specified buffer.

   papplSystemGetOrganizationalUnit
       Get the system organizational unit string, if any.

       char * papplSystemGetOrganizationalUnit (
           pappl_system_t *system,
           char *buffer,
           size_t bufsize
       );

       This function copies the current organizational  unit  name,  if  any,  to  the  specified
       buffer.

   papplSystemGetPassword
       Get the current web site access password.

       char * papplSystemGetPassword (
           pappl_system_t *system,
           char *buffer,
           size_t bufsize
       );

       This function copies the current web site password hash, if any, to the specified buffer.

       Note: The access password is only used when the PAM authentication service is not set.

   papplSystemGetServerHeader
       Get the Server: header for HTTP responses.

       const char * papplSystemGetServerHeader (
           pappl_system_t *system
       );

       This function returns the value of the HTTP "Server:" header that is used by the system.

   papplSystemGetSessionKey
       Get the current session key.

       char * papplSystemGetSessionKey (
           pappl_system_t *system,
           char *buffer,
           size_t bufsize
       );

       This  function copies the current session key to the specified buffer.  The session key is
       used for web interface forms to provide CSRF protection and is refreshed periodically.

   papplSystemGetTLSOnly
       Get the TLS-only state of the system.

       bool  papplSystemGetTLSOnly (
           pappl_system_t *system
       );

       This function returns whether the system will only accept encrypted connections.

   papplSystemGetUUID
       Get the "system-uuid" value.

       const char * papplSystemGetUUID (
           pappl_system_t *system
       );

       This function returns the system's UUID value.

   papplSystemGetVersions
       Get the firmware names and versions.

       int  papplSystemGetVersions (
           pappl_system_t *system,
           int max_versions,
           pappl_version_t *versions
       );

       This function copies the system firmware information to the specified buffer.  The  return
       value   is  always  the  number  of  firmware  versions  that  have  been  set  using  the
       papplSystemSetVersions function, regardless of the value of the "max_versions" argument.

   papplSystemHashPassword
       Generate a password hash using salt and password strings.

       char * papplSystemHashPassword (
           pappl_system_t *system,
           const char *salt,
           const char *password,
           char *buffer,
           size_t bufsize
       );

       This function generates a password hash using the  "salt"  and  "password"  strings.   The
       "salt"  string  should be NULL to generate a new password hash or the value of an existing
       password hash to verify that a given plaintext  "password"  string  matches  the  password
       hash.

       5      Note: Hashed access passwords are only used when the PAM authentication

       5      service is not set.

   papplSystemIsRunning
       Return whether the system is running.

       bool  papplSystemIsRunning (
           pappl_system_t *system
       );

       This function returns whether the system is running.

   papplSystemIsShutdown
       Return whether the system has been shutdown.

       bool  papplSystemIsShutdown (
           pappl_system_t *system
       );

       This function returns whether the system is shutdown or scheduled to shutdown.

   papplSystemIteratePrinters
       Iterate all of the printers.

       void papplSystemIteratePrinters (
           pappl_system_t *system,
           pappl_printer_cb_t cb,
           void *data
       );

       This  function  iterates each of the printers managed by the system.  The "cb" function is
       called once per printer with the "system" and "data" values.

   papplSystemLoadState
       Load the previous system state.

       bool  papplSystemLoadState (
           pappl_system_t *system,
           const char *filename
       );

       This  function  loads  the  previous  system  state   from   a   file   created   by   the
       papplSystemSaveState function.  The system state contains all of the system object values,
       the list of printers, and the jobs for each printer.

       When loading a printer definition, if the printer cannot be  created  (e.g.,  because  the
       driver name is no longer valid) then that printer and all of its job history will be lost.
       In the case of a bad driver name, a printer application's driver callback can perform  any
       necessary  mapping  of  the driver name, including the use its auto-add callback to find a
       compatible new driver.

       5      Note: This function must be called prior to papplSystemRun.

   papplSystemMatchDriver
       const char * papplSystemMatchDriver (
           pappl_system_t *system,
           const char *device_id
       );

   papplSystemRemoveTimerCallback
       Remove a timer callback.

       void papplSystemRemoveTimerCallback (
           pappl_system_t *system,
           pappl_timer_cb_t cb,
           void *cb_data
       );

       This function removes all matching timer callbacks from the specified  system.   Both  the
       callback function and data must match to remove a timer.

   papplSystemRun
       Run the printer application.

       void papplSystemRun (
           pappl_system_t *system
       );

       This  function runs the printer application, accepting new connections, handling requests,
       and processing jobs as needed.  It returns once the system is shutdown, either through  an
       IPP request or SIGTERM.

   papplSystemSaveState
       Save the current system state.

       bool  papplSystemSaveState (
           pappl_system_t *system,
           const char *filename
       );

       This  function  saves  the  current system state to a file.  It is typically used with the
       papplSystemSetSaveCallback function to periodically save the state:

           papplSystemSetSaveCallback(system, (pappl_save_cb_t)papplSystemSaveState,
               (void *)filename);

   papplSystemSetAdminGroup
       Set the administrative group.

       void papplSystemSetAdminGroup (
           pappl_system_t *system,
           const char *value
       );

       This function sets the group name used for  administrative  requests  such  as  adding  or
       deleting a printer.

       5      Note: The administrative group is only used when the PAM authorization

       5      service is also set when the system is created.

   papplSystemSetAuthCallback
       Set an authentication callback for the specified scheme.

       void papplSystemSetAuthCallback (
           pappl_system_t *system,
           const char *auth_scheme,
           pappl_auth_cb_t auth_cb,
           void *auth_cbdata
       );

       This  function  sets  the  authentication  callback that is used for Client requests.  The
       authentication callback is used for every Client request containing  the  WWW-Authenticate
       header  (HTTP_FIELD_WWW_AUTHENTICATE).   The  callback returns one of the following status
       codes:

       •    HTTP_STATUS_CONTINUE if the authentication succeeded,

       •    HTTP_STATUS_UNAUTHORIZED if the authentication failed, or

       •    HTTP_STATUS_FORBIDDEN if the authentication succeeded but the user is
              not part of the specified group.</li> </ul>

   papplSystemSetContact
       Set the "system-contact" value.

       void papplSystemSetContact (
           pappl_system_t *system,
           pappl_contact_t *contact
       );

       This function sets the system contact value.

   papplSystemSetDNSSDName
       Set the DNS-SD service name.

       void papplSystemSetDNSSDName (
           pappl_system_t *system,
           const char *value
       );

       This function  sets  the  DNS-SD  service  name  of  the  system.   If  NULL,  the  DNS-SD
       registration is removed.

   papplSystemSetDefaultPrintGroup
       Set the default print group.

       void papplSystemSetDefaultPrintGroup (
           pappl_system_t *system,
           const char *value
       );

       This function sets the default group name used for print requests.

       5      Note: The default print group is only used when the PAM authorization

       5      service is also set when the system is created.

   papplSystemSetDefaultPrinterID
       Set the "default-printer-id" value.

       void papplSystemSetDefaultPrinterID (
           pappl_system_t *system,
           int default_printer_id
       );

       This function sets the default printer using its unique positive integer identifier.

   papplSystemSetEventCallback
       Set a callback for monitoring system events.

       void papplSystemSetEventCallback (
           pappl_system_t *system,
           pappl_event_cb_t event_cb,
           void *event_data
       );

       This function sets a callback function to receive event notifications from the system.

   papplSystemSetFooterHTML
       Set the footer HTML for the web interface.

       void papplSystemSetFooterHTML (
           pappl_system_t *system,
           const char *html
       );

       This function sets the footer HTML for the web interface.

       5      Note: The footer HTML can only be set prior to calling

       5      papplSystemRun.

   papplSystemSetGeoLocation
       Set the geographic location string.

       void papplSystemSetGeoLocation (
           pappl_system_t *system,
           const char *value
       );

       This  function  sets  the geographic location of the system as a "geo:" URI.  If NULL, the
       location is cleared.

   papplSystemSetHostName
       Set the system hostname.

       void papplSystemSetHostName (
           pappl_system_t *system,
           const char *value
       );

       This function sets the system hostname.  If NULL, the default hostname is used.

   papplSystemSetLocation
       Set the system location string, if any.

       void papplSystemSetLocation (
           pappl_system_t *system,
           const char *value
       );

       This function sets the human-readable location of the system.  If NULL,  the  location  is
       cleared.

   papplSystemSetLogLevel
       Set the system log level

       void papplSystemSetLogLevel (
           pappl_system_t *system,
           pappl_loglevel_t loglevel
       );

       This function sets the log level as an enumeration.

   papplSystemSetMIMECallback
       Set the MIME typing callback for the system.

       void papplSystemSetMIMECallback (
           pappl_system_t *system,
           pappl_mime_cb_t cb,
           void *data
       );

       This function sets a custom MIME typing callback for the system.  The MIME typing callback
       extends the built-in MIME typing support for other media types that are supported  by  the
       application, typically vendor print formats.

       The callback function receives a buffer containing the initial bytes of the document data,
       the length of the buffer, and the callback data.  It can then return NULL if  the  content
       is  not  recognized  or  a  constant  string  containing  the MIME media type, for example
       "application/vnd.hp-pcl" for HP PCL print data.

   papplSystemSetMaxClients
       Set the maximum number of clients.

       void papplSystemSetMaxClients (
           pappl_system_t *system,
           int max_clients
       );

       This function sets the maximum number of simultaneous clients  that  are  allowed  by  the
       system from 0 (auto) to 32768 (half of the available TCP port numbers).

       The default maximum number of clients is based on available system resources.

   papplSystemSetMaxImageSize
       Set the maximum allowed JPEG/PNG image sizes.

       void papplSystemSetMaxImageSize (
           pappl_system_t *system,
           size_t max_size,
           int max_width,
           int max_height
       );

       This  function  sets the maximum size allowed for JPEG and PNG images.  The default limits
       are 16384x16384 and 1/10th the maximum  memory  the  current  process  can  use  or  1GiB,
       whichever is less.

   papplSystemSetMaxLogSize
       Set the maximum log file size in bytes.

       void papplSystemSetMaxLogSize (
           pappl_system_t *system,
           size_t maxsize
       );

       This  function  sets  the  maximum log file size in bytes, which is only used when logging
       directly to a file.  When the limit is  reached,  the  current  log  file  is  renamed  to
       "filename.O" and a new log file is created.  Set the maximum size to 0 to disable log file
       rotation.

       The default maximum log file size is 1MiB or 1048576 bytes.

   papplSystemSetMaxSubscriptions
       Set the maximum number of event subscriptions.

       void papplSystemSetMaxSubscriptions (
           pappl_system_t *system,
           size_t max_subscriptions
       );

       This function Sets the maximum number of event subscriptions that are allowed.  A  maximum
       of 0 means there is no limit.

       The default maximum number of event subscriptions is 100.

   papplSystemSetNetworkCallbacks
       Set the network configuration callbacks.

       void papplSystemSetNetworkCallbacks (
           pappl_system_t *system,
           pappl_network_get_cb_t get_cb,
           pappl_network_set_cb_t set_cb,
           void *cb_data
       );

       This  function  sets the network configuration callbacks for a system.  The "get" callback
       reads the configuration of  all  network  interfaces  and  stores  them  in  an  array  of
       pappl_network_t  structures that is passed to the callback.  The "set" callback writes the
       configuration of all network interfaces and returns a boolean value indicating whether the
       configuration has been written successfully.

   papplSystemSetNextPrinterID
       Set the next "printer-id" value.

       void papplSystemSetNextPrinterID (
           pappl_system_t *system,
           int next_printer_id
       );

       This  function  sets the unique positive integer identifier that will be used for the next
       printer that is created.  It is typically only called as part of restoring the state of  a
       system.

       5      Note: The next printer ID can only be set prior to calling

       5      papplSystemRun.

   papplSystemSetOperationCallback
       Set the IPP operation callback.

       void papplSystemSetOperationCallback (
           pappl_system_t *system,
           pappl_ipp_op_cb_t cb,
           void *data
       );

       This  function  sets  a custom IPP operation handler for the system that is called for any
       IPP operations that are not handled by the built-in IPP services.

       5      Note: The operation callback can only be set prior to calling

       5      papplSystemRun.

   papplSystemSetOrganization
       Set the system organization string, if any.

       void papplSystemSetOrganization (
           pappl_system_t *system,
           const char *value
       );

       This function sets the organization name for the system.  If NULL, the name is cleared.

   papplSystemSetOrganizationalUnit
       Set the system organizational unit
                                              string, if any.

       void papplSystemSetOrganizationalUnit (
           pappl_system_t *system,
           const char *value
       );

       This function sets the organizational unit name for the system.   If  NULL,  the  name  is
       cleared.

   papplSystemSetPassword
       Set the access password hash string.

       void papplSystemSetPassword (
           pappl_system_t *system,
           const char *hash
       );

       This  function  sets  the  hash for the web access password.  The hash string is generated
       using the papplSystemHashPassword function.

       5      Note: The access password is only used when the PAM authentication service

       5      is not set.

   papplSystemSetPrinterDrivers
       Set the list of drivers and the driver
                                          callbacks.

       void papplSystemSetPrinterDrivers (
           pappl_system_t *system,
           int num_drivers,
           pappl_pr_driver_t *drivers,
           pappl_pr_autoadd_cb_t autoadd_cb,
           pappl_pr_create_cb_t create_cb,
           pappl_pr_driver_cb_t driver_cb,
           void *data
       );

       This function sets the lists of printer drivers, the optional auto-add callback  function,
       the optional creation callback, and the required driver initialization callback function.

       The  auto-add  callback  ("autoadd_cb")  finds  a compatible driver name for the specified
       printer.  It is used when the client or user specifies the "auto" driver name, and for the
       "autoadd" sub-command for the papplMainloop API.

       The  creation  callback ("create_cb") is called at the end of printer creation to make any
       common changes or additions to a new printer.  It is  typically  used  to  add  extra  web
       pages,  add  per-printer  static  resources,  and/or  initialize  the contact and location
       information.

       The  driver  initialization  callback  ("driver_cb")   is   called   to   initialize   the
       pappl_pr_driver_data_t  structure,  which  provides  all  of  the printer capabilities and
       callbacks for printing.

   papplSystemSetSaveCallback
       Set the save callback.

       void papplSystemSetSaveCallback (
           pappl_system_t *system,
           pappl_save_cb_t cb,
           void *data
       );

       This function sets a callback that is used to periodically save the current system  state.
       Typically  the  callback  function  ("cb")  is  papplSystemSaveState and the callback data
       ("data") is the name of the state file:

           papplSystemSetSaveCallback(system, (pappl_save_cb_t)papplSystemSaveState,
               (void *)filename);

       5      Note: The save callback can only be set prior to calling

       5      papplSystemRun.

   papplSystemSetUUID
       Set the system UUID.

       void papplSystemSetUUID (
           pappl_system_t *system,
           const char *value
       );

       This function sets the system UUID value, overriding the default (generated) value.  It is
       typically used when restoring the state of a previous incarnation of the system.

       5      Note: The UUID can only be set prior to calling papplSystemRun.

   papplSystemSetVersions
       Set the firmware names and versions.

       void papplSystemSetVersions (
           pappl_system_t *system,
           int num_versions,
           pappl_version_t *versions
       );

       This  function  sets  the  names  and  versions of each firmware/software component of the
       printer application.

   papplSystemSetWiFiCallbacks
       Set Wi-Fi callbacks.

       void papplSystemSetWiFiCallbacks (
           pappl_system_t *system,
           pappl_wifi_join_cb_t join_cb,
           pappl_wifi_list_cb_t list_cb,
           pappl_wifi_status_cb_t status_cb,
           void *data
       );

       This function sets the 802.11 Wi-Fi interface callbacks for the system.  The "join_cb"  is
       used  to  join  a Wi-Fi network, the "list_cb" is used to list available networks, and the
       "status_cb" is used to query the current Wi-Fi network connection status  and  Secure  Set
       Identifier  (SSID).   The  "join_cb" and "status_cb" functions are used to support getting
       and setting the IPP "printer-wifi-state", "printer-wifi-ssid", and "printer-wifi-password"
       attributes,  while  the  "list_cb"  function  enables  changing the Wi-Fi network from the
       network web interface, if enabled.

       Note: The Wi-Fi callbacks can only be set prior to calling papplSystemRun.

   papplSystemShutdown
       Shutdown the system.

       void papplSystemShutdown (
           pappl_system_t *system
       );

       This function tells the system to perform an orderly  shutdown  of  all  printers  and  to
       terminate the main loop.

STRUCTURES

   pappl_network_s
       Network interface information

       struct pappl_network_s
       {
         http_addr_t addr4;
         http_addr_t addr6;
         pappl_netconf_t config4;
         pappl_netconf_t config6;
         http_addr_t dns[2];
         char domain[64];
         http_addr_t gateway4;
         http_addr_t gateway6;
         char ident[256];
         http_addr_t linkaddr6;
         http_addr_t mask4;
         char name[64];
         unsigned prefix6;
         bool up;
       };

   pappl_pr_driver_s
       Printer driver information

       struct pappl_pr_driver_s
       {
         const char *description;
         const char *device_id;
         void *extension;
         const char *name;
       };

   pappl_version_s
       Firmware version information

       struct pappl_version_s
       {
         char name[64];
         char patches[64];
         char sversion[64];
         unsigned short version[4];
       };

   pappl_wifi_s
       Wi-Fi status/configuration information

       struct pappl_wifi_s
       {
         char ssid[128];
         pappl_wifi_state_t state;
       };

TYPES

   pappl_auth_cb_t
       Authentication callback

       typedef http_status_t (*pappl_auth_cb_t)(pappl_client_t *client, const char *group, gid_t groupid, void *cb_data);

   pappl_ipp_op_cb_t
       IPP operation callback function

       typedef bool (*pappl_ipp_op_cb_t)(pappl_client_t *client, void *data);

   pappl_mime_cb_t
       MIME typing callback function

       typedef const char * (*pappl_mime_cb_t)(const unsigned char *header, size_t headersize, void *data);

   pappl_mime_filter_cb_t
       Filter callback function

       typedef bool (*pappl_mime_filter_cb_t)(pappl_job_t *job, pappl_device_t *device, void *data);

   pappl_netconf_t
       Network configuration mode

       typedef enum pappl_netconf_e pappl_netconf_t;

   pappl_network_get_cb_t
       Get networks callback

       typedef size_t (*pappl_network_get_cb_t)(pappl_system_t *system, void *cb_data, size_t max_networks, pappl_network_t *networks);

   pappl_network_set_cb_t
       Set networks callback

       typedef bool (*pappl_network_set_cb_t)(pappl_system_t *system, void *cb_data, size_t num_networks, pappl_network_t *networks);

   pappl_network_t
       Network interface information

       typedef struct pappl_network_s pappl_network_t;

   pappl_pr_autoadd_cb_t
       Auto-add callback

       typedef const char * (*pappl_pr_autoadd_cb_t)(const char *device_info, const char *device_uri, const char *device_id, void *data);

   pappl_pr_create_cb_t
       Printer creation callback

       typedef void (*pappl_pr_create_cb_t)(pappl_printer_t *printer, void *data);

   pappl_pr_driver_cb_t
       Driver callback function

       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);

   pappl_pr_driver_t
       Printer driver information

       typedef struct pappl_pr_driver_s pappl_pr_driver_t;

   pappl_printer_cb_t
       Printer iterator callback function

       typedef void (*pappl_printer_cb_t)(pappl_printer_t *printer, void *data);

   pappl_resource_cb_t
       Dynamic resource callback function

       typedef bool (*pappl_resource_cb_t)(pappl_client_t *client, void *data);

   pappl_save_cb_t
       Save callback function

       typedef bool (*pappl_save_cb_t)(pappl_system_t *system, void *data);

   pappl_soptions_t
       Bitfield for system options

       typedef unsigned pappl_soptions_t;

   pappl_timer_cb_t
       Timer callback function

       typedef bool (*pappl_timer_cb_t)(pappl_system_t *system, void *cb_data);

   pappl_version_t
       Firmware version information

       typedef struct pappl_version_s pappl_version_t;

   pappl_wifi_join_cb_t
       Wi-Fi join callback

       typedef bool (*pappl_wifi_join_cb_t)(pappl_system_t *system, void *data, const char *ssid, const char *psk);

   pappl_wifi_list_cb_t
       Wi-Fi list callback

       typedef int (*pappl_wifi_list_cb_t)(pappl_system_t *system, void *data, cups_dest_t **ssids);

   pappl_wifi_state_t
       "printer-wifi-state" values

       typedef enum pappl_wifi_state_e pappl_wifi_state_t;

   pappl_wifi_status_cb_t
       Wi-Fi status callback

       typedef pappl_wifi_t * (*pappl_wifi_status_cb_t)(pappl_system_t *system, void *data, pappl_wifi_t *wifi_data);

   pappl_wifi_t
       Wi-Fi status/configuration information

       typedef struct pappl_wifi_s pappl_wifi_t;

SEE ALSO

       pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3), pappl-mainline(3),
       pappl-makeresheader(1),     pappl-printer(3),     pappl-resource(3),      pappl-system(3),
       https://www.msweet.org/pappl

COPYRIGHT

       Copyright © 2019-2022 by Michael R Sweet.

       PAPPL  is  licensed  under  the Apache License Version 2.0 with an (optional) exception to
       allow linking against GPL2/LGPL2 software (like older versions of CUPS), so it can be used
       freely  in  any  project  you'd  like.  See the files "LICENSE" and "NOTICE" in the source
       distribution for more information.