1 /* 2 * libgimpprint stp_vars_t core functions. 3 * 4 * Copyright 1997-2000 Michael Sweet (mike@easysw.com) and 5 * Robert Krawitz (rlk@alum.mit.edu) 6 * 7 * This program is free software; you can redistribute it and/or modify it 8 * under the terms of the GNU General Public License as published by the Free 9 * Software Foundation; either version 2 of the License, or (at your option) 10 * any later version. 11 * 12 * This program is distributed in the hope that it will be useful, but 13 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 14 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * for more details. 16 * 17 * You should have received a copy of the GNU General Public License 18 * along with this program. If not, see <https://www.gnu.org/licenses/>. 19 */ 20 21 /** 22 * @file gutenprint/vars.h 23 * @brief Print job functions. 24 */ 25 26 #ifndef GUTENPRINT_VARS_H 27 #define GUTENPRINT_VARS_H 28 29 #include <gutenprint/types.h> 30 #include <gutenprint/array.h> 31 #include <gutenprint/curve.h> 32 #include <gutenprint/string-list.h> 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** 39 * The vars data type contains all the information about a print job, 40 * this includes information such as the printer model, paper size, 41 * print resolution etc. Most of these job options are expressed as 42 * parameters which vary according to the model and other options 43 * selected. 44 * 45 * The representation of printer settings has changed dramatically from 4.2. 46 * All (well most, anyway) settings outside of basics such as the printer 47 * model and sizing settings are now typed parameters. 48 * 49 * @defgroup vars vars 50 * @{ 51 */ 52 53 struct stp_vars; 54 /** The vars opaque data type. */ 55 typedef struct stp_vars stp_vars_t; 56 57 /** 58 * Parameter types. 59 * The following types are permitted for a printer setting. Not all 60 * are currently implemented. 61 */ 62 typedef enum 63 { 64 STP_PARAMETER_TYPE_STRING_LIST, /*!< Single string choice from a list. */ 65 STP_PARAMETER_TYPE_INT, /*!< Integer. */ 66 STP_PARAMETER_TYPE_BOOLEAN, /*!< Boolean. */ 67 STP_PARAMETER_TYPE_DOUBLE, /*!< Floating point number. */ 68 STP_PARAMETER_TYPE_CURVE, /*!< Curve. */ 69 STP_PARAMETER_TYPE_FILE, /*!< Filename (NYI, need to consider security). */ 70 STP_PARAMETER_TYPE_RAW, /*!< Raw, opaque data. */ 71 STP_PARAMETER_TYPE_ARRAY, /*!< Array. */ 72 STP_PARAMETER_TYPE_DIMENSION, /*!< Linear dimension. */ 73 STP_PARAMETER_TYPE_INVALID /*!< Invalid type (should never be used). */ 74 } stp_parameter_type_t; 75 76 /** 77 * Parameter class. 78 * What kind of setting this is, for the purpose of user interface 79 * representation. 80 */ 81 typedef enum 82 { 83 STP_PARAMETER_CLASS_FEATURE, /*!< Printer feature. */ 84 STP_PARAMETER_CLASS_OUTPUT, /*!< Output control. */ 85 STP_PARAMETER_CLASS_CORE, /*!< Core Gimp-Print parameter. */ 86 STP_PARAMETER_CLASS_INVALID /*!< Invalid class (should never be used). */ 87 } stp_parameter_class_t; 88 89 /** 90 * Parameter level. 91 * What "level" a setting is at, for UI design. 92 */ 93 typedef enum 94 { 95 STP_PARAMETER_LEVEL_BASIC, /*!< Basic parameter, shown by all UIs. */ 96 STP_PARAMETER_LEVEL_ADVANCED, /*!< Advanced parameter, shown by advanced UIs. */ 97 STP_PARAMETER_LEVEL_ADVANCED1, /*!< Advanced1 parameter, shown by advanced UIs. */ 98 STP_PARAMETER_LEVEL_ADVANCED2, /*!< Advanced2 parameter, shown by advanced UIs. */ 99 STP_PARAMETER_LEVEL_ADVANCED3, /*!< Advanced3 parameter, shown by advanced UIs. */ 100 STP_PARAMETER_LEVEL_ADVANCED4, /*!< Advanced4 parameter, shown by advanced UIs. */ 101 STP_PARAMETER_LEVEL_INTERNAL, /*!< Parameters used only within Gimp-Print. */ 102 STP_PARAMETER_LEVEL_EXTERNAL, /*!< Parameters used only outside Gimp-Print. */ 103 STP_PARAMETER_LEVEL_INVALID /*!< Invalid level (should never be used). */ 104 } stp_parameter_level_t; 105 106 /** 107 * Parameter activity. 108 * Whether a parameter is currently active (i. e. whether its value 109 * should be used by the driver or not). All parameters default to being 110 * active unless explicitly "turned off". 111 */ 112 typedef enum 113 { 114 STP_PARAMETER_INACTIVE, /*!< Parameter is inactive (unused). */ 115 STP_PARAMETER_DEFAULTED, /*!< Parameter is set to its default value. */ 116 STP_PARAMETER_ACTIVE /*!< Parameter is active (used). */ 117 } stp_parameter_activity_t; 118 119 /* 120 * Other parameter types 121 */ 122 123 /** Raw parameter. */ 124 typedef struct 125 { 126 size_t bytes; /*!< Size of data. */ 127 const void *data; /*!< Raw data. */ 128 } stp_raw_t; 129 130 #define STP_RAW(x) { sizeof((x)), (x) } 131 #define STP_RAW_STRING(x) { sizeof((x)) - 1, (x) } 132 133 /** double_bound (range) parameter. */ 134 typedef struct 135 { 136 double lower; /*!< Lower bound. */ 137 double upper; /*!< Upper bound. */ 138 } stp_double_bound_t; 139 140 /** int_bound (range) parameter. */ 141 typedef struct 142 { 143 int lower; /*!< Lower bound. */ 144 int upper; /*!< Upper bound. */ 145 } stp_int_bound_t; 146 147 /** dimension_bound (range) parameter. */ 148 typedef struct 149 { 150 stp_dimension_t lower; /*!< Lower bound. */ 151 stp_dimension_t upper; /*!< Upper bound. */ 152 } stp_dimension_bound_t; 153 154 #define STP_CHANNEL_NONE ((unsigned char) -1) 155 156 /** Parameter description. */ 157 typedef struct 158 { 159 const char *name; /*!< Internal name (key). */ 160 const char *text; /*!< User-visible name. */ 161 const char *category; /*!< User-visible category name. */ 162 const char *help; /*!< Help string. */ 163 stp_parameter_type_t p_type; /*!< Parameter type. */ 164 stp_parameter_class_t p_class; /*!< Parameter class. */ 165 stp_parameter_level_t p_level; /*!< Parameter level. */ 166 unsigned char is_mandatory; /*!< The parameter is required, even when set inactive. */ 167 unsigned char is_active; /*!< Is the parameter active? */ 168 unsigned char channel; /*!< The channel to which this parameter applies */ 169 unsigned char verify_this_parameter; /*!< Should the verify system check this parameter? */ 170 unsigned char read_only; 171 union 172 { 173 stp_curve_t *curve; /*!< curve parameter value. */ 174 stp_double_bound_t dbl; /*!< double_bound parameter value. */ 175 stp_int_bound_t integer; /*!< int_bound parameter value. */ 176 stp_dimension_bound_t dimension; /*!< dimension_bound parameter value. */ 177 stp_string_list_t *str; /*!< string_list parameter value. */ 178 stp_array_t *array; /*!< array parameter value. */ 179 } bounds; /*!< Limits on the values the parameter may take. */ 180 union 181 { 182 stp_curve_t *curve; /*!< Default curve parameter value. */ 183 double dbl; /*!< Default double parameter value. */ 184 stp_dimension_t dimension; /*!< Default dimension parameter value. */ 185 int integer; /*!< Default int parameter value. */ 186 int boolean; /*!< Default boolean parameter value. */ 187 const char *str; /*!< Default string parameter value. */ 188 stp_array_t *array; /*!< Default array parameter value. */ 189 } deflt; /*!< Default value of the parameter. */ 190 } stp_parameter_t; 191 192 /** The parameter_list opaque data type. */ 193 typedef void *stp_parameter_list_t; 194 /** The constant parameter_list opaque data type. */ 195 typedef const void *stp_const_parameter_list_t; 196 197 /** 198 * Output function supplied by the calling application. 199 * There are two output functions supplied by the caller, one to send 200 * output data and one to report errors. 201 * @param data a pointer to an opaque object owned by the calling 202 * application. 203 * @param buffer the data to output. 204 * @param bytes the size of buffer (in bytes). 205 */ 206 typedef void (*stp_outfunc_t) (void *data, const char *buffer, size_t bytes); 207 208 /** 209 * Print an stp_vars_t in debugging format. 210 * @param v stp_vars_t to dump 211 * @param prefix Prefix to prepend to each line (null pointer gives 212 * empty prefix) 213 */ 214 extern void stp_vars_print_error(const stp_vars_t *v, const char *prefix); 215 216 /**************************************************************** 217 * * 218 * BASIC PRINTER SETTINGS * 219 * * 220 ****************************************************************/ 221 222 /** 223 * Create a new vars object. 224 * @returns the newly created vars object. 225 */ 226 extern stp_vars_t *stp_vars_create(void); 227 228 /** 229 * Copy a vars object. 230 * Both dest and source must be valid vars objects previously 231 * created with stp_vars_create(). 232 * @param dest the destination vars. 233 * @param source the source vars. 234 */ 235 extern void stp_vars_copy(stp_vars_t *dest, const stp_vars_t *source); 236 237 /** 238 * Copy and allocate a vars object. 239 * source must be a valid vars object previously created with 240 * stp_vars_create(). 241 * @param source the source vars. 242 * @returns the new copy of the vars. 243 */ 244 extern stp_vars_t *stp_vars_create_copy(const stp_vars_t *source); 245 246 /** 247 * Destroy a vars object. 248 * It is an error to destroy the vars more than once. 249 * @param v the vars to destroy. 250 */ 251 extern void stp_vars_destroy(stp_vars_t *v); 252 253 /** 254 * Set the name of the printer driver. 255 * @param v the vars to use. 256 * @param val the name to set. 257 */ 258 extern void stp_set_driver(stp_vars_t *v, const char *val); 259 260 /** 261 * Set the name of the printer driver. 262 * @param v the vars to use. 263 * @param val the name to set. 264 * @param bytes the length of val (in bytes). 265 */ 266 extern void stp_set_driver_n(stp_vars_t *v, const char *val, int bytes); 267 268 /** 269 * Get the name of the printer driver. 270 * @returns the name of the printer driver (must not be freed). 271 */ 272 extern const char *stp_get_driver(const stp_vars_t *v); 273 274 /** 275 * Set the name of the color conversion routine, if not the default. 276 * @param v the vars to use. 277 * @param val the name to set. 278 */ 279 extern void stp_set_color_conversion(stp_vars_t *v, const char *val); 280 281 /** 282 * Set the name of the color conversion routine, if not the default. 283 * @param v the vars to use. 284 * @param val the name to set. 285 * @param bytes the length of val (in bytes). 286 */ 287 extern void stp_set_color_conversion_n(stp_vars_t *v, const char *val, int bytes); 288 289 /** 290 * Get the name of the color conversion routine. 291 * @returns the name of the color conversion routine (must not be freed). 292 */ 293 extern const char *stp_get_color_conversion(const stp_vars_t *v); 294 295 /* 296 * Set/get the position and size of the image 297 */ 298 299 /** 300 * Set the left edge of the image. 301 * @param v the vars to use. 302 * @param val the value to set. 303 */ 304 extern void stp_set_left(stp_vars_t *v, stp_dimension_t val); 305 306 /** 307 * Get the left edge of the image. 308 * @returns the left edge. 309 */ 310 extern stp_dimension_t stp_get_left(const stp_vars_t *v); 311 312 /** 313 * Set the top edge of the image. 314 * @param v the vars to use. 315 * @param val the value to set. 316 */ 317 extern void stp_set_top(stp_vars_t *v, stp_dimension_t val); 318 319 /** 320 * Get the top edge of the image. 321 * @returns the left edge. 322 */ 323 extern stp_dimension_t stp_get_top(const stp_vars_t *v); 324 325 /** 326 * Set the width of the image. 327 * @param v the vars to use. 328 * @param val the value to set. 329 */ 330 extern void stp_set_width(stp_vars_t *v, stp_dimension_t val); 331 332 /** 333 * Get the width edge of the image. 334 * @returns the left edge. 335 */ 336 extern stp_dimension_t stp_get_width(const stp_vars_t *v); 337 338 /** 339 * Set the height of the image. 340 * @param v the vars to use. 341 * @param val the value to set. 342 */ 343 extern void stp_set_height(stp_vars_t *v, stp_dimension_t val); 344 345 /** 346 * Get the height of the image. 347 * @returns the left edge. 348 */ 349 extern stp_dimension_t stp_get_height(const stp_vars_t *v); 350 351 /* 352 * For custom page widths, these functions may be used. 353 */ 354 355 /** 356 * Set the page width. 357 * @param v the vars to use. 358 * @param val the value to set. 359 */ 360 extern void stp_set_page_width(stp_vars_t *v, stp_dimension_t val); 361 362 /** 363 * Get the page width. 364 * @returns the page width. 365 */ 366 extern stp_dimension_t stp_get_page_width(const stp_vars_t *v); 367 368 /** 369 * Set the page height. 370 * @param v the vars to use. 371 * @param val the value to set. 372 */ 373 extern void stp_set_page_height(stp_vars_t *v, stp_dimension_t val); 374 375 /** 376 * Get the page height. 377 * @returns the page height. 378 */ 379 extern stp_dimension_t stp_get_page_height(const stp_vars_t *v); 380 381 /** 382 * Set the function used to print output information. 383 * These must be supplied by the caller. outdata is passed as an 384 * arguments to outfunc; typically it will be a file descriptor. 385 * @param v the vars to use. 386 * @param val the value to set. 387 */ 388 extern void stp_set_outfunc(stp_vars_t *v, stp_outfunc_t val); 389 390 /** 391 * Get the function used to print output information. 392 * @param v the vars to use. 393 * @returns the outfunc. 394 */ 395 extern stp_outfunc_t stp_get_outfunc(const stp_vars_t *v); 396 397 /** 398 * Set the function used to print error information. 399 * These must be supplied by the caller. errdata is passed as an 400 * arguments to errfunc; typically it will be a file descriptor. 401 * @param v the vars to use. 402 * @param val the value to set. 403 */ 404 extern void stp_set_errfunc(stp_vars_t *v, stp_outfunc_t val); 405 406 /** 407 * Get the function used to print output information. 408 * @param v the vars to use. 409 * @returns the outfunc. 410 */ 411 extern stp_outfunc_t stp_get_errfunc(const stp_vars_t *v); 412 413 /** 414 * Set the function used to print diagnostic information. 415 * These must be supplied by the caller. dbgdata is passed as an 416 * arguments to dbgfunc; typically it will be a file descriptor. 417 * @param v the vars to use. 418 * @param val the value to set. 419 */ 420 extern void stp_set_dbgfunc(stp_vars_t *v, stp_outfunc_t val); 421 422 /** 423 * Get the function used to print output information. 424 * @param v the vars to use. 425 * @returns the outfunc. 426 */ 427 extern stp_outfunc_t stp_get_dbgfunc(const stp_vars_t *v); 428 429 /** 430 * Set the output data. 431 * @param v the vars to use. 432 * @param val the output data. This will typically be a file 433 * descriptor, but it is entirely up to the caller exactly what type 434 * this might be. 435 */ 436 extern void stp_set_outdata(stp_vars_t *v, void *val); 437 438 /** 439 * Get the output data. 440 * @param v the vars to use. 441 * @returns the output data. 442 */ 443 extern void *stp_get_outdata(const stp_vars_t *v); 444 445 /** 446 * Set the error data. 447 * @param v the vars to use. 448 * @param val the error data. This will typically be a file 449 * descriptor, but it is entirely up to the caller exactly what type 450 * this might be. 451 */ 452 extern void stp_set_errdata(stp_vars_t *v, void *val); 453 454 /** 455 * Get the error data. 456 * @param v the vars to use. 457 * @returns the output data. 458 */ 459 extern void *stp_get_errdata(const stp_vars_t *v); 460 461 /** 462 * Set the debug output data. 463 * @param v the vars to use. 464 * @param val the debug data. This will typically be a file 465 * descriptor, but it is entirely up to the caller exactly what type 466 * this might be. 467 */ 468 extern void stp_set_dbgdata(stp_vars_t *v, void *val); 469 470 /** 471 * Get the debug output data. 472 * @param v the vars to use. 473 * @returns the output data. 474 */ 475 extern void *stp_get_dbgdata(const stp_vars_t *v); 476 477 /** 478 * Merge defaults for a printer with user-chosen settings. 479 * @deprecated This is likely to go away. 480 * @param user the destination vars. 481 * @param print the vars to merge into user. 482 */ 483 extern void stp_merge_printvars(stp_vars_t *user, const stp_vars_t *print); 484 485 /** 486 * Copy settings from one vars object to another, not modifying anything 487 * unset in the source. 488 * @param to the destination vars. 489 * @param from the vars to merge into user. 490 */ 491 extern void stp_copy_vars_from(stp_vars_t *to, const stp_vars_t *from); 492 493 494 /**************************************************************** 495 * * 496 * PARAMETER MANAGEMENT * 497 * * 498 ****************************************************************/ 499 500 /** 501 * List the available parameters for the currently chosen settings. 502 * This does not fill in the bounds and defaults; it merely provides 503 * a list of settings. To fill in detailed information for a setting, 504 * use stp_describe_parameter. 505 * @param v the vars to use. 506 * @returns a list of available parameters (must be freed with 507 * stp_parameter_list_destroy()). 508 */ 509 extern stp_parameter_list_t stp_get_parameter_list(const stp_vars_t *v); 510 511 /** 512 * List the number of available parameters for the currently chosen 513 * settings. 514 * @param list the parameter_list to use. 515 * @returns the number of parameters. 516 */ 517 extern size_t stp_parameter_list_count(stp_const_parameter_list_t list); 518 519 /** 520 * Find a parameter by its name. 521 * @param list the parameter_list to use. 522 * @param name the name of the parameter. 523 * @returns a pointer to the parameter (must not be freed), or NULL if 524 * no parameter was found. 525 */ 526 extern const stp_parameter_t * 527 stp_parameter_find(stp_const_parameter_list_t list, const char *name); 528 529 /** 530 * Find a parameter by its index number. 531 * @param list the parameter_list to use. 532 * @param item the index number of the parameter (must not be greater 533 * than stp_parameter_list_count - 1). 534 * @returns a pointer to the parameter (must not be freed), or NULL if 535 * no parameter was found. 536 */ 537 extern const stp_parameter_t * 538 stp_parameter_list_param(stp_const_parameter_list_t list, size_t item); 539 540 /** 541 * Destroy a parameter_list. 542 * It is an error to destroy the parameter_list more than once. 543 * @param list the parameter_list to destroy. 544 */ 545 extern void stp_parameter_list_destroy(stp_parameter_list_t list); 546 547 /** 548 * Create a parameter_list. 549 * @returns the newly created parameter_list. 550 */ 551 extern stp_parameter_list_t stp_parameter_list_create(void); 552 553 /** 554 * Add a parameter to a parameter_list. 555 * @param list the parameter_list to use. 556 * @param item the parameter to add. 557 */ 558 extern void stp_parameter_list_add_param(stp_parameter_list_t list, 559 const stp_parameter_t *item); 560 561 /** 562 * Copy and allocate a parameter_list. 563 * A new parameter_list will be created, and then the contents of 564 * source will be 565 * copied into it. 566 * @param list the source parameter_list. 567 * @returns the new copy of the parameter_list. 568 */ 569 extern stp_parameter_list_t 570 stp_parameter_list_copy(stp_const_parameter_list_t list); 571 572 /** 573 * Append one parameter_list to another. 574 * @param list the destination list (to append to). 575 * @param append the list of parameters to append. Each item that does 576 * not already exist in list will be appended. 577 */ 578 extern void 579 stp_parameter_list_append(stp_parameter_list_t list, 580 stp_const_parameter_list_t append); 581 582 /** 583 * Describe a parameter in detail. 584 * All of the parameter fields will be populated. 585 * @param v the vars to use. 586 * @param name the name of the parameter. 587 * @param description a pointer to an stp_parameter_t to store the 588 * parameter description in. 589 */ 590 extern void 591 stp_describe_parameter(const stp_vars_t *v, const char *name, 592 stp_parameter_t *description); 593 594 /** 595 * Destroy a parameter description. 596 * This must be called even if the stp_parameter_t was not allocated 597 * with malloc, since some members are dynamically allocated. 598 * @param description the parameter description to destroy. 599 */ 600 extern void stp_parameter_description_destroy(stp_parameter_t *description); 601 602 /** 603 * Find a parameter by its name from a vars object. 604 * @param v the vars to use. 605 * @param name the name of the parameter. 606 * @returns a pointer to the parameter (must not be freed), or NULL if 607 * no parameter was found. 608 */ 609 extern const stp_parameter_t * 610 stp_parameter_find_in_settings(const stp_vars_t *v, const char *name); 611 612 /** 613 * Set a string parameter. 614 * @param v the vars to use. 615 * @param parameter the name of the parameter. 616 * @param value the value to set. 617 */ 618 extern void stp_set_string_parameter(stp_vars_t *v, const char *parameter, 619 const char *value); 620 621 /** 622 * Set a string parameter. 623 * @param v the vars to use. 624 * @param parameter the name of the parameter. 625 * @param value the value to set (must not contain NUL). 626 * @param bytes the length of value (in bytes). 627 */ 628 extern void stp_set_string_parameter_n(stp_vars_t *v, const char *parameter, 629 const char *value, size_t bytes); 630 631 /** 632 * Set a file parameter. 633 * @param v the vars to use. 634 * @param parameter the name of the parameter. 635 * @param value the value to set. 636 */ 637 extern void stp_set_file_parameter(stp_vars_t *v, const char *parameter, 638 const char *value); 639 640 /** 641 * Set a file parameter. 642 * @param v the vars to use. 643 * @param parameter the name of the parameter. 644 * @param value the value to set (must not contain NUL). 645 * @param bytes the length of value (in bytes). 646 */ 647 extern void stp_set_file_parameter_n(stp_vars_t *v, const char *parameter, 648 const char *value, size_t bytes); 649 650 /** 651 * Set a float parameter. 652 * @param v the vars to use. 653 * @param parameter the name of the parameter. 654 * @param value the value to set. 655 */ 656 extern void stp_set_float_parameter(stp_vars_t *v, const char *parameter, 657 double value); 658 659 /** 660 * Set an integer parameter. 661 * @param v the vars to use. 662 * @param parameter the name of the parameter. 663 * @param value the value to set. 664 */ 665 extern void stp_set_int_parameter(stp_vars_t *v, const char *parameter, 666 int value); 667 668 /** 669 * Set a dimension parameter. 670 * @param v the vars to use. 671 * @param parameter the name of the parameter. 672 * @param value the value to set. 673 */ 674 extern void stp_set_dimension_parameter(stp_vars_t *v, const char *parameter, 675 stp_dimension_t value); 676 677 /** 678 * Set a boolean parameter. 679 * @param v the vars to use. 680 * @param parameter the name of the parameter. 681 * @param value the value to set. 682 */ 683 extern void stp_set_boolean_parameter(stp_vars_t *v, const char *parameter, 684 int value); 685 686 /** 687 * Set a curve parameter. 688 * @param v the vars to use. 689 * @param parameter the name of the parameter. 690 * @param value the value to set. 691 */ 692 extern void stp_set_curve_parameter(stp_vars_t *v, const char *parameter, 693 const stp_curve_t *value); 694 695 /** 696 * Set an array parameter. 697 * @param v the vars to use. 698 * @param parameter the name of the parameter. 699 * @param value the value to set. 700 */ 701 extern void stp_set_array_parameter(stp_vars_t *v, const char *parameter, 702 const stp_array_t *value); 703 704 /** 705 * Set a raw parameter. 706 * @param v the vars to use. 707 * @param parameter the name of the parameter. 708 * @param value the value to set. 709 * @param bytes the length of value (in bytes). 710 */ 711 extern void stp_set_raw_parameter(stp_vars_t *v, const char *parameter, 712 const void *value, size_t bytes); 713 714 /** 715 * Multiply the value of a float parameter by a scaling factor. 716 * @param v the vars to use. 717 * @param parameter the name of the parameter. 718 * @param scale the factor to multiply the value by. 719 */ 720 extern void stp_scale_float_parameter(stp_vars_t *v, const char *parameter, 721 double scale); 722 723 /** 724 * Set a default string parameter. 725 * The value is set if the parameter is not already set. This avoids 726 * having to check if the parameter is set prior to setting it, if you 727 * do not want to override the existing value. 728 * @param v the vars to use. 729 * @param parameter the name of the parameter. 730 * @param value the value to set. 731 */ 732 extern void stp_set_default_string_parameter(stp_vars_t *v, 733 const char *parameter, 734 const char *value); 735 736 /** 737 * Set a default string parameter. 738 * The value is set if the parameter is not already set. This avoids 739 * having to check if the parameter is set prior to setting it, if you 740 * do not want to override the existing value. 741 * @param v the vars to use. 742 * @param parameter the name of the parameter. 743 * @param value the value to set (must not contain NUL). 744 * @param bytes the length of value (in bytes). 745 */ 746 extern void stp_set_default_string_parameter_n(stp_vars_t *v, 747 const char *parameter, 748 const char *value, size_t bytes); 749 750 /** 751 * Set a default file parameter. 752 * The value is set if the parameter is not already set. This avoids 753 * having to check if the parameter is set prior to setting it, if you 754 * do not want to override the existing value. 755 * @param v the vars to use. 756 * @param parameter the name of the parameter. 757 * @param value the value to set. 758 */ 759 extern void stp_set_default_file_parameter(stp_vars_t *v, 760 const char *parameter, 761 const char *value); 762 763 /** 764 * Set a default file parameter. 765 * The value is set if the parameter is not already set. This avoids 766 * having to check if the parameter is set prior to setting it, if you 767 * do not want to override the existing value. 768 * @param v the vars to use. 769 * @param parameter the name of the parameter. 770 * @param value the value to set (must not contain NUL). 771 * @param bytes the length of value (in bytes). 772 */ 773 extern void stp_set_default_file_parameter_n(stp_vars_t *v, 774 const char *parameter, 775 const char *value, size_t bytes); 776 777 /** 778 * Set a default float parameter. 779 * The value is set if the parameter is not already set. This avoids 780 * having to check if the parameter is set prior to setting it, if you 781 * do not want to override the existing value. 782 * @param v the vars to use. 783 * @param parameter the name of the parameter. 784 * @param value the value to set. 785 */ 786 extern void stp_set_default_float_parameter(stp_vars_t *v, 787 const char *parameter, 788 double value); 789 790 /** 791 * Set a default integer parameter. 792 * The value is set if the parameter is not already set. This avoids 793 * having to check if the parameter is set prior to setting it, if you 794 * do not want to override the existing value. 795 * @param v the vars to use. 796 * @param parameter the name of the parameter. 797 * @param value the value to set. 798 */ 799 extern void stp_set_default_int_parameter(stp_vars_t *v, 800 const char *parameter, 801 int value); 802 803 /** 804 * Set a default dimension parameter. 805 * The value is set if the parameter is not already set. This avoids 806 * having to check if the parameter is set prior to setting it, if you 807 * do not want to override the existing value. 808 * @param v the vars to use. 809 * @param parameter the name of the parameter. 810 * @param value the value to set. 811 */ 812 extern void stp_set_default_dimension_parameter(stp_vars_t *v, 813 const char *parameter, 814 stp_dimension_t value); 815 816 /** 817 * Set a default boolean parameter. 818 * The value is set if the parameter is not already set. This avoids 819 * having to check if the parameter is set prior to setting it, if you 820 * do not want to override the existing value. 821 * @param v the vars to use. 822 * @param parameter the name of the parameter. 823 * @param value the value to set. 824 */ 825 extern void stp_set_default_boolean_parameter(stp_vars_t *v, 826 const char *parameter, 827 int value); 828 829 /** 830 * Set a default curve parameter. 831 * The value is set if the parameter is not already set. This avoids 832 * having to check if the parameter is set prior to setting it, if you 833 * do not want to override the existing value. 834 * @param v the vars to use. 835 * @param parameter the name of the parameter. 836 * @param value the value to set. 837 */ 838 extern void stp_set_default_curve_parameter(stp_vars_t *v, 839 const char *parameter, 840 const stp_curve_t *value); 841 842 /** 843 * Set a default array parameter. 844 * The value is set if the parameter is not already set. This avoids 845 * having to check if the parameter is set prior to setting it, if you 846 * do not want to override the existing value. 847 * @param v the vars to use. 848 * @param parameter the name of the parameter. 849 * @param value the value to set. 850 */ 851 extern void stp_set_default_array_parameter(stp_vars_t *v, 852 const char *parameter, 853 const stp_array_t *value); 854 855 /** 856 * Set a default raw parameter. 857 * The value is set if the parameter is not already set. This avoids 858 * having to check if the parameter is set prior to setting it, if you 859 * do not want to override the existing value. 860 * @param v the vars to use. 861 * @param parameter the name of the parameter. 862 * @param value the value to set. 863 * @param bytes the length of value (in bytes). 864 */ 865 extern void stp_set_default_raw_parameter(stp_vars_t *v, 866 const char *parameter, 867 const void *value, size_t bytes); 868 869 /** 870 * Get a string parameter. 871 * @param v the vars to use. 872 * @param parameter the name of the parameter. 873 * @returns the string, or NULL if no parameter was found. 874 */ 875 extern const char *stp_get_string_parameter(const stp_vars_t *v, 876 const char *parameter); 877 878 /** 879 * Get a file parameter. 880 * @param v the vars to use. 881 * @param parameter the name of the parameter. 882 * @returns the filename, or NULL if no parameter was found. 883 */ 884 extern const char *stp_get_file_parameter(const stp_vars_t *v, 885 const char *parameter); 886 887 /** 888 * Get a float parameter. 889 * @param v the vars to use. 890 * @param parameter the name of the parameter. 891 * @returns the float value. 892 */ 893 extern double stp_get_float_parameter(const stp_vars_t *v, 894 const char *parameter); 895 896 /** 897 * Get an integer parameter. 898 * @param v the vars to use. 899 * @param parameter the name of the parameter. 900 * @returns the integer value. 901 */ 902 extern int stp_get_int_parameter(const stp_vars_t *v, 903 const char *parameter); 904 905 /** 906 * Get a dimension parameter. 907 * @param v the vars to use. 908 * @param parameter the name of the parameter. 909 * @returns the dimension (integer) value. 910 */ 911 extern stp_dimension_t stp_get_dimension_parameter(const stp_vars_t *v, 912 const char *parameter); 913 914 /** 915 * Get a boolean parameter. 916 * @param v the vars to use. 917 * @param parameter the name of the parameter. 918 * @returns the boolean value. 919 */ 920 extern int stp_get_boolean_parameter(const stp_vars_t *v, 921 const char *parameter); 922 923 /** 924 * Get a curve parameter. 925 * @param v the vars to use. 926 * @param parameter the name of the parameter. 927 * @returns the curve, or NULL if no parameter was found. 928 */ 929 extern const stp_curve_t *stp_get_curve_parameter(const stp_vars_t *v, 930 const char *parameter); 931 932 /** 933 * Get an array parameter. 934 * @param v the vars to use. 935 * @param parameter the name of the parameter. 936 * @returns the array, or NULL if no parameter was found. 937 */ 938 extern const stp_array_t *stp_get_array_parameter(const stp_vars_t *v, 939 const char *parameter); 940 941 /** 942 * Get a raw parameter. 943 * @param v the vars to use. 944 * @param parameter the name of the parameter. 945 * @returns the raw data, or NULL if no parameter was found. 946 */ 947 extern const stp_raw_t *stp_get_raw_parameter(const stp_vars_t *v, 948 const char *parameter); 949 950 /** 951 * Clear a string parameter. 952 * The parameter is set to NULL. 953 * @param v the vars to use. 954 * @param parameter the name of the parameter. 955 */ 956 extern void stp_clear_string_parameter(stp_vars_t *v, const char *parameter); 957 958 /** 959 * Clear a file parameter. 960 * The parameter is set to NULL. 961 * @param v the vars to use. 962 * @param parameter the name of the parameter. 963 */ 964 extern void stp_clear_file_parameter(stp_vars_t *v, const char *parameter); 965 966 /** 967 * Clear (remove) a float parameter. 968 * @param v the vars to use. 969 * @param parameter the name of the parameter. 970 */ 971 extern void stp_clear_float_parameter(stp_vars_t *v, const char *parameter); 972 973 /** 974 * Clear (remove) an integer parameter. 975 * @param v the vars to use. 976 * @param parameter the name of the parameter. 977 */ 978 extern void stp_clear_int_parameter(stp_vars_t *v, const char *parameter); 979 980 /** 981 * Clear (remove) a dimension parameter. 982 * @param v the vars to use. 983 * @param parameter the name of the parameter. 984 */ 985 extern void stp_clear_dimension_parameter(stp_vars_t *v, const char *parameter); 986 987 /** 988 * Clear (remove) a boolean parameter. 989 * @param v the vars to use. 990 * @param parameter the name of the parameter. 991 */ 992 extern void stp_clear_boolean_parameter(stp_vars_t *v, const char *parameter); 993 994 /** 995 * Clear a curve parameter. 996 * The parameter is set to NULL. 997 * @param v the vars to use. 998 * @param parameter the name of the parameter. 999 */ 1000 extern void stp_clear_curve_parameter(stp_vars_t *v, const char *parameter); 1001 1002 /** 1003 * Clear an array parameter. 1004 * The parameter is set to NULL. 1005 * @param v the vars to use. 1006 * @param parameter the name of the parameter. 1007 */ 1008 extern void stp_clear_array_parameter(stp_vars_t *v, const char *parameter); 1009 1010 /** 1011 * Clear a raw parameter. 1012 * The parameter is set to NULL. 1013 * @param v the vars to use. 1014 * @param parameter the name of the parameter. 1015 */ 1016 extern void stp_clear_raw_parameter(stp_vars_t *v, const char *parameter); 1017 1018 /** 1019 * Clear a parameter. 1020 * @param v the vars to use. 1021 * @param parameter the name of the parameter. 1022 * @param type the type of the parameter. 1023 */ 1024 extern void stp_clear_parameter(stp_vars_t *v, const char *parameter, stp_parameter_type_t type); 1025 1026 1027 /** 1028 * List all string parameters. 1029 * The return value must be freed after use. 1030 * @param v the vars to use. 1031 */ 1032 extern stp_string_list_t *stp_list_string_parameters(const stp_vars_t *v); 1033 1034 /** 1035 * List all file parameters. 1036 * The return value must be freed after use. 1037 * @param v the vars to use. 1038 */ 1039 extern stp_string_list_t *stp_list_file_parameters(const stp_vars_t *v); 1040 1041 /** 1042 * List all float parameters. 1043 * The return value must be freed after use. 1044 * @param v the vars to use. 1045 */ 1046 extern stp_string_list_t *stp_list_float_parameters(const stp_vars_t *v); 1047 1048 /** 1049 * List all integer parameters. 1050 * The return value must be freed after use. 1051 * @param v the vars to use. 1052 */ 1053 extern stp_string_list_t *stp_list_int_parameters(const stp_vars_t *v); 1054 1055 /** 1056 * List all dimension parameters. 1057 * The return value must be freed after use. 1058 * @param v the vars to use. 1059 */ 1060 extern stp_string_list_t *stp_list_dimension_parameters(const stp_vars_t *v); 1061 1062 /** 1063 * List all boolean parameters. 1064 * The return value must be freed after use. 1065 * @param v the vars to use. 1066 */ 1067 extern stp_string_list_t *stp_list_boolean_parameters(const stp_vars_t *v); 1068 1069 /** 1070 * List all curve parameters. 1071 * The return value must be freed after use. 1072 * @param v the vars to use. 1073 */ 1074 extern stp_string_list_t *stp_list_curve_parameters(const stp_vars_t *v); 1075 1076 /** 1077 * List all array parameters. 1078 * The return value must be freed after use. 1079 * @param v the vars to use. 1080 */ 1081 extern stp_string_list_t *stp_list_array_parameters(const stp_vars_t *v); 1082 1083 /** 1084 * List all raw parameters. 1085 * The return value must be freed after use. 1086 * @param v the vars to use. 1087 */ 1088 extern stp_string_list_t *stp_list_raw_parameters(const stp_vars_t *v); 1089 1090 /** 1091 * List all parameters. 1092 * The return value must be freed after use. 1093 * @param v the vars to use. 1094 * @param type the type of the parameter. 1095 */ 1096 extern stp_string_list_t *stp_list_parameters(const stp_vars_t *v, 1097 stp_parameter_type_t type); 1098 1099 1100 /** 1101 * Set the activity of a string parameter. 1102 * @param v the vars to use. 1103 * @param parameter the name of the parameter. 1104 * @param active the activity status to set (should be set to 1105 * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE). 1106 */ 1107 extern void stp_set_string_parameter_active(stp_vars_t *v, 1108 const char *parameter, 1109 stp_parameter_activity_t active); 1110 1111 /** 1112 * Set the activity of a file parameter. 1113 * @param v the vars to use. 1114 * @param parameter the name of the parameter. 1115 * @param active the activity status to set (should be set to 1116 * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE). 1117 */ 1118 extern void stp_set_file_parameter_active(stp_vars_t *v, 1119 const char *parameter, 1120 stp_parameter_activity_t active); 1121 1122 /** 1123 * Set the activity of a float parameter. 1124 * @param v the vars to use. 1125 * @param parameter the name of the parameter. 1126 * @param active the activity status to set (should be set to 1127 * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE). 1128 */ 1129 extern void stp_set_float_parameter_active(stp_vars_t *v, 1130 const char *parameter, 1131 stp_parameter_activity_t active); 1132 1133 /** 1134 * Set the activity of an integer parameter. 1135 * @param v the vars to use. 1136 * @param parameter the name of the parameter. 1137 * @param active the activity status to set (should be set to 1138 * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE). 1139 */ 1140 extern void stp_set_int_parameter_active(stp_vars_t *v, 1141 const char *parameter, 1142 stp_parameter_activity_t active); 1143 1144 /** 1145 * Set the activity of a dimension parameter. 1146 * @param v the vars to use. 1147 * @param parameter the name of the parameter. 1148 * @param active the activity status to set (should be set to 1149 * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE). 1150 */ 1151 extern void stp_set_dimension_parameter_active(stp_vars_t *v, 1152 const char *parameter, 1153 stp_parameter_activity_t active); 1154 1155 /** 1156 * Set the activity of a boolean parameter. 1157 * @param v the vars to use. 1158 * @param parameter the name of the parameter. 1159 * @param active the activity status to set (should be set to 1160 * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE). 1161 */ 1162 extern void stp_set_boolean_parameter_active(stp_vars_t *v, 1163 const char *parameter, 1164 stp_parameter_activity_t active); 1165 1166 /** 1167 * Set the activity of a curveparameter. 1168 * @param v the vars to use. 1169 * @param parameter the name of the parameter. 1170 * @param active the activity status to set (should be set to 1171 * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE). 1172 */ 1173 extern void stp_set_curve_parameter_active(stp_vars_t *v, 1174 const char *parameter, 1175 stp_parameter_activity_t active); 1176 1177 /** 1178 * Set the activity of an array parameter. 1179 * @param v the vars to use. 1180 * @param parameter the name of the parameter. 1181 * @param active the activity status to set (should be set to 1182 * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE). 1183 */ 1184 extern void stp_set_array_parameter_active(stp_vars_t *v, 1185 const char *parameter, 1186 stp_parameter_activity_t active); 1187 1188 /** 1189 * Set the activity of a raw parameter. 1190 * @param v the vars to use. 1191 * @param parameter the name of the parameter. 1192 * @param active the activity status to set (should be set to 1193 * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE). 1194 */ 1195 extern void stp_set_raw_parameter_active(stp_vars_t *v, 1196 const char *parameter, 1197 stp_parameter_activity_t active); 1198 1199 /** 1200 * Set the activity of a parameter. 1201 * @param v the vars to use. 1202 * @param parameter the name of the parameter. 1203 * @param active the activity status to set (should be set to 1204 * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE). 1205 * @param type the type of the parameter. 1206 */ 1207 extern void stp_set_parameter_active(stp_vars_t *v, 1208 const char *parameter, 1209 stp_parameter_activity_t active, 1210 stp_parameter_type_t type); 1211 1212 /** 1213 * Check if a string parameter is set. 1214 * @param v the vars to use. 1215 * @param parameter the name of the parameter. 1216 * @param active the minimum activity status. 1217 */ 1218 extern int stp_check_string_parameter(const stp_vars_t *v, const char *parameter, 1219 stp_parameter_activity_t active); 1220 1221 /** 1222 * Check if a file parameter is set. 1223 * @param v the vars to use. 1224 * @param parameter the name of the parameter. 1225 * @param active the minimum activity status. 1226 */ 1227 extern int stp_check_file_parameter(const stp_vars_t *v, const char *parameter, 1228 stp_parameter_activity_t active); 1229 1230 /** 1231 * Check if a float parameter is set. 1232 * @param v the vars to use. 1233 * @param parameter the name of the parameter. 1234 * @param active the minimum activity status. 1235 */ 1236 extern int stp_check_float_parameter(const stp_vars_t *v, const char *parameter, 1237 stp_parameter_activity_t active); 1238 1239 /** 1240 * Check if an integer parameter is set. 1241 * @param v the vars to use. 1242 * @param parameter the name of the parameter. 1243 * @param active the minimum activity status. 1244 */ 1245 extern int stp_check_int_parameter(const stp_vars_t *v, const char *parameter, 1246 stp_parameter_activity_t active); 1247 1248 /** 1249 * Check if a dimension parameter is set. 1250 * @param v the vars to use. 1251 * @param parameter the name of the parameter. 1252 * @param active the minimum activity status. 1253 */ 1254 extern int stp_check_dimension_parameter(const stp_vars_t *v, const char *parameter, 1255 stp_parameter_activity_t active); 1256 1257 /** 1258 * Check if a boolean parameter is set. 1259 * @param v the vars to use. 1260 * @param parameter the name of the parameter. 1261 * @param active the minimum activity status. 1262 */ 1263 extern int stp_check_boolean_parameter(const stp_vars_t *v, const char *parameter, 1264 stp_parameter_activity_t active); 1265 1266 /** 1267 * Check if a curve parameter is set. 1268 * @param v the vars to use. 1269 * @param parameter the name of the parameter. 1270 * @param active the minimum activity status. 1271 */ 1272 extern int stp_check_curve_parameter(const stp_vars_t *v, const char *parameter, 1273 stp_parameter_activity_t active); 1274 1275 /** 1276 * Check if an array parameter is set. 1277 * @param v the vars to use. 1278 * @param parameter the name of the parameter. 1279 * @param active the minimum activity status. 1280 */ 1281 extern int stp_check_array_parameter(const stp_vars_t *v, const char *parameter, 1282 stp_parameter_activity_t active); 1283 1284 /** 1285 * Check if a raw parameter is set. 1286 * @param v the vars to use. 1287 * @param parameter the name of the parameter. 1288 * @param active the minimum activity status. 1289 */ 1290 extern int stp_check_raw_parameter(const stp_vars_t *v, const char *parameter, 1291 stp_parameter_activity_t active); 1292 1293 /** 1294 * Check if a parameter is set. 1295 * @param v the vars to use. 1296 * @param parameter the name of the parameter. 1297 * @param active the minimum activity status. 1298 * @param type the type of the parameter. 1299 */ 1300 extern int stp_check_parameter(const stp_vars_t *v, const char *parameter, 1301 stp_parameter_activity_t active, 1302 stp_parameter_type_t type); 1303 1304 /** 1305 * Get the activity status of a string parameter. 1306 * @param v the vars to use. 1307 * @param parameter the name of the parameter. 1308 * @returns the activity status. 1309 */ 1310 extern stp_parameter_activity_t 1311 stp_get_string_parameter_active(const stp_vars_t *v, const char *parameter); 1312 1313 /** 1314 * Get the activity status of a file parameter. 1315 * @param v the vars to use. 1316 * @param parameter the name of the parameter. 1317 * @returns the activity status. 1318 */ 1319 extern stp_parameter_activity_t 1320 stp_get_file_parameter_active(const stp_vars_t *v, const char *parameter); 1321 1322 /** 1323 * Get the activity status of a float parameter. 1324 * @param v the vars to use. 1325 * @param parameter the name of the parameter. 1326 * @returns the activity status. 1327 */ 1328 extern stp_parameter_activity_t 1329 stp_get_float_parameter_active(const stp_vars_t *v, const char *parameter); 1330 1331 /** 1332 * Get the activity status of an integer parameter. 1333 * @param v the vars to use. 1334 * @param parameter the name of the parameter. 1335 * @returns the activity status. 1336 */ 1337 extern stp_parameter_activity_t 1338 stp_get_int_parameter_active(const stp_vars_t *v, const char *parameter); 1339 1340 /** 1341 * Get the activity status of a dimension parameter. 1342 * @param v the vars to use. 1343 * @param parameter the name of the parameter. 1344 * @returns the activity status. 1345 */ 1346 extern stp_parameter_activity_t 1347 stp_get_dimension_parameter_active(const stp_vars_t *v, const char *parameter); 1348 1349 /** 1350 * Get the activity status of a boolean parameter. 1351 * @param v the vars to use. 1352 * @param parameter the name of the parameter. 1353 * @returns the activity status. 1354 */ 1355 extern stp_parameter_activity_t 1356 stp_get_boolean_parameter_active(const stp_vars_t *v, const char *parameter); 1357 1358 /** 1359 * Get the activity status of a curve parameter. 1360 * @param v the vars to use. 1361 * @param parameter the name of the parameter. 1362 * @returns the activity status. 1363 */ 1364 extern stp_parameter_activity_t 1365 stp_get_curve_parameter_active(const stp_vars_t *v, const char *parameter); 1366 1367 /** 1368 * Get the activity status of an array parameter. 1369 * @param v the vars to use. 1370 * @param parameter the name of the parameter. 1371 * @returns the activity status. 1372 */ 1373 extern stp_parameter_activity_t 1374 stp_get_array_parameter_active(const stp_vars_t *v, const char *parameter); 1375 1376 /** 1377 * Get the activity status of a raw parameter. 1378 * @param v the vars to use. 1379 * @param parameter the name of the parameter. 1380 * @returns the activity status. 1381 */ 1382 extern stp_parameter_activity_t 1383 stp_get_raw_parameter_active(const stp_vars_t *v, const char *parameter); 1384 1385 /** 1386 * Get the activity status of a parameter. 1387 * @param v the vars to use. 1388 * @param parameter the name of the parameter. 1389 * @param type the type of the parameter. 1390 */ 1391 extern stp_parameter_activity_t 1392 stp_get_parameter_active(const stp_vars_t *v, const char *parameter, 1393 stp_parameter_type_t type); 1394 1395 1396 1397 /**************************************************************** 1398 * * 1399 * INFORMATIONAL QUERIES * 1400 * * 1401 ****************************************************************/ 1402 1403 /** 1404 * Get the media (paper) size. 1405 * Retrieve the media size of the media type set in V, expressed in units 1406 * of 1/72". If the media size is invalid, width and height will be set 1407 * to -1. Values of 0 for width or height indicate that the dimension 1408 * is variable, so that custom page sizes or roll paper can be used. 1409 * In this case, the size limit should be used to determine maximum and 1410 * minimum values permitted. 1411 * @param v the vars to use. 1412 * @param width a pointer to an stp_dimension_t to store the media width in. 1413 * @param height a pointer to an stp_dimension_t to store the media height in. 1414 */ 1415 extern void stp_get_media_size(const stp_vars_t *v, 1416 stp_dimension_t *width, stp_dimension_t *height); 1417 1418 /** 1419 * Get the imagable area of the page. 1420 * Retrieve the boundaries of the printable area of the page. In combination 1421 * with the media size, this can be used to determine the actual printable 1422 * region, which callers can use to place the image precisely. The 1423 * dimensions are relative to the top left of the physical page. 1424 * 1425 * If a customizable page size is used (see stp_printer_get_media_size), 1426 * the actual desired width and/or height must be filled in using 1427 * stp_set_page_width and/or stp_set_page_height. If these are not filled 1428 * in, the margins will be returned. 1429 * 1430 * Returned values may be negative if a printer is capable of full bleed 1431 * by printing beyond the physical boundaries of the page. 1432 * 1433 * If the media size stored in V is invalid, the return values 1434 * will be indeterminate. It is up to the user to specify legal values. 1435 * @param v the vars to use. 1436 * @param left a pointer to a stp_dimension_t to store the left edge in. 1437 * @param right a pointer to a stp_dimension_t to store the right edge in. 1438 * @param bottom a pointer to a stp_dimension_t to store the bottom edge in. 1439 * @param top a pointer to a stp_dimension_t to store the top edge in. 1440 */ 1441 extern void stp_get_imageable_area(const stp_vars_t *v, 1442 stp_dimension_t *left, stp_dimension_t *right, 1443 stp_dimension_t *bottom, stp_dimension_t *top); 1444 1445 /** 1446 * Get the maximum imagable area of the page. 1447 * Retrieve the maximum (regardless of settings other than page sise) 1448 * boundaries of the printable area of the page. In combination 1449 * with the media size, this can be used to determine the actual printable 1450 * region, which callers can use to place the image precisely. The 1451 * dimensions are relative to the top left of the physical page. 1452 * 1453 * If a customizable page size is used (see stp_printer_get_media_size), 1454 * the actual desired width and/or height must be filled in using 1455 * stp_set_page_width and/or stp_set_page_height. If these are not filled 1456 * in, the margins will be returned. 1457 * 1458 * Returned values may be negative if a printer is capable of full bleed 1459 * by printing beyond the physical boundaries of the page. 1460 * 1461 * If the media size stored in V is invalid, the return values 1462 * will be indeterminate. It is up to the user to specify legal values. 1463 * @param v the vars to use. 1464 * @param left a pointer to a stp_dimension_t to store the left edge in. 1465 * @param right a pointer to a stp_dimension_t to store the right edge in. 1466 * @param bottom a pointer to a stp_dimension_t to store the bottom edge in. 1467 * @param top a pointer to a stp_dimension_t to store the top edge in. 1468 */ 1469 extern void stp_get_maximum_imageable_area(const stp_vars_t *v, 1470 stp_dimension_t *left, 1471 stp_dimension_t *right, 1472 stp_dimension_t *bottom, 1473 stp_dimension_t *top); 1474 1475 /** 1476 * Get the media size limits. 1477 * Retrieve the minimum and maximum size limits for custom media sizes 1478 * with the current printer settings. 1479 * @param v the vars to use. 1480 * @param max_width a pointer to a stp_dimension_t to store the maximum width in. 1481 * @param max_height a pointer to a stp_dimension_t to store the maximum height in. 1482 * @param min_width a pointer to a stp_dimension_t to store the minimum width in. 1483 * @param min_height a pointer to a stp_dimension_t to store the minimum height in. 1484 */ 1485 extern void 1486 stp_get_size_limit(const stp_vars_t *v, 1487 stp_dimension_t *max_width, stp_dimension_t *max_height, 1488 stp_dimension_t *min_width, stp_dimension_t *min_height); 1489 1490 1491 /** 1492 * Retrieve the printing resolution of the selected resolution. If the 1493 * resolution is invalid, -1 will be returned in both x and y. 1494 * @param v the vars to use. 1495 * @param x a pointer to a stp_resolution_t to store the horizontal resolution in. 1496 * @param y a pointer to a stp_resolution_t to store the vertical resolution in. 1497 */ 1498 extern void stp_describe_resolution(const stp_vars_t *v, 1499 stp_resolution_t *x, stp_resolution_t *y); 1500 1501 /** 1502 * Verify parameters. 1503 * Verify that the parameters selected are consistent with those allowed 1504 * by the driver. This must be called prior to printing; failure to do 1505 * so will result in printing failing. 1506 * @param v the vars to use. 1507 * @returns 0 on failure, 1 on success; other status values are reserved. 1508 */ 1509 extern int stp_verify(stp_vars_t *v); 1510 1511 /** 1512 * Get default global settings. The main use of this is to provide a 1513 * usable stp_vars_t for purposes of parameter inquiry in the absence 1514 * of a specific printer. This is currently used in a variety of 1515 * places to get information on the standard color parameters without 1516 * querying a particular printer. 1517 * @returns the default settings. 1518 */ 1519 extern const stp_vars_t *stp_default_settings(void); 1520 1521 /** 1522 * Get the value of a specified category for the specified parameter. 1523 * @param v the vars to use. 1524 * @param desc the parameter description to use (must already be described) 1525 * @param category the name of the category to search for. 1526 * @returns the value of the category or NULL. String must be freed by caller. 1527 */ 1528 extern char *stp_parameter_get_category(const stp_vars_t *v, 1529 const stp_parameter_t *desc, 1530 const char *category); 1531 1532 /** 1533 * Determine whether a parameter has a category with the specified value. 1534 * If a null value is passed in, return whether the parameter has 1535 * the category at all. Return -1 if any other error condition (null 1536 * vars, desc, or category). 1537 * @param v the vars to use. 1538 * @param desc the parameter description to use (must already be described) 1539 * @param category the name of the category to search for. 1540 * @param value the value of the category to search for. 1541 * @returns whether the parameter has the category with the specified value. 1542 */ 1543 extern int stp_parameter_has_category_value(const stp_vars_t *v, 1544 const stp_parameter_t *desc, 1545 const char *category, 1546 const char *value); 1547 1548 /** 1549 * Get the list of categories and their values for the specified parameter. 1550 * @param v the vars to use. 1551 * @param desc the parameter description to use (must already be described) 1552 * @returns the list of categories. 1553 */ 1554 extern stp_string_list_t *stp_parameter_get_categories(const stp_vars_t *v, 1555 const stp_parameter_t *desc); 1556 1557 typedef void *(*stp_copy_data_func_t)(void *); 1558 typedef void (*stp_free_data_func_t)(void *); 1559 1560 typedef enum 1561 { 1562 PARAMETER_BAD, 1563 PARAMETER_OK, 1564 PARAMETER_INACTIVE 1565 } stp_parameter_verify_t; 1566 1567 extern void stp_allocate_component_data(stp_vars_t *v, 1568 const char *name, 1569 stp_copy_data_func_t copyfunc, 1570 stp_free_data_func_t freefunc, 1571 void *data); 1572 extern void stp_destroy_component_data(stp_vars_t *v, const char *name); 1573 1574 struct stp_compdata; 1575 typedef struct stp_compdata compdata_t; 1576 1577 extern void *stp_get_component_data(const stp_vars_t *v, const char *name); 1578 1579 extern stp_parameter_verify_t stp_verify_parameter(const stp_vars_t *v, 1580 const char *parameter, 1581 int quiet); 1582 extern int stp_get_verified(const stp_vars_t *v); 1583 extern void stp_set_verified(stp_vars_t *v, int value); 1584 1585 extern void stp_copy_options(stp_vars_t *vd, const stp_vars_t *vs); 1586 1587 extern void 1588 stp_fill_parameter_settings(stp_parameter_t *desc, 1589 const stp_parameter_t *param); 1590 1591 /** @} */ 1592 1593 #ifdef __cplusplus 1594 } 1595 #endif 1596 1597 #endif /* GUTENPRINT_VARS_H */ 1598