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_REMOTE` for the `mask` argument.  The following constants can
 157 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` constant passed in the `mask` argument.
 164 - `CUPS_PRINTER_REMOTE`: A remote printer or class.
 165 - `CUPS_PRINTER_BW`: Can do B&W printing.
 166 - `CUPS_PRINTER_COLOR`: Can do color printing.
 167 - `CUPS_PRINTER_DUPLEX`: Can do two-sided printing.
 168 - `CUPS_PRINTER_STAPLE`: Can staple output.
 169 - `CUPS_PRINTER_COLLATE`: Can quickly collate copies.
 170 - `CUPS_PRINTER_PUNCH`: Can punch output.
 171 - `CUPS_PRINTER_COVER`: Can cover output.
 172 - `CUPS_PRINTER_BIND`: Can bind output.
 173 - `CUPS_PRINTER_SORT`: Can sort output (mailboxes, etc.)
 174 - `CUPS_PRINTER_SMALL`: Can print on Letter/Legal/A4-size media.
 175 - `CUPS_PRINTER_MEDIUM`: Can print on Tabloid/B/C/A3/A2-size media.
 176 - `CUPS_PRINTER_LARGE`: Can print on D/E/A1/A0-size media.
 177 - `CUPS_PRINTER_VARIABLE`: Can print on rolls and custom-size media.
 178
 179 The `cb` argument specifies a function to call for every destination that is
 180 found:
 181
 182     typedef int (*cups_dest_cb_t)(void *user_data,
 183                                   unsigned flags,
 184                                   cups_dest_t *dest);
 185
 186 The callback function receives a copy of the `user_data` argument along with a
 187 bitfield \(`flags`) and the destination that was found.  The `flags` argument
 188 can have any of the following constant (bit) values set:
 189
 190 - `CUPS_DEST_FLAGS_MORE`: There are more destinations coming.
 191 - `CUPS_DEST_FLAGS_REMOVED`: The destination has gone away and should be removed
 192   from the list of destinations a user can select.
 193 - `CUPS_DEST_FLAGS_ERROR`: An error occurred.  The reason for the error can be
 194   found by calling the `cupsLastError` and/or `cupsLastErrorString` functions.
 195
 196 The callback function returns 0 to stop enumeration or 1 to continue.
 197
 198 The following example shows how to use `cupsEnumDests` to get a filtered array
 199 of destinations:
 200
 201     typedef struct
 202     {
 203       int num_dests;
 204       cups_dest_t *dests;
 205     } my_user_data_t;
 206
 207     int
 208     my_dest_cb(my_user_data_t *user_data, unsigned flags,
 209                cups_dest_t *dest)
 210     {
 211       if (flags & CUPS_DEST_FLAGS_REMOVED)
 212       {
 213        /*
 214         * Remove destination from array...
 215         */
 216
 217         user_data->num_dests =
 218             cupsRemoveDest(dest->name, dest->instance,
 219                            user_data->num_dests,
 220                            &(user_data->dests));
 221       }
 222       else
 223       {
 224        /*
 225         * Add destination to array...
 226         */
 227
 228         user_data->num_dests =
 229             cupsCopyDest(dest, user_data->num_dests,
 230                          &(user_data->dests));
 231       }
 232
 233       return (1);
 234     }
 235
 236     int
 237     my_get_dests(cups_ptype_t type, cups_ptype_t mask,
 238                  cups_dest_t **dests)
 239     {
 240       my_user_data_t user_data = { 0, NULL };
 241
 242       if (!cupsEnumDests(CUPS_DEST_FLAGS_NONE, 1000, NULL, type,
 243                          mask, (cups_dest_cb_t)my_dest_cb,
 244                          &user_data))
 245       {
 246        /*
 247         * An error occurred, free all of the destinations and
 248         * return...
 249         */
 250
 251         cupsFreeDests(user_data.num_dests, user_dasta.dests);
 252
 253         *dests = NULL;
 254
 255         return (0);
 256       }
 257
 258      /*
 259       * Return the destination array...
 260       */
 261
 262       *dests = user_data.dests;
 263
 264       return (user_data.num_dests);
 265     }
 266
 267
 268 ## Basic Destination Information
 269
 270 The `num_options` and `options` members of the `cups_dest_t` structure provide
 271 basic attributes about the destination in addition to the user default options
 272 and values for that destination.  The following names are predefined for various
 273 destination attributes:
 274
 275 - "auth-info-required": The type of authentication required for printing to this
 276   destination: "none", "username,password", "domain,username,password", or
 277   "negotiate" (Kerberos).
 278 - "printer-info": The human-readable description of the destination such as "My
 279   Laser Printer".
 280 - "printer-is-accepting-jobs": "true" if the destination is accepting new jobs,
 281   "false" otherwise.
 282 - "printer-is-shared": "true" if the destination is being shared with other
 283   computers, "false" otherwise.
 284 - "printer-location": The human-readable location of the destination such as
 285   "Lab 4".
 286 - "printer-make-and-model": The human-readable make and model of the destination
 287   such as "ExampleCorp LaserPrinter 4000 Series".
 288 - "printer-state": "3" if the destination is idle, "4" if the destination is
 289   printing a job, and "5" if the destination is stopped.
 290 - "printer-state-change-time": The UNIX time when the destination entered the
 291   current state.
 292 - "printer-state-reasons": Additional comma-delimited state keywords for the
 293   destination such as "media-tray-empty-error" and "toner-low-warning".
 294 - "printer-type": The `cups_ptype_t` value associated with the destination.
 295
 296 Use the `cupsGetOption` function to retrieve the value.  For example, the
 297 following code gets the make and model of a destination:
 298
 299     const char *model = cupsGetOption("printer-make-and-model",
 300                                       dest->num_options,
 301                                       dest->options);
 302
 303 ## Detailed Destination Information
 304
 305 Once a destination has been chosen, the `cupsCopyDestInfo` function can be used
 306 to gather detailed information about the destination:
 307
 308     cups_dinfo_t *
 309     cupsCopyDestInfo(http_t *http, cups_dest_t *dest);
 310
 311 The `http` argument specifies a connection to the CUPS scheduler and is
 312 typically the constant `CUPS_HTTP_DEFAULT`.  The `dest` argument specifies the
 313 destination to query.
 314
 315 The `cups_dinfo_t` structure that is returned contains a snapshot of the
 316 supported options and their supported, ready, and default values.  It also can
 317 report constraints between different options and values, and recommend changes
 318 to resolve those constraints.
 319
 320 ### Getting Supported Options and Values
 321
 322 The `cupsCheckDestSupported` function can be used to test whether a particular
 323 option or option and value is supported:
 324
 325     int
 326     cupsCheckDestSupported(http_t *http, cups_dest_t *dest,
 327                            cups_dinfo_t *info,
 328                            const char *option,
 329                            const char *value);
 330
 331 The `option` argument specifies the name of the option to check.  The following
 332 constants can be used to check the various standard options:
 333
 334 - `CUPS_COPIES`: Controls the number of copies that are produced.
 335 - `CUPS_FINISHINGS`: A comma-delimited list of integer constants that control
 336   the finishing processes that are applied to the job, including stapling,
 337   punching, and folding.
 338 - `CUPS_MEDIA`: Controls the media size that is used, typically one of the
 339   following: `CUPS_MEDIA_3X5`, `CUPS_MEDIA_4X6`, `CUPS_MEDIA_5X7`,
 340   `CUPS_MEDIA_8X10`, `CUPS_MEDIA_A3`, `CUPS_MEDIA_A4`, `CUPS_MEDIA_A5`,
 341   `CUPS_MEDIA_A6`, `CUPS_MEDIA_ENV10`, `CUPS_MEDIA_ENVDL`, `CUPS_MEDIA_LEGAL`,
 342   `CUPS_MEDIA_LETTER`, `CUPS_MEDIA_PHOTO_L`, `CUPS_MEDIA_SUPERBA3`, or
 343   `CUPS_MEDIA_TABLOID`.
 344 - `CUPS_MEDIA_SOURCE`: Controls where the media is pulled from, typically either
 345   `CUPS_MEDIA_SOURCE_AUTO` or `CUPS_MEDIA_SOURCE_MANUAL`.
 346 - `CUPS_MEDIA_TYPE`: Controls the type of media that is used, typically one of
 347   the following: `CUPS_MEDIA_TYPE_AUTO`, `CUPS_MEDIA_TYPE_ENVELOPE`,
 348   `CUPS_MEDIA_TYPE_LABELS`, `CUPS_MEDIA_TYPE_LETTERHEAD`,
 349   `CUPS_MEDIA_TYPE_PHOTO`, `CUPS_MEDIA_TYPE_PHOTO_GLOSSY`,
 350   `CUPS_MEDIA_TYPE_PHOTO_MATTE`, `CUPS_MEDIA_TYPE_PLAIN`, or
 351   `CUPS_MEDIA_TYPE_TRANSPARENCY`.
 352 - `CUPS_NUMBER_UP`: Controls the number of document pages that are placed on
 353   each media side.
 354 - `CUPS_ORIENTATION`: Controls the orientation of document pages placed on the
 355   media: `CUPS_ORIENTATION_PORTRAIT` or `CUPS_ORIENTATION_LANDSCAPE`.
 356 - `CUPS_PRINT_COLOR_MODE`: Controls whether the output is in color
 357   \(`CUPS_PRINT_COLOR_MODE_COLOR`), grayscale
 358   \(`CUPS_PRINT_COLOR_MODE_MONOCHROME`), or either
 359   \(`CUPS_PRINT_COLOR_MODE_AUTO`).
 360 - `CUPS_PRINT_QUALITY`: Controls the generate quality of the output:
 361   `CUPS_PRINT_QUALITY_DRAFT`, `CUPS_PRINT_QUALITY_NORMAL`, or
 362   `CUPS_PRINT_QUALITY_HIGH`.
 363 - `CUPS_SIDES`: Controls whether prints are placed on one or both sides of the
 364   media: `CUPS_SIDES_ONE_SIDED`, `CUPS_SIDES_TWO_SIDED_PORTRAIT`, or
 365   `CUPS_SIDES_TWO_SIDED_LANDSCAPE`.
 366
 367 If the `value` argument is `NULL`, the `cupsCheckDestSupported` function returns
 368 whether the option is supported by the destination.  Otherwise, the function
 369 returns whether the specified value of the option is supported.
 370
 371 The `cupsFindDestSupported` function returns the IPP attribute containing the
 372 supported values for a given option:
 373
 374      ipp_attribute_t *
 375      cupsFindDestSupported(http_t *http, cups_dest_t *dest,
 376                            cups_dinfo_t *dinfo,
 377                            const char *option);
 378
 379 For example, the following code prints the supported finishing processes for a
 380 destination, if any, to the standard output:
 381
 382     cups_dinfo_t *info = cupsCopyDestInfo(CUPS_HTTP_DEFAULT,
 383                                           dest);
 384
 385     if (cupsCheckDestSupported(CUPS_HTTP_DEFAULT, dest, info,
 386                                CUPS_FINISHINGS, NULL))
 387     {
 388       ipp_attribute_t *finishings =
 389           cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info,
 390                                 CUPS_FINISHINGS);
 391       int i, count = ippGetCount(finishings);
 392
 393       puts("finishings supported:");
 394       for (i = 0; i < count; i ++)
 395         printf("  %d\n", ippGetInteger(finishings, i));
 396     }
 397     else
 398       puts("finishings not supported.");
 399
 400 The "job-creation-attributes" option can be queried to get a list of supported
 401 options.  For example, the following code prints the list of supported options
 402 to the standard output:
 403
 404     ipp_attribute_t *attrs =
 405         cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info,
 406                               "job-creation-attributes");
 407     int i, count = ippGetCount(attrs);
 408
 409     for (i = 0; i < count; i ++)
 410       puts(ippGetString(attrs, i, NULL));
 411
 412
 413 ### Getting Default Values
 414
 415 There are two sets of default values - user defaults that are available via the
 416 `num_options` and `options` members of the `cups_dest_t` structure, and
 417 destination defaults that available via the `cups_dinfo_t` structure and the
 418 `cupsFindDestDefault` function which returns the IPP attribute containing the
 419 default value(s) for a given option:
 420
 421     ipp_attribute_t *
 422     cupsFindDestDefault(http_t *http, cups_dest_t *dest,
 423                         cups_dinfo_t *dinfo,
 424                         const char *option);
 425
 426 The user defaults from `cupsGetOption` should always take preference over the
 427 destination defaults.  For example, the following code prints the default
 428 finishings value(s) to the standard output:
 429
 430     const char *def_value =
 431         cupsGetOption(CUPS_FINISHINGS, dest->num_options,
 432                       dest->options);
 433     ipp_attribute_t *def_attr =
 434         cupsFindDestDefault(CUPS_HTTP_DEFAULT, dest, info,
 435                             CUPS_FINISHINGS);
 436
 437     if (def_value != NULL)
 438     {
 439       printf("Default finishings: %s\n", def_value);
 440     }
 441     else
 442     {
 443       int i, count = ippGetCount(def_attr);
 444
 445       printf("Default finishings: %d",
 446              ippGetInteger(def_attr, 0));
 447       for (i = 1; i < count; i ++)
 448         printf(",%d", ippGetInteger(def_attr, i));
 449       putchar('\n');
 450     }
 451
 452
 453 ### Getting Ready (Loaded) Values
 454
 455 The finishings and media options also support queries for the ready, or loaded,
 456 values.  For example, a printer may have punch and staple finishers installed
 457 but be out of staples - the supported values will list both punch and staple
 458 finishing processes but the ready values will only list the punch processes.
 459 Similarly, a printer may support hundreds of different sizes of media but only
 460 have a single size loaded at any given time - the ready values are limited to
 461 the media that is actually in the printer.
 462
 463 The `cupsFindDestReady` function finds the IPP attribute containing the ready
 464 values for a given option:
 465
 466     ipp_attribute_t *
 467     cupsFindDestReady(http_t *http, cups_dest_t *dest,
 468                       cups_dinfo_t *dinfo, const char *option);
 469
 470 For example, the following code lists the ready finishing processes:
 471
 472     ipp_attribute_t *ready_finishings =
 473         cupsFindDestReady(CUPS_HTTP_DEFAULT, dest, info,
 474                           CUPS_FINISHINGS);
 475
 476     if (ready_finishings != NULL)
 477     {
 478       int i, count = ippGetCount(ready_finishings);
 479
 480       puts("finishings ready:");
 481       for (i = 0; i < count; i ++)
 482         printf("  %d\n", ippGetInteger(ready_finishings, i));
 483     }
 484     else
 485       puts("no finishings are ready.");
 486
 487
 488 ### Media Size Options
 489
 490 CUPS provides functions for querying the dimensions and margins for each of the
 491 supported media size options.  The `cups_size_t` structure is used to describe a
 492 media size:
 493
 494     typedef struct cups_size_s
 495     {
 496       char media[128];
 497       int width, length;
 498       int bottom, left, right, top;
 499     } cups_size_t;
 500
 501 The `width` and `length` members specify the dimensions of the media in
 502 hundredths of millimeters (1/2540th of an inch).  The `bottom`, `left`, `right`,
 503 and `top` members specify the margins of the printable area, also in hundredths
 504 of millimeters.
 505
 506 The `cupsGetDestMediaByName` and `cupsGetDestMediaBySize` functions lookup the
 507 media size information using a standard media size name or dimensions in
 508 hundredths of millimeters:
 509
 510     int
 511     cupsGetDestMediaByName(http_t *http, cups_dest_t *dest,
 512                            cups_dinfo_t *dinfo,
 513                            const char *media,
 514                            unsigned flags, cups_size_t *size);
 515
 516     int
 517     cupsGetDestMediaBySize(http_t *http, cups_dest_t *dest,
 518                            cups_dinfo_t *dinfo,
 519                            int width, int length,
 520                            unsigned flags, cups_size_t *size);
 521
 522 The `media`, `width`, and `length` arguments specify the size to lookup.  The
 523 `flags` argument specifies a bitfield controlling various lookup options:
 524
 525 - `CUPS_MEDIA_FLAGS_DEFAULT`: Find the closest size supported by the printer.
 526 - `CUPS_MEDIA_FLAGS_BORDERLESS`: Find a borderless size.
 527 - `CUPS_MEDIA_FLAGS_DUPLEX`: Find a size compatible with two-sided printing.
 528 - `CUPS_MEDIA_FLAGS_EXACT`: Find an exact match for the size.
 529 - `CUPS_MEDIA_FLAGS_READY`: If the printer supports media sensing or
 530   configuration of the media in each tray/source, find the size amongst the
 531   "ready" media.
 532
 533 If a matching size is found for the destination, the size information is stored
 534 in the structure pointed to by the `size` argument and 1 is returned.  Otherwise
 535 0 is returned.
 536
 537 For example, the following code prints the margins for two-sided printing on US
 538 Letter media:
 539
 540     cups_size_t size;
 541
 542     if (cupsGetDestMediaByName(CUPS_HTTP_DEFAULT, dest, info,
 543                                CUPS_MEDIA_LETTER,
 544                                CUPS_MEDIA_FLAGS_DUPLEX, &size))
 545     {
 546       puts("Margins for duplex US Letter:");
 547       printf("  Bottom: %.2fin\n", size.bottom / 2540.0);
 548       printf("    Left: %.2fin\n", size.left / 2540.0);
 549       printf("   Right: %.2fin\n", size.right / 2540.0);
 550       printf("     Top: %.2fin\n", size.top / 2540.0);
 551     }
 552     else
 553       puts("Margins for duplex US Letter are not available.");
 554
 555 You can also enumerate all of the sizes that match a given `flags` value using
 556 the `cupsGetDestMediaByIndex` and `cupsGetDestMediaCount` functions:
 557
 558     int
 559     cupsGetDestMediaByIndex(http_t *http, cups_dest_t *dest,
 560                             cups_dinfo_t *dinfo, int n,
 561                             unsigned flags, cups_size_t *size);
 562
 563     int
 564     cupsGetDestMediaCount(http_t *http, cups_dest_t *dest,
 565                           cups_dinfo_t *dinfo, unsigned flags);
 566
 567 For example, the following code prints the list of ready media and corresponding
 568 margins:
 569
 570     cups_size_t size;
 571     int i;
 572     int count = cupsGetDestMediaCount(CUPS_HTTP_DEFAULT,
 573                                       dest, info,
 574                                       CUPS_MEDIA_FLAGS_READY);
 575
 576     for (i = 0; i < count; i ++)
 577     {
 578       if (cupsGetDestMediaByIndex(CUPS_HTTP_DEFAULT, dest, info,
 579                                   i, CUPS_MEDIA_FLAGS_READY,
 580                                   &size))
 581       {
 582         printf("%s:\n", size.name);
 583         printf("   Width: %.2fin\n", size.width / 2540.0);
 584         printf("  Length: %.2fin\n", size.length / 2540.0);
 585         printf("  Bottom: %.2fin\n", size.bottom / 2540.0);
 586         printf("    Left: %.2fin\n", size.left / 2540.0);
 587         printf("   Right: %.2fin\n", size.right / 2540.0);
 588         printf("     Top: %.2fin\n", size.top / 2540.0);
 589       }
 590     }
 591
 592 Finally, the `cupsGetDestMediaDefault` function returns the default media size:
 593
 594     int
 595     cupsGetDestMediaDefault(http_t *http, cups_dest_t *dest,
 596                             cups_dinfo_t *dinfo, unsigned flags,
 597                             cups_size_t *size);
 598
 599
 600 ### Localizing Options and Values
 601
 602 CUPS provides three functions to get localized versions of options and values:
 603 `cupsLocalizeDestMedia`, `cupsLocalizeDestOption`, and `cupsLocalizeDestValue`:
 604
 605     const char *
 606     cupsLocalizeDestMedia(http_t *http, cups_dest_t *dest,
 607                           cups_dinfo_t *info, unsigned flags,
 608                           cups_size_t *size);
 609
 610     const char *
 611     cupsLocalizeDestOption(http_t *http, cups_dest_t *dest,
 612                            cups_dinfo_t *info,
 613                            const char *option);
 614
 615     const char *
 616     cupsLocalizeDestValue(http_t *http, cups_dest_t *dest,
 617                           cups_dinfo_t *info,
 618                           const char *option, const char *value);
 619
 620
 621 ## Submitting a Print Job
 622
 623 Once you are ready to submit a print job, you create a job using the
 624 `cupsCreateDestJob` function:
 625
 626     ipp_status_t
 627     cupsCreateDestJob(http_t *http, cups_dest_t *dest,
 628                       cups_dinfo_t *info, int *job_id,
 629                       const char *title, int num_options,
 630                       cups_option_t *options);
 631
 632 The `title` argument specifies a name for the print job such as "My Document".
 633 The `num_options` and `options` arguments specify the options for the print
 634 job which are allocated using the `cupsAddOption` function.
 635
 636 When successful, the job's numeric identifier is stored in the integer pointed
 637 to by the `job_id` argument and `IPP_STATUS_OK` is returned.  Otherwise, an IPP
 638 error status is returned.
 639
 640 For example, the following code creates a new job that will print 42 copies of a
 641 two-sided US Letter document:
 642
 643     int job_id = 0;
 644     int num_options = 0;
 645     cups_option_t *options = NULL;
 646
 647     num_options = cupsAddOption(CUPS_COPIES, "42",
 648                                 num_options, &options);
 649     num_options = cupsAddOption(CUPS_MEDIA, CUPS_MEDIA_LETTER,
 650                                 num_options, &options);
 651     num_options = cupsAddOption(CUPS_SIDES,
 652                                 CUPS_SIDES_TWO_SIDED_PORTRAIT,
 653                                 num_options, &options);
 654
 655     if (cupsCreateDestJob(CUPS_HTTP_DEFAULT, dest, info,
 656                           &job_id, "My Document", num_options,
 657                           options) == IPP_STATUS_OK)
 658       printf("Created job: %d\n", job_id);
 659     else
 660       printf("Unable to create job: %s\n",
 661              cupsLastErrorString());
 662
 663 Once the job is created, you submit documents for the job using the
 664 `cupsStartDestDocument`, `cupsWriteRequestData`, and `cupsFinishDestDocument`
 665 functions:
 666
 667     http_status_t
 668     cupsStartDestDocument(http_t *http, cups_dest_t *dest,
 669                           cups_dinfo_t *info, int job_id,
 670                           const char *docname,
 671                           const char *format,
 672                           int num_options,
 673                           cups_option_t *options,
 674                           int last_document);
 675
 676     http_status_t
 677     cupsWriteRequestData(http_t *http, const char *buffer,
 678                          size_t length);
 679
 680     ipp_status_t
 681     cupsFinishDestDocument(http_t *http, cups_dest_t *dest,
 682                            cups_dinfo_t *info);
 683
 684 The `docname` argument specifies the name of the document, typically the
 685 original filename.  The `format` argument specifies the MIME media type of the
 686 document, including the following constants:
 687
 688 - `CUPS_FORMAT_JPEG`: "image/jpeg"
 689 - `CUPS_FORMAT_PDF`: "application/pdf"
 690 - `CUPS_FORMAT_POSTSCRIPT`: "application/postscript"
 691 - `CUPS_FORMAT_TEXT`: "text/plain"
 692
 693 The `num_options` and `options` arguments specify per-document print options,
 694 which at present must be 0 and `NULL`.  The `last_document` argument specifies
 695 whether this is the last document in the job.
 696
 697 For example, the following code submits a PDF file to the job that was just
 698 created:
 699
 700     FILE *fp = fopen("filename.pdf", "rb");
 701     size_t bytes;
 702     char buffer[65536];
 703
 704     if (cupsStartDestDocument(CUPS_HTTP_DEFAULT, dest, info,
 705                               job_id, "filename.pdf", 0, NULL,
 706                               1) == HTTP_STATUS_CONTINUE)
 707     {
 708       while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0)
 709         if (cupsWriteRequestData(CUPS_HTTP_DEFAULT, buffer,
 710                                  bytes) != HTTP_STATUS_CONTINUE)
 711           break;
 712
 713       if (cupsFinishDestDocument(CUPS_HTTP_DEFAULT, dest,
 714                                  info) == IPP_STATUS_OK)
 715         puts("Document send succeeded.");
 716       else
 717         printf("Document send failed: %s\n",
 718                cupsLastErrorString());
 719     }
 720
 721     fclose(fp);