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-
174 specific data as needed
175 • "close_cb": Closes communication with a device and frees any de‐
177 vice-
178 specific data as needed
179 • "read_cb": Reads data from a device
181 • "write_cb": Write data to a device
183 • "status_cb": Gets basic printer state information from a device
185 (optional)
186 • "id_cb": Gets the current IEEE-1284 device ID from a device (op‐
188 tional)
189 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 papplDeviceAddScheme2
196 Add a device URI scheme with supply-level queries.
197 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 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 • dnssd: Network printers discovered using DNS-SD.
217 • file: Character device files, plain files, and directories.
219 • snmp: Network printers discovered using SNMPv1.
221 • socket: Network printers using a hostname or numeric IP address.
223 • usb: Class 1 (unidirectional) or 2 (bidirectional) USB printers.
225 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 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 Each of the callbacks corresponds to one of the papplDevice functions:
235 • "list_cb": Implements discovery of devices (optional)
237 • "open_cb": Opens communication with a device and allocates any de‐
239 vice-
240 specific data as needed
241 • "close_cb": Closes communication with a device and frees any de‐
243 vice-
244 specific data as needed
245 • "read_cb": Reads data from a device
247 • "write_cb": Write data to a device
249 • "status_cb": Gets basic printer state information from a device
251 (optional)
252 • "supplies_cb": Gets supply level information from a device (op‐
254 tional)
255 • "id_cb": Gets the current IEEE-1284 device ID from a device (op‐
257 tional)
258 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 papplDeviceClose
265 Close a device connection.
266 void papplDeviceClose (
268 pappl_device_t *device
269 );
270 This function flushes any pending write data and closes the connection
272 to a device.
273 papplDeviceError
275 Report an error on a device.
276 void papplDeviceError (
278 pappl_device_t *device,
279 const char *message,
280 ...
281 );
282 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 papplDeviceFlush
288 Flush any buffered data to the device.
289 void papplDeviceFlush (
291 pappl_device_t *device
292 );
293 This function flushes any pending write data sent using the papplDevi‐
295 cePrintf, papplDevicePuts, or papplDeviceWrite functions to the device.
296 papplDeviceGetData
298 Get device-specific data.
299 void * papplDeviceGetData (
301 pappl_device_t *device
302 );
303 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 papplDeviceGetID
309 Get the IEEE-1284 device ID.
310 char * papplDeviceGetID (
312 pappl_device_t *device,
313 char *buffer,
314 size_t bufsize
315 );
316 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 5 Note: This function can block for up to several seconds depend‐
322 ing on
323 5 the type of connection.
325 papplDeviceGetMetrics
327 Get the device metrics.
328 pappl_devmetrics_t * papplDeviceGetMetrics (
330 pappl_device_t *device,
331 pappl_devmetrics_t *metrics
332 );
333 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 papplDeviceGetStatus
342 Get the printer status bits.
343 pappl_preason_t papplDeviceGetStatus (
345 pappl_device_t *device
346 );
347 This function returns the current printer status bits, as applicable to
349 the current device.
350 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 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 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 5 Note: This function can block for several seconds while getting
365 the status
366 5 information.
368 papplDeviceGetSupplies
370 Get the current printer supplies.
371 int papplDeviceGetSupplies (
373 pappl_device_t *device,
374 int max_supplies,
375 pappl_supply_t *supplies
376 );
377 This function returns the number, type, and level of current printer
379 supply levels, as applicable to the current device.
380 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 The supply levels for other devices are not standardized and must be
386 queried using other methods.
387 5 Note: This function can block for several seconds while getting
389 the supply
390 5 information.
392 papplDeviceIsSupported
394 Determine whether a given URI is supported.
395 bool papplDeviceIsSupported (
397 const char *uri
398 );
399 This function determines whether a given URI or URI scheme is supported
401 as a device.
402 papplDeviceList
404 List available devices.
405 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 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 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 Any errors are reported using the supplied "err_cb" function. If you
425 specify NULL for this argument, errors are sent to stderr.
426 5 Note: This function will block (not return) until each of the
428 device URI
429 5 schemes has reported all of the devices or the supplied callback
431 function
432 5 returns true.
434 papplDeviceOpen
436 Open a connection to a device.
437 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 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 Any errors are reported using the supplied "err_cb" function. If you
450 specify NULL for this argument, errors are sent to stderr.
451 papplDeviceParseID
453 Parse an IEEE-1284 device ID string.
454 int papplDeviceParseID (
456 const char *device_id,
457 cups_option_t **pairs
458 );
459 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 papplDevicePrintf
465 Write a formatted string.
466 ssize_t papplDevicePrintf (
468 pappl_device_t *device,
469 const char *format,
470 ...
471 );
472 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 Call the papplDeviceFlush function to ensure that the formatted string
478 is immediately sent to the device.
479 papplDevicePuts
481 Write a literal string.
482 ssize_t papplDevicePuts (
484 pappl_device_t *device,
485 const char *s
486 );
487 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 papplDeviceRead
493 Read from a device.
494 ssize_t papplDeviceRead (
496 pappl_device_t *device,
497 void *buffer,
498 size_t bytes
499 );
500 This function reads data from the device. Depending on the device,
502 this function may block indefinitely.
503 papplDeviceRemoveScheme
505 Remove the named device URI scheme.
506 void papplDeviceRemoveScheme (
508 const char *scheme
509 );
510 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 papplDeviceRemoveTypes
516 Remove device URI schemes of the specified types.
517 void papplDeviceRemoveTypes (
519 pappl_devtype_t types
520 );
521 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 papplDeviceSetData
527 Set device-specific data.
528 void papplDeviceSetData (
530 pappl_device_t *device,
531 void *data
532 );
533 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 papplDeviceWrite
539 Write to a device.
540 ssize_t papplDeviceWrite (
542 pappl_device_t *device,
543 const void *buffer,
544 size_t bytes
545 );
546 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
552 pappl_devmetrics_s
553 Device metrics
554 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
568 pappl_devclose_cb_t
569 Device close callback
570 typedef void (*pappl_devclose_cb_t)(pappl_device_t *device);
572 pappl_deverror_cb_t
574 Device error callback
575 typedef void (*pappl_deverror_cb_t)(const char *message, void *err_data);
577 pappl_device_cb_t
579 Device callback - return true to stop, false to continue
580 typedef bool (*pappl_device_cb_t)(const char *device_info, const char *device_uri, const char *device_id, void *data);
582 pappl_devid_cb_t
584 Device ID callback
585 typedef char * (*pappl_devid_cb_t)(pappl_device_t *device, char *buffer, size_t bufsize);
587 pappl_devlist_cb_t
589 Device list callback
590 typedef bool (*pappl_devlist_cb_t)(pappl_device_cb_t cb, void *data, pappl_deverror_cb_t err_cb, void *err_data);
592 pappl_devmetrics_t
594 Device metrics
595 typedef struct pappl_devmetrics_s pappl_devmetrics_t;
597 pappl_devopen_cb_t
599 Device open callback
600 typedef bool (*pappl_devopen_cb_t)(pappl_device_t *device, const char *device_uri, const char *name);
602 pappl_devread_cb_t
604 Device read callback
605 typedef ssize_t (*pappl_devread_cb_t)(pappl_device_t *device, void *buffer, size_t bytes);
607 pappl_devstatus_cb_t
609 Device status callback
610 typedef pappl_preason_t (*pappl_devstatus_cb_t)(pappl_device_t *device);
612 pappl_devsupplies_cb_t
614 Device supplies callback
615 typedef int (*pappl_devsupplies_cb_t)(pappl_device_t *device, int max_supplies, pappl_supply_t *supplies);
617 pappl_devtype_t
619 Device type bitfield
620 typedef unsigned pappl_devtype_t;
622 pappl_devwrite_cb_t
624 Device write callback
625 typedef ssize_t (*pappl_devwrite_cb_t)(pappl_device_t *device, const void *buffer, size_t bytes);
627
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 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.
6412023-10-06 pappl device functions pappl-device(3)