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

/*
 * "$Id: cups.h 4918 2006-01-12 05:14:40Z mike $"
 *
 *   API definitions for the Common UNIX Printing System (CUPS).
 *
 *   Copyright 1997-2006 by Easy Software Products.
 *
 *   These coded instructions, statements, and computer programs are the
 *   property of Easy Software Products and are protected by Federal
 *   copyright law.  Distribution and use rights are outlined in the file
 *   "LICENSE.txt" which should have been included with this file.  If this
 *   file is missing or damaged please contact Easy Software Products
 *   at:
 *
 *       Attn: CUPS Licensing Information
 *       Easy Software Products
 *       44141 Airport View Drive, Suite 204
 *       Hollywood, Maryland 20636 USA
 *
 *       Voice: (301) 373-9600
 *       EMail: cups-info@cups.org
 *         WWW: http://www.cups.org
 *
 *   This file is subject to the Apple OS-Developed Software exception.
 */

#ifndef _CUPS_CUPS_H_
#  define _CUPS_CUPS_H_

/*
 * Include necessary headers...
 */

#  include "ipp.h"
#  include "ppd.h"

/*
 * With GCC 3.0 and higher, we can mark old APIs "deprecated" so you get
 * an error at compile-time.
 */

#  if defined(__GNUC__) && __GNUC__ > 2
#    define _CUPS_DEPRECATED __attribute__ ((__deprecated__))
#  else
#    define _CUPS_DEPRECATED
#  endif /* __GNUC__ && __GNUC__ > 2 */


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

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


/*
 * Constants...
 */

#  define CUPS_VERSION		1.0190
#  define CUPS_VERSION_MAJOR	1
#  define CUPS_VERSION_MINOR	2
#  define CUPS_VERSION_PATCH	-10
#  define CUPS_DATE_ANY		-1


/*
 * Types and structures...
 */

typedef unsigned cups_ptype_t;		/**** Printer Type/Capability Bits ****/
enum cups_ptype_e			/* Not a typedef'd enum so we can OR */
{
  CUPS_PRINTER_LOCAL = 0x0000,		/* Local printer or class */
  CUPS_PRINTER_CLASS = 0x0001,		/* Printer class */
  CUPS_PRINTER_REMOTE = 0x0002,		/* Remote printer or class */
  CUPS_PRINTER_BW = 0x0004,		/* Can do B&W printing */
  CUPS_PRINTER_COLOR = 0x0008,		/* Can do color printing */
  CUPS_PRINTER_DUPLEX = 0x0010,		/* Can do duplexing */
  CUPS_PRINTER_STAPLE = 0x0020,		/* Can staple output */
  CUPS_PRINTER_COPIES = 0x0040,		/* Can do copies */
  CUPS_PRINTER_COLLATE = 0x0080,	/* Can collage copies */
  CUPS_PRINTER_PUNCH = 0x0100,		/* Can punch output */
  CUPS_PRINTER_COVER = 0x0200,		/* Can cover output */
  CUPS_PRINTER_BIND = 0x0400,		/* Can bind output */
  CUPS_PRINTER_SORT = 0x0800,		/* Can sort output */
  CUPS_PRINTER_SMALL = 0x1000,		/* Can do Letter/Legal/A4 */
  CUPS_PRINTER_MEDIUM = 0x2000,		/* Can do Tabloid/B/C/A3/A2 */
  CUPS_PRINTER_LARGE = 0x4000,		/* Can do D/E/A1/A0 */
  CUPS_PRINTER_VARIABLE = 0x8000,	/* Can do variable sizes */
  CUPS_PRINTER_IMPLICIT = 0x10000,	/* Implicit class */
  CUPS_PRINTER_DEFAULT = 0x20000,	/* Default printer on network */
  CUPS_PRINTER_FAX = 0x40000,		/* Fax queue */
  CUPS_PRINTER_REJECTING = 0x80000,	/* Printer is rejecting jobs */
  CUPS_PRINTER_DELETE = 0x100000,	/* Delete printer @since CUPS 1.2@ */
  CUPS_PRINTER_NOT_SHARED = 0x200000,	/* Printer is not shared @since CUPS 1.2@ */
  CUPS_PRINTER_AUTHENTICATED = 0x400000,/* Printer requires authentication @since CUPS 1.2@ */
  CUPS_PRINTER_OPTIONS = 0x66fffc	/* ~(CLASS | REMOTE | IMPLICIT) */
};

