cups/cupspm.md

   1 ---
   2 title: CUPS Programming Manual
   3 author: Michael R Sweet
   4 copyright: Copyright © 2007-2017 by Apple Inc. All Rights Reserved.
   5 version: 2.2.4
   6 ...
   7
   8 > Note: This document is under active development and is incomplete, with a goal
   9 > completing it prior to releasing CUPS 2.2.4.  Please
  10 > [file issues on Github](https://github.com/apple/cups/issues)
  11 > to provide any feedback.
  12
  13
  14 # Introduction
  15
  16 CUPS provides the "cups" library to talk to the different parts of CUPS and with
  17 Internet Printing Protocol (IPP) printers. The "cups" library functions are
  18 accessed by including the `<cups/cups.h>` header.
  19
  20 CUPS is based on the Internet Printing Protocol ("IPP"), which allows clients
  21 (applications) to communicate with a server (the scheduler, printers, etc.) to
  22 get a list of destinations, send print jobs, and so forth.  You identify which
  23 server you want to communicate with using a pointer to the opaque structure
  24 `http_t`.  The `CUPS_HTTP_DEFAULT` constant can be used when you want to talk to
  25 the CUPS scheduler.
  26
  27
  28 ## Guidelines
  29
  30 When writing software that uses the "cups" library:
  31
  32 - Do not use undocumented or deprecated APIs,
  33 - Do not rely on pre-configured printers,
  34 - Do not assume that printers support specific features or formats, and
  35 - Do not rely on implementation details (PPDs, etc.)
  36
  37 CUPS is designed to insulate users and developers from the implementation
  38 details of printers and file formats.  The goal is to allow an application to
  39 supply a print file in a standard format with the user intent ("print four
  40 copies, two-sided on A4 media, and staple each copy") and have the printing
  41 system manage the printer communication and format conversion needed.
  42
  43 Similarly, printer and job management applications can use standard query
  44 operations to obtain the status information in a common, generic form and use
  45 standard management operations to control the state of those printers and jobs.
  46
  47
  48 ## Terms Used in This Document
  49
  50 A *Destination* is a printer or print queue that accepts print jobs.  A
  51 *Print Job* is one or more documents that are processed by a destination
  52 using options supplied when creating the job.  A *Document* is a file (JPEG
  53 image, PDF file, etc.) suitable for printing.  An *Option* controls some aspect
  54 of printing, such as the media used. *Media* is the sheets or roll that is
  55 printed on.  An *Attribute* is an option encoded for an Internet Printing
  56 Protocol (IPP) request.
  57
  58
  59 ## Compiling Programs That Use the CUPS API
  60
  61 The CUPS libraries can be used from any C, C++, or Objective C program.
  62 The method of compiling against the libraries varies depending on the
  63 operating system and installation of CUPS. The following sections show how
  64 to compile a simple program (shown below) in two common environments.
  65
  66 The following simple program lists the available destinations:
  67
  68     #include <stdio.h>
  69     #include <cups/cups.h>
  70
  71     int print_dest(void *user_data, unsigned flags, cups_dest_t *dest)
  72     {
  73       if (dest->instance)
  74         printf("%s/%s\n", dest->name, dest->instance);
  75       else
  76         puts(dest->name);
  77
  78       return (1);
  79     }
  80
  81     int main(void)
  82     {
  83       cupsEnumDests(CUPS_DEST_FLAGS_NONE, 1000, NULL, 0, 0, print_dest, NULL);
  84
  85       return (0);
  86     }
  87
  88
  89 ### Compiling with Xcode
  90
  91 In Xcode, choose *New Project...* from the *File* menu (or press SHIFT+CMD+N),
  92 then select the *Command Line Tool* under the macOS Application project type.
  93 Click *Next* and enter a name for the project, for example "firstcups".  Click
  94 *Next* and choose a project directory. The click *Next* to create the project.
  95
  96 In the project window, click on the *Build Phases* group and expand the
  97 *Link Binary with Libraries* section. Click *+*, type "libcups" to show the
  98 library, and then double-click on `libcups.tbd`.
  99
 100 Finally, click on the `main.c` file in the sidebar and copy the example program
 101 to the file.  Build and run (CMD+R) to see the list of destinations.
 102
 103
 104 ### Compiling with GCC
 105
 106 From the command-line, create a file called `sample.c` using your favorite
 107 editor, copy the example to this file, and save.  Then run the following command
 108 to compile it with GCC and run it:
 109
 110     gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
 111     ./simple
 112
 113 The `cups-config` command provides the compiler flags (`cups-config --cflags`)
 114 and libraries (`cups-config --libs`) needed for the local system.
 115
 116
 117 # Working with Destinations
 118
 119 Destinations, which in CUPS represent individual printers or classes
 120 (collections or pools) of printers, are represented by the `cups_dest_t`
 121 structure which includes the name \(`name`), instance \(`instance`, saved
 122 options/settings), whether the destination is the default for the user
 123 \(`is_default`), and the options and basic information associated with that
 124 destination \(`num_options` and `options`).
 125
 126 Historically destinations have been manually maintained by the administrator of
 127 a system or network, but CUPS also supports dynamic discovery of destinations on
 128 the current network.
 129
 130
 131 ## Finding Available Destinations
 132
 133 The `cupsEnumDests` function finds all of the available destinations:
 134
 135      int
 136      cupsEnumDests(unsigned flags, int msec, int *cancel,
 137                    cups_ptype_t type, cups_ptype_t mask,
 138                    cups_dest_cb_t cb, void *user_data)
 139
 140 The `flags` argument specifies enumeration options, which at present must be
 141 `CUPS_DEST_FLAGS_NONE`.
 142
 143 The `msec` argument specifies the maximum amount of time that should be used for
 144 enumeration in milliseconds - interactive applications should keep this value to
 145 5000 or less when run on the main thread.
 146
 147 The `cancel` argument points to an integer variable that, when set to a non-zero
 148 value, will cause enumeration to stop as soon as possible.  It can be `NULL` if
 149 not needed.
 150
 151 The `type` and `mask` arguments are bitfields that allow the caller to filter
 152 the destinations based on categories and/or capabilities.  The destination's
 153 "printer-type" value is masked by the `mask` value and compared to the `type`
 154 value when filtering.  For example, to only enumerate destinations that are
 155 hosted on the local system, pass `CUPS_PRINTER_LOCAL` for the `type` argument
 156 and `CUPS_PRINTER_DISCOVERED` for the `mask` argument.  The following constants
 157 can be used for filtering:
 158
 159 - `CUPS_PRINTER_CLASS`: A collection of destinations.
 160 - `CUPS_PRINTER_FAX`: A facsimile device.
 161 - `CUPS_PRINTER_LOCAL`: A local printer or class.  This constant has the value 0
 162   (no bits set) and is only used for the `type` argument and is paired with the
 163   `CUPS_PRINTER_REMOTE` or `CUPS_PRINTER_DISCOVERED` constant passed in the
 164   `mask` argument.
 165 - `CUPS_PRINTER_REMOTE`: A remote (shared) printer or class.
 166 - `CUPS_PRINTER_DISCOVERED`: An available network printer or class.
 167 - `CUPS_PRINTER_BW`: Can do B&W printing.
 168 - `CUPS_PRINTER_COLOR`: Can do color printing.
 169 - `CUPS_PRINTER_DUPLEX`: Can do two-sided printing.
 170 - `CUPS_PRINTER_STAPLE`: Can staple output.
 171 - `CUPS_PRINTER_COLLATE`: Can quickly collate copies.
 172 - `CUPS_PRINTER_PUNCH`: Can punch output.
 173 - `CUPS_PRINTER_COVER`: Can cover output.
 174 - `CUPS_PRINTER_BIND`: Can bind output.
 175 - `CUPS_PRINTER_SORT`: Can sort output (mailboxes, etc.)
 176 - `CUPS_PRINTER_SMALL`: Can print on Letter/Legal/A4-size media.
 177 - `CUPS_PRINTER_MEDIUM`: Can print on Tabloid/B/C/A3/A2-size media.
 178 - `CUPS_PRINTER_LARGE`: Can print on D/E/A1/A0-size media.
 179 - `CUPS_PRINTER_VARIABLE`: Can print on rolls and custom-size media.
 180
 181 The `cb` argument specifies a function to call for every destination that is
 182 found:
 183
 184     typedef int (*cups_dest_cb_t)(void *user_data,
 185                                   unsigned flags,
 186                                   cups_dest_t *dest);
 187
 188 The callback function receives a copy of the `user_data` argument along with a
 189 bitfield \(`flags`) and the destination that was found.  The `flags` argument
 190 can have any of the following constant (bit) values set:
 191
 192 - `CUPS_DEST_FLAGS_MORE`: There are more destinations coming.
 193 - `CUPS_DEST_FLAGS_REMOVED`: The destination has gone away and should be removed
 194   from the list of destinations a user can select.
 195 - `CUPS_DEST_FLAGS_ERROR`: An error occurred.  The reason for the error can be
 196   found by calling the `cupsLastError` and/or `cupsLastErrorString` functions.
 197
 198 The callback function returns 0 to stop enumeration or 1 to continue.
 199
 200 The following example shows how to use `cupsEnumDests` to get a filtered array
 201 of destinations:
 202
 203     typedef struct
 204     {
 205       int num_dests;
 206       cups_dest_t *dests;
 207     } my_user_data_t;
 208
 209     int
 210     my_dest_cb(my_user_data_t *user_data, unsigned flags,
 211                cups_dest_t *dest)
 212     {
 213       if (flags & CUPS_DEST_FLAGS_REMOVED)
 214       {
 215        /*
 216         * Remove destination from array...
 217         */
 218
 219         user_data->num_dests =
 220             cupsRemoveDest(dest->name, dest->instance,
 221                            user_data->num_dests,
 222                            &(user_data->dests));
 223       }
 224       else
 225       {
 226        /*
 227         * Add destination to array...
 228         */
 229
 230         user_data->num_dests =
 231             cupsCopyDest(dest, user_data->num_dests,
 232                          &(user_data->dests));
 233       }
 234
 235       return (1);
 236     }
 237
 238     int
 239     my_get_dests(cups_ptype_t type, cups_ptype_t mask,
 240                  cups_dest_t **dests)
 241     {
 242       my_user_data_t user_data = { 0, NULL };
 243
 244       if (!cupsEnumDests(CUPS_DEST_FLAGS_NONE, 1000, NULL, type,
 245                          mask, (cups_dest_cb_t)my_dest_cb,
 246                          &user_data))
 247       {
 248        /*
 249         * An error occurred, free all of the destinations and
 250         * return...
 251         */
 252
 253         cupsFreeDests(user_data.num_dests, user_dasta.dests);
 254
 255         *dests = NULL;
 256
 257         return (0);
 258       }
 259
 260      /*
 261       * Return the destination array...
 262       */
 263
 264       *dests = user_data.dests;
 265
 266       return (user_data.num_dests);
 267     }
 268
 269
 270 ## Basic Destination Information
 271
 272 The `num_options` and `options` members of the `cups_dest_t` structure provide
 273 basic attributes about the destination in addition to the user default options
 274 and values for that destination.  The following names are predefined for various
 275 destination attributes:
 276
 277 - "auth-info-required": The type of authentication required for printing to this
 278   destination: "none", "username,password", "domain,username,password", or
 279   "negotiate" (Kerberos).
 280 - "printer-info": The human-readable description of the destination such as "My
 281   Laser Printer".
 282 - "printer-is-accepting-jobs": "true" if the destination is accepting new jobs,
 283   "false" otherwise.
 284 - "printer-is-shared": "true" if the destination is being shared with other
 285   computers, "false" otherwise.
 286 - "printer-location": The human-readable location of the destination such as
 287   "Lab 4".
 288 - "printer-make-and-model": The human-readable make and model of the destination
 289   such as "ExampleCorp LaserPrinter 4000 Series".
 290 - "printer-state": "3" if the destination is idle, "4" if the destination is
 291   printing a job, and "5" if the destination is stopped.
 292 - "printer-state-change-time": The UNIX time when the destination entered the
 293   current state.
 294 - "printer-state-reasons": Additional comma-delimited state keywords for the
 295   destination such as "media-tray-empty-error" and "toner-low-warning".
 296 - "printer-type": The `cups_ptype_t` value associated with the destination.
 297 - "printer-uri": The URI associated with the destination; if not set, this
 298   destination was discovered but is not yet setup as a local printer.
 299
 300 Use the `cupsGetOption` function to retrieve the value.  For example, the
 301 following code gets the make and model of a destination:
 302
 303     const char *model = cupsGetOption("printer-make-and-model",
 304                                       dest->num_options,
 305                                       dest->options);
 306
 307 ## Detailed Destination Information
 308
 309 Once a destination has been chosen, the `cupsCopyDestInfo` function can be used
 310 to gather detailed information about the destination:
 311
 312     cups_dinfo_t *
 313     cupsCopyDestInfo(http_t *http, cups_dest_t *dest);
 314
 315 The `http` argument specifies a connection to the CUPS scheduler and is
 316 typically the constant `CUPS_HTTP_DEFAULT`.  The `dest` argument specifies the
 317 destination to query.
 318
 319 The `cups_dinfo_t` structure that is returned contains a snapshot of the
 320 supported options and their supported, ready, and default values.  It also can
 321 report constraints between different options and values, and recommend changes
 322 to resolve those constraints.
 323
 324 ### Getting Supported Options and Values
 325
 326 The `cupsCheckDestSupported` function can be used to test whether a particular
 327 option or option and value is supported:
 328
 329     int
 330     cupsCheckDestSupported(http_t *http, cups_dest_t *dest,
 331                            cups_dinfo_t *info,
 332                            const char *option,
 333                            const char *value);
 334
 335 The `option` argument specifies the name of the option to check.  The following
 336 constants can be used to check the various standard options:
 337
 338 - `CUPS_COPIES`: Controls the number of copies that are produced.
 339 - `CUPS_FINISHINGS`: A comma-delimited list of integer constants that control
 340   the finishing processes that are applied to the job, including stapling,
 341   punching, and folding.
 342 - `CUPS_MEDIA`: Controls the media size that is used, typically one of the
 343   following: `CUPS_MEDIA_3X5`, `CUPS_MEDIA_4X6`, `CUPS_MEDIA_5X7`,
 344   `CUPS_MEDIA_8X10`, `CUPS_MEDIA_A3`, `CUPS_MEDIA_A4`, `CUPS_MEDIA_A5`,
 345   `CUPS_MEDIA_A6`, `CUPS_MEDIA_ENV10`, `CUPS_MEDIA_ENVDL`, `CUPS_MEDIA_LEGAL`,
 346   `CUPS_MEDIA_LETTER`, `CUPS_MEDIA_PHOTO_L`, `CUPS_MEDIA_SUPERBA3`, or
 347   `CUPS_MEDIA_TABLOID`.
 348 - `CUPS_MEDIA_SOURCE`: Controls where the media is pulled from, typically either
 349   `CUPS_MEDIA_SOURCE_AUTO` or `CUPS_MEDIA_SOURCE_MANUAL`.
 350 - `CUPS_MEDIA_TYPE`: Controls the type of media that is used, typically one of
 351   the following: `CUPS_MEDIA_TYPE_AUTO`, `CUPS_MEDIA_TYPE_ENVELOPE`,
 352   `CUPS_MEDIA_TYPE_LABELS`, `CUPS_MEDIA_TYPE_LETTERHEAD`,
 353   `CUPS_MEDIA_TYPE_PHOTO`, `CUPS_MEDIA_TYPE_PHOTO_GLOSSY`,
 354   `CUPS_MEDIA_TYPE_PHOTO_MATTE`, `CUPS_MEDIA_TYPE_PLAIN`, or
 355   `CUPS_MEDIA_TYPE_TRANSPARENCY`.
 356 - `CUPS_NUMBER_UP`: Controls the number of document pages that are placed on
 357   each media side.
 358 - `CUPS_ORIENTATION`: Controls the orientation of document pages placed on the
 359   media: `CUPS_ORIENTATION_PORTRAIT` or `CUPS_ORIENTATION_LANDSCAPE`.
 360 - `CUPS_PRINT_COLOR_MODE`: Controls whether the output is in color
 361   \(`CUPS_PRINT_COLOR_MODE_COLOR`), grayscale
 362   \(`CUPS_PRINT_COLOR_MODE_MONOCHROME`), or either
 363   \(`CUPS_PRINT_COLOR_MODE_AUTO`).
 364 - `CUPS_PRINT_QUALITY`: Controls the generate quality of the output:
 365   `CUPS_PRINT_QUALITY_DRAFT`, `CUPS_PRINT_QUALITY_NORMAL`, or
 366   `CUPS_PRINT_QUALITY_HIGH`.
 367 - `CUPS_SIDES`: Controls whether prints are placed on one or both sides of the
 368   media: `CUPS_SIDES_ONE_SIDED`, `CUPS_SIDES_TWO_SIDED_PORTRAIT`, or
 369   `CUPS_SIDES_TWO_SIDED_LANDSCAPE`.
 370
 371 If the `value` argument is `NULL`, the `cupsCheckDestSupported` function returns
 372 whether the option is supported by the destination.  Otherwise, the function
 373 returns whether the specified value of the option is supported.
 374
 375 The `cupsFindDestSupported` function returns the IPP attribute containing the
 376 supported values for a given option:
 377
 378      ipp_attribute_t *
 379      cupsFindDestSupported(http_t *http, cups_dest_t *dest,
 380                            cups_dinfo_t *dinfo,
 381                            const char *option);
 382
 383 For example, the following code prints the supported finishing processes for a
 384 destination, if any, to the standard output:
 385
 386     cups_dinfo_t *info = cupsCopyDestInfo(CUPS_HTTP_DEFAULT,
 387                                           dest);
 388
 389     if (cupsCheckDestSupported(CUPS_HTTP_DEFAULT, dest, info,
 390                                CUPS_FINISHINGS, NULL))
 391     {
 392       ipp_attribute_t *finishings =
 393           cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info,
 394                                 CUPS_FINISHINGS);
 395       int i, count = ippGetCount(finishings);
 396
 397       puts("finishings supported:");
 398       for (i = 0; i < count; i ++)
 399         printf("  %d\n", ippGetInteger(finishings, i));
 400     }
 401     else
 402       puts("finishings not supported.");
 403
 404 The "job-creation-attributes" option can be queried to get a list of supported
 405 options.  For example, the following code prints the list of supported options
 406 to the standard output:
 407
 408     ipp_attribute_t *attrs =
 409         cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info,
 410                               "job-creation-attributes");
 411     int i, count = ippGetCount(attrs);
 412
 413     for (i = 0; i < count; i ++)
 414       puts(ippGetString(attrs, i, NULL));
 415
 416
 417 ### Getting Default Values
 418
 419 There are two sets of default values - user defaults that are available via the
 420 `num_options` and `options` members of the `cups_dest_t` structure, and
 421 destination defaults that available via the `cups_dinfo_t` structure and the
 422 `cupsFindDestDefault` function which returns the IPP attribute containing the
 423 default value(s) for a given option:
 424
 425     ipp_attribute_t *
 426     cupsFindDestDefault(http_t *http, cups_dest_t *dest,
 427                         cups_dinfo_t *dinfo,
 428                         const char *option);
 429
 430 The user defaults from `cupsGetOption` should always take preference over the
 431 destination defaults.  For example, the following code prints the default
 432 finishings value(s) to the standard output:
 433
 434     const char *def_value =
 435         cupsGetOption(CUPS_FINISHINGS, dest->num_options,
 436                       dest->options);
 437     ipp_attribute_t *def_attr =
 438         cupsFindDestDefault(CUPS_HTTP_DEFAULT, dest, info,
 439                             CUPS_FINISHINGS);
 440
 441     if (def_value != NULL)
 442     {
 443       printf("Default finishings: %s\n", def_value);
 444     }
 445     else
 446     {
 447       int i, count = ippGetCount(def_attr);
 448
 449       printf("Default finishings: %d",
 450              ippGetInteger(def_attr, 0));
 451       for (i = 1; i < count; i ++)
 452         printf(",%d", ippGetInteger(def_attr, i));
 453       putchar('\n');
 454     }
 455
 456
 457 ### Getting Ready (Loaded) Values
 458
 459 The finishings and media options also support queries for the ready, or loaded,
 460 values.  For example, a printer may have punch and staple finishers installed
 461 but be out of staples - the supported values will list both punch and staple
 462 finishing processes but the ready values will only list the punch processes.
 463 Similarly, a printer may support hundreds of different sizes of media but only
 464 have a single size loaded at any given time - the ready values are limited to
 465 the media that is actually in the printer.
 466
 467 The `cupsFindDestReady` function finds the IPP attribute containing the ready
 468 values for a given option:
 469
 470     ipp_attribute_t *
 471     cupsFindDestReady(http_t *http, cups_dest_t *dest,
 472                       cups_dinfo_t *dinfo, const char *option);
 473
 474 For example, the following code lists the ready finishing processes:
 475
 476     ipp_attribute_t *ready_finishings =
 477         cupsFindDestReady(CUPS_HTTP_DEFAULT, dest, info,
 478                           CUPS_FINISHINGS);
 479
 480     if (ready_finishings != NULL)
 481     {
 482       int i, count = ippGetCount(ready_finishings);
 483
 484       puts("finishings ready:");
 485       for (i = 0; i < count; i ++)
 486         printf("  %d\n", ippGetInteger(ready_finishings, i));
 487     }
 488     else
 489       puts("no finishings are ready.");
 490
 491
 492 ### Media Size Options
 493
 494 CUPS provides functions for querying the dimensions and margins for each of the
 495 supported media size options.  The `cups_size_t` structure is used to describe a
 496 media size:
 497
 498     typedef struct cups_size_s
 499     {
 500       char media[128];
 501       int width, length;
 502       int bottom, left, right, top;
 503     } cups_size_t;
 504
 505 The `width` and `length` members specify the dimensions of the media in
 506 hundredths of millimeters (1/2540th of an inch).  The `bottom`, `left`, `right`,
 507 and `top` members specify the margins of the printable area, also in hundredths
 508 of millimeters.
 509
 510 The `cupsGetDestMediaByName` and `cupsGetDestMediaBySize` functions lookup the
 511 media size information using a standard media size name or dimensions in
 512 hundredths of millimeters:
 513
 514     int
 515     cupsGetDestMediaByName(http_t *http, cups_dest_t *dest,
 516                            cups_dinfo_t *dinfo,
 517                            const char *media,
 518                            unsigned flags, cups_size_t *size);
 519
 520     int
 521     cupsGetDestMediaBySize(http_t *http, cups_dest_t *dest,
 522                            cups_dinfo_t *dinfo,
 523                            int width, int length,
 524                            unsigned flags, cups_size_t *size);
 525
 526 The `media`, `width`, and `length` arguments specify the size to lookup.  The
 527 `flags` argument specifies a bitfield controlling various lookup options:
 528
 529 - `CUPS_MEDIA_FLAGS_DEFAULT`: Find the closest size supported by the printer.
 530 - `CUPS_MEDIA_FLAGS_BORDERLESS`: Find a borderless size.
 531 - `CUPS_MEDIA_FLAGS_DUPLEX`: Find a size compatible with two-sided printing.
 532 - `CUPS_MEDIA_FLAGS_EXACT`: Find an exact match for the size.
 533 - `CUPS_MEDIA_FLAGS_READY`: If the printer supports media sensing or
 534   configuration of the media in each tray/source, find the size amongst the
 535   "ready" media.
 536
 537 If a matching size is found for the destination, the size information is stored
 538 in the structure pointed to by the `size` argument and 1 is returned.  Otherwise
 539 0 is returned.
 540
 541 For example, the following code prints the margins for two-sided printing on US
 542 Letter media:
 543
 544     cups_size_t size;
 545
 546     if (cupsGetDestMediaByName(CUPS_HTTP_DEFAULT, dest, info,
 547                                CUPS_MEDIA_LETTER,
 548                                CUPS_MEDIA_FLAGS_DUPLEX, &size))
 549     {
 550       puts("Margins for duplex US Letter:");
 551       printf("  Bottom: %.2fin\n", size.bottom / 2540.0);
 552       printf("    Left: %.2fin\n", size.left / 2540.0);
 553       printf("   Right: %.2fin\n", size.right / 2540.0);
 554       printf("     Top: %.2fin\n", size.top / 2540.0);
 555     }
 556     else
 557       puts("Margins for duplex US Letter are not available.");
 558
 559 You can also enumerate all of the sizes that match a given `flags` value using
 560 the `cupsGetDestMediaByIndex` and `cupsGetDestMediaCount` functions:
 561
 562     int
 563     cupsGetDestMediaByIndex(http_t *http, cups_dest_t *dest,
 564                             cups_dinfo_t *dinfo, int n,
 565                             unsigned flags, cups_size_t *size);
 566
 567     int
 568     cupsGetDestMediaCount(http_t *http, cups_dest_t *dest,
 569                           cups_dinfo_t *dinfo, unsigned flags);
 570
 571 For example, the following code prints the list of ready media and corresponding
 572 margins:
 573
 574     cups_size_t size;
 575     int i;
 576     int count = cupsGetDestMediaCount(CUPS_HTTP_DEFAULT,
 577                                       dest, info,
 578                                       CUPS_MEDIA_FLAGS_READY);
 579
 580     for (i = 0; i < count; i ++)
 581     {
 582       if (cupsGetDestMediaByIndex(CUPS_HTTP_DEFAULT, dest, info,
 583                                   i, CUPS_MEDIA_FLAGS_READY,
 584                                   &size))
 585       {
 586         printf("%s:\n", size.name);
 587         printf("   Width: %.2fin\n", size.width / 2540.0);
 588         printf("  Length: %.2fin\n", size.length / 2540.0);
 589         printf("  Bottom: %.2fin\n", size.bottom / 2540.0);
 590         printf("    Left: %.2fin\n", size.left / 2540.0);
 591         printf("   Right: %.2fin\n", size.right / 2540.0);
 592         printf("     Top: %.2fin\n", size.top / 2540.0);
 593       }
 594     }
 595
 596 Finally, the `cupsGetDestMediaDefault` function returns the default media size:
 597
 598     int
 599     cupsGetDestMediaDefault(http_t *http, cups_dest_t *dest,
 600                             cups_dinfo_t *dinfo, unsigned flags,
 601                             cups_size_t *size);
 602
 603
 604 ### Localizing Options and Values
 605
 606 CUPS provides three functions to get localized versions of options and values:
 607 `cupsLocalizeDestMedia`, `cupsLocalizeDestOption`, and `cupsLocalizeDestValue`:
 608
 609     const char *
 610     cupsLocalizeDestMedia(http_t *http, cups_dest_t *dest,
 611                           cups_dinfo_t *info, unsigned flags,
 612                           cups_size_t *size);
 613
 614     const char *
 615     cupsLocalizeDestOption(http_t *http, cups_dest_t *dest,
 616                            cups_dinfo_t *info,
 617                            const char *option);
 618
 619     const char *
 620     cupsLocalizeDestValue(http_t *http, cups_dest_t *dest,
 621                           cups_dinfo_t *info,
 622                           const char *option, const char *value);
 623
 624
 625 ## Submitting a Print Job
 626
 627 Once you are ready to submit a print job, you create a job using the
 628 `cupsCreateDestJob` function:
 629
 630     ipp_status_t
 631     cupsCreateDestJob(http_t *http, cups_dest_t *dest,
 632                       cups_dinfo_t *info, int *job_id,
 633                       const char *title, int num_options,
 634                       cups_option_t *options);
 635
 636 The `title` argument specifies a name for the print job such as "My Document".
 637 The `num_options` and `options` arguments specify the options for the print
 638 job which are allocated using the `cupsAddOption` function.
 639
 640 When successful, the job's numeric identifier is stored in the integer pointed
 641 to by the `job_id` argument and `IPP_STATUS_OK` is returned.  Otherwise, an IPP
 642 error status is returned.
 643
 644 For example, the following code creates a new job that will print 42 copies of a
 645 two-sided US Letter document:
 646
 647     int job_id = 0;
 648     int num_options = 0;
 649     cups_option_t *options = NULL;
 650
 651     num_options = cupsAddOption(CUPS_COPIES, "42",
 652                                 num_options, &options);
 653     num_options = cupsAddOption(CUPS_MEDIA, CUPS_MEDIA_LETTER,
 654                                 num_options, &options);
 655     num_options = cupsAddOption(CUPS_SIDES,
 656                                 CUPS_SIDES_TWO_SIDED_PORTRAIT,
 657                                 num_options, &options);
 658
 659     if (cupsCreateDestJob(CUPS_HTTP_DEFAULT, dest, info,
 660                           &job_id, "My Document", num_options,
 661                           options) == IPP_STATUS_OK)
 662       printf("Created job: %d\n", job_id);
 663     else
 664       printf("Unable to create job: %s\n",
 665              cupsLastErrorString());
 666
 667 Once the job is created, you submit documents for the job using the
 668 `cupsStartDestDocument`, `cupsWriteRequestData`, and `cupsFinishDestDocument`
 669 functions:
 670
 671     http_status_t
 672     cupsStartDestDocument(http_t *http, cups_dest_t *dest,
 673                           cups_dinfo_t *info, int job_id,
 674                           const char *docname,
 675                           const char *format,
 676                           int num_options,
 677                           cups_option_t *options,
 678                           int last_document);
 679
 680     http_status_t
 681     cupsWriteRequestData(http_t *http, const char *buffer,
 682                          size_t length);
 683
 684     ipp_status_t
 685     cupsFinishDestDocument(http_t *http, cups_dest_t *dest,
 686                            cups_dinfo_t *info);
 687
 688 The `docname` argument specifies the name of the document, typically the
 689 original filename.  The `format` argument specifies the MIME media type of the
 690 document, including the following constants:
 691
 692 - `CUPS_FORMAT_JPEG`: "image/jpeg"
 693 - `CUPS_FORMAT_PDF`: "application/pdf"
 694 - `CUPS_FORMAT_POSTSCRIPT`: "application/postscript"
 695 - `CUPS_FORMAT_TEXT`: "text/plain"
 696
 697 The `num_options` and `options` arguments specify per-document print options,
 698 which at present must be 0 and `NULL`.  The `last_document` argument specifies
 699 whether this is the last document in the job.
 700
 701 For example, the following code submits a PDF file to the job that was just
 702 created:
 703
 704     FILE *fp = fopen("filename.pdf", "rb");
 705     size_t bytes;
 706     char buffer[65536];
 707
 708     if (cupsStartDestDocument(CUPS_HTTP_DEFAULT, dest, info,
 709                               job_id, "filename.pdf", 0, NULL,
 710                               1) == HTTP_STATUS_CONTINUE)
 711     {
 712       while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0)
 713         if (cupsWriteRequestData(CUPS_HTTP_DEFAULT, buffer,
 714                                  bytes) != HTTP_STATUS_CONTINUE)
 715           break;
 716
 717       if (cupsFinishDestDocument(CUPS_HTTP_DEFAULT, dest,
 718                                  info) == IPP_STATUS_OK)
 719         puts("Document send succeeded.");
 720       else
 721         printf("Document send failed: %s\n",
 722                cupsLastErrorString());
 723     }
 724
 725     fclose(fp);