pappl-system(3)

📦

version 1.4.12 · 5 versions

1.4.12 · arch rolling, fedora 43, fedora 44, nixpkgs unstable (latest)
1.4.7 · opensuse-leap 16.0
1.0.3 · ubuntu jammy
1.4.9 · fedora 43, fedora 44, nixos 26.05, ubuntu questing, ubuntu resolute, ubuntu stonking
1.3.1 · debian bookworm, debian trixie, ubuntu noble

, in arch rolling, fedora 43, fedora 44, nixpkgs unstable

💖 pappl-system(3) 💖

okay bestie, sit down, hydrate, because we are reading pappl-system — that's the pappl system functions from section 3 of the manual. this is the whole beating heart of a printer application and it's honestly giving main character energy. no cap, we're about to go through every single one of these. 🫶

✨ 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 💅

so the PAPPL system functions are basically your backstage pass to the system object. 🎟️ Systems get created and deleted by the printer application, but the life cycle of the pappl_system_t object? that's managed automatically for the printer application. so you don't gotta babysit it, she handles herself. periodt.

papplSystemCreate makes you a brand new system, and papplSystemDelete deletes a system. that's the whole circle of life. 🦋

papplSystemRun starts a system running, while papplSystemShutdown stops a running system. start, stop. slay.

and then the classics: the papplSystemGet functions get the current values associated with a system, while the papplSystemSet functions set the current values associated with a system. get, set. the way that naming convention just works. 💅

🎀 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

the "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 one adds socket listeners. the name parameter is the listener address, and here's the tea: names starting with a slash (/) specify a UNIX domain socket path, otherwise the name gets treated as a fully-qualified domain name or a numeric IPv4 or IPv6 address. and if name is NULL? the "any" addresses get used ("0.0.0.0" and "[::]"). she's flexible like that. 💁

⚠️ Listeners cannot be added after papplSystemRun is called. so like, do it before the glow-up, bestie.

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 adds a file filter to the system so it can process 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. iykyk. ✨

😭 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 schedules a function that will be called on the main run loop thread at the specified time, and optionally every interval seconds thereafter. timing accuracy is typically within a few milliseconds but it is not guaranteed, so don't come for her if it's a lil late. 🙈

and because the callback runs on the main run loop thread, functions should create a new thread for any long-running operations. do not block the main character. ✋

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. 👑

papplSystemCreate

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

okay bestie, this is THE one — it makes a whole new system object, and that object is basically the main character that runs the show: it manages all the printers, jobs, and resources your printer app uses. 👑

The options argument says which options are turned on for the server:

PAPPL_SOPTIONS_NONE — no options at all, bare minimum era.
PAPPL_SOPTIONS_DNSSD_HOST — when DNS-SD service name collisions get resolved, 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, queen behavior.
PAPPL_SOPTIONS_WEB_NETWORK — include the network settings web page.
PAPPL_SOPTIONS_RAW_SOCKET — accept jobs via raw sockets starting on port 9100 (all but Windows).
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 is a human-readable name for the system. give it a cute one 💖

The port argument is the port number to bind to. if you pass 0, an available port number gets assigned later — specifically when the first listener is added with the papplSystemAddListeners function. lowkey magical ✨

The subtypes argument is one or more comma-delimited DNS-SD service sub-types, like "_print" and "_universal".

The spooldir argument is where job files live. if it's NULL, a temporary directory gets created instead.

The logfile argument is where log messages go. three special values are recognized:

NULL — log messages are written to a temporary file.
"-" — log messages are written to the standard error file.
"syslog" — log messages are sent to the system logging daemon.

The loglevel argument is the initial logging level.

The auth_service argument is a PAM authentication service name. if it's NULL, no user authentication will be provided. no gatekeeping then 🫶

The tls_only argument controls whether the printer application will accept unencrypted connections. and fr fr, this one should basically always be false (allow unencrypted connections), because not all clients support encrypted printing. don't be that girl who locks everyone out 💅

papplSystemCreatePrinters

Create newly discovered printers.

bool papplSystemCreatePrinters (
    pappl_system_t *system,
    pappl_devtype_t types,
    pappl_pr_create_cb_t cb,
    void *cb_data
);

This one lists all devices specified by types and tries to add any new printers it finds. the callback function cb gets invoked for each printer that gets added. so it's like a lil printer scavenger hunt 🔍

papplSystemDelete

Delete a system object.

void papplSystemDelete (
    pappl_system_t *system
);