typedef const char *(*cups_password_cb_t)(const char *);

typedef struct cups_option_s		/**** Printer Options ****/
{
  char		*name;			/* Name of option */
  char		*value;			/* Value of option */
} cups_option_t;

typedef struct cups_dest_s		/**** Destination ****/
{
  char		*name,			/* Printer or class name */
		*instance;		/* Local instance name or NULL */
  int		is_default;		/* Is this printer the default? */
  int		num_options;		/* Number of options */
  cups_option_t	*options;		/* Options */
} cups_dest_t;

typedef struct cups_job_s		/**** Job ****/
{
  int		id;			/* The job ID */
  char		*dest,			/* Printer or class name */
		*title,			/* Title/job name */
		*user,			/* User the submitted the job */
		*format;		/* Document format */
  ipp_jstate_t	state;			/* Job state */
  int		size,			/* Size in kilobytes */
		priority;		/* Priority (1-100) */
  time_t	completed_time,		/* Time the job was completed */
		creation_time,		/* Time the job was created */
		processing_time;	/* Time the job was processed */
} cups_job_t;


/*
 * Functions...
 */

extern int		cupsCancelJob(const char *printer, int job);
#define			cupsDoRequest(http,request,resource) cupsDoFileRequest((http),(request),(resource),NULL)
extern ipp_t		*cupsDoFileRequest(http_t *http, ipp_t *request,
			                   const char *resource, const char *filename);
extern http_encryption_t cupsEncryption(void);
extern void		cupsFreeJobs(int num_jobs, cups_job_t *jobs);
extern int		cupsGetClasses(char ***classes) _CUPS_DEPRECATED;
extern const char	*cupsGetDefault(void);
extern int		cupsGetJobs(cups_job_t **jobs, const char *dest,
			            int myjobs, int completed);
extern const char	*cupsGetPPD(const char *printer);
extern int		cupsGetPrinters(char ***printers) _CUPS_DEPRECATED;
extern ipp_status_t	cupsLastError(void);
extern int		cupsPrintFile(const char *printer, const char *filename,
			              const char *title, int num_options,
				      cups_option_t *options);
extern int		cupsPrintFiles(const char *printer, int num_files,
			               const char **files, const char *title,
				       int num_options, cups_option_t *options);
extern char		*cupsTempFile(char *filename, int len) _CUPS_DEPRECATED;
extern int		cupsTempFd(char *filename, int len);

extern int		cupsAddDest(const char *name, const char *instance,
			            int num_dests, cups_dest_t **dests);
extern void		cupsFreeDests(int num_dests, cups_dest_t *dests);
extern cups_dest_t	*cupsGetDest(const char *name, const char *instance,
			             int num_dests, cups_dest_t *dests);
extern int		cupsGetDests(cups_dest_t **dests);
extern void		cupsSetDests(int num_dests, cups_dest_t *dests);

extern int		cupsAddOption(const char *name, const char *value,
			              int num_options, cups_option_t **options);
extern void		cupsEncodeOptions(ipp_t *ipp, int num_options,
					  cups_option_t *options);
extern void		cupsFreeOptions(int num_options, cups_option_t *options);
extern const char	*cupsGetOption(const char *name, int num_options,
			               cups_option_t *options);
extern int		cupsParseOptions(const char *arg, int num_options,
			                 cups_option_t **options);
extern int		cupsMarkOptions(ppd_file_t *ppd, int num_options,
			                cups_option_t *options);

extern const char	*cupsGetPassword(const char *prompt);
extern const char	*cupsServer(void);
extern void		cupsSetEncryption(http_encryption_t e);
extern void		cupsSetPasswordCB(cups_password_cb_t cb);
extern void		cupsSetServer(const char *server);
extern void		cupsSetUser(const char *user);
extern const char	*cupsUser(void);

/**** New in CUPS 1.1.20 ****/
extern int		cupsDoAuthentication(http_t *http, const char *method,
			                     const char *resource);
extern http_status_t	cupsGetFile(http_t *http, const char *resource,
			            const char *filename);
