[thirdparty/cups.git] / cups / sidechannel.h

/*
 * Side-channel API definitions for CUPS.
 *
 * Copyright © 2007-2019 by Apple Inc.
 * Copyright © 2006 by Easy Software Products.
 *
 * Licensed under Apache License v2.0.  See the file "LICENSE" for more information.
 */

#ifndef _CUPS_SIDECHANNEL_H_
#  define _CUPS_SIDECHANNEL_H_

/*
 * Include necessary headers...
 */

#  include "versioning.h"
#  include <sys/types.h>
#  if defined(_WIN32) && !defined(__CUPS_SSIZE_T_DEFINED)
#    define __CUPS_SSIZE_T_DEFINED
#    include <stddef.h>
/* Windows does not support the ssize_t type, so map it to long... */
typedef long ssize_t;			/* @private@ */
#  endif /* _WIN32 && !__CUPS_SSIZE_T_DEFINED */


/*
 * C++ magic...
 */

#  ifdef __cplusplus
extern "C" {
#  endif /* __cplusplus */


/*
 * Constants...
 */

#define CUPS_SC_FD	4		/* File descriptor for select/poll */


/*
 * Enumerations...
 */

enum cups_sc_bidi_e			/**** Bidirectional capability values ****/
{
  CUPS_SC_BIDI_NOT_SUPPORTED = 0,	/* Bidirectional I/O is not supported */
  CUPS_SC_BIDI_SUPPORTED = 1		/* Bidirectional I/O is supported */
};
typedef enum cups_sc_bidi_e cups_sc_bidi_t;
					/**** Bidirectional capabilities ****/

enum cups_sc_command_e			/**** Request command codes ****/
{
  CUPS_SC_CMD_NONE = 0,			/* No command @private@ */
  CUPS_SC_CMD_SOFT_RESET = 1,		/* Do a soft reset */
  CUPS_SC_CMD_DRAIN_OUTPUT = 2,		/* Drain all pending output */
  CUPS_SC_CMD_GET_BIDI = 3,		/* Return bidirectional capabilities */
  CUPS_SC_CMD_GET_DEVICE_ID = 4,	/* Return the IEEE-1284 device ID */
  CUPS_SC_CMD_GET_STATE = 5,		/* Return the device state */
  CUPS_SC_CMD_SNMP_GET = 6,		/* Query an SNMP OID @since CUPS 1.4/macOS 10.6@ */
  CUPS_SC_CMD_SNMP_GET_NEXT = 7,	/* Query the next SNMP OID @since CUPS 1.4/macOS 10.6@ */
  CUPS_SC_CMD_GET_CONNECTED = 8,	/* Return whether the backend is "connected" to the printer @since CUPS 1.5/macOS 10.7@ */
  CUPS_SC_CMD_MAX			/* End of valid values @private@ */
};
typedef enum cups_sc_command_e cups_sc_command_t;
					/**** Request command codes ****/

enum cups_sc_connected_e		/**** Connectivity values ****/
{
  CUPS_SC_NOT_CONNECTED = 0,		/* Backend is not "connected" to printer */
  CUPS_SC_CONNECTED = 1			/* Backend is "connected" to printer */
};
typedef enum cups_sc_connected_e cups_sc_connected_t;
					/**** Connectivity values ****/


enum cups_sc_state_e			/**** Printer state bits ****/
{
  CUPS_SC_STATE_OFFLINE = 0,		/* Device is offline */
  CUPS_SC_STATE_ONLINE = 1,		/* Device is online */
  CUPS_SC_STATE_BUSY = 2,		/* Device is busy */
  CUPS_SC_STATE_ERROR = 4,		/* Other error condition */
  CUPS_SC_STATE_MEDIA_LOW = 16,		/* Paper low condition */
  CUPS_SC_STATE_MEDIA_EMPTY = 32,	/* Paper out condition */
  CUPS_SC_STATE_MARKER_LOW = 64,	/* Toner/ink low condition */
  CUPS_SC_STATE_MARKER_EMPTY = 128	/* Toner/ink out condition */
};
typedef enum cups_sc_state_e cups_sc_state_t;
					/**** Printer state bits ****/

enum cups_sc_status_e			/**** Response status codes ****/
{
  CUPS_SC_STATUS_NONE,			/* No status */
  CUPS_SC_STATUS_OK,			/* Operation succeeded */
  CUPS_SC_STATUS_IO_ERROR,		/* An I/O error occurred */
  CUPS_SC_STATUS_TIMEOUT,		/* The backend did not respond */
  CUPS_SC_STATUS_NO_RESPONSE,		/* The device did not respond */
  CUPS_SC_STATUS_BAD_MESSAGE,		/* The command/response message was invalid */
  CUPS_SC_STATUS_TOO_BIG,		/* Response too big */
  CUPS_SC_STATUS_NOT_IMPLEMENTED	/* Command not implemented */
};
typedef enum cups_sc_status_e cups_sc_status_t;
					/**** Response status codes ****/

typedef void (*cups_sc_walk_func_t)(const char *oid, const char *data,
                                    int datalen, void *context);
					/**** SNMP walk callback ****/


/*
 * Prototypes...
 */

/**** New in CUPS 1.2/macOS 10.5 ****/
extern ssize_t		cupsBackChannelRead(char *buffer, size_t bytes,
			                    double timeout) _CUPS_API_1_2;
extern ssize_t		cupsBackChannelWrite(const char *buffer, size_t bytes,
			                     double timeout) _CUPS_API_1_2;

/**** New in CUPS 1.3/macOS 10.5 ****/
extern cups_sc_status_t	cupsSideChannelDoRequest(cups_sc_command_t command,
			                         char *data, int *datalen,
						 double timeout) _CUPS_API_1_3;
extern int		cupsSideChannelRead(cups_sc_command_t *command,
			                    cups_sc_status_t *status,
					    char *data, int *datalen,
					    double timeout) _CUPS_API_1_3;
extern int		cupsSideChannelWrite(cups_sc_command_t command,
			                     cups_sc_status_t status,
					     const char *data, int datalen,
					     double timeout) _CUPS_API_1_3;

/**** New in CUPS 1.4/macOS 10.6 ****/
extern cups_sc_status_t	cupsSideChannelSNMPGet(const char *oid, char *data,
			                       int *datalen, double timeout)
					       _CUPS_API_1_4;
extern cups_sc_status_t	cupsSideChannelSNMPWalk(const char *oid, double timeout,
						cups_sc_walk_func_t cb,
						void *context) _CUPS_API_1_4;


#  ifdef __cplusplus
}
#  endif /* __cplusplus */

