2 * Side-channel API code for CUPS.
4 * Copyright 2007-2014 by Apple Inc.
5 * Copyright 2006 by Easy Software Products.
7 * Licensed under Apache License v2.0. See the file "LICENSE" for more information.
11 * Include necessary headers...
14 #include "sidechannel.h"
15 #include "cups-private.h"
22 # include <sys/select.h>
23 # include <sys/time.h>
27 #endif /* HAVE_POLL */
31 * Buffer size for side-channel requests...
34 #define _CUPS_SC_MAX_DATA 65535
35 #define _CUPS_SC_MAX_BUFFER 65540
39 * 'cupsSideChannelDoRequest()' - Send a side-channel command to a backend and wait for a response.
41 * This function is normally only called by filters, drivers, or port
42 * monitors in order to communicate with the backend used by the current
43 * printer. Programs must be prepared to handle timeout or "not
44 * implemented" status codes, which indicate that the backend or device
45 * do not support the specified side-channel command.
47 * The "datalen" parameter must be initialized to the size of the buffer
48 * pointed to by the "data" parameter. cupsSideChannelDoRequest() will
49 * update the value to contain the number of data bytes in the buffer.
51 * @since CUPS 1.3/macOS 10.5@
54 cups_sc_status_t
/* O - Status of command */
55 cupsSideChannelDoRequest(
56 cups_sc_command_t command
, /* I - Command to send */
57 char *data
, /* O - Response data buffer pointer */
58 int *datalen
, /* IO - Size of data buffer on entry, number of bytes in buffer on return */
59 double timeout
) /* I - Timeout in seconds */
61 cups_sc_status_t status
; /* Status of command */
62 cups_sc_command_t rcommand
; /* Response command */
65 if (cupsSideChannelWrite(command
, CUPS_SC_STATUS_NONE
, NULL
, 0, timeout
))
66 return (CUPS_SC_STATUS_TIMEOUT
);
68 if (cupsSideChannelRead(&rcommand
, &status
, data
, datalen
, timeout
))
69 return (CUPS_SC_STATUS_TIMEOUT
);
71 if (rcommand
!= command
)
72 return (CUPS_SC_STATUS_BAD_MESSAGE
);
79 * 'cupsSideChannelRead()' - Read a side-channel message.
81 * This function is normally only called by backend programs to read
82 * commands from a filter, driver, or port monitor program. The
83 * caller must be prepared to handle incomplete or invalid messages
84 * and return the corresponding status codes.
86 * The "datalen" parameter must be initialized to the size of the buffer
87 * pointed to by the "data" parameter. cupsSideChannelDoRequest() will
88 * update the value to contain the number of data bytes in the buffer.
90 * @since CUPS 1.3/macOS 10.5@
93 int /* O - 0 on success, -1 on error */
95 cups_sc_command_t
*command
, /* O - Command code */
96 cups_sc_status_t
*status
, /* O - Status code */
97 char *data
, /* O - Data buffer pointer */
98 int *datalen
, /* IO - Size of data buffer on entry, number of bytes in buffer on return */
99 double timeout
) /* I - Timeout in seconds */
101 char *buffer
; /* Message buffer */
102 ssize_t bytes
; /* Bytes read */
103 int templen
; /* Data length from message */
104 int nfds
; /* Number of file descriptors */
106 struct pollfd pfd
; /* Poll structure for poll() */
108 fd_set input_set
; /* Input set for select() */
109 struct timeval stimeout
; /* Timeout value for select() */
110 #endif /* HAVE_POLL */
113 DEBUG_printf(("cupsSideChannelRead(command=%p, status=%p, data=%p, "
114 "datalen=%p(%d), timeout=%.3f)", command
, status
, data
,
115 datalen
, datalen
? *datalen
: -1, timeout
));
118 * Range check input...
121 if (!command
|| !status
)
125 * See if we have pending data on the side-channel socket...
132 while ((nfds
= poll(&pfd
, 1,
133 timeout
< 0.0 ? -1 : (int)(timeout
* 1000))) < 0 &&
134 (errno
== EINTR
|| errno
== EAGAIN
))
139 FD_SET(CUPS_SC_FD
, &input_set
);
141 stimeout
.tv_sec
= (int)timeout
;
142 stimeout
.tv_usec
= (int)(timeout
* 1000000) % 1000000;
144 while ((nfds
= select(CUPS_SC_FD
+ 1, &input_set
, NULL
, NULL
,
145 timeout
< 0.0 ? NULL
: &stimeout
)) < 0 &&
146 (errno
== EINTR
|| errno
== EAGAIN
))
149 #endif /* HAVE_POLL */
153 *command
= CUPS_SC_CMD_NONE
;
154 *status
= nfds
==0 ? CUPS_SC_STATUS_TIMEOUT
: CUPS_SC_STATUS_IO_ERROR
;
159 * Read a side-channel message for the format:
161 * Byte(s) Description
162 * ------- -------------------------------------------
165 * 2-3 Data length (network byte order)
169 if ((buffer
= _cupsBufferGet(_CUPS_SC_MAX_BUFFER
)) == NULL
)
171 *command
= CUPS_SC_CMD_NONE
;
172 *status
= CUPS_SC_STATUS_TOO_BIG
;
177 while ((bytes
= read(CUPS_SC_FD
, buffer
, _CUPS_SC_MAX_BUFFER
)) < 0)
178 if (errno
!= EINTR
&& errno
!= EAGAIN
)
180 DEBUG_printf(("1cupsSideChannelRead: Read error: %s", strerror(errno
)));
182 _cupsBufferRelease(buffer
);
184 *command
= CUPS_SC_CMD_NONE
;
185 *status
= CUPS_SC_STATUS_IO_ERROR
;
191 * Watch for EOF or too few bytes...
196 DEBUG_printf(("1cupsSideChannelRead: Short read of " CUPS_LLFMT
" bytes", CUPS_LLCAST bytes
));
198 _cupsBufferRelease(buffer
);
200 *command
= CUPS_SC_CMD_NONE
;
201 *status
= CUPS_SC_STATUS_BAD_MESSAGE
;
207 * Validate the command code in the message...
210 if (buffer
[0] < CUPS_SC_CMD_SOFT_RESET
||
211 buffer
[0] >= CUPS_SC_CMD_MAX
)
213 DEBUG_printf(("1cupsSideChannelRead: Bad command %d!", buffer
[0]));
215 _cupsBufferRelease(buffer
);
217 *command
= CUPS_SC_CMD_NONE
;
218 *status
= CUPS_SC_STATUS_BAD_MESSAGE
;
223 *command
= (cups_sc_command_t
)buffer
[0];
226 * Validate the data length in the message...
229 templen
= ((buffer
[2] & 255) << 8) | (buffer
[3] & 255);
231 if (templen
> 0 && (!data
|| !datalen
))
234 * Either the response is bigger than the provided buffer or the
235 * response is bigger than we've read...
238 *status
= CUPS_SC_STATUS_TOO_BIG
;
240 else if (!datalen
|| templen
> *datalen
|| templen
> (bytes
- 4))
243 * Either the response is bigger than the provided buffer or the
244 * response is bigger than we've read...
247 *status
= CUPS_SC_STATUS_TOO_BIG
;
252 * The response data will fit, copy it over and provide the actual
256 *status
= (cups_sc_status_t
)buffer
[1];
259 memcpy(data
, buffer
+ 4, (size_t)templen
);
262 _cupsBufferRelease(buffer
);
264 DEBUG_printf(("1cupsSideChannelRead: Returning status=%d", *status
));
271 * 'cupsSideChannelSNMPGet()' - Query a SNMP OID's value.
273 * This function asks the backend to do a SNMP OID query on behalf of the
274 * filter, port monitor, or backend using the default community name.
276 * "oid" contains a numeric OID consisting of integers separated by periods,
277 * for example ".1.3.6.1.2.1.43". Symbolic names from SNMP MIBs are not
278 * supported and must be converted to their numeric forms.
280 * On input, "data" and "datalen" provide the location and size of the
281 * buffer to hold the OID value as a string. HEX-String (binary) values are
282 * converted to hexadecimal strings representing the binary data, while
283 * NULL-Value and unknown OID types are returned as the empty string.
284 * The returned "datalen" does not include the trailing nul.
286 * @code CUPS_SC_STATUS_NOT_IMPLEMENTED@ is returned by backends that do not
287 * support SNMP queries. @code CUPS_SC_STATUS_NO_RESPONSE@ is returned when
288 * the printer does not respond to the SNMP query.
290 * @since CUPS 1.4/macOS 10.6@
293 cups_sc_status_t
/* O - Query status */
294 cupsSideChannelSNMPGet(
295 const char *oid
, /* I - OID to query */
296 char *data
, /* I - Buffer for OID value */
297 int *datalen
, /* IO - Size of OID buffer on entry, size of value on return */
298 double timeout
) /* I - Timeout in seconds */
300 cups_sc_status_t status
; /* Status of command */
301 cups_sc_command_t rcommand
; /* Response command */
302 char *real_data
; /* Real data buffer for response */
303 int real_datalen
, /* Real length of data buffer */
304 real_oidlen
; /* Length of returned OID string */
307 DEBUG_printf(("cupsSideChannelSNMPGet(oid=\"%s\", data=%p, datalen=%p(%d), "
308 "timeout=%.3f)", oid
, data
, datalen
, datalen
? *datalen
: -1,
312 * Range check input...
315 if (!oid
|| !*oid
|| !data
|| !datalen
|| *datalen
< 2)
316 return (CUPS_SC_STATUS_BAD_MESSAGE
);
321 * Send the request to the backend and wait for a response...
324 if (cupsSideChannelWrite(CUPS_SC_CMD_SNMP_GET
, CUPS_SC_STATUS_NONE
, oid
,
325 (int)strlen(oid
) + 1, timeout
))
326 return (CUPS_SC_STATUS_TIMEOUT
);
328 if ((real_data
= _cupsBufferGet(_CUPS_SC_MAX_BUFFER
)) == NULL
)
329 return (CUPS_SC_STATUS_TOO_BIG
);
331 real_datalen
= _CUPS_SC_MAX_BUFFER
;
332 if (cupsSideChannelRead(&rcommand
, &status
, real_data
, &real_datalen
, timeout
))
334 _cupsBufferRelease(real_data
);
335 return (CUPS_SC_STATUS_TIMEOUT
);
338 if (rcommand
!= CUPS_SC_CMD_SNMP_GET
)
340 _cupsBufferRelease(real_data
);
341 return (CUPS_SC_STATUS_BAD_MESSAGE
);
344 if (status
== CUPS_SC_STATUS_OK
)
347 * Parse the response of the form "oid\0value"...
350 real_oidlen
= (int)strlen(real_data
) + 1;
351 real_datalen
-= real_oidlen
;
353 if ((real_datalen
+ 1) > *datalen
)
355 _cupsBufferRelease(real_data
);
356 return (CUPS_SC_STATUS_TOO_BIG
);
359 memcpy(data
, real_data
+ real_oidlen
, (size_t)real_datalen
);
360 data
[real_datalen
] = '\0';
362 *datalen
= real_datalen
;
365 _cupsBufferRelease(real_data
);
372 * 'cupsSideChannelSNMPWalk()' - Query multiple SNMP OID values.
374 * This function asks the backend to do multiple SNMP OID queries on behalf
375 * of the filter, port monitor, or backend using the default community name.
376 * All OIDs under the "parent" OID are queried and the results are sent to
377 * the callback function you provide.
379 * "oid" contains a numeric OID consisting of integers separated by periods,
380 * for example ".1.3.6.1.2.1.43". Symbolic names from SNMP MIBs are not
381 * supported and must be converted to their numeric forms.
383 * "timeout" specifies the timeout for each OID query. The total amount of
384 * time will depend on the number of OID values found and the time required
387 * "cb" provides a function to call for every value that is found. "context"
388 * is an application-defined pointer that is sent to the callback function
389 * along with the OID and current data. The data passed to the callback is the
390 * same as returned by @link cupsSideChannelSNMPGet@.
392 * @code CUPS_SC_STATUS_NOT_IMPLEMENTED@ is returned by backends that do not
393 * support SNMP queries. @code CUPS_SC_STATUS_NO_RESPONSE@ is returned when
394 * the printer does not respond to the first SNMP query.
396 * @since CUPS 1.4/macOS 10.6@
399 cups_sc_status_t
/* O - Status of first query of @code CUPS_SC_STATUS_OK@ on success */
400 cupsSideChannelSNMPWalk(
401 const char *oid
, /* I - First numeric OID to query */
402 double timeout
, /* I - Timeout for each query in seconds */
403 cups_sc_walk_func_t cb
, /* I - Function to call with each value */
404 void *context
) /* I - Application-defined pointer to send to callback */
406 cups_sc_status_t status
; /* Status of command */
407 cups_sc_command_t rcommand
; /* Response command */
408 char *real_data
; /* Real data buffer for response */
409 int real_datalen
; /* Real length of data buffer */
410 size_t real_oidlen
, /* Length of returned OID string */
411 oidlen
; /* Length of first OID */
412 const char *current_oid
; /* Current OID */
413 char last_oid
[2048]; /* Last OID */
416 DEBUG_printf(("cupsSideChannelSNMPWalk(oid=\"%s\", timeout=%.3f, cb=%p, "
417 "context=%p)", oid
, timeout
, cb
, context
));
420 * Range check input...
423 if (!oid
|| !*oid
|| !cb
)
424 return (CUPS_SC_STATUS_BAD_MESSAGE
);
426 if ((real_data
= _cupsBufferGet(_CUPS_SC_MAX_BUFFER
)) == NULL
)
427 return (CUPS_SC_STATUS_TOO_BIG
);
430 * Loop until the OIDs don't match...
434 oidlen
= strlen(oid
);
440 * Send the request to the backend and wait for a response...
443 if (cupsSideChannelWrite(CUPS_SC_CMD_SNMP_GET_NEXT
, CUPS_SC_STATUS_NONE
,
444 current_oid
, (int)strlen(current_oid
) + 1, timeout
))
446 _cupsBufferRelease(real_data
);
447 return (CUPS_SC_STATUS_TIMEOUT
);
450 real_datalen
= _CUPS_SC_MAX_BUFFER
;
451 if (cupsSideChannelRead(&rcommand
, &status
, real_data
, &real_datalen
,
454 _cupsBufferRelease(real_data
);
455 return (CUPS_SC_STATUS_TIMEOUT
);
458 if (rcommand
!= CUPS_SC_CMD_SNMP_GET_NEXT
)
460 _cupsBufferRelease(real_data
);
461 return (CUPS_SC_STATUS_BAD_MESSAGE
);
464 if (status
== CUPS_SC_STATUS_OK
)
467 * Parse the response of the form "oid\0value"...
470 if (strncmp(real_data
, oid
, oidlen
) || real_data
[oidlen
] != '.' ||
471 !strcmp(real_data
, last_oid
))
474 * Done with this set of OIDs...
477 _cupsBufferRelease(real_data
);
478 return (CUPS_SC_STATUS_OK
);
481 if ((size_t)real_datalen
< sizeof(real_data
))
482 real_data
[real_datalen
] = '\0';
484 real_oidlen
= strlen(real_data
) + 1;
485 real_datalen
-= (int)real_oidlen
;
488 * Call the callback with the OID and data...
491 (*cb
)(real_data
, real_data
+ real_oidlen
, real_datalen
, context
);
494 * Update the current OID...
497 current_oid
= real_data
;
498 strlcpy(last_oid
, current_oid
, sizeof(last_oid
));
501 while (status
== CUPS_SC_STATUS_OK
);
503 _cupsBufferRelease(real_data
);
510 * 'cupsSideChannelWrite()' - Write a side-channel message.
512 * This function is normally only called by backend programs to send
513 * responses to a filter, driver, or port monitor program.
515 * @since CUPS 1.3/macOS 10.5@
518 int /* O - 0 on success, -1 on error */
519 cupsSideChannelWrite(
520 cups_sc_command_t command
, /* I - Command code */
521 cups_sc_status_t status
, /* I - Status code */
522 const char *data
, /* I - Data buffer pointer */
523 int datalen
, /* I - Number of bytes of data */
524 double timeout
) /* I - Timeout in seconds */
526 char *buffer
; /* Message buffer */
527 ssize_t bytes
; /* Bytes written */
529 struct pollfd pfd
; /* Poll structure for poll() */
531 fd_set output_set
; /* Output set for select() */
532 struct timeval stimeout
; /* Timeout value for select() */
533 #endif /* HAVE_POLL */
537 * Range check input...
540 if (command
< CUPS_SC_CMD_SOFT_RESET
|| command
>= CUPS_SC_CMD_MAX
||
541 datalen
< 0 || datalen
> _CUPS_SC_MAX_DATA
|| (datalen
> 0 && !data
))
545 * See if we can safely write to the side-channel socket...
550 pfd
.events
= POLLOUT
;
554 if (poll(&pfd
, 1, -1) < 1)
557 else if (poll(&pfd
, 1, (int)(timeout
* 1000)) < 1)
561 FD_ZERO(&output_set
);
562 FD_SET(CUPS_SC_FD
, &output_set
);
566 if (select(CUPS_SC_FD
+ 1, NULL
, &output_set
, NULL
, NULL
) < 1)
571 stimeout
.tv_sec
= (int)timeout
;
572 stimeout
.tv_usec
= (int)(timeout
* 1000000) % 1000000;
574 if (select(CUPS_SC_FD
+ 1, NULL
, &output_set
, NULL
, &stimeout
) < 1)
577 #endif /* HAVE_POLL */
580 * Write a side-channel message in the format:
582 * Byte(s) Description
583 * ------- -------------------------------------------
586 * 2-3 Data length (network byte order) <= 16384
590 if ((buffer
= _cupsBufferGet((size_t)datalen
+ 4)) == NULL
)
595 buffer
[2] = (char)(datalen
>> 8);
596 buffer
[3] = (char)(datalen
& 255);
602 memcpy(buffer
+ 4, data
, (size_t)datalen
);
606 while (write(CUPS_SC_FD
, buffer
, (size_t)bytes
) < 0)
607 if (errno
!= EINTR
&& errno
!= EAGAIN
)
609 _cupsBufferRelease(buffer
);
613 _cupsBufferRelease(buffer
);