extern http_status_t	cupsGetFd(http_t *http, const char *resource, int fd);
extern http_status_t	cupsPutFile(http_t *http, const char *resource,
			            const char *filename);
extern http_status_t	cupsPutFd(http_t *http, const char *resource, int fd);

/**** New in CUPS 1.1.21 ****/
extern const char	*cupsGetDefault2(http_t *http);
extern int		cupsGetDests2(http_t *http, cups_dest_t **dests);
extern int		cupsGetJobs2(http_t *http, cups_job_t **jobs,
			             const char *dest, int myjobs,
				     int completed);
extern const char	*cupsGetPPD2(http_t *http, const char *printer);
extern int		cupsPrintFile2(http_t *http, const char *printer,
			               const char *filename,
				       const char *title, int num_options,
				       cups_option_t *options);
extern int		cupsPrintFiles2(http_t *http, const char *printer,
			                int num_files, const char **files,
					const char *title, int num_options,
					cups_option_t *options);
extern int		cupsSetDests2(http_t *http, int num_dests,
			              cups_dest_t *dests);

/**** New in CUPS 1.2 ****/
extern int		cupsBackchannelRead(char *buffer, int bytes, double timeout);
extern int		cupsBackchannelWrite(const char *buffer, int bytes,
			                     double timeout);
extern void		cupsEncodeOptions2(ipp_t *ipp, int num_options,
					   cups_option_t *options,
					   ipp_tag_t group_tag);
extern const char	*cupsLastErrorString(void);
extern cups_file_t	*cupsTempFile2(char *filename, int len);


#  ifdef __cplusplus
}
#  endif /* __cplusplus */

#endif /* !_CUPS_CUPS_H_ */

/*
 * End of "$Id: cups.h 4918 2006-01-12 05:14:40Z mike $".
 */
