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