⚠️ Note: a system object cannot be deleted while the system is running. not while it's on its grind, bestie.

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, its unique integer identifier, or its device URI. if you don't specify any of those, it just hands you the current default printer. 🖨️

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, into 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 the system is using 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 info into 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, into 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, into 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. zero means nobody's holding the crown 👑

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. you can set that footer HTML with 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, into 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 into 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's 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, into 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 max number of simultaneous clients the system allows. it's giving capacity limit 💅

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 max log file size — and heads up, that's only used when logging directly to a file. once the limit is hit, the current log file gets renamed to "filename.O" and a brand new log file is created. set the max size to 0 to disable log file rotation entirely.

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 max number of event subscriptions that are allowed. a maximum of 0 means there's no limit at all — unlimited era ✨

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 into 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 gets created. manifesting the next one 🔮

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, into 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, into 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, into 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 hands you back the value of the HTTP Server: header that the system is out here repping. That's its whole personality. ✨

papplSystemGetSessionKey

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

Okay so this one copies the current session key into the buffer you handed it. And bestie, that session key is not decorative — it's what the web interface forms use for CSRF protection, and it gets refreshed periodically. So like, don't hoard it. 🔐

papplSystemGetTLSOnly

bool  papplSystemGetTLSOnly (
    pappl_system_t *system
);

Tells you whether the system is in its "encrypted connections only, no exceptions" era. 💅

papplSystemGetUUID

const char * papplSystemGetUUID (
    pappl_system_t *system
);

Returns the system's system-uuid value. That's it, that's the whole vibe. 🦋

papplSystemGetVersions

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

This copies the system firmware info into the buffer you specified. And here's the little plot twist: the return value is always the number of firmware versions that have been set using the papplSystemSetVersions function — no matter what you passed for max_versions. So max_versions is lowkey just a suggestion, but the count is the truth. 💀

papplSystemHashPassword

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

Generates a password hash using the salt and password strings. The tea on how to use it:

Pass salt as NULL when you want to generate a brand-new password hash.
Pass salt as the value of an existing password hash when you want to verify that a given plaintext password string actually matches that hash.

📌 Note: Hashed access passwords are only used when the PAM authentication service is not set. So if PAM's on the scene, this whole thing is sitting it out. 🙈

papplSystemIsRunning

bool  papplSystemIsRunning (
    pappl_system_t *system
);

Returns whether the system is running. Yes, the function name really does tell you everything. Main character behaviour. 👑

papplSystemIsShutdown

bool  papplSystemIsShutdown (
    pappl_system_t *system
);

Returns whether the system is shutdown or scheduled to shutdown. Two moods, one boolean. 😭

papplSystemIteratePrinters

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

Iterates every single printer managed by the system. Your cb function gets called once per printer, and it receives the system and data values. It's giving "roll call, everybody say present". 🫶

papplSystemLoadState

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

Loads the previous system state from a file that was created by the papplSystemSaveState function. And that state file is stuffed: all of the system object values, the list of printers, and the jobs for each printer. It's the whole scrapbook. 📖

Now here's the part where you gotta pay attention: when loading a printer definition, if the printer can't be created — say, because the driver name is no longer valid — then that printer and all of its job history will be lost. Gone. Poof. 💀 In the case of a bad driver name, though, a printer application's driver callback can perform any necessary mapping of the driver name, including using its auto-add callback to find a compatible new driver. So there's a rescue arc available if you write it.

📌 Note: This function must be called prior to papplSystemRun. Not after. Prior. Periodt.

papplSystemMatchDriver

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

That's literally the whole entry — signature only, no blurb. It's mysterious. It's giving silent but iconic. 🤫

papplSystemRemoveTimerCallback

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

Removes all matching timer callbacks from the specified system. And bestie, it's strict about it: both the callback function and the data have to match for a timer to get removed. Half a match? Not enough. Not on its watch. ✋

papplSystemRun

void papplSystemRun (
    pappl_system_t *system
);

This is the one that actually 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. So yeah, this is the function that's just out here living its life until somebody tells it to stop. 🌈

papplSystemSaveState

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

Saves the current system state to a file. It's typically used together with the papplSystemSetSaveCallback function to periodically save the state, like this:

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

Look at that little duo. Saving the state on a schedule. So responsible of them. 🎀

papplSystemSetAdminGroup

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

Sets the group name used for administrative requests — you know, the big-girl stuff like adding or deleting a printer. 👑

📌 Note: The administrative group is only used when the PAM authorization service is also set when the system is created. Both or nothing, bestie.

papplSystemSetAuthCallback

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