Commit	Line	Data
ef416fc2	1	/*
	2	* "$Id: cups.h 4918 2006-01-12 05:14:40Z mike $"
	3	*
	4	* API definitions for the Common UNIX Printing System (CUPS).
	5	*
	6	* Copyright 1997-2006 by Easy Software Products.
	7	*
	8	* These coded instructions, statements, and computer programs are the
	9	* property of Easy Software Products and are protected by Federal
	10	* copyright law. Distribution and use rights are outlined in the file
	11	* "LICENSE.txt" which should have been included with this file. If this
	12	* file is missing or damaged please contact Easy Software Products
	13	* at:
	14	*
	15	* Attn: CUPS Licensing Information
	16	* Easy Software Products
	17	* 44141 Airport View Drive, Suite 204
	18	* Hollywood, Maryland 20636 USA
	19	*
	20	* Voice: (301) 373-9600
	21	* EMail: cups-info@cups.org
	22	* WWW: http://www.cups.org
	23	*
	24	* This file is subject to the Apple OS-Developed Software exception.
	25	*/
	26
	27	#ifndef _CUPS_CUPS_H_
	28	# define _CUPS_CUPS_H_
	29
	30	/*
	31	* Include necessary headers...
	32	*/
	33
	34	# include "ipp.h"
	35	# include "ppd.h"
	36
	37	/*
	38	* With GCC 3.0 and higher, we can mark old APIs "deprecated" so you get
	39	* an error at compile-time.
	40	*/
	41
	42	# if defined(__GNUC__) && __GNUC__ > 2
	43	# define _CUPS_DEPRECATED __attribute__ ((__deprecated__))
	44	# else
	45	# define _CUPS_DEPRECATED
	46	# endif /* __GNUC__ && __GNUC__ > 2 */
	47
	48
	49	/*
	50	* C++ magic...
	51	*/
	52
	53	# ifdef __cplusplus
	54	extern "C" {
	55	# endif /* __cplusplus */
	56
	57
	58	/*
	59	* Constants...
	60	*/
	61
	62	# define CUPS_VERSION 1.0190
	63	# define CUPS_VERSION_MAJOR 1
	64	# define CUPS_VERSION_MINOR 2
65	# define CUPS_VERSION_PATCH -10
66	# define CUPS_DATE_ANY -1
67
68
69	/*
70	* Types and structures...
71	*/
72
73	typedef unsigned cups_ptype_t; /** Printer Type/Capability Bits **/
74	enum cups_ptype_e /* Not a typedef'd enum so we can OR */
75	{
76	CUPS_PRINTER_LOCAL = 0x0000, /* Local printer or class */
77	CUPS_PRINTER_CLASS = 0x0001, /* Printer class */
78	CUPS_PRINTER_REMOTE = 0x0002, /* Remote printer or class */
79	CUPS_PRINTER_BW = 0x0004, /* Can do B&W printing */
80	CUPS_PRINTER_COLOR = 0x0008, /* Can do color printing */
81	CUPS_PRINTER_DUPLEX = 0x0010, /* Can do duplexing */
82	CUPS_PRINTER_STAPLE = 0x0020, /* Can staple output */
83	CUPS_PRINTER_COPIES = 0x0040, /* Can do copies */
84	CUPS_PRINTER_COLLATE = 0x0080, /* Can collage copies */
85	CUPS_PRINTER_PUNCH = 0x0100, /* Can punch output */
86	CUPS_PRINTER_COVER = 0x0200, /* Can cover output */
87	CUPS_PRINTER_BIND = 0x0400, /* Can bind output */
88	CUPS_PRINTER_SORT = 0x0800, /* Can sort output */
89	CUPS_PRINTER_SMALL = 0x1000, /* Can do Letter/Legal/A4 */
90	CUPS_PRINTER_MEDIUM = 0x2000, /* Can do Tabloid/B/C/A3/A2 */
91	CUPS_PRINTER_LARGE = 0x4000, /* Can do D/E/A1/A0 */
92	CUPS_PRINTER_VARIABLE = 0x8000, /* Can do variable sizes */
93	CUPS_PRINTER_IMPLICIT = 0x10000, /* Implicit class */
94	CUPS_PRINTER_DEFAULT = 0x20000, /* Default printer on network */
95	CUPS_PRINTER_FAX = 0x40000, /* Fax queue */
96	CUPS_PRINTER_REJECTING = 0x80000, /* Printer is rejecting jobs */
97	CUPS_PRINTER_DELETE = 0x100000, /* Delete printer @since CUPS 1.2@ */
98	CUPS_PRINTER_NOT_SHARED = 0x200000, /* Printer is not shared @since CUPS 1.2@ */
99	CUPS_PRINTER_AUTHENTICATED = 0x400000,/* Printer requires authentication @since CUPS 1.2@ */
100	CUPS_PRINTER_OPTIONS = 0x66fffc /* ~(CLASS \| REMOTE \| IMPLICIT) */
101	};
102
103	typedef const char (cups_password_cb_t)(const char *);
104
105	typedef struct cups_option_s /** Printer Options **/
106	{
107	char name; / Name of option */
108	char value; / Value of option */
109	} cups_option_t;
110
111	typedef struct cups_dest_s /** Destination **/
112	{
113	char name, / Printer or class name */
114	instance; / Local instance name or NULL */
115	int is_default; /* Is this printer the default? */
116	int num_options; /* Number of options */
117	cups_option_t options; / Options */
118	} cups_dest_t;
119
120	typedef struct cups_job_s /** Job **/
121	{
122	int id; /* The job ID */
123	char dest, / Printer or class name */
124	title, / Title/job name */
125	user, / User the submitted the job */
126	format; / Document format */
127	ipp_jstate_t state; /* Job state */
128	int size, /* Size in kilobytes */
129	priority; /* Priority (1-100) */
130	time_t completed_time, /* Time the job was completed */
131	creation_time, /* Time the job was created */
132	processing_time; /* Time the job was processed */
133	} cups_job_t;
134
135
136	/*
137	* Functions...
138	*/
139
140	extern int cupsCancelJob(const char *printer, int job);
141	#define cupsDoRequest(http,request,resource) cupsDoFileRequest((http),(request),(resource),NULL)
142	extern ipp_t cupsDoFileRequest(http_t http, ipp_t *request,
143	const char resource, const char filename);
144	extern http_encryption_t cupsEncryption(void);
145	extern void cupsFreeJobs(int num_jobs, cups_job_t *jobs);
146	extern int cupsGetClasses(char ***classes) _CUPS_DEPRECATED;
147	extern const char *cupsGetDefault(void);
148	extern int cupsGetJobs(cups_job_t *jobs, const char dest,
149	int myjobs, int completed);
150	extern const char cupsGetPPD(const char printer);
151	extern int cupsGetPrinters(char ***printers) _CUPS_DEPRECATED;
152	extern ipp_status_t cupsLastError(void);
153	extern int cupsPrintFile(const char printer, const char filename,
154	const char *title, int num_options,
155	cups_option_t *options);
156	extern int cupsPrintFiles(const char *printer, int num_files,
157	const char *files, const char title,
158	int num_options, cups_option_t *options);
159	extern char cupsTempFile(char filename, int len) _CUPS_DEPRECATED;
160	extern int cupsTempFd(char *filename, int len);
161
162	extern int cupsAddDest(const char name, const char instance,
163	int num_dests, cups_dest_t **dests);
164	extern void cupsFreeDests(int num_dests, cups_dest_t *dests);
165	extern cups_dest_t cupsGetDest(const char name, const char *instance,
166	int num_dests, cups_dest_t *dests);
167	extern int cupsGetDests(cups_dest_t **dests);
168	extern void cupsSetDests(int num_dests, cups_dest_t *dests);
169
170	extern int cupsAddOption(const char name, const char value,
171	int num_options, cups_option_t **options);
172	extern void cupsEncodeOptions(ipp_t *ipp, int num_options,
173	cups_option_t *options);
174	extern void cupsFreeOptions(int num_options, cups_option_t *options);
175	extern const char cupsGetOption(const char name, int num_options,
176	cups_option_t *options);
177	extern int cupsParseOptions(const char *arg, int num_options,
178	cups_option_t **options);
179	extern int cupsMarkOptions(ppd_file_t *ppd, int num_options,
180	cups_option_t *options);
181
182	extern const char cupsGetPassword(const char prompt);
183	extern const char *cupsServer(void);
184	extern void cupsSetEncryption(http_encryption_t e);
185	extern void cupsSetPasswordCB(cups_password_cb_t cb);
186	extern void cupsSetServer(const char *server);
187	extern void cupsSetUser(const char *user);
188	extern const char *cupsUser(void);
189
190	/** New in CUPS 1.1.20 **/
191	extern int cupsDoAuthentication(http_t http, const char method,
192	const char *resource);
193	extern http_status_t cupsGetFile(http_t http, const char resource,
194	const char *filename);
195	extern http_status_t cupsGetFd(http_t http, const char resource, int fd);
196	extern http_status_t cupsPutFile(http_t http, const char resource,
197	const char *filename);
198	extern http_status_t cupsPutFd(http_t http, const char resource, int fd);
199
200	/** New in CUPS 1.1.21 **/
201	extern const char cupsGetDefault2(http_t http);
202	extern int cupsGetDests2(http_t http, cups_dest_t *dests);
203	extern int cupsGetJobs2(http_t http, cups_job_t *jobs,
204	const char *dest, int myjobs,
205	int completed);
206	extern const char cupsGetPPD2(http_t http, const char *printer);
207	extern int cupsPrintFile2(http_t http, const char printer,
208	const char *filename,
209	const char *title, int num_options,
210	cups_option_t *options);
211	extern int cupsPrintFiles2(http_t http, const char printer,
212	int num_files, const char **files,
213	const char *title, int num_options,
214	cups_option_t *options);
215	extern int cupsSetDests2(http_t *http, int num_dests,
216	cups_dest_t *dests);
217
218	/** New in CUPS 1.2 **/
219	extern int cupsBackchannelRead(char *buffer, int bytes, double timeout);
220	extern int cupsBackchannelWrite(const char *buffer, int bytes,
221	double timeout);
222	extern void cupsEncodeOptions2(ipp_t *ipp, int num_options,
223	cups_option_t *options,
224	ipp_tag_t group_tag);
225	extern const char *cupsLastErrorString(void);
226	extern cups_file_t cupsTempFile2(char filename, int len);
227
228
229	# ifdef __cplusplus
230	}
231	# endif /* __cplusplus */
232
233	#endif /* !_CUPS_CUPS_H_ */
234
235	/*
236	* End of "$Id: cups.h 4918 2006-01-12 05:14:40Z mike $".
237	*/