#endif /* !_CUPS_SIDECHANNEL_H_ */
Commit	Line	Data
f7deaa1a	1	/*
503b54c9	2	* Side-channel API definitions for CUPS.
f7deaa1a	3	*
ffbf1e61 MS	4	* Copyright © 2007-2019 by Apple Inc.
ffbf1e61 MS	5	* Copyright © 2006 by Easy Software Products.
f7deaa1a	6	*
e3101897	7	* Licensed under Apache License v2.0. See the file "LICENSE" for more information.
f7deaa1a	8	*/
	9
	10	#ifndef _CUPS_SIDECHANNEL_H_
	11	# define _CUPS_SIDECHANNEL_H_
	12
2fb76298 MS	13	/*
	14	* Include necessary headers...
	15	*/
	16
	17	# include "versioning.h"
ffbf1e61 MS	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 */
2fb76298 MS	25
2fb76298 MS	26
f7deaa1a	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
79e1d494	47	enum cups_sc_bidi_e /** Bidirectional capability values **/
f7deaa1a	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 */
5a738aea MS	51	};
	52	typedef enum cups_sc_bidi_e cups_sc_bidi_t;
	53	/** Bidirectional capabilities **/
f7deaa1a	54
5a738aea	55	enum cups_sc_command_e /** Request command codes **/
f7deaa1a	56	{
18ecb428	57	CUPS_SC_CMD_NONE = 0, /* No command @private@ */
f7deaa1a	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 */
20fbc903	62	CUPS_SC_CMD_GET_STATE = 5, /* Return the device state */
8072030b MS	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@ */
f14324a7	66	CUPS_SC_CMD_MAX /* End of valid values @private@ */
5a738aea MS	67	};
	68	typedef enum cups_sc_command_e cups_sc_command_t;
	69	/** Request command codes **/
f7deaa1a	70
f14324a7 MS	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
5a738aea	80	enum cups_sc_state_e /** Printer state bits **/
f7deaa1a	81	{
79e1d494 MS	82	CUPS_SC_STATE_OFFLINE = 0, /* Device is offline */
79e1d494 MS	83	CUPS_SC_STATE_ONLINE = 1, /* Device is online */
f7deaa1a	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 */
5a738aea MS	90	};
	91	typedef enum cups_sc_state_e cups_sc_state_t;
	92	/** Printer state bits **/
f7deaa1a	93
5a738aea	94	enum cups_sc_status_e /** Response status codes **/
f7deaa1a	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 */
5a738aea MS	104	};
	105	typedef enum cups_sc_status_e cups_sc_status_t;
	106	/** Response status codes **/
f7deaa1a	107
20fbc903 MS	108	typedef void (cups_sc_walk_func_t)(const char oid, const char *data,
	109	int datalen, void *context);
	110	/** SNMP walk callback **/
	111
f7deaa1a	112
	113	/*
	114	* Prototypes...
	115	*/
	116
ffbf1e61 MS	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 **/
f7deaa1a	124	extern cups_sc_status_t cupsSideChannelDoRequest(cups_sc_command_t command,
f7deaa1a	125	char data, int datalen,
2fb76298	126	double timeout) _CUPS_API_1_3;
f7deaa1a	127	extern int cupsSideChannelRead(cups_sc_command_t *command,
	128	cups_sc_status_t *status,
	129	char data, int datalen,
2fb76298	130	double timeout) _CUPS_API_1_3;
f7deaa1a	131	extern int cupsSideChannelWrite(cups_sc_command_t command,
	132	cups_sc_status_t status,
	133	const char *data, int datalen,
2fb76298	134	double timeout) _CUPS_API_1_3;
f7deaa1a	135
ffbf1e61	136	/** New in CUPS 1.4/macOS 10.6 **/
20fbc903 MS	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
f7deaa1a	144
	145	# ifdef __cplusplus
	146	}
	147	# endif /* __cplusplus */
	148
	149	#endif /* !_CUPS_SIDECHANNEL_H_ */