Sets the authentication callback used for Client requests. This callback fires for every Client request that contains the WWW-Authenticate header (HTTP_FIELD_WWW_AUTHENTICATE). And the callback returns one of these status codes:

HTTP_STATUS_CONTINUE if the authentication succeeded ✅
HTTP_STATUS_UNAUTHORIZED if the authentication failed 🙅
HTTP_STATUS_FORBIDDEN if the authentication succeeded but the user is not part of the specified group 😤

📌 Note: The authentication callback can only be set prior to calling papplSystemRun. After that? Too late, the party's started.

papplSystemSetContact

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

Sets the system-contact value. Somebody's gotta be the point of contact, and today it's this function. 📮

papplSystemSetDNSSDName

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

Sets the DNS-SD service name of the system. And if you pass NULL? The DNS-SD registration gets removed. So NULL is the "actually never mind" option. ✨

papplSystemSetDefaultPrintGroup

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

Sets the default group name used for print requests.

📌 Note: The default print group is only used when the PAM authorization service is also set when the system is created. Same deal as the admin group, no cap.

papplSystemSetDefaultPrinterID

void papplSystemSetDefaultPrinterID (
    pappl_system_t *system,
    int default_printer_id
);

Sets the default printer using its unique positive integer identifier. So like, the number, not the name. 🎯

papplSystemSetEventCallback

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

Sets a callback function to receive event notifications from the system. It's the system's way of going "bestie, something happened". 🔔

papplSystemSetFooterHTML

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

Sets the footer HTML for the web interface. Give that footer some flavour. 💅

📌 Note: The footer HTML can only be set prior to calling papplSystemRun.

papplSystemSetGeoLocation

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

Sets the geographic location of the system as a geo: URI. Pass NULL and the location gets cleared — the system's just cosmically nowhere now. 🗺️

papplSystemSetHostName

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

Sets the system hostname. And if you pass NULL, the default hostname gets used. No name? Fine, it'll pick one itself. 🦋

papplSystemSetLocation

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

Sets the human-readable location of the system — the "hey I'm on the second floor by the window" kind of location, not the fancy URI kind. Pass NULL and the location is cleared. 🌸

papplSystemSetLogLevel

void papplSystemSetLogLevel (
    pappl_system_t *system,
    pappl_loglevel_t loglevel
);

Sets the log level as an enumeration. Yes bestie, it takes a pappl_loglevel_t, not a number you made up. Respect the enum. 🎀

papplSystemSetMIMECallback

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

Sets a custom MIME typing callback for the system. What does that do for you? It extends the built-in MIME typing support to cover other media types your application supports — typically vendor print formats. So your weird little proprietary format can finally get recognised. 😌

The callback function receives a buffer containing the initial bytes of the document data, the length of the buffer, and the callback data. Then it can do one of two things:

Return NULL if the content is not recognized 🙈
Return a constant string containing the MIME media type — for example "application/vnd.hp-pcl" for HP PCL print data 🔥

papplSystemSetMaxClients

void papplSystemSetMaxClients (
    pappl_system_t *system,
    int max_clients
);

Sets the maximum number of simultaneous clients the system will allow, and the range goes from 0 (auto) all the way up to 32768 — which, fun fact, is half of the available TCP port numbers. 🧮

The default maximum number of clients is based on available system resources. So it just reads the room and decides. ✨

papplSystemSetMaxImageSize

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

Sets the maximum size allowed for JPEG and PNG images. The default limits are 16384x16384, plus 1/10th the maximum memory the current process can use — or 1GiB, whichever is less. So it's the smaller of the two, always. Don't try to sneak a giant image past it. 💀

papplSystemSetMaxLogSize

void papplSystemSetMaxLogSize (
    pappl_system_t *system,
    size_t maxsize
);

okay so continuing from where we left off, bestie — this one sets the maximum log file size in bytes, and it's literally only used when you're logging straight to a file. when the limit hits, the current log file gets renamed to "filename.O" and a brand-new log file pops off. set the maximum size to 0 to disable log file rotation entirely. no cap. 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. 💾

Note: The next printer ID can only be set prior to calling 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. 👑

Note: The operation callback can only be set prior to calling 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. 💖

Note: The access password is only used when the PAM authentication service 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);

Note: The save callback can only be set prior to calling 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. 🔄

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 🦋

ok so this is the cast of characters — all the typedefs and callback signatures PAPPL hands you so you can plug your own brain into it. every single one, no skips 💖

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

this is the bouncer at the door bestie 🚪✨ — it gets handed the client, a group name, a groupid, and your cb_data, and it decides whether they get in.

