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

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.