1pappl-device(3) pappl device functions pappl-device(3)
2
6 pappl-device - pappl device functions
7
9 Printer Application Framework (libpappl, "pkg-config --cflags --libs
10 pappl")
11
13 #include <pappl/pappl.h>
14 typedef struct _pappl_device_s pappl_device_t;
16 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 void
24 papplDeviceClose(pappl_device_t *device);
25 void
27 papplDeviceError(pappl_device_t *device, const char *message, ...);
28 void
30 papplDeviceFlush(pappl_device_t *device);
31 void *
33 papplDeviceGetData(pappl_device_t *device);
34 pappl_dmetrics_t *
36 papplDeviceGetMetrics(pappl_device_t *device, pappl_dmetrics_t *met‐
37 rics);
38 pappl_preason_t
40 papplDeviceGetStatus(pappl_device_t *device);
41 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 pappl_device_t *
47 papplDeviceOpen(const char *device_uri, const char *name, pappl_dever‐
48 ror_cb_t err_cb, void *err_data);
49 int
51 papplDeviceParse1284ID(const char *device_id, cups_option_t **pairs);
52 ssize_t
54 papplDevicePrintf(pappl_device_t *device, const char *format, ...);
55 ssize_t
57 papplDevicePuts(pappl_device_t *device, const char *s);
58 ssize_t
60 papplDeviceRead(pappl_device_t *device, void *buffer, size_t bytes);
61 void
63 papplDeviceSetData(pappl_device_t *device, void *data);
64 ssize_t
66 papplDeviceWrite(pappl_device_t *device, const void *buffer, size_t
67 bytes);
68
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 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 The papplDeviceOpen function opens a connection to an output device us‐
84 ing its URI. The papplDeviceClose function closes the connection.
85 The papplDevicePrintf, papplDevicePuts, and papplDeviceWrite functions
87 send data to the device, while the papplDeviceRead function reads data
88 from the device.
89 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
96 pappl_devtype_e
97 Device type bit values
98 PAPPL_DEVTYPE_ALL
100 All printers
101 PAPPL_DEVTYPE_CUSTOM_LOCAL
103 Local printer using a custom interface or protocol
104 PAPPL_DEVTYPE_CUSTOM_NETWORK
106 Network printer using a custom interface or protocol
107 PAPPL_DEVTYPE_DNS_SD
109 Network printers discovered via DNS-SD/mDNS
110 PAPPL_DEVTYPE_FILE
112 Local file/directory
113 PAPPL_DEVTYPE_LOCAL
115 All local printers
116 PAPPL_DEVTYPE_NETWORK
118 All network printers
119 PAPPL_DEVTYPE_SNMP
121 Network printers discovered via SNMP
122 PAPPL_DEVTYPE_SOCKET
124 Network printers using raw socket
125 PAPPL_DEVTYPE_USB
127 USB printers
128
130 papplDeviceAddScheme
131 Add a device URI scheme.
132 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 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 • dnssd: Network printers discovered using DNS-SD.
151 • file: Character device files, plain files, and directories.
153 • snmp: Network printers discovered using SNMPv1.
155 • socket: Network printers using a hostname or numeric IP address.
157 • usb: Class 1 (unidirectional) or 2 (bidirectional) USB printers.
159 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 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 Each of the callbacks corresponds to one of the papplDevice functions:
169 • "list_cb": Implements discovery of devices (optional)
171 • "open_cb": Opens communication with a device and allocates any de‐
173 vice- specific data as needed
174 • "close_cb": Closes communication with a device and frees any de‐
176 vice- specific data as needed
177 • "read_cb": Reads data from a device
179 • "write_cb": Write data to a device
181 • "status_cb": Gets basic printer state information from a device
183 (optional)
184 • "id_cb": Gets the current IEEE-1284 device ID from a device (op‐
186 tional)
187 The "open_cb" callback typically calls papplDeviceSetData to store a
189 pointer to contextual information for the connection while the
190 "close_cb", "id_cb", "read_cb", "write_cb", and "status_cb" callbacks
191 typically call papplDeviceGetData to retrieve it.
192 papplDeviceAddScheme2
194 Add a device URI scheme with supply-level queries.
195 void papplDeviceAddScheme2 (
197 const char *scheme,
198 pappl_devtype_t dtype,
199 pappl_devlist_cb_t list_cb,
200 pappl_devopen_cb_t open_cb,
201 pappl_devclose_cb_t close_cb,
202 pappl_devread_cb_t read_cb,
203 pappl_devwrite_cb_t write_cb,
204 pappl_devstatus_cb_t status_cb,
205 pappl_devsupplies_cb_t supplies_cb,
206 pappl_devid_cb_t id_cb
207 );
208 This function registers a device URI scheme with PAPPL, so that devices
210 using the named scheme can receive print data, report status informa‐
211 tion, and so forth. PAPPL includes support for the following URI
212 schemes:
213 • dnssd: Network printers discovered using DNS-SD.
215 • file: Character device files, plain files, and directories.
217 • snmp: Network printers discovered using SNMPv1.
219 • socket: Network printers using a hostname or numeric IP address.
221 • usb: Class 1 (unidirectional) or 2 (bidirectional) USB printers.
223 The "scheme" parameter specifies the URI scheme and must consist of
225 lowercase letters, digits, "-", "_", and/or ".", for example "x-foo" or
226 "com.example.bar".
227 The "dtype" parameter specifies the device type and should be
229 PAPPL_DTYPE_CUSTOM_LOCAL for locally connected printers and
230 PAPPL_DTYPE_CUSTOM_NETWORK for network printers.
231 Each of the callbacks corresponds to one of the papplDevice functions:
233 • "list_cb": Implements discovery of devices (optional)
235 • "open_cb": Opens communication with a device and allocates any de‐
237 vice- specific data as needed
238 • "close_cb": Closes communication with a device and frees any de‐
240 vice- specific data as needed
241 • "read_cb": Reads data from a device
243 • "write_cb": Write data to a device
245 • "status_cb": Gets basic printer state information from a device
247 (optional)
248 • "supplies_cb": Gets supply level information from a device (op‐
250 tional)
251 • "id_cb": Gets the current IEEE-1284 device ID from a device (op‐
253 tional)
254 The "open_cb" callback typically calls papplDeviceSetData to store a
256 pointer to contextual information for the connection while the
257 "close_cb", "id_cb", "read_cb", "write_cb", "status_cb", and "sup‐
258 plies_cb" callbacks typically call papplDeviceGetData to retrieve it.
259 papplDeviceClose
261 Close a device connection.
262 void papplDeviceClose (
264 pappl_device_t *device
265 );
266 This function flushes any pending write data and closes the connection
268 to a device.
269 papplDeviceError
271 Report an error on a device.
272 void papplDeviceError (
274 pappl_device_t *device,
275 const char *message,
276 ...
277 );
278 This function reports an error on a device using the client-supplied
280 callback function. It is normally called from any custom device URI
281 scheme callbacks you implement.
282 papplDeviceFlush
284 Flush any buffered data to the device.
285 void papplDeviceFlush (
287 pappl_device_t *device
288 );
289 This function flushes any pending write data sent using the papplDevi‐
291 cePrintf, papplDevicePuts, or papplDeviceWrite functions to the device.
292 papplDeviceGetData
294 Get device-specific data.
295 void * papplDeviceGetData (
297 pappl_device_t *device
298 );
299 This function returns any device-specific data that has been set by the
301 device open callback. It is normally only called from any custom de‐
302 vice URI scheme callbacks you implement.
303 papplDeviceGetID
305 Get the IEEE-1284 device ID.
306 char * papplDeviceGetID (
308 pappl_device_t *device,
309 char *buffer,
310 size_t bufsize
311 );
312 This function queries the IEEE-1284 device ID from the device and
314 copies it to the provided buffer. The buffer must be at least 64 bytes
315 and should be at least 1024 bytes in length.
316 5 Note: This function can block for up to several seconds depend‐
318 ing on
319 5 the type of connection.
321 papplDeviceGetMetrics
323 Get the device metrics.
324 pappl_devmetrics_t * papplDeviceGetMetrics (
326 pappl_device_t *device,
327 pappl_devmetrics_t *metrics
328 );
329 This function returns a copy of the device metrics data, which includes
331 the number, length (in bytes), and duration (in milliseconds) of read,
332 status, and write requests for the current session. This information
333 is normally used for performance measurement and optimization during
334 development of a printer application. It can also be useful diagnostic
335 information.
336 papplDeviceGetStatus
338 Get the printer status bits.
339 pappl_preason_t papplDeviceGetStatus (
341 pappl_device_t *device
342 );
343 This function returns the current printer status bits, as applicable to
345 the current device.
346 The status bits for USB devices come from the original Centronics par‐
348 allel printer "standard" which was later formally standardized in IEEE
349 1284-1984 and the USB Device Class Definition for Printing Devices.
350 Some vendor extensions are also supported.
351 The status bits for network devices come from the hrPrinterDetectedEr‐
353 rorState property that is defined in the SNMP Printer MIB v2 (RFC
354 3805).
355 This function returns a pappl_preason_t bitfield which can be passed to
357 the papplPrinterSetReasons function. Use the PAPPL_PREASON_DEVICE_STA‐
358 TUS value as the value of the "remove" argument.
359 5 Note: This function can block for several seconds while getting
361 the status
362 5 information.
364 papplDeviceGetSupplies
366 Get the current printer supplies.
367 int papplDeviceGetSupplies (
369 pappl_device_t *device,
370 int max_supplies,
371 pappl_supply_t *supplies
372 );
373 This function returns the number, type, and level of current printer
375 supply levels, as applicable to the current device.
376 The supply levels for network devices come from the prtSupplyTable and
378 prtMarkerColorantTable properties that are defined in the SNMP Printer
379 MIB v2 (RFC 3805).
380 The supply levels for other devices are not standardized and must be
382 queried using other methods.
383 5 Note: This function can block for several seconds while getting
385 the supply
386 5 information.
388 papplDeviceIsSupported
390 Determine whether a given URI is supported.
391 bool papplDeviceIsSupported (
393 const char *uri
394 );
395 This function determines whether a given URI or URI scheme is supported
397 as a device.
398 papplDeviceList
400 List available devices.
401 bool papplDeviceList (
403 pappl_devtype_t types,
404 pappl_device_cb_t cb,
405 void *data,
406 pappl_deverror_cb_t err_cb,
407 void *err_data
408 );
409 This function lists the available devices, calling the "cb" function
411 once per device that is discovered/listed. The callback function re‐
412 ceives the device URI, IEEE-1284 device ID (if any), and "data"
413 pointer, and returns true to stop listing devices and false to con‐
414 tinue.
415 The "types" argument determines which devices are listed, for example
417 PAPPL_DEVTYPE_ALL will list all types of devices while PAPPL_DEV‐
418 TYPE_USB only lists USB printers.
419 Any errors are reported using the supplied "err_cb" function. If you
421 specify NULL for this argument, errors are sent to stderr.
422 5 Note: This function will block (not return) until each of the
424 device URI
425 5 schemes has reported all of the devices or the supplied callback
427 function
428 5 returns true.
430 papplDeviceOpen
432 Open a connection to a device.
433 pappl_device_t * papplDeviceOpen (
435 const char *device_uri,
436 const char *name,
437 pappl_deverror_cb_t err_cb,
438 void *err_data
439 );
440 This function opens a connection to the specified device URI. The
442 "name" argument provides textual context for the connection and is usu‐
443 ally the name (title) of the print job.
444 Any errors are reported using the supplied "err_cb" function. If you
446 specify NULL for this argument, errors are sent to stderr.
447 papplDeviceParseID
449 Parse an IEEE-1284 device ID string.
450 int papplDeviceParseID (
452 const char *device_id,
453 cups_option_t **pairs
454 );
455 This function parses an IEEE-1284 device ID string and returns an array
457 of key/value pairs as a cups_option_t array. The returned array must
458 be freed using the cupsFreeOptions function.
459 papplDevicePrintf
461 Write a formatted string.
462 ssize_t papplDevicePrintf (
464 pappl_device_t *device,
465 const char *format,
466 ...
467 );
468 This function buffers a formatted string that will be sent to the de‐
470 vice. The "format" argument accepts all printf format specifiers and
471 behaves identically to that function.
472 Call the papplDeviceFlush function to ensure that the formatted string
474 is immediately sent to the device.
475 papplDevicePuts
477 Write a literal string.
478 ssize_t papplDevicePuts (
480 pappl_device_t *device,
481 const char *s
482 );
483 This function buffers a literal string that will be sent to the device.
485 Call the papplDeviceFlush function to ensure that the literal string is
486 immediately sent to the device.
487 papplDeviceRead
489 Read from a device.
490 ssize_t papplDeviceRead (
492 pappl_device_t *device,
493 void *buffer,
494 size_t bytes
495 );
496 This function reads data from the device. Depending on the device,
498 this function may block indefinitely.
499 papplDeviceSetData
501 Set device-specific data.
502 void papplDeviceSetData (
504 pappl_device_t *device,
505 void *data
506 );
507 This function sets any device-specific data needed to communicate with
509 the device. It is normally only called from the open callback that was
510 registered for the device URI scheme.
511 papplDeviceWrite
513 Write to a device.
514 ssize_t papplDeviceWrite (
516 pappl_device_t *device,
517 const void *buffer,
518 size_t bytes
519 );
520 This function buffers data that will be sent to the device. Call the
522 papplDeviceFlush function to ensure that the data is immediately sent
523 to the device.
524
526 pappl_devmetrics_s
527 Device metrics
528 struct pappl_devmetrics_s
530 {
531 size_t read_bytes;
532 size_t read_msecs;
533 size_t read_requests;
534 size_t status_msecs;
535 size_t status_requests;
536 size_t write_bytes;
537 size_t write_msecs;
538 size_t write_requests;
539 };
540
542 pappl_devclose_cb_t
543 Device close callback
544 typedef void (*pappl_devclose_cb_t)(pappl_device_t *device);
546 pappl_deverror_cb_t
548 Device error callback
549 typedef void (*pappl_deverror_cb_t)(const char *message, void *err_data);
551 pappl_device_cb_t
553 Device callback - return true to stop, false to continue
554 typedef bool (*pappl_device_cb_t)(const char *device_info, const char *device_uri, const char *device_id, void *data);
556 pappl_devid_cb_t
558 Device ID callback
559 typedef char * (*pappl_devid_cb_t)(pappl_device_t *device, char *buffer, size_t bufsize);
561 pappl_devlist_cb_t
563 Device list callback
564 typedef bool (*pappl_devlist_cb_t)(pappl_device_cb_t cb, void *data, pappl_deverror_cb_t err_cb, void *err_data);
566 pappl_devmetrics_t
568 Device metrics
569 typedef struct pappl_devmetrics_s pappl_devmetrics_t;
571 pappl_devopen_cb_t
573 Device open callback
574 typedef bool (*pappl_devopen_cb_t)(pappl_device_t *device, const char *device_uri, const char *name);
576 pappl_devread_cb_t
578 Device read callback
579 typedef ssize_t (*pappl_devread_cb_t)(pappl_device_t *device, void *buffer, size_t bytes);
581 pappl_devstatus_cb_t
583 Device status callback
584 typedef pappl_preason_t (*pappl_devstatus_cb_t)(pappl_device_t *device);
586 pappl_devsupplies_cb_t
588 Device supplies callback
589 typedef int (*pappl_devsupplies_cb_t)(pappl_device_t *device, int max_supplies, pappl_supply_t *supplies);
591 pappl_devtype_t
593 Device type bitfield
594 typedef unsigned pappl_devtype_t;
596 pappl_devwrite_cb_t
598 Device write callback
599 typedef ssize_t (*pappl_devwrite_cb_t)(pappl_device_t *device, const void *buffer, size_t bytes);
601
603 pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3),
604 pappl-mainline(3), pappl-makeresheader(1), pappl-printer(3), pappl-re‐
605 source(3), pappl-system(3), https://www.msweet.org/pappl
606
608 Copyright © 2019-2022 by Michael R Sweet.
609 PAPPL is licensed under the Apache License Version 2.0 with an (op‐
611 tional) exception to allow linking against GPL2/LGPL2 software (like
612 older versions of CUPS), so it can be used freely in any project you'd
613 like. See the files "LICENSE" and "NOTICE" in the source distribution
614 for more information.
6152022-05-10 pappl device functions pappl-device(3)