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 papplDeviceClose
194 Close a device connection.
195 void papplDeviceClose (
197 pappl_device_t *device
198 );
199 This function flushes any pending write data and closes the connection
201 to a device.
202 papplDeviceError
204 Report an error on a device.
205 void papplDeviceError (
207 pappl_device_t *device,
208 const char *message,
209 ...
210 );
211 This function reports an error on a device using the client-supplied
213 callback function. It is normally called from any custom device URI
214 scheme callbacks you implement.
215 papplDeviceFlush
217 Flush any buffered data to the device.
218 void papplDeviceFlush (
220 pappl_device_t *device
221 );
222 This function flushes any pending write data sent using the papplDevi‐
224 cePrintf, papplDevicePuts, or papplDeviceWrite functions to the device.
225 papplDeviceGetData
227 Get device-specific data.
228 void * papplDeviceGetData (
230 pappl_device_t *device
231 );
232 This function returns any device-specific data that has been set by the
234 device open callback. It is normally only called from any custom de‐
235 vice URI scheme callbacks you implement.
236 papplDeviceGetID
238 Get the IEEE-1284 device ID.
239 char * papplDeviceGetID (
241 pappl_device_t *device,
242 char *buffer,
243 size_t bufsize
244 );
245 This function queries the IEEE-1284 device ID from the device and
247 copies it to the provided buffer. The buffer must be at least 64 bytes
248 and should be at least 1024 bytes in length.
249 5 Note: This function can block for up to several seconds depend‐
251 ing on
252 5 the type of connection.
254 papplDeviceGetMetrics
256 Get the device metrics.
257 pappl_devmetrics_t * papplDeviceGetMetrics (
259 pappl_device_t *device,
260 pappl_devmetrics_t *metrics
261 );
262 This function returns a copy of the device metrics data, which includes
264 the number, length (in bytes), and duration (in milliseconds) of read,
265 status, and write requests for the current session. This information
266 is normally used for performance measurement and optimization during
267 development of a printer application. It can also be useful diagnostic
268 information.
269 papplDeviceGetStatus
271 Get the printer status bits.
272 pappl_preason_t papplDeviceGetStatus (
274 pappl_device_t *device
275 );
276 This function returns the current printer status bits, as applicable to
278 the current device.
279 The status bits for USB devices come from the original Centronics par‐
281 allel printer "standard" which was later formally standardized in IEEE
282 1284-1984 and the USB Device Class Definition for Printing Devices.
283 Some vendor extensions are also supported.
284 The status bits for network devices come from the hrPrinterDetectedEr‐
286 rorState property that is defined in the SNMP Printer MIB v2 (RFC
287 3805).
288 This function returns a pappl_preason_t bitfield which can be passed to
290 the papplPrinterSetReasons function. Use the PAPPL_PREASON_DEVICE_STA‐
291 TUS value as the value of the "remove" argument.
292 5 Note: This function can block for several seconds while getting
294 the status
295 5 information.
297 papplDeviceIsSupported
299 Determine whether a given URI is supported.
300 bool papplDeviceIsSupported (
302 const char *uri
303 );
304 This function determines whether a given URI or URI scheme is supported
306 as a device.
307 papplDeviceList
309 List available devices.
310 bool papplDeviceList (
312 pappl_devtype_t types,
313 pappl_device_cb_t cb,
314 void *data,
315 pappl_deverror_cb_t err_cb,
316 void *err_data
317 );
318 This function lists the available devices, calling the "cb" function
320 once per device that is discovered/listed. The callback function re‐
321 ceives the device URI, IEEE-1284 device ID (if any), and "data"
322 pointer, and returns true to stop listing devices and false to con‐
323 tinue.
324 The "types" argument determines which devices are listed, for example
326 PAPPL_DEVTYPE_ALL will list all types of devices while PAPPL_DEV‐
327 TYPE_USB only lists USB printers.
328 Any errors are reported using the supplied "err_cb" function. If you
330 specify NULL for this argument, errors are sent to stderr.
331 5 Note: This function will block (not return) until each of the
333 device URI
334 5 schemes has reported all of the devices or the supplied callback
336 function
337 5 returns true.
339 papplDeviceOpen
341 Open a connection to a device.
342 pappl_device_t * papplDeviceOpen (
344 const char *device_uri,
345 const char *name,
346 pappl_deverror_cb_t err_cb,
347 void *err_data
348 );
349 This function opens a connection to the specified device URI. The
351 "name" argument provides textual context for the connection and is usu‐
352 ally the name (title) of the print job.
353 Any errors are reported using the supplied "err_cb" function. If you
355 specify NULL for this argument, errors are sent to stderr.
356 papplDeviceParseID
358 Parse an IEEE-1284 device ID string.
359 int papplDeviceParseID (
361 const char *device_id,
362 cups_option_t **pairs
363 );
364 This function parses an IEEE-1284 device ID string and returns an array
366 of key/value pairs as a cups_option_t array. The returned array must
367 be freed using the cupsFreeOptions function.
368 papplDevicePrintf
370 Write a formatted string.
371 ssize_t papplDevicePrintf (
373 pappl_device_t *device,
374 const char *format,
375 ...
376 );
377 This function buffers a formatted string that will be sent to the de‐
379 vice. The "format" argument accepts all printf format specifiers and
380 behaves identically to that function.
381 Call the papplDeviceFlush function to ensure that the formatted string
383 is immediately sent to the device.
384 papplDevicePuts
386 Write a literal string.
387 ssize_t papplDevicePuts (
389 pappl_device_t *device,
390 const char *s
391 );
392 This function buffers a literal string that will be sent to the device.
394 Call the papplDeviceFlush function to ensure that the literal string is
395 immediately sent to the device.
396 papplDeviceRead
398 Read from a device.
399 ssize_t papplDeviceRead (
401 pappl_device_t *device,
402 void *buffer,
403 size_t bytes
404 );
405 This function reads data from the device. Depending on the device,
407 this function may block indefinitely.
408 papplDeviceSetData
410 Set device-specific data.
411 void papplDeviceSetData (
413 pappl_device_t *device,
414 void *data
415 );
416 This function sets any device-specific data needed to communicate with
418 the device. It is normally only called from the open callback that was
419 registered for the device URI scheme.
420 papplDeviceWrite
422 Write to a device.
423 ssize_t papplDeviceWrite (
425 pappl_device_t *device,
426 const void *buffer,
427 size_t bytes
428 );
429 This function buffers data that will be sent to the device. Call the
431 papplDeviceFlush function to ensure that the data is immediately sent
432 to the device.
433
435 pappl_devmetrics_s
436 Device metrics
437 struct pappl_devmetrics_s
439 {
440 size_t read_bytes;
441 size_t read_msecs;
442 size_t read_requests;
443 size_t status_msecs;
444 size_t status_requests;
445 size_t write_bytes;
446 size_t write_msecs;
447 size_t write_requests;
448 };
449
451 pappl_devclose_cb_t
452 Device close callback
453 typedef void (*pappl_devclose_cb_t)(pappl_device_t *device);
455 pappl_deverror_cb_t
457 Device error callback
458 typedef void (*pappl_deverror_cb_t)(const char *message, void *err_data);
460 pappl_device_cb_t
462 Device callback - return true to stop, false to continue
463 typedef bool (*pappl_device_cb_t)(const char *device_info, const char *device_uri, const char *device_id, void *data);
465 pappl_devid_cb_t
467 Device ID callback
468 typedef char * (*pappl_devid_cb_t)(pappl_device_t *device, char *buffer, size_t bufsize);
470 pappl_devlist_cb_t
472 Device list callback
473 typedef bool (*pappl_devlist_cb_t)(pappl_device_cb_t cb, void *data, pappl_deverror_cb_t err_cb, void *err_data);
475 pappl_devmetrics_t
477 Device metrics
478 typedef struct pappl_devmetrics_s pappl_devmetrics_t;
480 pappl_devopen_cb_t
482 Device open callback
483 typedef bool (*pappl_devopen_cb_t)(pappl_device_t *device, const char *device_uri, const char *name);
485 pappl_devread_cb_t
487 Device read callback
488 typedef ssize_t (*pappl_devread_cb_t)(pappl_device_t *device, void *buffer, size_t bytes);
490 pappl_devstatus_cb_t
492 Device status callback
493 typedef pappl_preason_t (*pappl_devstatus_cb_t)(pappl_device_t *device);
495 pappl_devtype_t
497 Device type bitfield
498 typedef unsigned pappl_devtype_t;
500 pappl_devwrite_cb_t
502 Device write callback
503 typedef ssize_t (*pappl_devwrite_cb_t)(pappl_device_t *device, const void *buffer, size_t bytes);
505
507 pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3),
508 pappl-mainline(3), pappl-makeresheader(1), pappl-printer(3), pappl-re‐
509 source(3), pappl-system(3), https://www.msweet.org/pappl
510
512 Copyright © 2019-2020 by Michael R Sweet.
513 PAPPL is licensed under the Apache License Version 2.0 with an (op‐
515 tional) exception to allow linking against GPL2/LGPL2 software (like
516 older versions of CUPS), so it can be used freely in any project you'd
517 like. See the files "LICENSE" and "NOTICE" in the source distribution
518 for more information.
5192021-02-15 pappl device functions pappl-device(3)