Provided by: libpappl-dev_1.3.1-2.1build3_amd64 
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.