1/*
2 * "$Id: printers.h,v 1.7 2010/08/07 02:30:38 rlk Exp $"
3 *
4 *   libgimpprint printer functions.
5 *
6 *   Copyright 1997-2000 Michael Sweet (mike@easysw.com) and
7 *	Robert Krawitz (rlk@alum.mit.edu)
8 *
9 *   This program is free software; you can redistribute it and/or modify it
10 *   under the terms of the GNU General Public License as published by the Free
11 *   Software Foundation; either version 2 of the License, or (at your option)
12 *   any later version.
13 *
14 *   This program is distributed in the hope that it will be useful, but
15 *   WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
16 *   or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
17 *   for more details.
18 *
19 *   You should have received a copy of the GNU General Public License
20 *   along with this program; if not, write to the Free Software
21 *   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
22 */
23
24/**
25 * @file gutenprint/printers.h
26 * @brief Printer functions.
27 */
28
29#ifndef GUTENPRINT_PRINTERS_H
30#define GUTENPRINT_PRINTERS_H
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
36#include <gutenprint/string-list.h>
37#include <gutenprint/list.h>
38#include <gutenprint/vars.h>
39
40/**
41 * The printer type represents a printer model.  A particular
42 * printer model must selected in order to be able to print.  Each
43 * printer model provides default print options through a default
44 * vars object.
45 *
46 * @defgroup printer printer
47 * @{
48 */
49
50struct stp_printer;
51/** The printer opaque data type (representation of printer model). */
52typedef struct stp_printer stp_printer_t;
53
54/**
55 * Get the number of available printer models.
56 * @returns the number of printer models.
57 */
58extern int stp_printer_model_count(void);
59
60/**
61 * Get a printer model by its index number.
62 * @param idx the index number.  This must not be greater than (total
63 * number of printers - 1).
64 * @returns a pointer to the printer model, or NULL on failure.  The
65 * pointer should not be freed.
66 */
67extern const stp_printer_t *stp_get_printer_by_index(int idx);
68
69/**
70 * Get a printer model by its long (translated) name.
71 * @param long_name the printer model's long (translated) name.
72 * @returns a pointer to the printer model, or NULL on failure.  The
73 * pointer should not be freed.
74 */
75extern const stp_printer_t *stp_get_printer_by_long_name(const char *long_name);
76
77/**
78 * Get a printer model by its short name.
79 * @param driver the printer model's short (driver) name.
80 * @returns a pointer to the printer model, or NULL on failure.  The
81 * pointer should not be freed.
82 */
83extern const stp_printer_t *stp_get_printer_by_driver(const char *driver);
84
85/**
86 * Get a printer model by its IEEE 1284 device ID.
87 * @param device_id the printer model's device ID.
88 * @returns a pointer to the printer model, or NULL on failure.  The
89 * pointer should not be freed.
90 */
91extern const stp_printer_t *stp_get_printer_by_device_id(const char *device_id);
92
93/**
94 * Get a printer model by its foomatic ID.
95 * @param foomatic_id the printer model's foomatic ID
96 * @returns a pointer to the printer model, or NULL on failure.  The
97 * pointer should not be freed.
98 */
99extern const stp_printer_t *stp_get_printer_by_foomatic_id(const char *foomatic_id);
100
101/**
102 * Get the printer model from a vars object.
103 * @param v the vars to use.
104 * @returns a pointer to the printer model, or NULL on failure.  The
105 * pointer should not be freed.
106 */
107extern const stp_printer_t *stp_get_printer(const stp_vars_t *v);
108
109/**
110 * Get the printer index number from the printer model short (driver) name.
111 * @deprecated There should never be any need to use this function.
112 * @param driver the printer model's short (driver) name.
113 * @returns the index number, or -1 on failure.
114 */
115extern int stp_get_printer_index_by_driver(const char *driver);
116
117/**
118 * Get a printer model's long (translated) name.
119 * @param p the printer model to use.
120 * @returns the long name (should never be freed).
121 */
122extern const char *stp_printer_get_long_name(const stp_printer_t * p);
123
124/**
125 * Get a printer model's short (driver) name.
126 * @param p the printer model to use.
127 * @returns the short name (should never be freed).
128 */
129extern const char *stp_printer_get_driver(const stp_printer_t *p);
130
131/**
132 * Get a printer model's IEEE 1284 device ID, if known.
133 * @param p the printer model to use.
134 * @returns the IEEE 1284 device ID, or NULL if not known.
135 */
136extern const char *stp_printer_get_device_id(const stp_printer_t *p);
137
138/**
139 * Get a printer model's family name.
140 * The family name is the name of the modular "family" driver this
141 * model uses.
142 * @param p the printer model to use.
143 * @returns the family name (should never be freed).
144 */
145extern const char *stp_printer_get_family(const stp_printer_t *p);
146
147/**
148 * Get a printer model's manufacturer's name.
149 * @param p the printer model to use.
150 * @returns the manufacturer's name (should never be freed).
151 */
152extern const char *stp_printer_get_manufacturer(const stp_printer_t *p);
153
154/**
155 * Get a printer model's foomatic ID
156 * @param p the printer model to use.
157 * @returns the foomatic ID or NULL (should never be freed)
158 */
159extern const char *stp_printer_get_foomatic_id(const stp_printer_t *p);
160
161/**
162 * Get a printer model's model number.
163 * The model number is used internally by the "family" driver module,
164 * and has no meaning out of that context.  It bears no relation to
165 * the model name/number actually found on the printer itself.
166 * @param p the printer model to use.
167 * @returns the model number.
168 */
169extern int stp_printer_get_model(const stp_printer_t *p);
170
171/**
172 * Get the default vars for a particular printer model.
173 * The default vars should be copied to a new vars object and
174 * customised prior to printing.
175 * @param p the printer model to use.
176 * @returns the printer model's default vars.
177 */
178extern const stp_vars_t *stp_printer_get_defaults(const stp_printer_t *p);
179
180/**
181 * Set a vars object to use a particular driver, and set the parameters
182 * to their defaults.
183 * @param v the vars to use.
184 * @param p the printer model to use.
185 */
186extern void stp_set_printer_defaults(stp_vars_t *v, const stp_printer_t *p);
187
188/**
189 * Set a vars object to use a particular driver, and set any unset parameters
190 * to their defaults.
191 * @param v the vars to use.
192 * @param p the printer model to use.
193 */
194extern void stp_set_printer_defaults_soft(stp_vars_t *v, const stp_printer_t *p);
195
196
197/**
198 * Print the image.
199 * @warning stp_job_start() must be called prior to the first call to
200 * this function.
201 * @param v the vars to use.
202 * @param image the image to print.
203 * @returns 0 on failure, 1 on success, 2 on abort requested by the
204 * driver.
205 */
206extern int stp_print(const stp_vars_t *v, stp_image_t *image);
207
208/**
209 * Start a print job.
210 * @warning This function must be called prior to the first call to
211 * stp_print().
212 * @param v the vars to use.
213 * @param image the image to print.
214 * @returns 1 on success, 0 on failure.
215 */
216extern int stp_start_job(const stp_vars_t *v, stp_image_t *image);
217
218/**
219 * End a print job.
220 * @param v the vars to use.
221 * @param image the image to print.
222 * @returns 1 on success, 0 on failure.
223 */
224extern int stp_end_job(const stp_vars_t *v, stp_image_t *image);
225
226/**
227 * Retrieve options that need to be passed to the underlying print
228 * system.
229 * @param v the vars to use.
230 * @returns list of options in a string list ('name' is the name
231 * of the option; 'text' is the value it takes on).  NULL return means
232 * no external options are required.  User must stp_string_list_destroy
233 * the list after use.
234 */
235extern stp_string_list_t *stp_get_external_options(const stp_vars_t *v);
236
237typedef struct
238{
239  stp_parameter_list_t (*list_parameters)(const stp_vars_t *v);
240  void  (*parameters)(const stp_vars_t *v, const char *name,
241		      stp_parameter_t *);
242  void  (*media_size)(const stp_vars_t *v, int *width, int *height);
243  void  (*imageable_area)(const stp_vars_t *v,
244			  int *left, int *right, int *bottom, int *top);
245  void  (*maximum_imageable_area)(const stp_vars_t *v, int *left, int *right,
246				  int *bottom, int *top);
247  void  (*limit)(const stp_vars_t *v, int *max_width, int *max_height,
248                 int *min_width, int *min_height);
249  int   (*print)(const stp_vars_t *v, stp_image_t *image);
250  void  (*describe_resolution)(const stp_vars_t *v, int *x, int *y);
251  const char *(*describe_output)(const stp_vars_t *v);
252  int   (*verify)(stp_vars_t *v);
253  int   (*start_job)(const stp_vars_t *v, stp_image_t *image);
254  int   (*end_job)(const stp_vars_t *v, stp_image_t *image);
255  stp_string_list_t *(*get_external_options)(const stp_vars_t *v);
256} stp_printfuncs_t;
257
258typedef struct stp_family
259{
260  const stp_printfuncs_t *printfuncs;   /* printfuncs for the printer */
261  stp_list_t             *printer_list; /* list of printers */
262} stp_family_t;
263
264extern int stp_get_model_id(const stp_vars_t *v);
265
266extern int stp_verify_printer_params(stp_vars_t *v);
267
268extern int stp_family_register(stp_list_t *family);
269extern int stp_family_unregister(stp_list_t *family);
270extern void stp_initialize_printer_defaults(void);
271
272extern stp_parameter_list_t stp_printer_list_parameters(const stp_vars_t *v);
273
274extern void
275stp_printer_describe_parameter(const stp_vars_t *v, const char *name,
276			       stp_parameter_t *description);
277
278const char *stp_describe_output(const stp_vars_t *v);
279
280/** @} */
281
282#ifdef __cplusplus
283  }
284#endif
285
286#endif /* GUTENPRINT_PRINTERS_H */
287/*
288 * End of "$Id: printers.h,v 1.7 2010/08/07 02:30:38 rlk Exp $".
289 */
290