michaelrsweet
commented
12 years ago CUPS.org User: mike
Doing development on cups-api-1.6 branch...
The new PPD replacement APIs address the standard option names and values (all from IPP/AirPrint) along with getting the supported and "ready" options and values, media sizes and margins, and localizations of options and values,
/* Number of copies; option values are integers as strings */
define CUPS_COPIES "copies"
/* Finishings; applied to the job as a whole, also see IPP_FINISHINGS_xxx in <cups/ipp.h> */
define CUPS_FINISHINGS "finishings"
define CUPS_FINISHINGS_BIND "7"
define CUPS_FINISHINGS_COVER "6"
define CUPS_FINISHINGS_FOLD "10"
define CUPS_FINISHINGS_NONE "3"
define CUPS_FINISHINGS_PUNCH "5"
define CUPS_FINISHINGS_STAPLE "4"
define CUPS_FINISHINGS_TRIM "11"
/* Media (size); when looking up supported values, CUPS_MEDIA contains all of the possible values while CUPS_MEDIA_READY contains the media that is loaded in the printer (if the printer supported media sensing). Use cupsGetDestMedia to get the dimensions and margins for a given name. */
define CUPS_MEDIA "media"
define CUPS_MEDIA_READY "media-ready"
define CUPS_MEDIA_3X5 "na_index-3x5_3x5in"
define CUPS_MEDIA_4X6 "na_index-4x6_4x6in"
define CUPS_MEDIA_5X7 "na_5x7_5x7in"
define CUPS_MEDIA_8X10 "na_govt-letter_8x10in"
define CUPS_MEDIA_A3 "iso_a3_297x420mm"
define CUPS_MEDIA_A4 "iso_a4_210x297mm"
define CUPS_MEDIA_A5 "iso_a5_148x210mm"
define CUPS_MEDIA_A6 "iso_a6_105x148mm"
define CUPS_MEDIA_ENV10 "na_number-10_4.125x9.5in"
define CUPS_MEDIA_ENVDL "iso_dl_110x220mm"
define CUPS_MEDIA_LEGAL "na_legal_8.5x14in"
define CUPS_MEDIA_LETTER "na_letter_8.5x11in"
define CUPS_MEDIA_PHOTO_L "oe_photo-l_3.5x5in"
define CUPS_MEDIA_SUPERBA3 "na_super-b_13x19in"
define CUPS_MEDIA_TABLOID "na_ledger_11x17in"
/* Media source; "auto" is the default */
define CUPS_MEDIA_SOURCE "media-source"
define CUPS_MEDIA_SOURCE_AUTO "auto"
define CUPS_MEDIA_SOURCE_MANUAL "manual"
/* Media type; "auto" is the default */
define CUPS_MEDIA_TYPE "media-type"
define CUPS_MEDIA_TYPE_AUTO "auto"
define CUPS_MEDIA_TYPE_ENVELOPE "envelope"
define CUPS_MEDIA_TYPE_LABELS "labels"
define CUPS_MEDIA_TYPE_LETTERHEAD "stationery-letterhead"
define CUPS_MEDIA_TYPE_PHOTO "photographic"
define CUPS_MEDIA_TYPE_PHOTO_GLOSSY "photographic-glossy"
define CUPS_MEDIA_TYPE_PHOTO_MATTE "photographic-matte"
define CUPS_MEDIA_TYPE_PLAIN "stationery"
define CUPS_MEDIA_TYPE_TRANSPARENCY "transparency"
/* Number-up; option values are integers as strings */
define CUPS_NUMBER_UP "number-up"
/* Orientation; also see the ipp_orient_t values in <cups/ipp.h> */
define CUPS_ORIENTATION "orientation-requested"
define CUPS_ORIENTATION_PORTRAIT "3"
define CUPS_ORIENTATION_LANDSCAPE "4"
/* Color mode; "auto" is the default, "monochrome" and "color" force the corresponding output. */
define CUPS_PRINT_COLOR_MODE "print-color-mode"
define CUPS_PRINT_COLOR_MODE_AUTO "auto"
define CUPS_PRINT_COLOR_MODE_MONOCHROME "monochrome"
define CUPS_PRINT_COLOR_MODE_COLOR "color"
/* Print quality; also see the IPP_QUALITY_xxx values in <cups/ipp.h> */
define CUPS_PRINT_QUALITY "print-quality"
define CUPS_PRINT_QUALITY_DRAFT "3"
define CUPS_PRINT_QUALITY_NORMAL "4"
define CUPS_PRINT_QUALITY_HIGH "5"
/* Duplex mode; long-edge is typically for portrait output and short-edge for landscape output */
define CUPS_SIDES "sides"
define CUPS_SIDES_ONE_SIDED "one-sided"
define CUPS_SIDES_TWO_SIDED_PORTRAIT "two-sided-long-edge"
define CUPS_SIDES_TWO_SIDED_LANDSCAPE "two-sided-short-edge"
/* Get the supported values/capabilities for the destination as an IPP message. The caller is responsible for calling ippDelete() on the return value. NULL is returned on error.
Replaces ppdOpen */
ipp_t cupsCopyDestSupported(http_t http, cups_dest_t *dest);
/* Get media names, dimensions, and margins - replaces ppdPageSize and others. The "media" string is a PWG media name, while "width" and "length" are the dimensions in hundredths of millimeters. "flags" provides some matching guidance (multiple flags can be combined):
CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the size amongst the "ready" media.
The matching result (if any) is returned in the "cups_size_t" structure.
Returns 1 when there is a match and 0 if there is not a match. */
define CUPS_MEDIA_FLAGS_DEFAULT 0
define CUPS_MEDIA_FLAGS_BORDERLESS 1
define CUPS_MEDIA_FLAGS_DUPLEX 2
define CUPS_MEDIA_FLAGS_EXACT 4
define CUPS_MEDIA_FLAGS_READY 8
typedef struct _cups_sizes { char media[128]; /* Media name to use / int width, / Width in hundredths of millimeters / length, / Length in hundredths of millimeters / bottom. / Bottom margin in hundredths of millimeters / left. / Left margin in hundredths of millimeters / right, / Right margin in hundredths of millimeters / top; /_ Top margin in hundredths of millimeters */ } cups_size_t;
int cupsGetDestMediaByName(http_t http, cups_dest_t dest, ipp_t supported, const char media, unsigned flags, cups_size_t size); int cupsGetDestMediaBySize(http_t http, cups_dest_t dest, ipp_t supported, int width, int length, unsigned flags, cups_size_t *size);
/* Check that the option and value are supported by the destination - replaces ppdFindChoice() and ppdInstallableConflict(). Returns 1 if supported, 0 otherwise. */
int cupsCheckDestSupported(http_t http, cups_dest_t dest, ipp_t supported, const char option, const char *value);
/* Get conflicts and resolutions for a new option/value pair. This single API replaces ppdConflicts, cupsGetConflicts, and cupsResolveConflicts.
"num_options" and "options" represent the currently selected options by the user. "new_option" and "new_value" are the setting the user has just changed.
Returns 1 if there is a conflict and 0 otherwise.
If "num_conflicts" and "conflicts" are not NULL, they are set to contain the list of conflicting option/value pairs. Similarly, if "num_resolved" and "resolved" are not NULL they will be set to the list of changes needed to resolve the conflict.
If cupsCopyDestConflicts returns 1 but "num_resolved" and "resolved" are set to 0 and NULL, respectively, then the conflict cannot be resolved. */
int cupsCopyDestConflicts(http_t _http, cups_dest_t dest, ipp_t supported, int num_options, cups_option_t options, const char new_option, const char new_value, int num_conflicts, cups_option_t _conflicts, int _num_resolved, cups_option_t _resolved);
/* Get localization information for the current locale from the destination, with English as the fallback - replaces ppdLocalize*.
The caller must call cupsArrayDelete on the returned array. */
cups_array_t cupsCopyDestLocalizations(http_t http, cups_dest_t *dest);
/* Get the localized string for a destination option - replaces ppdLocalize and the lookup in the ppd_option_t structure.
The returned string is stored in the localization array and will become invalid if the localization array is deleted. */
const char cupsLocalizeDestOption(http_t http, cups_dest_t dest, cups_array_t localization, const char *option);
/* Get the localized string for a destination option+value pair - replaces ppdLocalize* and the lookup in the ppd_choice_t structure.
The returned string is stored in the localization array and will become invalid if the localization array is deleted. */
const char cupsLocalizeDestValue(http_t http, cups_dest_t dest, cups_array_t localization, const char option, const char value);
Version: 1.6-feature CUPS.org User: mike
In the continuing march towards IPP Everywhere, we need an API that exposes the supported and default job template attributes along with the constraints.
Initially this will be provided by the existing PPD mapping code, but long term we should be able to simply discover what a printer can handle and act accordingly.