summaryrefslogtreecommitdiff
path: root/include/gutenprint/printers.h
blob: 2739c1d2b7d954b58b01e1127e35b8df1fb581bc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
/*
 * "$Id: printers.h,v 1.7 2010/08/07 02:30:38 rlk Exp $"
 *
 *   libgimpprint printer functions.
 *
 *   Copyright 1997-2000 Michael Sweet (mike@easysw.com) and
 *	Robert Krawitz (rlk@alum.mit.edu)
 *
 *   This program is free software; you can redistribute it and/or modify it
 *   under the terms of the GNU General Public License as published by the Free
 *   Software Foundation; either version 2 of the License, or (at your option)
 *   any later version.
 *
 *   This program is distributed in the hope that it will be useful, but
 *   WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 *   or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 *   for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program; if not, write to the Free Software
 *   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/**
 * @file gutenprint/printers.h
 * @brief Printer functions.
 */

#ifndef GUTENPRINT_PRINTERS_H
#define GUTENPRINT_PRINTERS_H

#ifdef __cplusplus
extern "C" {
#endif

#include <gutenprint/string-list.h>
#include <gutenprint/list.h>
#include <gutenprint/vars.h>

/**
 * The printer type represents a printer model.  A particular
 * printer model must selected in order to be able to print.  Each
 * printer model provides default print options through a default
 * vars object.
 *
 * @defgroup printer printer
 * @{
 */

struct stp_printer;
/** The printer opaque data type (representation of printer model). */
typedef struct stp_printer stp_printer_t;

/**
 * Get the number of available printer models.
 * @returns the number of printer models.
 */
extern int stp_printer_model_count(void);

/**
 * Get a printer model by its index number.
 * @param idx the index number.  This must not be greater than (total
 * number of printers - 1).
 * @returns a pointer to the printer model, or NULL on failure.  The
 * pointer should not be freed.
 */
extern const stp_printer_t *stp_get_printer_by_index(int idx);

/**
 * Get a printer model by its long (translated) name.
 * @param long_name the printer model's long (translated) name.
 * @returns a pointer to the printer model, or NULL on failure.  The
 * pointer should not be freed.
 */
extern const stp_printer_t *stp_get_printer_by_long_name(const char *long_name);

/**
 * Get a printer model by its short name.
 * @param driver the printer model's short (driver) name.
 * @returns a pointer to the printer model, or NULL on failure.  The
 * pointer should not be freed.
 */
extern const stp_printer_t *stp_get_printer_by_driver(const char *driver);

/**
 * Get a printer model by its IEEE 1284 device ID.
 * @param device_id the printer model's device ID.
 * @returns a pointer to the printer model, or NULL on failure.  The
 * pointer should not be freed.
 */
extern const stp_printer_t *stp_get_printer_by_device_id(const char *device_id);

/**
 * Get a printer model by its foomatic ID.
 * @param foomatic_id the printer model's foomatic ID
 * @returns a pointer to the printer model, or NULL on failure.  The
 * pointer should not be freed.
 */
extern const stp_printer_t *stp_get_printer_by_foomatic_id(const char *foomatic_id);

/**
 * Get the printer model from a vars object.
 * @param v the vars to use.
 * @returns a pointer to the printer model, or NULL on failure.  The
 * pointer should not be freed.
 */
extern const stp_printer_t *stp_get_printer(const stp_vars_t *v);

/**
 * Get the printer index number from the printer model short (driver) name.
 * @deprecated There should never be any need to use this function.
 * @param driver the printer model's short (driver) name.
 * @returns the index number, or -1 on failure.
 */
extern int stp_get_printer_index_by_driver(const char *driver);

/**
 * Get a printer model's long (translated) name.
 * @param p the printer model to use.
 * @returns the long name (should never be freed).
 */
extern const char *stp_printer_get_long_name(const stp_printer_t * p);

/**
 * Get a printer model's short (driver) name.
 * @param p the printer model to use.
 * @returns the short name (should never be freed).
 */
extern const char *stp_printer_get_driver(const stp_printer_t *p);

/**
 * Get a printer model's IEEE 1284 device ID, if known.
 * @param p the printer model to use.
 * @returns the IEEE 1284 device ID, or NULL if not known.
 */
extern const char *stp_printer_get_device_id(const stp_printer_t *p);

/**
 * Get a printer model's family name.
 * The family name is the name of the modular "family" driver this
 * model uses.
 * @param p the printer model to use.
 * @returns the family name (should never be freed).
 */
extern const char *stp_printer_get_family(const stp_printer_t *p);

/**
 * Get a printer model's manufacturer's name.
 * @param p the printer model to use.
 * @returns the manufacturer's name (should never be freed).
 */
extern const char *stp_printer_get_manufacturer(const stp_printer_t *p);

/**
 * Get a printer model's foomatic ID
 * @param p the printer model to use.
 * @returns the foomatic ID or NULL (should never be freed)
 */
extern const char *stp_printer_get_foomatic_id(const stp_printer_t *p);

/**
 * Get a printer model's model number.
 * The model number is used internally by the "family" driver module,
 * and has no meaning out of that context.  It bears no relation to
 * the model name/number actually found on the printer itself.
 * @param p the printer model to use.
 * @returns the model number.
 */
extern int stp_printer_get_model(const stp_printer_t *p);

/**
 * Get the default vars for a particular printer model.
 * The default vars should be copied to a new vars object and
 * customised prior to printing.
 * @param p the printer model to use.
 * @returns the printer model's default vars.
 */
extern const stp_vars_t *stp_printer_get_defaults(const stp_printer_t *p);

/**
 * Set a vars object to use a particular driver, and set the parameters
 * to their defaults.
 * @param v the vars to use.
 * @param p the printer model to use.
 */
extern void stp_set_printer_defaults(stp_vars_t *v, const stp_printer_t *p);

/**
 * Set a vars object to use a particular driver, and set any unset parameters
 * to their defaults.
 * @param v the vars to use.
 * @param p the printer model to use.
 */
extern void stp_set_printer_defaults_soft(stp_vars_t *v, const stp_printer_t *p);


/**
 * Print the image.
 * @warning stp_job_start() must be called prior to the first call to
 * this function.
 * @param v the vars to use.
 * @param image the image to print.
 * @returns 0 on failure, 1 on success, 2 on abort requested by the
 * driver.
 */
extern int stp_print(const stp_vars_t *v, stp_image_t *image);

/**
 * Start a print job.
 * @warning This function must be called prior to the first call to
 * stp_print().
 * @param v the vars to use.
 * @param image the image to print.
 * @returns 1 on success, 0 on failure.
 */
extern int stp_start_job(const stp_vars_t *v, stp_image_t *image);

/**
 * End a print job.
 * @param v the vars to use.
 * @param image the image to print.
 * @returns 1 on success, 0 on failure.
 */
extern int stp_end_job(const stp_vars_t *v, stp_image_t *image);

/**
 * Retrieve options that need to be passed to the underlying print
 * system.
 * @param v the vars to use.
 * @returns list of options in a string list ('name' is the name
 * of the option; 'text' is the value it takes on).  NULL return means
 * no external options are required.  User must stp_string_list_destroy
 * the list after use.
 */
extern stp_string_list_t *stp_get_external_options(const stp_vars_t *v);

typedef struct
{
  stp_parameter_list_t (*list_parameters)(const stp_vars_t *v);
  void  (*parameters)(const stp_vars_t *v, const char *name,
		      stp_parameter_t *);
  void  (*media_size)(const stp_vars_t *v, int *width, int *height);
  void  (*imageable_area)(const stp_vars_t *v,
			  int *left, int *right, int *bottom, int *top);
  void  (*maximum_imageable_area)(const stp_vars_t *v, int *left, int *right,
				  int *bottom, int *top);
  void  (*limit)(const stp_vars_t *v, int *max_width, int *max_height,
                 int *min_width, int *min_height);
  int   (*print)(const stp_vars_t *v, stp_image_t *image);
  void  (*describe_resolution)(const stp_vars_t *v, int *x, int *y);
  const char *(*describe_output)(const stp_vars_t *v);
  int   (*verify)(stp_vars_t *v);
  int   (*start_job)(const stp_vars_t *v, stp_image_t *image);
  int   (*end_job)(const stp_vars_t *v, stp_image_t *image);
  stp_string_list_t *(*get_external_options)(const stp_vars_t *v);
} stp_printfuncs_t;

typedef struct stp_family
{
  const stp_printfuncs_t *printfuncs;   /* printfuncs for the printer */
  stp_list_t             *printer_list; /* list of printers */
} stp_family_t;

extern int stp_get_model_id(const stp_vars_t *v);

extern int stp_verify_printer_params(stp_vars_t *v);

extern int stp_family_register(stp_list_t *family);
extern int stp_family_unregister(stp_list_t *family);
extern void stp_initialize_printer_defaults(void);

extern stp_parameter_list_t stp_printer_list_parameters(const stp_vars_t *v);

extern void
stp_printer_describe_parameter(const stp_vars_t *v, const char *name,
			       stp_parameter_t *description);

const char *stp_describe_output(const stp_vars_t *v);

/** @} */

#ifdef __cplusplus
  }
#endif

#endif /* GUTENPRINT_PRINTERS_H */
/*
 * End of "$Id: printers.h,v 1.7 2010/08/07 02:30:38 rlk Exp $".
 */