cups/sidechannel.h

   1 /*
   2  * Side-channel API definitions for CUPS.
   3  *
   4  * Copyright © 2007-2019 by Apple Inc.
   5  * Copyright © 2006 by Easy Software Products.
   6  *
   7  * Licensed under Apache License v2.0.  See the file "LICENSE" for more information.
   8  */
   9
  10 #ifndef _CUPS_SIDECHANNEL_H_
  11 #  define _CUPS_SIDECHANNEL_H_
  12
  13 /*
  14  * Include necessary headers...
  15  */
  16
  17 #  include "versioning.h"
  18 #  include <sys/types.h>
  19 #  if defined(_WIN32) && !defined(__CUPS_SSIZE_T_DEFINED)
  20 #    define __CUPS_SSIZE_T_DEFINED
  21 #    include <stddef.h>
  22 /* Windows does not support the ssize_t type, so map it to long... */
  23 typedef long ssize_t;                   /* @private@ */
  24 #  endif /* _WIN32 && !__CUPS_SSIZE_T_DEFINED */
  25
  26
  27 /*
  28  * C++ magic...
  29  */
  30
  31 #  ifdef __cplusplus
  32 extern "C" {
  33 #  endif /* __cplusplus */
  34
  35
  36 /*
  37  * Constants...
  38  */
  39
  40 #define CUPS_SC_FD      4               /* File descriptor for select/poll */
  41
  42
  43 /*
  44  * Enumerations...
  45  */
  46
  47 enum cups_sc_bidi_e                     /**** Bidirectional capability values ****/
  48 {
  49   CUPS_SC_BIDI_NOT_SUPPORTED = 0,       /* Bidirectional I/O is not supported */
  50   CUPS_SC_BIDI_SUPPORTED = 1            /* Bidirectional I/O is supported */
  51 };
  52 typedef enum cups_sc_bidi_e cups_sc_bidi_t;
  53                                         /**** Bidirectional capabilities ****/
  54
  55 enum cups_sc_command_e                  /**** Request command codes ****/
  56 {
  57   CUPS_SC_CMD_NONE = 0,                 /* No command @private@ */
  58   CUPS_SC_CMD_SOFT_RESET = 1,           /* Do a soft reset */
  59   CUPS_SC_CMD_DRAIN_OUTPUT = 2,         /* Drain all pending output */
  60   CUPS_SC_CMD_GET_BIDI = 3,             /* Return bidirectional capabilities */
  61   CUPS_SC_CMD_GET_DEVICE_ID = 4,        /* Return the IEEE-1284 device ID */
  62   CUPS_SC_CMD_GET_STATE = 5,            /* Return the device state */
  63   CUPS_SC_CMD_SNMP_GET = 6,             /* Query an SNMP OID @since CUPS 1.4/macOS 10.6@ */
  64   CUPS_SC_CMD_SNMP_GET_NEXT = 7,        /* Query the next SNMP OID @since CUPS 1.4/macOS 10.6@ */
  65   CUPS_SC_CMD_GET_CONNECTED = 8,        /* Return whether the backend is "connected" to the printer @since CUPS 1.5/macOS 10.7@ */
  66   CUPS_SC_CMD_MAX                       /* End of valid values @private@ */
  67 };
  68 typedef enum cups_sc_command_e cups_sc_command_t;
  69                                         /**** Request command codes ****/
  70
  71 enum cups_sc_connected_e                /**** Connectivity values ****/
  72 {
  73   CUPS_SC_NOT_CONNECTED = 0,            /* Backend is not "connected" to printer */
  74   CUPS_SC_CONNECTED = 1                 /* Backend is "connected" to printer */
  75 };
  76 typedef enum cups_sc_connected_e cups_sc_connected_t;
  77                                         /**** Connectivity values ****/
  78
  79
  80 enum cups_sc_state_e                    /**** Printer state bits ****/
  81 {
  82   CUPS_SC_STATE_OFFLINE = 0,            /* Device is offline */
  83   CUPS_SC_STATE_ONLINE = 1,             /* Device is online */
  84   CUPS_SC_STATE_BUSY = 2,               /* Device is busy */
  85   CUPS_SC_STATE_ERROR = 4,              /* Other error condition */
  86   CUPS_SC_STATE_MEDIA_LOW = 16,         /* Paper low condition */
  87   CUPS_SC_STATE_MEDIA_EMPTY = 32,       /* Paper out condition */
  88   CUPS_SC_STATE_MARKER_LOW = 64,        /* Toner/ink low condition */
  89   CUPS_SC_STATE_MARKER_EMPTY = 128      /* Toner/ink out condition */
  90 };
  91 typedef enum cups_sc_state_e cups_sc_state_t;
  92                                         /**** Printer state bits ****/
  93
  94 enum cups_sc_status_e                   /**** Response status codes ****/
  95 {
  96   CUPS_SC_STATUS_NONE,                  /* No status */
  97   CUPS_SC_STATUS_OK,                    /* Operation succeeded */
  98   CUPS_SC_STATUS_IO_ERROR,              /* An I/O error occurred */
  99   CUPS_SC_STATUS_TIMEOUT,               /* The backend did not respond */
 100   CUPS_SC_STATUS_NO_RESPONSE,           /* The device did not respond */
 101   CUPS_SC_STATUS_BAD_MESSAGE,           /* The command/response message was invalid */
 102   CUPS_SC_STATUS_TOO_BIG,               /* Response too big */
 103   CUPS_SC_STATUS_NOT_IMPLEMENTED        /* Command not implemented */
 104 };
 105 typedef enum cups_sc_status_e cups_sc_status_t;
 106                                         /**** Response status codes ****/
 107
 108 typedef void (*cups_sc_walk_func_t)(const char *oid, const char *data,
 109                                     int datalen, void *context);
 110                                         /**** SNMP walk callback ****/
 111
 112
 113 /*
 114  * Prototypes...
 115  */
 116
 117 /**** New in CUPS 1.2/macOS 10.5 ****/
 118 extern ssize_t          cupsBackChannelRead(char *buffer, size_t bytes,
 119                                             double timeout) _CUPS_API_1_2;
 120 extern ssize_t          cupsBackChannelWrite(const char *buffer, size_t bytes,
 121                                              double timeout) _CUPS_API_1_2;
 122
 123 /**** New in CUPS 1.3/macOS 10.5 ****/
 124 extern cups_sc_status_t cupsSideChannelDoRequest(cups_sc_command_t command,
 125                                                  char *data, int *datalen,
 126                                                  double timeout) _CUPS_API_1_3;
 127 extern int              cupsSideChannelRead(cups_sc_command_t *command,
 128                                             cups_sc_status_t *status,
 129                                             char *data, int *datalen,
 130                                             double timeout) _CUPS_API_1_3;
 131 extern int              cupsSideChannelWrite(cups_sc_command_t command,
 132                                              cups_sc_status_t status,
 133                                              const char *data, int datalen,
 134                                              double timeout) _CUPS_API_1_3;
 135
 136 /**** New in CUPS 1.4/macOS 10.6 ****/
 137 extern cups_sc_status_t cupsSideChannelSNMPGet(const char *oid, char *data,
 138                                                int *datalen, double timeout)
 139                                                _CUPS_API_1_4;
 140 extern cups_sc_status_t cupsSideChannelSNMPWalk(const char *oid, double timeout,
 141                                                 cups_sc_walk_func_t cb,
 142                                                 void *context) _CUPS_API_1_4;
 143
 144
 145 #  ifdef __cplusplus
 146 }
 147 #  endif /* __cplusplus */
 148
 149 #endif /* !_CUPS_SIDECHANNEL_H_ */