Provided by: libpappl-dev_1.3.1-2_amd64 
NAME
pappl-device - pappl device functions
LIBRARY
Printer Application Framework (libpappl, "pkg-config --cflags --libs pappl")
SYNOPSIS
#include <pappl/pappl.h>
typedef struct _pappl_device_s pappl_device_t;
void
papplDeviceAddScheme(const char *scheme, pappl_dtype_t dtype, pappl_devlist_cb_t list_cb,
pappl_devopen_cb_t open_cb, pappl_devclose_cb_t close_cb, pappl_devread_cb_t read_cb,
pappl_devwrite_cb_t write_cb, pappl_devstatus_cb_t status_cb);
void
papplDeviceClose(pappl_device_t *device);
void
papplDeviceError(pappl_device_t *device, const char *message, ...);
void
papplDeviceFlush(pappl_device_t *device);
void *
papplDeviceGetData(pappl_device_t *device);
pappl_dmetrics_t *
papplDeviceGetMetrics(pappl_device_t *device, pappl_dmetrics_t *metrics);
pappl_preason_t
papplDeviceGetStatus(pappl_device_t *device);
bool
papplDeviceList(pappl_dtype_t types, pappl_device_cb_t cb, void *data, pappl_deverror_cb_t
err_cb, void *err_data);
pappl_device_t *
papplDeviceOpen(const char *device_uri, const char *name, pappl_deverror_cb_t err_cb, void
*err_data);
int
papplDeviceParse1284ID(const char *device_id, cups_option_t **pairs);
ssize_t
papplDevicePrintf(pappl_device_t *device, const char *format, ...);
ssize_t
papplDevicePuts(pappl_device_t *device, const char *s);
ssize_t
papplDeviceRead(pappl_device_t *device, void *buffer, size_t bytes);
void
papplDeviceSetData(pappl_device_t *device, void *data);
ssize_t
papplDeviceWrite(pappl_device_t *device, const void *buffer, size_t bytes);
DESCRIPTION
The PAPPL device functions provide access to output device connections and to list
available output devices. Output devices are accessed using Uniform Resource Identifier
(URI) strings such as "file:///path/to/file-or-directory", "socket://11.22.33.44", and
"usb://make/model?serial=number".
The papplDeviceList function lists available output devices, providing each available
output device to the supplied callback function. The list only contains devices whose URI
scheme supports discovery, at present USB printers and network printers that advertise
themselves using DNS-SD/mDNS and/or SNMPv1.
The papplDeviceOpen function opens a connection to an output device using its URI. The
papplDeviceClose function closes the connection.
The papplDevicePrintf, papplDevicePuts, and papplDeviceWrite functions send data to the
device, while the papplDeviceRead function reads data from the device.
The papplDeviceGetMetrics function gets statistical information about all communications
with the device while it has been open, while the papplDeviceGetStatus function gets the
hardware status of a device and maps it to the pappl_preason_t bitfield.
ENUMERATIONS
pappl_devtype_e
Device type bit values
PAPPL_DEVTYPE_ALL
All printers
PAPPL_DEVTYPE_CUSTOM_LOCAL
Local printer using a custom interface or protocol
PAPPL_DEVTYPE_CUSTOM_NETWORK
Network printer using a custom interface or protocol
PAPPL_DEVTYPE_DNS_SD
Network printers discovered via DNS-SD/mDNS
PAPPL_DEVTYPE_FILE
Local file/directory
PAPPL_DEVTYPE_LOCAL
All local printers
PAPPL_DEVTYPE_NETWORK
All network printers
PAPPL_DEVTYPE_SNMP
Network printers discovered via SNMP
PAPPL_DEVTYPE_SOCKET
Network printers using raw socket
PAPPL_DEVTYPE_USB
USB printers
FUNCTIONS
papplDeviceAddScheme
Add a device URI scheme.
void papplDeviceAddScheme (
const char *scheme,
pappl_devtype_t dtype,
pappl_devlist_cb_t list_cb,
pappl_devopen_cb_t open_cb,
pappl_devclose_cb_t close_cb,
pappl_devread_cb_t read_cb,
pappl_devwrite_cb_t write_cb,
pappl_devstatus_cb_t status_cb,
pappl_devid_cb_t id_cb
);
This function registers a device URI scheme with PAPPL, so that devices using the named
scheme can receive print data, report status information, and so forth. PAPPL includes
support for the following URI schemes:
• dnssd: Network printers discovered using DNS-SD.
• file: Character device files, plain files, and directories.
• snmp: Network printers discovered using SNMPv1.
• socket: Network printers using a hostname or numeric IP address.
• usb: Class 1 (unidirectional) or 2 (bidirectional) USB printers.
The "scheme" parameter specifies the URI scheme and must consist of lowercase letters,
digits, "-", "_", and/or ".", for example "x-foo" or "com.example.bar".
The "dtype" parameter specifies the device type and should be PAPPL_DTYPE_CUSTOM_LOCAL for
locally connected printers and PAPPL_DTYPE_CUSTOM_NETWORK for network printers.
Each of the callbacks corresponds to one of the papplDevice functions:
• "list_cb": Implements discovery of devices (optional)
• "open_cb": Opens communication with a device and allocates any device-
specific data as needed
• "close_cb": Closes communication with a device and frees any device-
specific data as needed
• "read_cb": Reads data from a device
• "write_cb": Write data to a device
• "status_cb": Gets basic printer state information from a device (optional)
• "id_cb": Gets the current IEEE-1284 device ID from a device (optional)
The "open_cb" callback typically calls papplDeviceSetData to store a pointer to contextual
information for the connection while the "close_cb", "id_cb", "read_cb", "write_cb", and
"status_cb" callbacks typically call papplDeviceGetData to retrieve it.
papplDeviceAddScheme2
Add a device URI scheme with supply-level queries.
void papplDeviceAddScheme2 (
const char *scheme,
pappl_devtype_t dtype,
pappl_devlist_cb_t list_cb,
pappl_devopen_cb_t open_cb,
pappl_devclose_cb_t close_cb,
pappl_devread_cb_t read_cb,
pappl_devwrite_cb_t write_cb,
pappl_devstatus_cb_t status_cb,
pappl_devsupplies_cb_t supplies_cb,
pappl_devid_cb_t id_cb
);
This function registers a device URI scheme with PAPPL, so that devices using the named
scheme can receive print data, report status information, and so forth. PAPPL includes
support for the following URI schemes:
• dnssd: Network printers discovered using DNS-SD.
• file: Character device files, plain files, and directories.
• snmp: Network printers discovered using SNMPv1.
• socket: Network printers using a hostname or numeric IP address.
• usb: Class 1 (unidirectional) or 2 (bidirectional) USB printers.
The "scheme" parameter specifies the URI scheme and must consist of lowercase letters,
digits, "-", "_", and/or ".", for example "x-foo" or "com.example.bar".
The "dtype" parameter specifies the device type and should be PAPPL_DTYPE_CUSTOM_LOCAL for
locally connected printers and PAPPL_DTYPE_CUSTOM_NETWORK for network printers.
Each of the callbacks corresponds to one of the papplDevice functions:
• "list_cb": Implements discovery of devices (optional)
• "open_cb": Opens communication with a device and allocates any device-
specific data as needed
• "close_cb": Closes communication with a device and frees any device-
specific data as needed
• "read_cb": Reads data from a device
• "write_cb": Write data to a device
• "status_cb": Gets basic printer state information from a device (optional)
• "supplies_cb": Gets supply level information from a device (optional)
• "id_cb": Gets the current IEEE-1284 device ID from a device (optional)
The "open_cb" callback typically calls papplDeviceSetData to store a pointer to contextual
information for the connection while the "close_cb", "id_cb", "read_cb", "write_cb",
"status_cb", and "supplies_cb" callbacks typically call papplDeviceGetData to retrieve it.
papplDeviceClose
Close a device connection.
void papplDeviceClose (
pappl_device_t *device
);
This function flushes any pending write data and closes the connection to a device.
papplDeviceError
Report an error on a device.
void papplDeviceError (
pappl_device_t *device,
const char *message,
...
);
This function reports an error on a device using the client-supplied callback function.
It is normally called from any custom device URI scheme callbacks you implement.
papplDeviceFlush
Flush any buffered data to the device.
void papplDeviceFlush (
pappl_device_t *device
);
This function flushes any pending write data sent using the papplDevicePrintf,
papplDevicePuts, or papplDeviceWrite functions to the device.
papplDeviceGetData
Get device-specific data.
void * papplDeviceGetData (
pappl_device_t *device
);
This function returns any device-specific data that has been set by the device open
callback. It is normally only called from any custom device URI scheme callbacks you
implement.
papplDeviceGetID
Get the IEEE-1284 device ID.
char * papplDeviceGetID (
pappl_device_t *device,
char *buffer,
size_t bufsize
);
This function queries the IEEE-1284 device ID from the device and copies it to the
provided buffer. The buffer must be at least 64 bytes and should be at least 1024 bytes
in length.
5 Note: This function can block for up to several seconds depending on
5 the type of connection.
papplDeviceGetMetrics
Get the device metrics.
pappl_devmetrics_t * papplDeviceGetMetrics (
pappl_device_t *device,
pappl_devmetrics_t *metrics
);
This function returns a copy of the device metrics data, which includes the number, length
(in bytes), and duration (in milliseconds) of read, status, and write requests for the
current session. This information is normally used for performance measurement and
optimization during development of a printer application. It can also be useful
diagnostic information.
papplDeviceGetStatus
Get the printer status bits.
pappl_preason_t papplDeviceGetStatus (
pappl_device_t *device
);
This function returns the current printer status bits, as applicable to the current
device.
The status bits for USB devices come from the original Centronics parallel printer
"standard" which was later formally standardized in IEEE 1284-1984 and the USB Device
Class Definition for Printing Devices. Some vendor extensions are also supported.
The status bits for network devices come from the hrPrinterDetectedErrorState property
that is defined in the SNMP Printer MIB v2 (RFC 3805).
This function returns a pappl_preason_t bitfield which can be passed to the
papplPrinterSetReasons function. Use the PAPPL_PREASON_DEVICE_STATUS value as the value
of the "remove" argument.
5 Note: This function can block for several seconds while getting the status
5 information.
papplDeviceGetSupplies
Get the current printer supplies.
int papplDeviceGetSupplies (
pappl_device_t *device,
int max_supplies,
pappl_supply_t *supplies
);
This function returns the number, type, and level of current printer supply levels, as
applicable to the current device.
The supply levels for network devices come from the prtSupplyTable and
prtMarkerColorantTable properties that are defined in the SNMP Printer MIB v2 (RFC 3805).
The supply levels for other devices are not standardized and must be queried using other
methods.
5 Note: This function can block for several seconds while getting the supply
5 information.
papplDeviceIsSupported
Determine whether a given URI is supported.
bool papplDeviceIsSupported (
const char *uri
);
This function determines whether a given URI or URI scheme is supported as a device.
papplDeviceList
List available devices.
bool papplDeviceList (
pappl_devtype_t types,
pappl_device_cb_t cb,
void *data,
pappl_deverror_cb_t err_cb,
void *err_data
);
This function lists the available devices, calling the "cb" function once per device that
is discovered/listed. The callback function receives the device URI, IEEE-1284 device ID
(if any), and "data" pointer, and returns true to stop listing devices and false to
continue.
The "types" argument determines which devices are listed, for example PAPPL_DEVTYPE_ALL
will list all types of devices while PAPPL_DEVTYPE_USB only lists USB printers.
Any errors are reported using the supplied "err_cb" function. If you specify NULL for
this argument, errors are sent to stderr.
5 Note: This function will block (not return) until each of the device URI
5 schemes has reported all of the devices or the supplied callback function
5 returns true.
papplDeviceOpen
Open a connection to a device.
pappl_device_t * papplDeviceOpen (
const char *device_uri,
const char *name,
pappl_deverror_cb_t err_cb,
void *err_data
);
This function opens a connection to the specified device URI. The "name" argument
provides textual context for the connection and is usually the name (title) of the print
job.
Any errors are reported using the supplied "err_cb" function. If you specify NULL for
this argument, errors are sent to stderr.
papplDeviceParseID
Parse an IEEE-1284 device ID string.
int papplDeviceParseID (
const char *device_id,
cups_option_t **pairs
);
This function parses an IEEE-1284 device ID string and returns an array of key/value pairs
as a cups_option_t array. The returned array must be freed using the cupsFreeOptions
function.
papplDevicePrintf
Write a formatted string.
ssize_t papplDevicePrintf (
pappl_device_t *device,
const char *format,
...
);
This function buffers a formatted string that will be sent to the device. The "format"
argument accepts all printf format specifiers and behaves identically to that function.
Call the papplDeviceFlush function to ensure that the formatted string is immediately sent
to the device.
papplDevicePuts
Write a literal string.
ssize_t papplDevicePuts (
pappl_device_t *device,
const char *s
);
This function buffers a literal string that will be sent to the device. Call the
papplDeviceFlush function to ensure that the literal string is immediately sent to the
device.
papplDeviceRead
Read from a device.
ssize_t papplDeviceRead (
pappl_device_t *device,
void *buffer,
size_t bytes
);
This function reads data from the device. Depending on the device, this function may
block indefinitely.
papplDeviceSetData
Set device-specific data.
void papplDeviceSetData (
pappl_device_t *device,
void *data
);
This function sets any device-specific data needed to communicate with the device. It is
normally only called from the open callback that was registered for the device URI scheme.
papplDeviceWrite
Write to a device.
ssize_t papplDeviceWrite (
pappl_device_t *device,
const void *buffer,
size_t bytes
);
This function buffers data that will be sent to the device. Call the papplDeviceFlush
function to ensure that the data is immediately sent to the device.
STRUCTURES
pappl_devmetrics_s
Device metrics
struct pappl_devmetrics_s
{
size_t read_bytes;
size_t read_msecs;
size_t read_requests;
size_t status_msecs;
size_t status_requests;
size_t write_bytes;
size_t write_msecs;
size_t write_requests;
};
TYPES
pappl_devclose_cb_t
Device close callback
typedef void (*pappl_devclose_cb_t)(pappl_device_t *device);
pappl_deverror_cb_t
Device error callback
typedef void (*pappl_deverror_cb_t)(const char *message, void *err_data);
pappl_device_cb_t
Device callback - return true to stop, false to continue
typedef bool (*pappl_device_cb_t)(const char *device_info, const char *device_uri, const char *device_id, void *data);
pappl_devid_cb_t
Device ID callback
typedef char * (*pappl_devid_cb_t)(pappl_device_t *device, char *buffer, size_t bufsize);
pappl_devlist_cb_t
Device list callback
typedef bool (*pappl_devlist_cb_t)(pappl_device_cb_t cb, void *data, pappl_deverror_cb_t err_cb, void *err_data);
pappl_devmetrics_t
Device metrics
typedef struct pappl_devmetrics_s pappl_devmetrics_t;
pappl_devopen_cb_t
Device open callback
typedef bool (*pappl_devopen_cb_t)(pappl_device_t *device, const char *device_uri, const char *name);
pappl_devread_cb_t
Device read callback
typedef ssize_t (*pappl_devread_cb_t)(pappl_device_t *device, void *buffer, size_t bytes);
pappl_devstatus_cb_t
Device status callback
typedef pappl_preason_t (*pappl_devstatus_cb_t)(pappl_device_t *device);
pappl_devsupplies_cb_t
Device supplies callback
typedef int (*pappl_devsupplies_cb_t)(pappl_device_t *device, int max_supplies, pappl_supply_t *supplies);
pappl_devtype_t
Device type bitfield
typedef unsigned pappl_devtype_t;
pappl_devwrite_cb_t
Device write callback
typedef ssize_t (*pappl_devwrite_cb_t)(pappl_device_t *device, const void *buffer, size_t bytes);
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.