🌸 `pappl_ipp_op_cb_t`

IPP operation callback function

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

custom IPP operation handler energy. client plus your data, returns a bool. slay.

🎀 `pappl_mime_cb_t`

MIME typing callback function

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

you look at a header blob of headersize bytes and hand back the MIME type as a const char *. it's giving "i'll tell you what this file is" 💅

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

you get a job and a device and your data, and you return bool. filter behavior, iconic.

✨ `pappl_netconf_t`

Network configuration mode

typedef enum pappl_netconf_e pappl_netconf_t;

just a lil typedef so you can say pappl_netconf_t instead of enum pappl_netconf_e 🫶

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

you fill up to max_networks entries into networks and report back how many you actually gave them (size_t). no cap, only as many as fit 💀

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

the setter twin — num_networks of them, in networks, and you return bool to say if it worked.

🍓 `pappl_network_t`

Network interface information

typedef struct pappl_network_s pappl_network_t;

opaque struct handle for network interface info. main character of the network world 👑

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

you get device_info, device_uri, device_id and data, and you return a const char * — the magic of auto-adding printers to the lineup ✨

💖 `pappl_pr_create_cb_t`

Printer creation callback

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

returns nothing, just vibes. it hands you the freshly created printer and your data — go do your thing 🎀

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

the big one. system, driver_name, device_uri, device_id, a driver_data pointer, a driver_attrs double-pointer, and your data. returns bool. this is the driver plug-in point, periodt 🔥

🌟 `pappl_pr_driver_t`

Printer driver information

typedef struct pappl_pr_driver_s pappl_pr_driver_t;

opaque handle holding printer driver info. very demure, very opaque 💅

🌸 `pappl_printer_cb_t`

Printer iterator callback function

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

for looping over printers — you get each printer and your data, and you return absolutely nothing. iterator vibes only 🦋

🎀 `pappl_resource_cb_t`

Dynamic resource callback function

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

client + data, returns bool. this is how you serve up dynamic resources, iykyk.

✨ `pappl_save_cb_t`

Save callback function

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

save that state bestie 💾 — system and data in, bool out.

🧚 `pappl_soptions_t`

Bitfield for system options

typedef unsigned pappl_soptions_t;

just an unsigned doing bitfield duties for system options. bitwise girlies rise 🫶

💜 `pappl_timer_cb_t`

Timer callback function

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

ding! ⏰ system and cb_data in, bool out. your recurring moment to shine.

🌈 `pappl_version_t`

Firmware version information

typedef struct pappl_version_s pappl_version_t;

opaque struct for firmware version info. it's giving "we don't show you the internals" 💅

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

you get the ssid and the psk and you go connect. returns bool — did we get in or not 😭

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

hand back a list of ssids as cups_dest_t ** and return an int. show me the networks, bestie 📶

✨ `pappl_wifi_state_t`

"printer-wifi-state" values

typedef enum pappl_wifi_state_e pappl_wifi_state_t;

enum typedef for the values that live in printer-wifi-state. literally the wifi mood ring.

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

you get wifi_data and hand back a pappl_wifi_t *. status check slay 💖

👑 `pappl_wifi_t`

Wi-Fi status/configuration information

typedef struct pappl_wifi_s pappl_wifi_t;

opaque struct holding Wi-Fi status and configuration. the whole wifi situation, wrapped up 🎀

🌟 SEE ALSO 🌟

the whole friend group, go say hi 👋

💖 COPYRIGHT 💖

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.

okay so real talk — that optional exception is the whole reason it can play nice with older CUPS builds, so don't lose the LICENSE and NOTICE files, fr fr 🙈

and that's a wrap on the whole page, bestie 🎀 this part came from the pappl system functions side of the docs, filed under pappl-system(3), dated 2026-08-11. go forth and build printers, you absolute icon 💅✨👑

📦 where this page comes from

arch rolling: pappl 1.4.12-1 · Apache-2.0 WITH LLVM-exception
fedora 43: pappl-devel 1.4.12-1.fc43 · Apache-2.0 WITH LLVM-exception
fedora 43: pappl-devel 1.4.12-1.fc43 · Apache-2.0 WITH LLVM-exception
fedora 44: pappl-devel 1.4.12-1.fc44 · Apache-2.0 WITH LLVM-exception
fedora 44: pappl-devel 1.4.12-1.fc44 · Apache-2.0 WITH LLVM-exception
nixpkgs unstable: pappl 1.4.12
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-19: a language model's rewrite of the original, under its terms