1pappl-device(3)             pappl device functions             pappl-device(3)
2
3
4

NAME

6       pappl-device - pappl device functions
7

LIBRARY

9       Printer  Application  Framework  (libpappl, "pkg-config --cflags --libs
10       pappl")
11

SYNOPSIS

13       #include <pappl/pappl.h>
14
15       typedef struct _pappl_device_s pappl_device_t;
16
17       void
18       papplDeviceAddScheme(const char *scheme, pappl_dtype_t dtype, pappl_de‐
19       vlist_cb_t  list_cb,  pappl_devopen_cb_t  open_cb,  pappl_devclose_cb_t
20       close_cb,  pappl_devread_cb_t  read_cb,  pappl_devwrite_cb_t  write_cb,
21       pappl_devstatus_cb_t status_cb);
22
23       void
24       papplDeviceClose(pappl_device_t *device);
25
26       void
27       papplDeviceError(pappl_device_t *device, const char *message, ...);
28
29       void
30       papplDeviceFlush(pappl_device_t *device);
31
32       void *
33       papplDeviceGetData(pappl_device_t *device);
34
35       pappl_dmetrics_t *
36       papplDeviceGetMetrics(pappl_device_t  *device,  pappl_dmetrics_t  *met‐
37       rics);
38
39       pappl_preason_t
40       papplDeviceGetStatus(pappl_device_t *device);
41
42       bool
43       papplDeviceList(pappl_dtype_t types, pappl_device_cb_t cb, void  *data,
44       pappl_deverror_cb_t err_cb, void *err_data);
45
46       pappl_device_t *
47       papplDeviceOpen(const  char *device_uri, const char *name, pappl_dever‐
48       ror_cb_t err_cb, void *err_data);
49
50       int
51       papplDeviceParse1284ID(const char *device_id, cups_option_t **pairs);
52
53       ssize_t
54       papplDevicePrintf(pappl_device_t *device, const char *format, ...);
55
56       ssize_t
57       papplDevicePuts(pappl_device_t *device, const char *s);
58
59       ssize_t
60       papplDeviceRead(pappl_device_t *device, void *buffer, size_t bytes);
61
62       void
63       papplDeviceSetData(pappl_device_t *device, void *data);
64
65       ssize_t
66       papplDeviceWrite(pappl_device_t *device,  const  void  *buffer,  size_t
67       bytes);
68
69

DESCRIPTION

71       The  PAPPL device functions provide access to output device connections
72       and to list available output devices.  Output devices are accessed  us‐
73       ing    Uniform    Resource    Identifier    (URI)   strings   such   as
74       "file:///path/to/file-or-directory",    "socket://11.22.33.44",     and
75       "usb://make/model?serial=number".
76
77       The  papplDeviceList function lists available output devices, providing
78       each available output device to the supplied  callback  function.   The
79       list  only  contains  devices  whose  URI scheme supports discovery, at
80       present USB printers and network printers that advertise themselves us‐
81       ing DNS-SD/mDNS and/or SNMPv1.
82
83       The papplDeviceOpen function opens a connection to an output device us‐
84       ing its URI. The papplDeviceClose function closes the connection.
85
86       The papplDevicePrintf, papplDevicePuts, and papplDeviceWrite  functions
87       send  data to the device, while the papplDeviceRead function reads data
88       from the device.
89
90       The papplDeviceGetMetrics function gets statistical  information  about
91       all  communications  with  the device while it has been open, while the
92       papplDeviceGetStatus function gets the hardware status of a device  and
93       maps it to the pappl_preason_t bitfield.
94

ENUMERATIONS

96   pappl_devtype_e
97       Device type bit values
98
99       PAPPL_DEVTYPE_ALL
100            All printers
101
102       PAPPL_DEVTYPE_CUSTOM_LOCAL
103            Local printer using a custom interface or protocol
104
105       PAPPL_DEVTYPE_CUSTOM_NETWORK
106            Network printer using a custom interface or protocol
107
108       PAPPL_DEVTYPE_DNS_SD
109            Network printers discovered via DNS-SD/mDNS
110
111       PAPPL_DEVTYPE_FILE
112            Local file/directory
113
114       PAPPL_DEVTYPE_LOCAL
115            All local printers
116
117       PAPPL_DEVTYPE_NETWORK
118            All network printers
119
120       PAPPL_DEVTYPE_SNMP
121            Network printers discovered via SNMP
122
123       PAPPL_DEVTYPE_SOCKET
124            Network printers using raw socket
125
126       PAPPL_DEVTYPE_USB
127            USB printers
128

FUNCTIONS

130   papplDeviceAddScheme
131       Add a device URI scheme.
132
133       void papplDeviceAddScheme (
134           const char *scheme,
135           pappl_devtype_t dtype,
136           pappl_devlist_cb_t list_cb,
137           pappl_devopen_cb_t open_cb,
138           pappl_devclose_cb_t close_cb,
139           pappl_devread_cb_t read_cb,
140           pappl_devwrite_cb_t write_cb,
141           pappl_devstatus_cb_t status_cb,
142           pappl_devid_cb_t id_cb
143       );
144
145       This function registers a device URI scheme with PAPPL, so that devices
146       using the named scheme can receive print data, report  status  informa‐
147       tion,  and  so  forth.   PAPPL  includes  support for the following URI
148       schemes:
149
150dnssd: Network printers discovered using DNS-SD.
151
152file: Character device files, plain files, and directories.
153
154snmp: Network printers discovered using SNMPv1.
155
156socket: Network printers using a hostname or numeric IP address.
157
158usb: Class 1 (unidirectional) or 2 (bidirectional) USB printers.
159
160       The "scheme" parameter specifies the URI scheme  and  must  consist  of
161       lowercase letters, digits, "-", "_", and/or ".", for example "x-foo" or
162       "com.example.bar".
163
164       The  "dtype"  parameter  specifies  the  device  type  and  should   be
165       PAPPL_DTYPE_CUSTOM_LOCAL    for    locally   connected   printers   and
166       PAPPL_DTYPE_CUSTOM_NETWORK for network printers.
167
168       Each of the callbacks corresponds to one of the papplDevice functions:
169
170       •    "list_cb": Implements discovery of devices (optional)
171
172       •    "open_cb": Opens communication with a device and allocates any de‐
173            vice-
174              specific data as needed
175
176       •    "close_cb":  Closes  communication with a device and frees any de‐
177            vice-
178              specific data as needed
179
180       •    "read_cb": Reads data from a device
181
182       •    "write_cb": Write data to a device
183
184       •    "status_cb": Gets basic printer state information  from  a  device
185            (optional)
186
187       •    "id_cb":  Gets  the current IEEE-1284 device ID from a device (op‐
188            tional)
189
190       The "open_cb" callback typically calls papplDeviceSetData  to  store  a
191       pointer   to  contextual  information  for  the  connection  while  the
192       "close_cb", "id_cb", "read_cb", "write_cb", and  "status_cb"  callbacks
193       typically call papplDeviceGetData to retrieve it.
194
195   papplDeviceAddScheme2
196       Add a device URI scheme with supply-level queries.
197
198       void papplDeviceAddScheme2 (
199           const char *scheme,
200           pappl_devtype_t dtype,
201           pappl_devlist_cb_t list_cb,
202           pappl_devopen_cb_t open_cb,
203           pappl_devclose_cb_t close_cb,
204           pappl_devread_cb_t read_cb,
205           pappl_devwrite_cb_t write_cb,
206           pappl_devstatus_cb_t status_cb,
207           pappl_devsupplies_cb_t supplies_cb,
208           pappl_devid_cb_t id_cb
209       );
210
211       This function registers a device URI scheme with PAPPL, so that devices
212       using the named scheme can receive print data, report  status  informa‐
213       tion,  and  so  forth.   PAPPL  includes  support for the following URI
214       schemes:
215
216dnssd: Network printers discovered using DNS-SD.
217
218file: Character device files, plain files, and directories.
219
220snmp: Network printers discovered using SNMPv1.
221
222socket: Network printers using a hostname or numeric IP address.
223
224usb: Class 1 (unidirectional) or 2 (bidirectional) USB printers.
225
226       The "scheme" parameter specifies the URI scheme  and  must  consist  of
227       lowercase letters, digits, "-", "_", and/or ".", for example "x-foo" or
228       "com.example.bar".
229
230       The  "dtype"  parameter  specifies  the  device  type  and  should   be
231       PAPPL_DTYPE_CUSTOM_LOCAL    for    locally   connected   printers   and
232       PAPPL_DTYPE_CUSTOM_NETWORK for network printers.
233
234       Each of the callbacks corresponds to one of the papplDevice functions:
235
236       •    "list_cb": Implements discovery of devices (optional)
237
238       •    "open_cb": Opens communication with a device and allocates any de‐
239            vice-
240              specific data as needed
241
242       •    "close_cb":  Closes  communication with a device and frees any de‐
243            vice-
244              specific data as needed
245
246       •    "read_cb": Reads data from a device
247
248       •    "write_cb": Write data to a device
249
250       •    "status_cb": Gets basic printer state information  from  a  device
251            (optional)
252
253       •    "supplies_cb":  Gets  supply  level information from a device (op‐
254            tional)
255
256       •    "id_cb": Gets the current IEEE-1284 device ID from a  device  (op‐
257            tional)
258
259       The  "open_cb"  callback  typically calls papplDeviceSetData to store a
260       pointer  to  contextual  information  for  the  connection  while   the
261       "close_cb",  "id_cb",  "read_cb",  "write_cb",  "status_cb",  and "sup‐
262       plies_cb" callbacks typically call papplDeviceGetData to retrieve it.
263
264   papplDeviceClose
265       Close a device connection.
266
267       void papplDeviceClose (
268           pappl_device_t *device
269       );
270
271       This function flushes any pending write data and closes the  connection
272       to a device.
273
274   papplDeviceError
275       Report an error on a device.
276
277       void papplDeviceError (
278           pappl_device_t *device,
279           const char *message,
280           ...
281       );
282
283       This  function  reports  an error on a device using the client-supplied
284       callback function.  It is normally called from any  custom  device  URI
285       scheme callbacks you implement.
286
287   papplDeviceFlush
288       Flush any buffered data to the device.
289
290       void papplDeviceFlush (
291           pappl_device_t *device
292       );
293
294       This  function flushes any pending write data sent using the papplDevi‐
295       cePrintf, papplDevicePuts, or papplDeviceWrite functions to the device.
296
297   papplDeviceGetData
298       Get device-specific data.
299
300       void * papplDeviceGetData (
301           pappl_device_t *device
302       );
303
304       This function returns any device-specific data that has been set by the
305       device  open  callback.  It is normally only called from any custom de‐
306       vice URI scheme callbacks you implement.
307
308   papplDeviceGetID
309       Get the IEEE-1284 device ID.
310
311       char * papplDeviceGetID (
312           pappl_device_t *device,
313           char *buffer,
314           size_t bufsize
315       );
316
317       This function queries the IEEE-1284  device  ID  from  the  device  and
318       copies it to the provided buffer.  The buffer must be at least 64 bytes
319       and should be at least 1024 bytes in length.
320
321       5      Note: This function can block for up to several seconds  depend‐
322              ing on
323
324       5      the type of connection.
325
326   papplDeviceGetMetrics
327       Get the device metrics.
328
329       pappl_devmetrics_t * papplDeviceGetMetrics (
330           pappl_device_t *device,
331           pappl_devmetrics_t *metrics
332       );
333
334       This function returns a copy of the device metrics data, which includes
335       the number, length (in bytes), and duration (in milliseconds) of  read,
336       status,  and  write requests for the current session.  This information
337       is normally used for performance measurement  and  optimization  during
338       development of a printer application.  It can also be useful diagnostic
339       information.
340
341   papplDeviceGetStatus
342       Get the printer status bits.
343
344       pappl_preason_t  papplDeviceGetStatus (
345           pappl_device_t *device
346       );
347
348       This function returns the current printer status bits, as applicable to
349       the current device.
350
351       The  status bits for USB devices come from the original Centronics par‐
352       allel printer "standard" which was later formally standardized in  IEEE
353       1284-1984  and  the  USB  Device Class Definition for Printing Devices.
354       Some vendor extensions are also supported.
355
356       The status bits for network devices come from the  hrPrinterDetectedEr‐
357       rorState  property  that  is  defined  in  the SNMP Printer MIB v2 (RFC
358       3805).
359
360       This function returns a pappl_preason_t bitfield which can be passed to
361       the papplPrinterSetReasons function.  Use the PAPPL_PREASON_DEVICE_STA‐
362       TUS value as the value of the "remove" argument.
363
364       5      Note: This function can block for several seconds while  getting
365              the status
366
367       5      information.
368
369   papplDeviceGetSupplies
370       Get the current printer supplies.
371
372       int  papplDeviceGetSupplies (
373           pappl_device_t *device,
374           int max_supplies,
375           pappl_supply_t *supplies
376       );
377
378       This  function  returns  the number, type, and level of current printer
379       supply levels, as applicable to the current device.
380
381       The supply levels for network devices come from the prtSupplyTable  and
382       prtMarkerColorantTable  properties that are defined in the SNMP Printer
383       MIB v2 (RFC 3805).
384
385       The supply levels for other devices are not standardized  and  must  be
386       queried using other methods.
387
388       5      Note:  This function can block for several seconds while getting
389              the supply
390
391       5      information.
392
393   papplDeviceIsSupported
394       Determine whether a given URI is supported.
395
396       bool  papplDeviceIsSupported (
397           const char *uri
398       );
399
400       This function determines whether a given URI or URI scheme is supported
401       as a device.
402
403   papplDeviceList
404       List available devices.
405
406       bool  papplDeviceList (
407           pappl_devtype_t types,
408           pappl_device_cb_t cb,
409           void *data,
410           pappl_deverror_cb_t err_cb,
411           void *err_data
412       );
413
414       This  function  lists  the available devices, calling the "cb" function
415       once per device that is discovered/listed.  The callback  function  re‐
416       ceives  the  device  URI,  IEEE-1284  device  ID  (if  any), and "data"
417       pointer, and returns true to stop listing devices  and  false  to  con‐
418       tinue.
419
420       The  "types"  argument determines which devices are listed, for example
421       PAPPL_DEVTYPE_ALL will list  all  types  of  devices  while  PAPPL_DEV‐
422       TYPE_USB only lists USB printers.
423
424       Any  errors  are reported using the supplied "err_cb" function.  If you
425       specify NULL for this argument, errors are sent to stderr.
426
427       5      Note: This function will block (not return) until  each  of  the
428              device URI
429
430       5      schemes has reported all of the devices or the supplied callback
431              function
432
433       5      returns true.
434
435   papplDeviceOpen
436       Open a connection to a device.
437
438       pappl_device_t * papplDeviceOpen (
439           const char *device_uri,
440           const char *name,
441           pappl_deverror_cb_t err_cb,
442           void *err_data
443       );
444
445       This function opens a connection to  the  specified  device  URI.   The
446       "name" argument provides textual context for the connection and is usu‐
447       ally the name (title) of the print job.
448
449       Any errors are reported using the supplied "err_cb" function.   If  you
450       specify NULL for this argument, errors are sent to stderr.
451
452   papplDeviceParseID
453       Parse an IEEE-1284 device ID string.
454
455       int  papplDeviceParseID (
456           const char *device_id,
457           cups_option_t **pairs
458       );
459
460       This function parses an IEEE-1284 device ID string and returns an array
461       of key/value pairs as a cups_option_t array.  The returned  array  must
462       be freed using the cupsFreeOptions function.
463
464   papplDevicePrintf
465       Write a formatted string.
466
467       ssize_t  papplDevicePrintf (
468           pappl_device_t *device,
469           const char *format,
470           ...
471       );
472
473       This  function  buffers a formatted string that will be sent to the de‐
474       vice.  The "format" argument accepts all printf format  specifiers  and
475       behaves identically to that function.
476
477       Call  the papplDeviceFlush function to ensure that the formatted string
478       is immediately sent to the device.
479
480   papplDevicePuts
481       Write a literal string.
482
483       ssize_t  papplDevicePuts (
484           pappl_device_t *device,
485           const char *s
486       );
487
488       This function buffers a literal string that will be sent to the device.
489       Call the papplDeviceFlush function to ensure that the literal string is
490       immediately sent to the device.
491
492   papplDeviceRead
493       Read from a device.
494
495       ssize_t  papplDeviceRead (
496           pappl_device_t *device,
497           void *buffer,
498           size_t bytes
499       );
500
501       This function reads data from the device.   Depending  on  the  device,
502       this function may block indefinitely.
503
504   papplDeviceRemoveScheme
505       Remove the named device URI scheme.
506
507       void papplDeviceRemoveScheme (
508           const char *scheme
509       );
510
511       This  function  removes  support  for the named device URI scheme.  Use
512       only when you want to disable a URI scheme for security  or  functional
513       reasons, for example to disable the "file" URI scheme.
514
515   papplDeviceRemoveTypes
516       Remove device URI schemes of the specified types.
517
518       void papplDeviceRemoveTypes (
519           pappl_devtype_t types
520       );
521
522       This  function  removes device URI schemes of the specified types.  Use
523       only when you want to disable URI schemes for  security  or  functional
524       reasons, for example to disable all network URI schemes.
525
526   papplDeviceSetData
527       Set device-specific data.
528
529       void papplDeviceSetData (
530           pappl_device_t *device,
531           void *data
532       );
533
534       This  function sets any device-specific data needed to communicate with
535       the device.  It is normally only called from the open callback that was
536       registered for the device URI scheme.
537
538   papplDeviceWrite
539       Write to a device.
540
541       ssize_t  papplDeviceWrite (
542           pappl_device_t *device,
543           const void *buffer,
544           size_t bytes
545       );
546
547       This  function  buffers data that will be sent to the device.  Call the
548       papplDeviceFlush function to ensure that the data is  immediately  sent
549       to the device.
550

STRUCTURES

552   pappl_devmetrics_s
553       Device metrics
554
555       struct pappl_devmetrics_s
556       {
557         size_t read_bytes;
558         size_t read_msecs;
559         size_t read_requests;
560         size_t status_msecs;
561         size_t status_requests;
562         size_t write_bytes;
563         size_t write_msecs;
564         size_t write_requests;
565       };
566

TYPES

568   pappl_devclose_cb_t
569       Device close callback
570
571       typedef void (*pappl_devclose_cb_t)(pappl_device_t *device);
572
573   pappl_deverror_cb_t
574       Device error callback
575
576       typedef void (*pappl_deverror_cb_t)(const char *message, void *err_data);
577
578   pappl_device_cb_t
579       Device callback - return true to stop, false to continue
580
581       typedef bool (*pappl_device_cb_t)(const char *device_info, const char *device_uri, const char *device_id, void *data);
582
583   pappl_devid_cb_t
584       Device ID callback
585
586       typedef char * (*pappl_devid_cb_t)(pappl_device_t *device, char *buffer, size_t bufsize);
587
588   pappl_devlist_cb_t
589       Device list callback
590
591       typedef bool (*pappl_devlist_cb_t)(pappl_device_cb_t cb, void *data, pappl_deverror_cb_t err_cb, void *err_data);
592
593   pappl_devmetrics_t
594       Device metrics
595
596       typedef struct pappl_devmetrics_s pappl_devmetrics_t;
597
598   pappl_devopen_cb_t
599       Device open callback
600
601       typedef bool (*pappl_devopen_cb_t)(pappl_device_t *device, const char *device_uri, const char *name);
602
603   pappl_devread_cb_t
604       Device read callback
605
606       typedef ssize_t (*pappl_devread_cb_t)(pappl_device_t *device, void *buffer, size_t bytes);
607
608   pappl_devstatus_cb_t
609       Device status callback
610
611       typedef pappl_preason_t (*pappl_devstatus_cb_t)(pappl_device_t *device);
612
613   pappl_devsupplies_cb_t
614       Device supplies callback
615
616       typedef int (*pappl_devsupplies_cb_t)(pappl_device_t *device, int max_supplies, pappl_supply_t *supplies);
617
618   pappl_devtype_t
619       Device type bitfield
620
621       typedef unsigned pappl_devtype_t;
622
623   pappl_devwrite_cb_t
624       Device write callback
625
626       typedef ssize_t (*pappl_devwrite_cb_t)(pappl_device_t *device, const void *buffer, size_t bytes);
627

SEE ALSO

629       pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3),
630       pappl-mainline(3), pappl-makeresheader(1), pappl-printer(3),  pappl-re‐
631       source(3), pappl-system(3), https://www.msweet.org/pappl
632
634       Copyright © 2019-2022 by Michael R Sweet.
635
636       PAPPL  is  licensed  under  the Apache License Version 2.0 with an (op‐
637       tional) exception to allow linking against  GPL2/LGPL2  software  (like
638       older  versions of CUPS), so it can be used freely in any project you'd
639       like.  See the files "LICENSE" and "NOTICE" in the source  distribution
640       for more information.
641
642
643
6442023-10-06                  pappl device functions             pappl-device(3)
Impressum