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_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

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.

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

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

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

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.

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.

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

pappl_loglevel_t  papplSystemGetLogLevel (


    pappl_system_t *system
);

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.

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.

papplSystemGetPort

Get the port number for network connections to the system.

int  papplSystemGetPort (


    pappl_system_t *system
);

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

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.

Note: Hashed access passwords are only used when the PAM authentication 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.

Note: This function must be called prior to papplSystemRun.

papplSystemMatchDriver

const char * papplSystemMatchDriver (


    pappl_system_t *system,


    const char *device_id
);

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


    ```

Note: This function must be called prior to papplSystemRun

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.

Note: The administrative group is only used when the PAM authorization service is also set when the system is created.

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.

Note: The default print group is only used when the PAM authorization 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.

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.

Note: The footer HTML can only be set prior to calling 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.

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.

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

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.

Note: The firmware information 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.

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_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_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_version_t

Firmware version information

typedef struct pappl_version_s pappl_version_t;