diff options
-rw-r--r-- | cups/Makefile | 50 | ||||
-rw-r--r-- | cups/cups.h | 18 | ||||
-rw-r--r-- | cups/cupspm.md | 1489 | ||||
-rw-r--r-- | cups/dest.c | 10 | ||||
-rw-r--r-- | doc/Makefile | 6 | ||||
-rw-r--r-- | doc/help/api-admin.html | 55 | ||||
-rw-r--r-- | doc/help/api-array.html | 1074 | ||||
-rw-r--r-- | doc/help/api-cups.html | 3587 | ||||
-rw-r--r-- | doc/help/api-filedir.html | 1005 | ||||
-rw-r--r-- | doc/help/api-filter.html | 89 | ||||
-rw-r--r-- | doc/help/api-httpipp.html | 6742 | ||||
-rw-r--r-- | doc/help/api-overview.html | 516 | ||||
-rw-r--r-- | doc/help/api-ppd.html | 531 | ||||
-rw-r--r-- | doc/help/cupspm.epub | bin | 0 -> 58626 bytes | |||
-rw-r--r-- | doc/help/cupspm.html | 10312 | ||||
-rw-r--r-- | packaging/cups.list.in | 3 | ||||
-rw-r--r-- | packaging/cups.spec.in | 1 |
17 files changed, 11224 insertions, 14264 deletions
diff --git a/cups/Makefile b/cups/Makefile index 1df7d8552..00a97bc91 100644 --- a/cups/Makefile +++ b/cups/Makefile @@ -571,56 +571,27 @@ tlscheck: tlscheck.o $(LIBCUPSSTATIC) apihelp: echo Generating CUPS API help files... - mxmldoc --section "Programming" \ - --title "Introduction to CUPS Programming" \ - --css ../doc/cups-printable.css \ - --header api-overview.header --intro api-overview.shtml \ - >../doc/help/api-overview.html + mxmldoc --section "Programming" --body cupspm.md \ + cupspm.xml \ + array.[ch] auth.c cups.h dest*.c dir.[ch] encode.c \ + file.[ch] http.h http*.c ipp.h ipp*.c language.[ch] \ + notify.c options.c pwg.h pwg-media.c tempfile.c \ + tls-darwin.c usersys.c util.c \ + --epub ../doc/help/cupspm.epub + mxmldoc --section "Programming" --body cupspm.md \ + cupspm.xml > ../doc/help/cupspm.html + $(RM) cupspm.xml mxmldoc --section "Programming" --title "Administration APIs" \ --css ../doc/cups-printable.css \ --header api-admin.header --intro api-admin.shtml \ api-admin.xml \ adminutil.c adminutil.h getdevices.c >../doc/help/api-admin.html - mxmldoc --tokens help/api-admin.html api-admin.xml >../doc/help/api-admin.tokens $(RM) api-admin.xml - mxmldoc --section "Programming" --title "Array API" \ - --css ../doc/cups-printable.css \ - --header api-array.header --intro api-array.shtml \ - api-array.xml \ - array.h array.c >../doc/help/api-array.html - mxmldoc --tokens help/api-array.html api-array.xml >../doc/help/api-array.tokens - $(RM) api-array.xml - mxmldoc --section "Programming" --title "CUPS API" \ - --css ../doc/cups-printable.css \ - --header api-cups.header --intro api-cups.shtml \ - api-cups.xml \ - cups.h pwg.h adminutil.c dest*.c language.c notify.c \ - options.c pwg-media.c tempfile.c usersys.c \ - util.c >../doc/help/api-cups.html - mxmldoc --tokens help/api-cups.html api-cups.xml >../doc/help/api-cups.tokens - $(RM) api-cups.xml - mxmldoc --section "Programming" --title "File and Directory APIs" \ - --css ../doc/cups-printable.css \ - --header api-filedir.header --intro api-filedir.shtml \ - api-filedir.xml \ - file.h file.c dir.h dir.c >../doc/help/api-filedir.html - mxmldoc --tokens api-filedir.xml >../doc/help/api-filedir.tokens - $(RM) api-filedir.xml mxmldoc --section "Programming" --title "PPD API (DEPRECATED)" \ --css ../doc/cups-printable.css \ --header api-ppd.header --intro api-ppd.shtml \ api-ppd.xml ppd.h ppd-*.c >../doc/help/api-ppd.html - mxmldoc --tokens help/api-ppd.html api-ppd.xml >../doc/help/api-ppd.tokens $(RM) api-ppd.xml - mxmldoc --section "Programming" --title "HTTP and IPP APIs" \ - --css ../doc/cups-printable.css \ - --header api-httpipp.header --intro api-httpipp.shtml \ - api-httpipp.xml \ - http.h ipp.h auth.c getdevices.c getputfile.c encode.c \ - http.c http-addr.c http-support.c ipp.c ipp-support.c \ - md5passwd.c request.c >../doc/help/api-httpipp.html - mxmldoc --tokens help/api-httpipp.html api-httpipp.xml >../doc/help/api-httpipp.tokens - $(RM) api-httpipp.xml mxmldoc --section "Programming" \ --title "Filter and Backend Programming" \ --css ../doc/cups-printable.css \ @@ -628,7 +599,6 @@ apihelp: api-filter.xml \ backchannel.c backend.h backend.c sidechannel.c sidechannel.h \ >../doc/help/api-filter.html - mxmldoc --tokens help/api-filter.html api-filter.xml >../doc/help/api-filter.tokens $(RM) api-filter.xml diff --git a/cups/cups.h b/cups/cups.h index 7e117bae6..b2419f1b5 100644 --- a/cups/cups.h +++ b/cups/cups.h @@ -78,7 +78,7 @@ extern "C" { # define CUPS_DEST_FLAGS_NONE 0x00 /* No flags are set */ # define CUPS_DEST_FLAGS_UNCONNECTED 0x01 - /* There is not connection */ + /* There is no connection */ # define CUPS_DEST_FLAGS_MORE 0x02 /* There are more destinations */ # define CUPS_DEST_FLAGS_REMOVED 0x04 @@ -207,18 +207,18 @@ enum cups_ptype_e /* Printer type/capability bit CUPS_PRINTER_REMOTE = 0x0002, /* Remote printer or class */ CUPS_PRINTER_BW = 0x0004, /* Can do B&W printing */ CUPS_PRINTER_COLOR = 0x0008, /* Can do color printing */ - CUPS_PRINTER_DUPLEX = 0x0010, /* Can do duplexing */ + CUPS_PRINTER_DUPLEX = 0x0010, /* Can do two-sided printing */ CUPS_PRINTER_STAPLE = 0x0020, /* Can staple output */ - CUPS_PRINTER_COPIES = 0x0040, /* Can do copies */ - CUPS_PRINTER_COLLATE = 0x0080, /* Can collage copies */ + CUPS_PRINTER_COPIES = 0x0040, /* Can do copies in hardware */ + CUPS_PRINTER_COLLATE = 0x0080, /* Can quickly collate copies */ CUPS_PRINTER_PUNCH = 0x0100, /* Can punch output */ CUPS_PRINTER_COVER = 0x0200, /* Can cover output */ CUPS_PRINTER_BIND = 0x0400, /* Can bind output */ CUPS_PRINTER_SORT = 0x0800, /* Can sort output */ - CUPS_PRINTER_SMALL = 0x1000, /* Can do Letter/Legal/A4 */ - CUPS_PRINTER_MEDIUM = 0x2000, /* Can do Tabloid/B/C/A3/A2 */ - CUPS_PRINTER_LARGE = 0x4000, /* Can do D/E/A1/A0 */ - CUPS_PRINTER_VARIABLE = 0x8000, /* Can do variable sizes */ + CUPS_PRINTER_SMALL = 0x1000, /* Can print on Letter/Legal/A4-size media */ + CUPS_PRINTER_MEDIUM = 0x2000, /* Can print on Tabloid/B/C/A3/A2-size media */ + CUPS_PRINTER_LARGE = 0x4000, /* Can print on D/E/A1/A0-size media */ + CUPS_PRINTER_VARIABLE = 0x8000, /* Can print on rolls and custom-size media */ CUPS_PRINTER_IMPLICIT = 0x10000, /* Implicit class @private@ * @since Deprecated@ */ CUPS_PRINTER_DEFAULT = 0x20000, /* Default printer on network */ @@ -269,7 +269,7 @@ typedef struct cups_job_s /**** Job ****/ int id; /* The job ID */ char *dest; /* Printer or class name */ char *title; /* Title/job name */ - char *user; /* User the submitted the job */ + char *user; /* User that submitted the job */ char *format; /* Document format */ ipp_jstate_t state; /* Job state */ int size; /* Size in kilobytes */ diff --git a/cups/cupspm.md b/cups/cupspm.md index 120612809..704cc1a20 100644 --- a/cups/cupspm.md +++ b/cups/cupspm.md @@ -5,6 +5,12 @@ copyright: Copyright (c) 2007-2017 by Apple Inc. All Rights Reserved. version: 2.2.4 ... +> Note: This document is under active development and is incomplete, with a goal +> completing it prior to releasing CUPS 2.2.4. Please +> [file issues on Github](https://github.com/apple/cups/issues) +> to provide any feedback. + + # Introduction CUPS provides the "cups" library to talk to the different parts of CUPS and with @@ -110,1011 +116,606 @@ and libraries (`cups-config --libs`) needed for the local system. # Working with Destinations +Destinations, which in CUPS represent individual printers or classes +(collections) of printers, are represented by the `cups_dest_t` structure which +includes the name \(`name`), instance \(`instance`, saved options/settings), +whether the destination is the default for the user \(`is_default`), and the +options and attributes associated with that destination \(`num_options` and +`options`). -## Finding Available Destinations - - -## Getting Information About a Destination - - -### Getting Supported Options and Values - -cupsCheckDestSupported and cups +Historically destinations have been manually maintained by the administrator of +a system or network, but CUPS also supports dynamic discovery of destinations on +the current network. -### Getting Default Options and Values -### Getting Ready Options and Values +## Finding Available Destinations -### Media Options +The `cupsEnumDests` function finds all of the available destinations: + + int + cupsEnumDests(unsigned flags, int msec, int *cancel, + cups_ptype_t type, cups_ptype_t mask, + cups_dest_cb_t cb, void *user_data) + +The `flags` argument specifies enumeration options, which at present must be +`CUPS_DEST_FLAGS_NONE`. + +The `msec` argument specifies the maximum amount of time that should be used for +enumeration in milliseconds - interactive applications should keep this value to +5000 or less when run on the main thread. + +The `cancel` argument points to an integer variable that, when set to a non-zero +value, will cause enumeration to stop as soon as possible. It can be `NULL` if +not needed. + +The `type` and `mask` arguments are bitfields that allow the caller to filter +the destinations based on categories and/or capabilities. The destination's +"printer-type" value is masked by the `mask` value and compared to the `type` +value when filtering. For example, to only enumerate destinations that are +hosted on the local system, pass `CUPS_PRINTER_LOCAL` for the `type` argument +and `CUPS_PRINTER_REMOTE` for the `mask` argument. The following constants can +be used for filtering: + +- `CUPS_PRINTER_CLASS`: A collection of destinations. +- `CUPS_PRINTER_FAX`: A facsimile device. +- `CUPS_PRINTER_LOCAL`: A local printer or class. This constant has the value 0 + (no bits set) and is only used for the `type` argument and is paired with the + `CUPS_PRINTER_REMOTE` constant passed in the `mask` argument. +- `CUPS_PRINTER_REMOTE`: A remote printer or class. +- `CUPS_PRINTER_BW`: Can do B&W printing. +- `CUPS_PRINTER_COLOR`: Can do color printing. +- `CUPS_PRINTER_DUPLEX`: Can do two-sided printing. +- `CUPS_PRINTER_STAPLE`: Can staple output. +- `CUPS_PRINTER_COLLATE`: Can quickly collate copies. +- `CUPS_PRINTER_PUNCH`: Can punch output. +- `CUPS_PRINTER_COVER`: Can cover output. +- `CUPS_PRINTER_BIND`: Can bind output. +- `CUPS_PRINTER_SORT`: Can sort output (mailboxes, etc.) +- `CUPS_PRINTER_SMALL`: Can print on Letter/Legal/A4-size media. +- `CUPS_PRINTER_MEDIUM`: Can print on Tabloid/B/C/A3/A2-size media. +- `CUPS_PRINTER_LARGE`: Can print on D/E/A1/A0-size media. +- `CUPS_PRINTER_VARIABLE`: Can print on rolls and custom-size media. + +The `cb` argument specifies a function to call for every destination that is +found: + + typedef int (*cups_dest_cb_t)(void *user_data, + unsigned flags, + cups_dest_t *dest); + +The callback function receives a copy of the `user_data` argument along with a +bitfield \(`flags`) and the destination that was found. The `flags` argument +can have any of the following constant (bit) values set: + +- `CUPS_DEST_FLAGS_MORE`: There are more destinations coming. +- `CUPS_DEST_FLAGS_REMOVED`: The destination has gone away and should be removed + from the list of destinations a user can select. +- `CUPS_DEST_FLAGS_ERROR`: An error occurred. The reason for the error can be + found by calling the `cupsLastError` and/or `cupsLastErrorString` functions. + +The callback function returns 0 to stop enumeration or 1 to continue. + +The following example shows how to use `cupsEnumDests` to get a filtered array +of destinations: + + typedef struct + { + int num_dests; + cups_dest_t *dests; + } my_user_data_t; -### Other Standard Options + int + my_dest_cb(my_user_data_t *user_data, unsigned flags, + cups_dest_t *dest) + { + if (flags & CUPS_DEST_FLAGS_REMOVED) + { + /* + * Remove destination from array... + */ + + user_data->num_dests = + cupsRemoveDest(dest->name, dest->instance, + user_data->num_dests, + &(user_data->dests)); + } + else + { + /* + * Add destination to array... + */ -### Localizing Options and Values + user_data->num_dests = + cupsCopyDest(dest, user_data->num_dests, + &(user_data->dests)); + } -## Submitting a Print Job + return (1); + } -## Canceling a Print Job + int + my_get_dests(cups_ptype_t type, cups_ptype_t mask, + cups_dest_t **dests) + { + my_user_data_t user_data = { 0, NULL }; + if (!cupsEnumDests(CUPS_DEST_FLAGS_NONE, 1000, NULL, type, + mask, (cups_dest_cb_t)my_dest_cb, + &user_data)) + { + /* + * An error occurred, free all of the destinations and + * return... + */ -# IPP Requests and Responses + cupsFreeDests(user_data.num_dests, user_dasta.dests); -Why you'd want to do this, etc. + *dests = NULL; + return (0); + } -## Connecting to a Destination + /* + * Return the destination array... + */ -## Sending an IPP Request + *dests = user_data.dests; -## Getting the IPP Response + return (user_data.num_dests); + } -## Handling Authentication -## Handling Certificate Validation +## Basic Destination Information + +The `num_options` and `options` members of the `cups_dest_t` structure provide +basic attributes about the destination in addition to the user default options +and values for that destination. The following names are predefined for various +destination attributes: + +- "auth-info-required": The type of authentication required for printing to this + destination: "none", "username,password", "domain,username,password", or + "negotiate" (Kerberos). +- "printer-info": The human-readable description of the destination such as "My + Laser Printer". +- "printer-is-accepting-jobs": "true" if the destination is accepting new jobs, + "false" otherwise. +- "printer-is-shared": "true" if the destination is being shared with other + computers, "false" otherwise. +- "printer-location": The human-readable location of the destination such as + "Lab 4". +- "printer-make-and-model": The human-readable make and model of the destination + such as "ExampleCorp LaserPrinter 4000 Series". +- "printer-state": "3" if the destination is idle, "4" if the destination is + printing a job, and "5" if the destination is stopped. +- "printer-state-change-time": The UNIX time when the destination entered the + current state. +- "printer-state-reasons": Additional comma-delimited state keywords for the + destination such as "media-tray-empty-error" and "toner-low-warning". +- "printer-type": The `cups_ptype_t` value associated with the destination. + +Use the `cupsGetOption` function to retrieve the value. For example, the +following code gets the make and model of a destination: + + const char *model = cupsGetOption("printer-make-and-model", + dest->num_options, + dest->options); + +## Detailed Destination Information + +Once a destination has been chosen, the `cupsCopyDestInfo` function can be used +to gather detailed information about the destination: + + cups_dinfo_t * + cupsCopyDestInfo(http_t *http, cups_dest_t *dest); + +The `http` argument specifies a connection to the CUPS scheduler and is +typically the constant `CUPS_HTTP_DEFAULT`. The `dest` argument specifies the +destination to query. + +The `cups_dinfo_t` structure that is returned contains a snapshot of the +supported options and their supported, ready, and default values. It also can +report constraints between different options and values, and recommend changes +to resolve those constraints. +### Getting Supported Options and Values +The `cupsCheckDestSupported` function can be used to test whether a particular +option or option and value is supported: + + int + cupsCheckDestSupported(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, + const char *option, + const char *value); + +The `option` argument specifies the name of the option to check. The following +constants can be used to check the various standard options: + +- `CUPS_COPIES`: Controls the number of copies that are produced. +- `CUPS_FINISHINGS`: A comma-delimited list of integer constants that control + the finishing processes that are applied to the job, including stapling, + punching, and folding. +- `CUPS_MEDIA`: Controls the media size that is used, typically one of the + following: `CUPS_MEDIA_3X5`, `CUPS_MEDIA_4X6`, `CUPS_MEDIA_5X7`, + `CUPS_MEDIA_8X10`, `CUPS_MEDIA_A3`, `CUPS_MEDIA_A4`, `CUPS_MEDIA_A5`, + `CUPS_MEDIA_A6`, `CUPS_MEDIA_ENV10`, `CUPS_MEDIA_ENVDL`, `CUPS_MEDIA_LEGAL`, + `CUPS_MEDIA_LETTER`, `CUPS_MEDIA_PHOTO_L`, `CUPS_MEDIA_SUPERBA3`, or + `CUPS_MEDIA_TABLOID`. +- `CUPS_MEDIA_SOURCE`: Controls where the media is pulled from, typically either + `CUPS_MEDIA_SOURCE_AUTO` or `CUPS_MEDIA_SOURCE_MANUAL`. +- `CUPS_MEDIA_TYPE`: Controls the type of media that is used, typically one of + the following: `CUPS_MEDIA_TYPE_AUTO`, `CUPS_MEDIA_TYPE_ENVELOPE`, + `CUPS_MEDIA_TYPE_LABELS`, `CUPS_MEDIA_TYPE_LETTERHEAD`, + `CUPS_MEDIA_TYPE_PHOTO`, `CUPS_MEDIA_TYPE_PHOTO_GLOSSY`, + `CUPS_MEDIA_TYPE_PHOTO_MATTE`, `CUPS_MEDIA_TYPE_PLAIN`, or + `CUPS_MEDIA_TYPE_TRANSPARENCY`. +- `CUPS_NUMBER_UP`: Controls the number of document pages that are placed on + each media side. +- `CUPS_ORIENTATION`: Controls the orientation of document pages placed on the + media: `CUPS_ORIENTATION_PORTRAIT` or `CUPS_ORIENTATION_LANDSCAPE`. +- `CUPS_PRINT_COLOR_MODE`: Controls whether the output is in color + \(`CUPS_PRINT_COLOR_MODE_COLOR`), grayscale + \(`CUPS_PRINT_COLOR_MODE_MONOCHROME`), or either + \(`CUPS_PRINT_COLOR_MODE_AUTO`). +- `CUPS_PRINT_QUALITY`: Controls the generate quality of the output: + `CUPS_PRINT_QUALITY_DRAFT`, `CUPS_PRINT_QUALITY_NORMAL`, or + `CUPS_PRINT_QUALITY_HIGH`. +- `CUPS_SIDES`: Controls whether prints are placed on one or both sides of the + media: `CUPS_SIDES_ONE_SIDED`, `CUPS_SIDES_TWO_SIDED_PORTRAIT`, or + `CUPS_SIDES_TWO_SIDED_LANDSCAPE`. + +If the `value` argument is `NULL`, the `cupsCheckDestSupported` function returns +whether the option is supported by the destination. Otherwise, the function +returns whether the specified value of the option is supported. + +The `cupsFindDestSupported` function returns the IPP attribute containing the +supported values for a given option: + + ipp_attribute_t * + cupsFindDestSupported(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, + const char *option); + +For example, the following code prints the supported finishing processes for a +destination, if any, to the standard output: + + cups_dinfo_t *info = cupsCopyDestInfo(CUPS_HTTP_DEFAULT, + dest); + + if (cupsCheckDestSupported(CUPS_HTTP_DEFAULT, dest, info, + CUPS_FINISHINGS, NULL)) + { + ipp_attribute_t *finishings = + cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info, + CUPS_FINISHINGS); + int i, count = ippGetCount(finishings); + + puts("finishings supported:"); + for (i = 0; i < count; i ++) + printf(" %d\n", ippGetInteger(finishings, i)); + } + else + puts("finishings not supported."); +The "job-creation-attributes" option can be queried to get a list of supported +options. For example, the following code prints the list of supported options +to the standard output: + ipp_attribute_t *attrs = + cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info, + "job-creation-attributes"); + int i, count = ippGetCount(attrs); + for (i = 0; i < count; i ++) + puts(ippGetString(attrs, i, NULL)); +### Getting Default Values +There are two sets of default values - user defaults that are available via the +`num_options` and `options` members of the `cups_dest_t` structure, and +destination defaults that available via the `cups_dinfo_t` structure and the +`cupsFindDestDefault` function which returns the IPP attribute containing the +default value(s) for a given option: + ipp_attribute_t * + cupsFindDestDefault(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, + const char *option); +The user defaults from `cupsGetOption` should always take preference over the +destination defaults. For example, the following code prints the default +finishings value(s) to the standard output: + const char *def_value = + cupsGetOption(CUPS_FINISHINGS, dest->num_options, + dest->options); + ipp_attribute_t *def_attr = + cupsFindDestDefault(CUPS_HTTP_DEFAULT, dest, info, + CUPS_FINISHINGS); + if (def_value != NULL) + { + printf("Default finishings: %s\n", def_value); + } + else + { + int i, count = ippGetCount(def_attr); + printf("Default finishings: %d", + ippGetInteger(def_attr, 0)); + for (i = 1; i < count; i ++) + printf(",%d", ippGetInteger(def_attr, i)); + putchar('\n'); + } +### Getting Ready (Loaded) Values +The finishings and media options also support queries for the ready, or loaded, +values. For example, a printer may have punch and staple finishers installed +but be out of staples - the supported values will list both punch and staple +finishing processes but the ready values will only list the punch processes. +Similarly, a printer may support hundreds of different sizes of media but only +have a single size loaded at any given time - the ready values are limited to +the media that is actually in the printer. +The `cupsFindDestReady` function finds the IPP attribute containing the ready +values for a given option: + ipp_attribute_t * + cupsFindDestReady(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, const char *option); -<h3><a name='PRINTERS_AND_CLASSES'>Printers and Classes</a></h3> +For example, the following code lists the ready finishing processes: -<p>Printers and classes (collections of printers) are accessed through -the <a href="#cups_dest_t"><code>cups_dest_t</code></a> structure which -includes the name (<code>name</code>), instance (<code>instance</code> - -a way of selecting certain saved options/settings), and the options and -attributes associated with that destination (<code>num_options</code> and -<code>options</code>). Destinations are created using the -<a href="#cupsGetDests"><code>cupsGetDests</code></a> function and freed -using the <a href='#cupsFreeDests'><code>cupsFreeDests</code></a> function. -The <a href='#cupsGetDest'><code>cupsGetDest</code></a> function finds a -specific destination for printing:</p> + ipp_attribute_t *ready_finishings = + cupsFindDestReady(CUPS_HTTP_DEFAULT, dest, info, + CUPS_FINISHINGS); -<pre class='example'> -#include <cups/cups.h> + if (ready_finishings != NULL) + { + int i, count = ippGetCount(ready_finishings); -<a href='#cups_dest_t'>cups_dest_t</a> *dests; -int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests); -<a href='#cups_dest_t'>cups_dest_t</a> *dest = <a href='#cupsGetDest'>cupsGetDest</a>("name", NULL, num_dests, dests); + puts("finishings ready:"); + for (i = 0; i < count; i ++) + printf(" %d\n", ippGetInteger(ready_finishings, i)); + } + else + puts("no finishings are ready."); -/* do something with dest */ -<a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests); -</pre> +### Media Size Options -<p>Passing <code>NULL</code> to -<a href='#cupsGetDest'><code>cupsGetDest</code></a> for the destination name -will return the default destination. Similarly, passing a <code>NULL</code> -instance will return the default instance for that destination.</p> +CUPS provides functions for querying the dimensions and margins for each of the +supported media size options. The `cups_size_t` structure is used to describe a +media size: -<div class='table'><table summary='Table 1: Printer Attributes' width='80%'> -<caption>Table 1: <a name='TABLE1'>Printer Attributes</a></caption> -<thead> -<tr> - <th>Attribute Name</th> - <th>Description</th> -</tr> -</thead> -<tbody> -<tr> - <td>"auth-info-required"</td> - <td>The type of authentication required for printing to this - destination: "none", "username,password", "domain,username,password", - or "negotiate" (Kerberos)</td> -</tr> -<tr> - <td>"printer-info"</td> - <td>The human-readable description of the destination such as "My - Laser Printer".</td> -</tr> -<tr> - <td>"printer-is-accepting-jobs"</td> - <td>"true" if the destination is accepting new jobs, "false" if - not.</td> -</tr> -<tr> - <td>"printer-is-shared"</td> - <td>"true" if the destination is being shared with other computers, - "false" if not.</td> -</tr> -<tr> - <td>"printer-location"</td> - <td>The human-readable location of the destination such as "Lab 4".</td> -</tr> -<tr> - <td>"printer-make-and-model"</td> - <td>The human-readable make and model of the destination such as "HP - LaserJet 4000 Series".</td> -</tr> -<tr> - <td>"printer-state"</td> - <td>"3" if the destination is idle, "4" if the destination is printing - a job, and "5" if the destination is stopped.</td> -</tr> -<tr> - <td>"printer-state-change-time"</td> - <td>The UNIX time when the destination entered the current state.</td> -</tr> -<tr> - <td>"printer-state-reasons"</td> - <td>Additional comma-delimited state keywords for the destination - such as "media-tray-empty-error" and "toner-low-warning".</td> -</tr> -<tr> - <td>"printer-type"</td> - <td>The <a href='#cups_printer_t'><code>cups_printer_t</code></a> - value associated with the destination.</td> -</tr> -</tbody> -</table></div> - -<h3><a name='OPTIONS'>Options</a></h3> - -<p>Options are stored in arrays of -<a href='#cups_option_t'><code>cups_option_t</code></a> structures. Each -option has a name (<code>name</code>) and value (<code>value</code>) -associated with it. The <a href='#cups_dest_t'><code>cups_dest_t</code></a> -<code>num_options</code> and <code>options</code> members contain the -default options for a particular destination, along with several informational -attributes about the destination as shown in <a href='#TABLE1'>Table 1</a>. -The <a href='#cupsGetOption'><code>cupsGetOption</code></a> function gets -the value for the named option. For example, the following code lists the -available destinations and their human-readable descriptions:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dests; -int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests); -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int i; -const char *value; - -for (i = num_dests, dest = dests; i > 0; i --, dest ++) - if (dest->instance == NULL) - { - value = <a href='#cupsGetOption'>cupsGetOption</a>("printer-info", dest->num_options, dest->options); - printf("%s (%s)\n", dest->name, value ? value : "no description"); - } - -<a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests); -</pre> - -<p>You can create your own option arrays using the -<a href='#cupsAddOption'><code>cupsAddOption</code></a> function, which -adds a single named option to an array:</p> - -<pre class='example'> -#include <cups/cups.h> - -int num_options = 0; -<a href='#cups_option_t'>cups_option_t</a> *options = NULL; - -/* The returned num_options value is updated as needed */ -num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "value", num_options, &options); - -/* This adds a second option value */ -num_options = <a href='#cupsAddOption'>cupsAddOption</a>("second", "value", num_options, &options); - -/* This replaces the first option we added */ -num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "new value", num_options, &options); -</pre> - -<p>Use a <code>for</code> loop to copy the options from a destination:</p> - -<pre class='example'> -#include <cups/cups.h> - -int i; -int num_options = 0; -<a href='#cups_option_t'>cups_option_t</a> *options = NULL; -<a href='#cups_dest_t'>cups_dest_t</a> *dest; - -for (i = 0; i < dest->num_options; i ++) - num_options = <a href='#cupsAddOption'>cupsAddOption</a>(dest->options[i].name, dest->options[i].value, - num_options, &options); -</pre> - -<p>Use the <a href='#cupsFreeOptions'><code>cupsFreeOptions</code></a> -function to free the options array when you are done using it:</p> - -<pre class='example'> -<a href='#cupsFreeOptions'>cupsFreeOptions</a>(num_options, options); -</pre> - -<h3><a name='PRINT_JOBS'>Print Jobs</a></h3> - -<p>Print jobs are identified by a locally-unique job ID number from 1 to -2<sup>31</sup>-1 and have options and one or more files for printing to a -single destination. The <a href='#cupsPrintFile'><code>cupsPrintFile</code></a> -function creates a new job with one file. The following code prints the CUPS -test page file:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int num_options; -<a href='#cups_option_t'>cups_option_t</a> *options; -int job_id; - -/* Print a single file */ -job_id = <a href='#cupsPrintFile'>cupsPrintFile</a>(dest->name, "/usr/share/cups/data/testprint.ps", - "Test Print", num_options, options); -</pre> - -<p>The <a href='#cupsPrintFiles'><code>cupsPrintFiles</code></a> function -creates a job with multiple files. The files are provided in a -<code>char *</code> array:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int num_options; -<a href='#cups_option_t'>cups_option_t</a> *options; -int job_id; -char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" }; - -/* Print three files */ -job_id = <a href='#cupsPrintFiles'>cupsPrintFiles</a>(dest->name, 3, files, "Test Print", num_options, options); -</pre> - -<p>Finally, the <a href='#cupsCreateJob'><code>cupsCreateJob</code></a> -function creates a new job with no files in it. Files are added using the -<a href='#cupsStartDocument'><code>cupsStartDocument</code></a>, -<a href='api-httpipp.html#cupsWriteRequestData'><code>cupsWriteRequestData</code></a>, -and <a href='#cupsFinishDocument'><code>cupsFinishDocument</code></a> functions. -The following example creates a job with 10 text files for printing:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int num_options; -<a href='#cups_option_t'>cups_option_t</a> *options; -int job_id; -int i; -char buffer[1024]; - -/* Create the job */ -job_id = <a href='#cupsCreateJob'>cupsCreateJob</a>(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files", - num_options, options); - -/* If the job is created, add 10 files */ -if (job_id > 0) -{ - for (i = 1; i <= 10; i ++) - { - snprintf(buffer, sizeof(buffer), "file%d.txt", i); - - <a href='#cupsStartDocument'>cupsStartDocument</a>(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer, - CUPS_FORMAT_TEXT, i == 10); - - snprintf(buffer, sizeof(buffer), - "File %d\n" - "\n" - "One fish,\n" - "Two fish,\n - "Red fish,\n - "Blue fish\n", i); - - /* cupsWriteRequestData can be called as many times as needed */ - <a href='#cupsWriteRequestData'>cupsWriteRequestData</a>(CUPS_HTTP_DEFAULT, buffer, strlen(buffer)); - - <a href='#cupsFinishDocument'>cupsFinishDocument</a>(CUPS_HTTP_DEFAULT, dest->name); - } -} -</pre> - -<p>Once you have created a job, you can monitor its status using the -<a href='#cupsGetJobs'><code>cupsGetJobs</code></a> function, which returns -an array of <a href='#cups_job_t'><code>cups_job_t</code></a> structures. -Each contains the job ID (<code>id</code>), destination name -(<code>dest</code>), title (<code>title</code>), and other information -associated with the job. The job array is freed using the -<a href='#cupsFreeJobs'><code>cupsFreeJobs</code></a> function. The following -example monitors a specific job ID, showing the current job state once every -5 seconds until the job is completed:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int job_id; -int num_jobs; -<a href='#cups_job_t'>cups_job_t</a> *jobs; -int i; -ipp_jstate_t job_state = IPP_JOB_PENDING; - -while (job_state < IPP_JOB_STOPPED) -{ - /* Get my jobs (1) with any state (-1) */ - num_jobs = <a href='#cupsGetJobs'>cupsGetJobs</a>(&jobs, dest->name, 1, -1); - - /* Loop to find my job */ - job_state = IPP_JOB_COMPLETED; - - for (i = 0; i < num_jobs; i ++) - if (jobs[i].id == job_id) + typedef struct cups_size_s + { + char media[128]; + int width, length; + int bottom, left, right, top; + } cups_size_t; + +The `width` and `length` members specify the dimensions of the media in +hundredths of millimeters (1/2540th of an inch). The `bottom`, `left`, `right`, +and `top` members specify the margins of the printable area, also in hundredths +of millimeters. + +The `cupsGetDestMediaByName` and `cupsGetDestMediaBySize` functions lookup the +media size information using a standard media size name or dimensions in +hundredths of millimeters: + + int + cupsGetDestMediaByName(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, + const char *media, + unsigned flags, cups_size_t *size); + + int + cupsGetDestMediaBySize(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, + int width, int length, + unsigned flags, cups_size_t *size); + +The `media`, `width`, and `length` arguments specify the size to lookup. The +`flags` argument specifies a bitfield controlling various lookup options: + +- `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 two-sided printing. +- `CUPS_MEDIA_FLAGS_EXACT`: Find an exact match for the size. +- `CUPS_MEDIA_FLAGS_READY`: If the printer supports media sensing or + configuration of the media in each tray/source, find the size amongst the + "ready" media. + +If a matching size is found for the destination, the size information is stored +in the structure pointed to by the `size` argument and 1 is returned. Otherwise +0 is returned. + +For example, the following code prints the margins for two-sided printing on US +Letter media: + + cups_size_t size; + + if (cupsGetDestMediaByName(CUPS_HTTP_DEFAULT, dest, info, + CUPS_MEDIA_LETTER, + CUPS_MEDIA_FLAGS_DUPLEX, &size)) { - job_state = jobs[i].state; - break; + puts("Margins for duplex US Letter:"); + printf(" Bottom: %.2fin\n", size.bottom / 2540.0); + printf(" Left: %.2fin\n", size.left / 2540.0); + printf(" Right: %.2fin\n", size.right / 2540.0); + printf(" Top: %.2fin\n", size.top / 2540.0); } + else + puts("Margins for duplex US Letter are not available."); - /* Free the job array */ - <a href='#cupsFreeJobs'>cupsFreeJobs</a>(num_jobs, jobs); - - /* Show the current state */ - switch (job_state) - { - case IPP_JOB_PENDING : - printf("Job %d is pending.\n", job_id); - break; - case IPP_JOB_HELD : - printf("Job %d is held.\n", job_id); - break; - case IPP_JOB_PROCESSING : - printf("Job %d is processing.\n", job_id); - break; - case IPP_JOB_STOPPED : - printf("Job %d is stopped.\n", job_id); - break; - case IPP_JOB_CANCELED : - printf("Job %d is canceled.\n", job_id); - break; - case IPP_JOB_ABORTED : - printf("Job %d is aborted.\n", job_id); - break; - case IPP_JOB_COMPLETED : - printf("Job %d is completed.\n", job_id); - break; - } - - /* Sleep if the job is not finished */ - if (job_state < IPP_JOB_STOPPED) - sleep(5); -} -</pre> - -<p>To cancel a job, use the -<a href='#cupsCancelJob'><code>cupsCancelJob</code></a> function with the -job ID:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int job_id; - -<a href='#cupsCancelJob'>cupsCancelJob</a>(dest->name, job_id); -</pre> - -<h3><a name='ERROR_HANDLING'>Error Handling</a></h3> - -<p>If any of the CUPS API printing functions returns an error, the reason for -that error can be found by calling the -<a href='#cupsLastError'><code>cupsLastError</code></a> and -<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> functions. -<a href='#cupsLastError'><code>cupsLastError</code></a> returns the last IPP -error code -(<a href='api-httpipp.html#ipp_status_t'><code>ipp_status_t</code></a>) -that was encountered, while -<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> returns -a (localized) human-readable string that can be shown to the user. For example, -if any of the job creation functions returns a job ID of 0, you can use -<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> to show -the reason why the job could not be created:</p> - -<pre class='example'> -#include <cups/cups.h> - -int job_id; - -if (job_id == 0) - puts(cupsLastErrorString()); -</pre> - -<h3><a name='PASSWORDS_AND_AUTHENTICATION'>Passwords and Authentication</a></h3> - -<p>CUPS supports authentication of any request, including submission of print -jobs. The default mechanism for getting the username and password is to use the -login user and a password from the console.</p> - -<p>To support other types of applications, in particular Graphical User -Interfaces ("GUIs"), the CUPS API provides functions to set the default -username and to register a callback function that returns a password string.</p> - -<p>The <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> -function is used to set a password callback in your program. Only one -function can be used at any time.</p> - -<p>The <a href="#cupsSetUser"><code>cupsSetUser</code></a> function sets the -current username for authentication. This function can be called by your -password callback function to change the current username as needed.</p> - -<p>The following example shows a simple password callback that gets a -username and password from the user:</p> - -<pre class='example'> -#include <cups/cups.h> - -const char * -my_password_cb(const char *prompt) -{ - char user[65]; - - - puts(prompt); - - /* Get a username from the user */ - printf("Username: "); - if (fgets(user, sizeof(user), stdin) == NULL) - return (NULL); - - /* Strip the newline from the string and set the user */ - user[strlen(user) - 1] = '\0'; - - <a href='#cupsSetUser'>cupsSetUser</a>(user); - - /* Use getpass() to ask for the password... */ - return (getpass("Password: ")); -} - -<a href='#cupsSetPasswordCB'>cupsSetPasswordCB</a>(my_password_cb); -</pre> - -<p>Similarly, a GUI could display the prompt string in a window with input -fields for the username and password. The username should default to the -string returned by the <a href="#cupsUser"><code>cupsUser</code></a> -function.</p> -<!-- - HTTP and IPP API introduction for CUPS. - - Copyright 2007-2012 by Apple Inc. - Copyright 1997-2006 by Easy Software Products, all rights reserved. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h2 class='title'><a name='OVERVIEW'>Overview</a></h2> - -<p>The CUPS HTTP and IPP APIs provide low-level access to the HTTP and IPP -protocols and CUPS scheduler. They are typically used by monitoring and -administration programs to perform specific functions not supported by the -high-level CUPS API functions.</p> - -<p>The HTTP APIs use an opaque structure called -<a href='#http_t'><code>http_t</code></a> to manage connections to -a particular HTTP or IPP server. The -<a href='#httpConnectEncrypt'><code>httpConnectEncrypt</code></a> function is -used to create an instance of this structure for a particular server. -The constant <code>CUPS_HTTP_DEFAULT</code> can be used with all of the -<code>cups</code> functions to refer to the default CUPS server - the functions -create a per-thread <a href='#http_t'><code>http_t</code></a> as needed.</p> - -<p>The IPP APIs use two opaque structures for requests (messages sent to the CUPS scheduler) and responses (messages sent back to your application from the scheduler). The <a href='#ipp_t'><code>ipp_t</code></a> type holds a complete request or response and is allocated using the <a href='#ippNew'><code>ippNew</code></a> or <a href='#ippNewRequest'><code>ippNewRequest</code></a> functions and freed using the <a href='#ippDelete'><code>ippDelete</code></a> function.</p> - -<p>The second opaque structure is called <a href='#ipp_attribute_t'><code>ipp_attribute_t</code></a> and holds a single IPP attribute which consists of a group tag (<a href='#ippGetGroupTag'><code>ippGetGroupTag</code></a>), a value type tag (<a href='#ippGetValueTag'><code>ippGetValueTag</code></a>), the attribute name (<a href='#ippGetName'><code>ippGetName</code></a>), and 1 or more values (<a href='#ippGetCount'><code>ippGetCount</code></a>, <a href='#ippGetBoolean'><code>ippGetBoolean</code></a>, <a href='#ippGetCollection'><code>ippGetCollection</code></a>, <a href='#ippGetDate'><code>ippGetDate</code></a>, <a href='#ippGetInteger'><code>ippGetInteger</code></a>, <a href='#ippGetRange'><code>ippGetRange</code></a>, <a href='#ippGetResolution'><code>ippGetResolution</code></a>, and <a href='#ippGetString'><code>ippGetString</code></a>). Attributes are added to an <a href='#ipp_t'><code>ipp_t</code></a> pointer using one of the <code>ippAdd</code> functions. For example, use <a href='#ippAddString'><code>ippAddString</code></a> to add the "printer-uri" and "requesting-user-name" string attributes to a request:</p> - -<pre class='example'> -<a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_GET_JOBS); +You can also enumerate all of the sizes that match a given `flags` value using +the `cupsGetDestMediaByIndex` and `cupsGetDestMediaCount` functions: -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", - NULL, "ipp://localhost/printers/"); -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", - NULL, cupsUser()); -</pre> + int + cupsGetDestMediaByIndex(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, int n, + unsigned flags, cups_size_t *size); -<p>Once you have created an IPP request, use the <code>cups</code> functions to send the request to and read the response from the server. For example, the <a href='#cupsDoRequest'><code>cupsDoRequest</code></a> function can be used for simple query operations that do not involve files:</p> + int + cupsGetDestMediaCount(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, unsigned flags); -<pre class='example'> -#include <cups/cups.h> +For example, the following code prints the list of ready media and corresponding +margins: + cups_size_t size; + int i; + int count = cupsGetDestMediaCount(CUPS_HTTP_DEFAULT, + dest, info, + CUPS_MEDIA_FLAGS_READY); -<a href='#ipp_t'>ipp_t</a> *<a name='get_jobs'>get_jobs</a>(void) -{ - <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_GET_JOBS); - - <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", - NULL, "ipp://localhost/printers/"); - <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", - NULL, cupsUser()); - - return (<a href='#cupsDoRequest'>cupsDoRequest</a>(CUPS_HTTP_DEFAULT, request, "/")); -} -</pre> + for (i = 0; i < count; i ++) + { + if (cupsGetDestMediaByIndex(CUPS_HTTP_DEFAULT, dest, info, + i, CUPS_MEDIA_FLAGS_READY, + &size)) + { + printf("%s:\n", size.name); + printf(" Width: %.2fin\n", size.width / 2540.0); + printf(" Length: %.2fin\n", size.length / 2540.0); + printf(" Bottom: %.2fin\n", size.bottom / 2540.0); + printf(" Left: %.2fin\n", size.left / 2540.0); + printf(" Right: %.2fin\n", size.right / 2540.0); + printf(" Top: %.2fin\n", size.top / 2540.0); + } + } -<p>The <a href='#cupsDoRequest'><code>cupsDoRequest</code></a> function frees the request and returns an IPP response or <code>NULL</code> pointer if the request could not be sent to the server. Once you have a response from the server, you can either use the <a href='#ippFindAttribute'><code>ippFindAttribute</code></a> and <a href='#ippFindNextAttribute'><code>ippFindNextAttribute</code></a> functions to find specific attributes, for example:</p> +Finally, the `cupsGetDestMediaDefault` function returns the default media size: -<pre class='example'> -<a href='#ipp_t'>ipp_t</a> *response; -<a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr; + int + cupsGetDestMediaDefault(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, unsigned flags, + cups_size_t *size); -attr = <a href='#ippFindAttribute'>ippFindAttribute</a>(response, "printer-state", IPP_TAG_ENUM); -</pre> -<p>You can also walk the list of attributes with a simple <code>for</code> loop like this:</p> +### Localizing Options and Values -<pre class='example'> -<a href='#ipp_t'>ipp_t</a> *response; -<a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr; +CUPS provides three functions to get localized versions of options and values: +`cupsLocalizeDestMedia`, `cupsLocalizeDestOption`, and `cupsLocalizeDestValue`: -for (attr = <a href='#ippFirstAttribute'>ippFirstAttribute</a>(response); attr != NULL; attr = <a href='#ippNextAttribute'>ippNextAttribute</a>(response)) - if (ippGetName(attr) == NULL) - puts("--SEPARATOR--"); - else - puts(ippGetName(attr)); -</pre> + const char * + cupsLocalizeDestMedia(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, unsigned flags, + cups_size_t *size); -<p>The <code>for</code> loop approach is normally used when collecting attributes for multiple objects (jobs, printers, etc.) in a response. Attributes with <code>NULL</code> names indicate a separator between the attributes of each object. For example, the following code will list the jobs returned from our previous <a href='#get_jobs'><code>get_jobs</code></a> example code:</p> + const char * + cupsLocalizeDestOption(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, + const char *option); -<pre class='example'> -<a href='#ipp_t'>ipp_t</a> *response = <a href='#get_jobs'>get_jobs</a>(); + const char * + cupsLocalizeDestValue(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, + const char *option, const char *value); -if (response != NULL) -{ - <a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr; - const char *attrname; - int job_id = 0; - const char *job_name = NULL; - const char *job_originating_user_name = NULL; - puts("Job ID Owner Title"); - puts("------ ---------------- ---------------------------------"); +## Submitting a Print Job - for (attr = <a href='#ippFirstAttribute'>ippFirstAttribute</a>(response); attr != NULL; attr = <a href='#ippNextAttribute'>ippNextAttribute</a>(response)) - { - /* Attributes without names are separators between jobs */ - attrname = ippGetName(attr); - if (attrname == NULL) +Once you are ready to submit a print job, you create a job using the +`cupsCreateDestJob` function: + + ipp_status_t + cupsCreateDestJob(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, int *job_id, + const char *title, int num_options, + cups_option_t *options); + +The `title` argument specifies a name for the print job such as "My Document". +The `num_options` and `options` arguments specify the options for the print +job which are allocated using the `cupsAddOption` function. + +When successful, the job's numeric identifier is stored in the integer pointed +to by the `job_id` argument and `IPP_STATUS_OK` is returned. Otherwise, an IPP +error status is returned. + +For example, the following code creates a new job that will print 42 copies of a +two-sided US Letter document: + + int job_id = 0; + int num_options = 0; + cups_option_t *options = NULL; + + num_options = cupsAddOption(CUPS_COPIES, "42", + num_options, &options); + num_options = cupsAddOption(CUPS_MEDIA, CUPS_MEDIA_LETTER, + num_options, &options); + num_options = cupsAddOption(CUPS_SIDES, + CUPS_SIDES_TWO_SIDED_PORTRAIT, + num_options, &options); + + if (cupsCreateDestJob(CUPS_HTTP_DEFAULT, dest, info, + &job_id, "My Document", num_options, + options) == IPP_STATUS_OK) + printf("Created job: %d\n", job_id); + else + printf("Unable to create job: %s\n", + cupsLastErrorString()); + +Once the job is created, you submit documents for the job using the +`cupsStartDestDocument`, `cupsWriteRequestData`, and `cupsFinishDestDocument` +functions: + + http_status_t + cupsStartDestDocument(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, int job_id, + const char *docname, + const char *format, + int num_options, + cups_option_t *options, + int last_document); + + http_status_t + cupsWriteRequestData(http_t *http, const char *buffer, + size_t length); + + ipp_status_t + cupsFinishDestDocument(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info); + +The `docname` argument specifies the name of the document, typically the +original filename. The `format` argument specifies the MIME media type of the +document, including the following constants: + +- `CUPS_FORMAT_JPEG`: "image/jpeg" +- `CUPS_FORMAT_PDF`: "application/pdf" +- `CUPS_FORMAT_POSTSCRIPT`: "application/postscript" +- `CUPS_FORMAT_TEXT`: "text/plain" + +The `num_options` and `options` arguments specify per-document print options, +which at present must be 0 and `NULL`. The `last_document` argument specifies +whether this is the last document in the job. + +For example, the following code submits a PDF file to the job that was just +created: + + FILE *fp = fopen("filename.pdf", "rb"); + size_t bytes; + char buffer[65536]; + + if (cupsStartDestDocument(CUPS_HTTP_DEFAULT, dest, info, + job_id, "filename.pdf", 0, NULL, + 1) == HTTP_STATUS_CONTINUE) { - if (job_id > 0) - { - if (job_name == NULL) - job_name = "(withheld)"; - - if (job_originating_user_name == NULL) - job_originating_user_name = "(withheld)"; - - printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); - } - - job_id = 0; - job_name = NULL; - job_originating_user_name = NULL; - continue; + while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) + if (cupsWriteRequestData(CUPS_HTTP_DEFAULT, buffer, + bytes) != HTTP_STATUS_CONTINUE) + break; + + if (cupsFinishDestDocument(CUPS_HTTP_DEFAULT, dest, + info) == IPP_STATUS_OK) + puts("Document send succeeded."); + else + printf("Document send failed: %s\n", + cupsLastErrorString()); } - else if (!strcmp(attrname, "job-id") && ippGetValueTag(attr) == IPP_TAG_INTEGER) - job_id = ippGetInteger(attr, 0); - else if (!strcmp(attrname, "job-name") && ippGetValueTag(attr) == IPP_TAG_NAME) - job_name = ippGetString(attr, 0, NULL); - else if (!strcmp(attrname, "job-originating-user-name") && - ippGetValueTag(attr) == IPP_TAG_NAME) - job_originating_user_name = ippGetString(attr, 0, NULL); - } - - if (job_id > 0) - { - if (job_name == NULL) - job_name = "(withheld)"; - - if (job_originating_user_name == NULL) - job_originating_user_name = "(withheld)"; - - printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); - } -} -</pre> - -<h3><a name='CREATING_URI_STRINGS'>Creating URI Strings</a></h3> - -<p>To ensure proper encoding, the -<a href='#httpAssembleURIf'><code>httpAssembleURIf</code></a> function must be -used to format a "printer-uri" string for all printer-based requests:</p> - -<pre class='example'> -const char *name = "Foo"; -char uri[1024]; -<a href='#ipp_t'>ipp_t</a> *request; - -<a href='#httpAssembleURIf'>httpAssembleURIf</a>(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(), - ippPort(), "/printers/%s", name); -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri); -</pre> - -<h3><a name='SENDING_REQUESTS_WITH_FILES'>Sending Requests with Files</a></h3> - -<p>The <a href='#cupsDoFileRequest'><code>cupsDoFileRequest</code></a> and -<a href='#cupsDoIORequest'><code>cupsDoIORequest</code></a> functions are -used for requests involving files. The -<a href='#cupsDoFileRequest'><code>cupsDoFileRequest</code></a> function -attaches the named file to a request and is typically used when sending a print -file or changing a printer's PPD file:</p> - -<pre class='example'> -const char *filename = "/usr/share/cups/data/testprint.ps"; -const char *name = "Foo"; -char uri[1024]; -char resource[1024]; -<a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_PRINT_JOB); -<a href='#ipp_t'>ipp_t</a> *response; - -/* Use httpAssembleURIf for the printer-uri string */ -<a href='#httpAssembleURIf'>httpAssembleURIf</a>(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(), - ippPort(), "/printers/%s", name); -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri); -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", - NULL, cupsUser()); -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name", - NULL, "testprint.ps"); - -/* Use snprintf for the resource path */ -snprintf(resource, sizeof(resource), "/printers/%s", name); - -response = <a href='#cupsDoFileRequest'>cupsDoFileRequest</a>(CUPS_HTTP_DEFAULT, request, resource, filename); -</pre> - -<p>The <a href='#cupsDoIORequest'><code>cupsDoIORequest</code></a> function -optionally attaches a file to the request and optionally saves a file in the -response from the server. It is used when using a pipe for the request -attachment or when using a request that returns a file, currently only -<code>CUPS_GET_DOCUMENT</code> and <code>CUPS_GET_PPD</code>. For example, -the following code will download the PPD file for the sample HP LaserJet -printer driver:</p> - -<pre class='example'> -char tempfile[1024]; -int tempfd; -<a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD); -<a href='#ipp_t'>ipp_t</a> *response; - -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", - NULL, "laserjet.ppd"); - -tempfd = cupsTempFd(tempfile, sizeof(tempfile)); - -response = <a href='#cupsDoIORequest'>cupsDoIORequest</a>(CUPS_HTTP_DEFAULT, request, "/", -1, tempfd); -</pre> - -<p>The example passes <code>-1</code> for the input file descriptor to specify -that no file is to be attached to the request. The PPD file attached to the -response is written to the temporary file descriptor we created using the -<code>cupsTempFd</code> function.</p> - -<h3><a name='ASYNCHRONOUS_REQUEST_PROCESSING'>Asynchronous Request Processing</a></h3> - -<p>The <a href='#cupsSendRequest'><code>cupsSendRequest</code></a> and -<a href='#cupsGetResponse'><code>cupsGetResponse</code></a> support -asynchronous communications with the server. Unlike the other request -functions, the IPP request is not automatically freed, so remember to -free your request with the <a href='#ippDelete'><code>ippDelete</code></a> -function.</p> - -<p>File data is attached to the request using the -<a href='#cupsWriteRequestData'><code>cupsWriteRequestData</code></a> -function, while file data returned from the server is read using the -<a href='#cupsReadResponseData'><code>cupsReadResponseData</code></a> -function. We can rewrite the previous <code>CUPS_GET_PPD</code> example -to use the asynchronous functions quite easily:</p> - -<pre class='example'> -char tempfile[1024]; -int tempfd; -<a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD); -<a href='#ipp_t'>ipp_t</a> *response; - -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", - NULL, "laserjet.ppd"); - -tempfd = cupsTempFd(tempfile, sizeof(tempfile)); - -if (<a href='#cupsSendRequest'>cupsSendRequest</a>(CUPS_HTTP_DEFAULT, request, "/") == HTTP_CONTINUE) -{ - response = <a href='#cupsGetResponse'>cupsGetResponse</a>(CUPS_HTTP_DEFAULT, "/"); - - if (response != NULL) - { - ssize_t bytes; - char buffer[8192]; - - while ((bytes = <a href='#cupsReadResponseData'>cupsReadResponseData</a>(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0) - write(tempfd, buffer, bytes); - } -} - -/* Free the request! */ -<a href='#ippDelete'>ippDelete</a>(request); -</pre> - -<p>The <a href='#cupsSendRequest'><code>cupsSendRequest</code></a> function -returns the initial HTTP request status, typically either -<code>HTTP_CONTINUE</code> or <code>HTTP_UNAUTHORIZED</code>. The latter status -is returned when the request requires authentication of some sort. The -<a href='#cupsDoAuthentication'><code>cupsDoAuthentication</code></a> function -must be called when your see <code>HTTP_UNAUTHORIZED</code> and the request -re-sent. We can add authentication support to our example code by using a -<code>do ... while</code> loop:</p> - -<pre class='example'> -char tempfile[1024]; -int tempfd; -<a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD); -<a href='#ipp_t'>ipp_t</a> *response; -http_status_t status; - -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", - NULL, "laserjet.ppd"); - -tempfd = cupsTempFd(tempfile, sizeof(tempfile)); - -/* Loop for authentication */ -do -{ - status = <a href='#cupsSendRequest'>cupsSendRequest</a>(CUPS_HTTP_DEFAULT, request, "/"); - - if (status == HTTP_UNAUTHORIZED) - { - /* Try to authenticate, break out of the loop if that fails */ - if (<a href='#cupsDoAuthentication'>cupsDoAuthentication</a>(CUPS_HTTP_DEFAULT, "POST", "/")) - break; - } -} -while (status != HTTP_CONTINUE && status != HTTP_UNAUTHORIZED); - -if (status == HTTP_CONTINUE) -{ - response = <a href='#cupsGetResponse'>cupsGetResponse</a>(CUPS_HTTP_DEFAULT, "/"); - - if (response != NULL) - { - ssize_t bytes; - char buffer[8192]; - - while ((bytes = <a href='#cupsReadResponseData'>cupsReadResponseData</a>(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0) - write(tempfd, buffer, bytes); - } -} - -/* Free the request! */ -<a href='#ippDelete'>ippDelete</a>(request); -</pre> -<!-- - File and directory API introduction for CUPS. - - Copyright 2007-2011 by Apple Inc. - Copyright 1997-2005 by Easy Software Products, all rights reserved. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h2 class='title'><a name="OVERVIEW">Overview</a></h2> - -<p>The CUPS file and directory APIs provide portable interfaces -for manipulating files and listing files and directories. Unlike -stdio <code>FILE</code> streams, the <code>cupsFile</code> functions -allow you to open more than 256 files at any given time. They -also manage the platform-specific details of locking, large file -support, line endings (CR, LF, or CR LF), and reading and writing -files using Flate ("gzip") compression. Finally, you can also -connect, read from, and write to network connections using the -<code>cupsFile</code> functions.</p> - -<p>The <code>cupsDir</code> functions manage the platform-specific -details of directory access/listing and provide a convenient way -to get both a list of files and the information (permissions, -size, timestamp, etc.) for each of those files.</p> -<!-- - Array API introduction for CUPS. - - Copyright 2007-2011 by Apple Inc. - Copyright 1997-2006 by Easy Software Products, all rights reserved. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h2 class='title'><a name='OVERVIEW'>Overview</a></h2> - -<p>The CUPS array API provides a high-performance generic array container. -The contents of the array container can be sorted and the container itself is -designed for optimal speed and memory usage under a wide variety of conditions. -Sorted arrays use a binary search algorithm from the last found or inserted -element to quickly find matching elements in the array. Arrays created with the -optional hash function can often find elements with a single lookup. The -<a href='#cups_array_t'><code>cups_array_t</code></a> type is used when -referring to a CUPS array.</p> - -<p>The CUPS scheduler (<tt>cupsd</tt>) and many of the CUPS API -functions use the array API to efficiently manage large lists of -data.</p> - -<h3><a name='MANAGING_ARRAYS'>Managing Arrays</a></h3> - -<p>Arrays are created using either the -<a href='#cupsArrayNew'><code>cupsArrayNew</code></a>, -<a href='#cupsArrayNew2'><code>cupsArrayNew2</code></a>, or -<a href='#cupsArrayNew2'><code>cupsArrayNew3</code></a> functions. The -first function creates a new array with the specified callback function -and user data pointer:</p> - -<pre class='example'> -#include <cups/array.h> - -static int compare_func(void *first, void *second, void *user_data); - -void *user_data; -<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew'>cupsArrayNew</a>(compare_func, user_data); -</pre> - -<p>The comparison function (type -<a href="#cups_arrayfunc_t"><code>cups_arrayfunc_t</code></a>) is called -whenever an element is added to the array and can be <code>NULL</code> to -create an unsorted array. The function returns -1 if the first element should -come before the second, 0 if the first and second elements should have the same -ordering, and 1 if the first element should come after the second.</p> - -<p>The "user_data" pointer is passed to your comparison function. Pass -<code>NULL</code> if you do not need to associate the elements in your array -with additional information.</p> - -<p>The <a href='#cupsArrayNew2'><code>cupsArrayNew2</code></a> function adds -two more arguments to support hashed lookups, which can potentially provide -instantaneous ("O(1)") lookups in your array:</p> - -<pre class='example'> -#include <cups/array.h> - -#define HASH_SIZE 512 /* Size of hash table */ - -static int compare_func(void *first, void *second, void *user_data); -static int hash_func(void *element, void *user_data); - -void *user_data; -<a href='#cups_array_t'>cups_array_t</a> *hash_array = <a href='#cupsArrayNew2'>cupsArrayNew2</a>(compare_func, user_data, hash_func, HASH_SIZE); -</pre> - -<p>The hash function (type -<a href="#cups_ahash_func_t"><code>cups_ahash_func_t</code></a>) should return a -number from 0 to (hash_size-1) that (hopefully) uniquely identifies the -element and is called whenever you look up an element in the array with -<a href='#cupsArrayFind'><code>cupsArrayFind</code></a>. The hash size is -only limited by available memory, but generally should not be larger than -16384 to realize any performance improvement.</p> - -<p>The <a href='#cupsArrayNew3'><code>cupsArrayNew3</code></a> function adds -copy and free callbacks to support basic memory management of elements:</p> - -<pre class='example'> -#include <cups/array.h> - -#define HASH_SIZE 512 /* Size of hash table */ - -static int compare_func(void *first, void *second, void *user_data); -static void *copy_func(void *element, void *user_data); -static void free_func(void *element, void *user_data); -static int hash_func(void *element, void *user_data); - -void *user_data; -<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew3'>cupsArrayNew3</a>(compare_func, user_data, NULL, 0, copy_func, free_func); - -<a href='#cups_array_t'>cups_array_t</a> *hash_array = <a href='#cupsArrayNew3'>cupsArrayNew3</a>(compare_func, user_data, hash_func, HASH_SIZE, copy_func, free_func); -</pre> - -<p>Once you have created the array, you add elements using the -<a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> -<a href='#cupsArrayInsert'><code>cupsArrayInsert</code></a> functions. -The first function adds an element to the array, adding the new element -after any elements that have the same order, while the second inserts the -element before others with the same order. For unsorted arrays, -<a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> appends the element to -the end of the array while -<a href='#cupsArrayInsert'><code>cupsArrayInsert</code></a> inserts the -element at the beginning of the array. For example, the following code -creates a sorted array of character strings:</p> - -<pre class='example'> -#include <cups/array.h> - -/* Use strcmp() to compare strings - it will ignore the user_data pointer */ -<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew'>cupsArrayNew</a>((<a href='#cups_array_func_t'>cups_array_func_t</a>)strcmp, NULL); - -/* Add four strings to the array */ -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "One Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Two Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Red Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Blue Fish"); -</pre> - -<p>Elements are removed using the -<a href='#cupsArrayRemove'><code>cupsArrayRemove</code></a> function, for -example:</p> - -<pre class='example'> -#include <cups/array.h> - -/* Use strcmp() to compare strings - it will ignore the user_data pointer */ -<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew'>cupsArrayNew</a>((<a href='#cups_array_func_t'>cups_array_func_t</a>)strcmp, NULL); - -/* Add four strings to the array */ -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "One Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Two Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Red Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Blue Fish"); - -/* Remove "Red Fish" */ -<a href='#cupsArrayRemove'>cupsArrayRemove</a>(array, "Red Fish"); -</pre> - -<p>Finally, you free the memory used by the array using the -<a href='#cupsArrayDelete'><code>cupsArrayDelete</code></a> function. All -of the memory for the array and hash table (if any) is freed, however <em>CUPS -does not free the elements unless you provide copy and free functions</em>.</p> - -<h3><a name='FINDING_AND_ENUMERATING'>Finding and Enumerating Elements</a></h3> - -<p>CUPS provides several functions to find and enumerate elements in an -array. Each one sets or updates a "current index" into the array, such that -future lookups will start where the last one left off:</p> - -<dl> - <dt><a href='#cupsArrayFind'><code>cupsArrayFind</code></a></dt> - <dd>Returns the first matching element.</dd> - <dt><a href='#cupsArrayFirst'><code>cupsArrayFirst</code></a></dt> - <dd>Returns the first element in the array.</dd> - <dt><a href='#cupsArrayIndex'><code>cupsArrayIndex</code></a></dt> - <dd>Returns the Nth element in the array, starting at 0.</dd> - <dt><a href='#cupsArrayLast'><code>cupsArrayLast</code></a></dt> - <dd>Returns the last element in the array.</dd> - <dt><a href='#cupsArrayNext'><code>cupsArrayNext</code></a></dt> - <dd>Returns the next element in the array.</dd> - <dt><a href='#cupsArrayPrev'><code>cupsArrayPrev</code></a></dt> - <dd>Returns the previous element in the array.</dd> -</dl> - -<p>Each of these functions returns <code>NULL</code> when there is no -corresponding element. For example, a simple <code>for</code> loop using the -<a href='#cupsArrayFirst'><code>cupsArrayFirst</code></a> and -<a href='#cupsArrayNext'><code>cupsArrayNext</code></a> functions will -enumerate all of the strings in our previous example:</p> - -<pre class='example'> -#include <cups/array.h> - -/* Use strcmp() to compare strings - it will ignore the user_data pointer */ -<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew'>cupsArrayNew</a>((<a href='#cups_array_func_t'>cups_array_func_t</a>)strcmp, NULL); - -/* Add four strings to the array */ -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "One Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Two Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Red Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Blue Fish"); - -/* Show all of the strings in the array */ -char *s; -for (s = (char *)<a href='#cupsArrayFirst'>cupsArrayFirst</a>(array); s != NULL; s = (char *)<a href='#cupsArrayNext'>cupsArrayNext</a>(array)) - puts(s); -</pre> + + fclose(fp); diff --git a/cups/dest.c b/cups/dest.c index 802f93151..e6fc66b38 100644 --- a/cups/dest.c +++ b/cups/dest.c @@ -769,10 +769,10 @@ cupsConnectDestBlock( * @since CUPS 1.6/macOS 10.8@ */ -int -cupsCopyDest(cups_dest_t *dest, - int num_dests, - cups_dest_t **dests) +int /* O - New number of destinations */ +cupsCopyDest(cups_dest_t *dest, /* I - Destination to copy */ + int num_dests, /* I - Number of destinations */ + cups_dest_t **dests) /* IO - Destination array */ { int i; /* Looping var */ cups_dest_t *new_dest; /* New destination pointer */ @@ -3736,7 +3736,7 @@ cups_elapsed(struct timeval *t) /* IO - Previous time */ return (msecs); } - + /* * 'cups_find_dest()' - Find a destination using a binary search. */ diff --git a/doc/Makefile b/doc/Makefile index eb7ae6836..3b1b71178 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -45,15 +45,11 @@ HELPIMAGES = \ HELPFILES = \ help/accounting.html \ help/api-admin.html \ - help/api-array.html \ - help/api-cups.html \ - help/api-filedir.html \ help/api-filter.html \ - help/api-httpipp.html \ - help/api-overview.html \ help/api-ppd.html \ help/api-raster.html \ help/cgi.html \ + help/cupspm.html \ help/encryption.html \ help/glossary.html \ help/kerberos.html \ diff --git a/doc/help/api-admin.html b/doc/help/api-admin.html index 2af3c86b0..2d2d96a71 100644 --- a/doc/help/api-admin.html +++ b/doc/help/api-admin.html @@ -8,6 +8,7 @@ <meta name="creator" content="Mini-XML v2.11"> <meta name="author" content="Unknown"> <meta name="copyright" content="Unknown"> + <meta name="version" content="0.0"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -507,11 +508,11 @@ show_devices(void) <h3 class="function"><span class="info"> DEPRECATED </span><a id="cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></h3> <p class="description">Create the Windows PPD file for a printer.</p> <p class="code"> -char *cupsAdminCreateWindowsPPD (<br /> -    http_t *http,<br /> -    const char *dest,<br /> -    char *buffer,<br /> -    int bufsize<br /> +char *cupsAdminCreateWindowsPPD (<br> +    http_t *http,<br> +    const char *dest,<br> +    char *buffer,<br> +    int bufsize<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -529,13 +530,13 @@ char *cupsAdminCreateWindowsPPD (<br /> <h3 class="function"><span class="info"> DEPRECATED </span><a id="cupsAdminExportSamba">cupsAdminExportSamba</a></h3> <p class="description">Export a printer to Samba.</p> <p class="code"> -int cupsAdminExportSamba (<br /> -    const char *dest,<br /> -    const char *ppd,<br /> -    const char *samba_server,<br /> -    const char *samba_user,<br /> -    const char *samba_password,<br /> -    FILE *logfile<br /> +int cupsAdminExportSamba (<br> +    const char *dest,<br> +    const char *ppd,<br> +    const char *samba_server,<br> +    const char *samba_user,<br> +    const char *samba_password,<br> +    FILE *logfile<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -557,10 +558,10 @@ int cupsAdminExportSamba (<br /> <h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3> <p class="description">Get settings from the server.</p> <p class="code"> -int cupsAdminGetServerSettings (<br /> -    http_t *http,<br /> -    int *num_settings,<br /> -    cups_option_t **settings<br /> +int cupsAdminGetServerSettings (<br> +    http_t *http,<br> +    int *num_settings,<br> +    cups_option_t **settings<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -581,10 +582,10 @@ you are done with them. <h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3> <p class="description">Set settings on the server.</p> <p class="code"> -int cupsAdminSetServerSettings (<br /> -    http_t *http,<br /> -    int num_settings,<br /> -    cups_option_t *settings<br /> +int cupsAdminSetServerSettings (<br> +    http_t *http,<br> +    int num_settings,<br> +    cups_option_t *settings<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -600,13 +601,13 @@ int cupsAdminSetServerSettings (<br /> <h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsGetDevices">cupsGetDevices</a></h3> <p class="description">Get available printer devices.</p> <p class="code"> -ipp_status_t cupsGetDevices (<br /> -    http_t *http,<br /> -    int timeout,<br /> -    const char *include_schemes,<br /> -    const char *exclude_schemes,<br /> -    <a href="#cups_device_cb_t">cups_device_cb_t</a> callback,<br /> -    void *user_data<br /> +ipp_status_t cupsGetDevices (<br> +    http_t *http,<br> +    int timeout,<br> +    const char *include_schemes,<br> +    const char *exclude_schemes,<br> +    <a href="#cups_device_cb_t">cups_device_cb_t</a> callback,<br> +    void *user_data<br> );</p> <h4 class="parameters">Parameters</h4> <dl> diff --git a/doc/help/api-array.html b/doc/help/api-array.html deleted file mode 100644 index 9aaf121ce..000000000 --- a/doc/help/api-array.html +++ /dev/null @@ -1,1074 +0,0 @@ -<!doctype html> -<html> -<!-- SECTION: Programming --> - <head> - <title>Array API</title> - <meta name="keywords" content="Programming"> - <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> - <meta name="creator" content="Mini-XML v2.11"> - <meta name="author" content="Unknown"> - <meta name="copyright" content="Unknown"> - <style type="text/css"><!-- -BODY { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -H1, H2, H3, H4, H5, H6, P, TD, TH { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -KBD { - font-family: monaco, courier, monospace; - font-weight: bold; -} - -PRE { - font-family: monaco, courier, monospace; -} - -PRE.command { - border: dotted thin #7f7f7f; - margin-left: 36pt; - padding: 10px; -} - -P.compact { - margin: 0; -} - -P.example { - font-style: italic; - margin-left: 36pt; -} - -DL.man DD { - margin-left: 5em; -} - -DL.man DT { - margin-left: 0; -} - -PRE.man { - margin: 0; -} - -PRE.example { - background: #eeeeee; - border: dotted thin #999999; - margin-left: 36pt; - padding: 10pt; -} - -PRE.command EM, PRE.example EM { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -P.command { - font-family: monaco, courier, monospace; - margin-left: 36pt; -} - -P.formula { - font-style: italic; - margin-left: 36pt; -} - -BLOCKQUOTE { - background: #eeeeee; - border: solid thin #999999; - padding: 10pt; -} - -A IMG { - border: none; -} - -A:link:hover IMG { - background: #f0f0f0; - border-radius: 10px; - -moz-border-radius: 10px; -} - -A:link, A:visited { - font-weight: inherit; - text-decoration: none; -} - -A:link:hover, A:visited:hover, A:active { - text-decoration: underline; -} - -SUB, SUP { - font-size: 50%; -} - -TR.data, TD.data, TR.data TD { - margin-top: 10pt; - padding: 5pt; - border-bottom: solid 1pt #999999; -} - -TR.data TH { - border-bottom: solid 1pt #999999; - padding-top: 10pt; - padding-left: 5pt; - text-align: left; -} - -DIV.table TABLE { - border: solid thin #999999; - border-collapse: collapse; - border-spacing: 0; - margin-left: auto; - margin-right: auto; -} - -DIV.table CAPTION { - caption-side: top; - font-size: 120%; - font-style: italic; - font-weight: bold; - margin-left: auto; - margin-right: auto; -} - -DIV.table TABLE TD { - border: solid thin #cccccc; - padding-top: 5pt; -} - -DIV.table TABLE TH { - background: #cccccc; - border: none; - border-bottom: solid thin #999999; -} - -DIV.figure TABLE { - margin-left: auto; - margin-right: auto; -} - -DIV.figure CAPTION { - caption-side: bottom; - font-size: 120%; - font-style: italic; - font-weight: bold; - margin-left: auto; - margin-right: auto; -} - -TH.label { - text-align: right; - vertical-align: top; -} - -TH.sublabel { - text-align: right; - font-weight: normal; -} - -HR { - border: solid thin; -} - -SPAN.info { - background: black; - border: thin solid black; - color: white; - font-size: 80%; - font-style: italic; - font-weight: bold; - white-space: nowrap; -} - -H2 SPAN.info, H3 SPAN.info, H4 SPAN.info { - float: right; - font-size: 100%; -} - -H1.title { -} - -H2.title, H3.title { - border-bottom: solid 2pt #000000; -} - -DIV.indent, TABLE.indent { - margin-top: 2em; - margin-left: auto; - margin-right: auto; - width: 90%; -} - -TABLE.indent { - border-collapse: collapse; -} - -TABLE.indent TD, TABLE.indent TH { - padding: 0; -} - -TABLE.list { - border-collapse: collapse; - margin-left: auto; - margin-right: auto; - width: 90%; -} - -TABLE.list TH { - background: white; - border-bottom: solid thin #cccccc; - color: #444444; - padding-top: 10pt; - padding-left: 5pt; - text-align: left; - vertical-align: bottom; - white-space: nowrap; -} - -TABLE.list TH A { - color: #4444cc; -} - -TABLE.list TD { - border-bottom: solid thin #eeeeee; - padding-top: 5pt; - padding-left: 5pt; -} - -TABLE.list TR:nth-child(even) { - background: #f8f8f8; -} - -TABLE.list TR:nth-child(odd) { - background: #f4f4f4; -} - -DT { - margin-left: 36pt; - margin-top: 12pt; -} - -DD { - margin-left: 54pt; -} - -DL.category DT { - font-weight: bold; -} - -P.summary { - margin-left: 36pt; - font-family: monaco, courier, monospace; -} - -DIV.summary TABLE { - border: solid thin #999999; - border-collapse: collapse; - border-spacing: 0; - margin: 10px; -} - -DIV.summary TABLE TD, DIV.summary TABLE TH { - border: solid thin #999999; - padding: 5px; - text-align: left; - vertical-align: top; -} - -DIV.summary TABLE THEAD TH { - background: #eeeeee; -} - -/* API documentation styles... */ -div.body h1 { - margin: 0; -} -div.body h2 { - margin-top: 1.5em; -} -div.body h3, div.body h4, div.body h5 { - margin-bottom: 0.5em; - margin-top: 1.5em; -} -.class, .enumeration, .function, .struct, .typedef, .union { - border-bottom: solid thin #999999; - margin-bottom: 0; - margin-top: 2em; -} -.description { - margin-top: 0.5em; -} -code, p.code, pre, ul.code li { - font-family: monaco, courier, monospace; - font-size: 90%; -} -ul.code, ul.contents, ul.subcontents { - list-style-type: none; - margin: 0; - padding-left: 0; -} -ul.code li { - margin: 0; -} -ul.contents > li { - margin-top: 1em; -} -ul.contents li ul.code, ul.contents li ul.subcontents { - padding-left: 2em; -} -div.body dl { - margin-left: 0; - margin-top: 0; -} -div.body dt { - font-style: italic; - margin-left: 0; - margin-top: 0; -} -div.body dd { - margin-bottom: 0.5em; -} - -/* This is just for the HTML files generated with the framedhelp target */ -div.contents { - background: #e8e8e8; - border: solid thin black; - padding: 10px; -} -div.contents h1 { - font-size: 110%; -} -div.contents h2 { - font-size: 100%; -} -div.contents ul.contents { - font-size: 80%; -} -div.contents ul.subcontents li { - margin-left: 1em; - text-indent: -1em; -} ---></style> - </head> - <body> -<!-- - Array API header for CUPS. - - Copyright 2008-2011 by Apple Inc. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h1 class='title'>Array API</h1> - -<div class='summary'><table summary='General Information'> -<thead> -<tr> - <th>Header</th> - <th>cups/array.h</th> -</tr> -</thead> -<tbody> -<tr> - <th>Library</th> - <td>-lcups</td> -</tr> -<tr> - <th>See Also</th> - <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a></td> -</tr> -</tbody> -</table></div> - <div class="contents"> - <h2 class="title">Contents</h2> - <ul class="contents"> - <li><a href="#OVERVIEW">Overview</a><ul class="subcontents"> - <li><a href="#MANAGING_ARRAYS">Managing Arrays</a></li> - <li><a href="#FINDING_AND_ENUMERATING">Finding and Enumerating Elements</a></li> - </ul></li> - <li><a href="#FUNCTIONS">Functions</a><ul class="subcontents"> - <li><a href="#cupsArrayAdd">cupsArrayAdd</a></li> - <li><a href="#cupsArrayClear">cupsArrayClear</a></li> - <li><a href="#cupsArrayCount">cupsArrayCount</a></li> - <li><a href="#cupsArrayCurrent">cupsArrayCurrent</a></li> - <li><a href="#cupsArrayDelete">cupsArrayDelete</a></li> - <li><a href="#cupsArrayDup">cupsArrayDup</a></li> - <li><a href="#cupsArrayFind">cupsArrayFind</a></li> - <li><a href="#cupsArrayFirst">cupsArrayFirst</a></li> - <li><a href="#cupsArrayGetIndex">cupsArrayGetIndex</a></li> - <li><a href="#cupsArrayGetInsert">cupsArrayGetInsert</a></li> - <li><a href="#cupsArrayIndex">cupsArrayIndex</a></li> - <li><a href="#cupsArrayInsert">cupsArrayInsert</a></li> - <li><a href="#cupsArrayLast">cupsArrayLast</a></li> - <li><a href="#cupsArrayNew">cupsArrayNew</a></li> - <li><a href="#cupsArrayNew2">cupsArrayNew2</a></li> - <li><a href="#cupsArrayNew3">cupsArrayNew3</a></li> - <li><a href="#cupsArrayNext">cupsArrayNext</a></li> - <li><a href="#cupsArrayPrev">cupsArrayPrev</a></li> - <li><a href="#cupsArrayRemove">cupsArrayRemove</a></li> - <li><a href="#cupsArrayRestore">cupsArrayRestore</a></li> - <li><a href="#cupsArraySave">cupsArraySave</a></li> - <li><a href="#cupsArrayUserData">cupsArrayUserData</a></li> - </ul></li> - <li><a href="#TYPES">Data Types</a><ul class="subcontents"> - <li><a href="#cups_acopy_func_t">cups_acopy_func_t</a></li> - <li><a href="#cups_afree_func_t">cups_afree_func_t</a></li> - <li><a href="#cups_ahash_func_t">cups_ahash_func_t</a></li> - <li><a href="#cups_array_func_t">cups_array_func_t</a></li> - <li><a href="#cups_array_t">cups_array_t</a></li> - </ul></li> - </ul> - </div> - <div class="body"> -<!-- - Array API introduction for CUPS. - - Copyright 2007-2011 by Apple Inc. - Copyright 1997-2006 by Easy Software Products, all rights reserved. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h2 class='title'><a name='OVERVIEW'>Overview</a></h2> - -<p>The CUPS array API provides a high-performance generic array container. -The contents of the array container can be sorted and the container itself is -designed for optimal speed and memory usage under a wide variety of conditions. -Sorted arrays use a binary search algorithm from the last found or inserted -element to quickly find matching elements in the array. Arrays created with the -optional hash function can often find elements with a single lookup. The -<a href='#cups_array_t'><code>cups_array_t</code></a> type is used when -referring to a CUPS array.</p> - -<p>The CUPS scheduler (<tt>cupsd</tt>) and many of the CUPS API -functions use the array API to efficiently manage large lists of -data.</p> - -<h3><a name='MANAGING_ARRAYS'>Managing Arrays</a></h3> - -<p>Arrays are created using either the -<a href='#cupsArrayNew'><code>cupsArrayNew</code></a>, -<a href='#cupsArrayNew2'><code>cupsArrayNew2</code></a>, or -<a href='#cupsArrayNew2'><code>cupsArrayNew3</code></a> functions. The -first function creates a new array with the specified callback function -and user data pointer:</p> - -<pre class='example'> -#include <cups/array.h> - -static int compare_func(void *first, void *second, void *user_data); - -void *user_data; -<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew'>cupsArrayNew</a>(compare_func, user_data); -</pre> - -<p>The comparison function (type -<a href="#cups_arrayfunc_t"><code>cups_arrayfunc_t</code></a>) is called -whenever an element is added to the array and can be <code>NULL</code> to -create an unsorted array. The function returns -1 if the first element should -come before the second, 0 if the first and second elements should have the same -ordering, and 1 if the first element should come after the second.</p> - -<p>The "user_data" pointer is passed to your comparison function. Pass -<code>NULL</code> if you do not need to associate the elements in your array -with additional information.</p> - -<p>The <a href='#cupsArrayNew2'><code>cupsArrayNew2</code></a> function adds -two more arguments to support hashed lookups, which can potentially provide -instantaneous ("O(1)") lookups in your array:</p> - -<pre class='example'> -#include <cups/array.h> - -#define HASH_SIZE 512 /* Size of hash table */ - -static int compare_func(void *first, void *second, void *user_data); -static int hash_func(void *element, void *user_data); - -void *user_data; -<a href='#cups_array_t'>cups_array_t</a> *hash_array = <a href='#cupsArrayNew2'>cupsArrayNew2</a>(compare_func, user_data, hash_func, HASH_SIZE); -</pre> - -<p>The hash function (type -<a href="#cups_ahash_func_t"><code>cups_ahash_func_t</code></a>) should return a -number from 0 to (hash_size-1) that (hopefully) uniquely identifies the -element and is called whenever you look up an element in the array with -<a href='#cupsArrayFind'><code>cupsArrayFind</code></a>. The hash size is -only limited by available memory, but generally should not be larger than -16384 to realize any performance improvement.</p> - -<p>The <a href='#cupsArrayNew3'><code>cupsArrayNew3</code></a> function adds -copy and free callbacks to support basic memory management of elements:</p> - -<pre class='example'> -#include <cups/array.h> - -#define HASH_SIZE 512 /* Size of hash table */ - -static int compare_func(void *first, void *second, void *user_data); -static void *copy_func(void *element, void *user_data); -static void free_func(void *element, void *user_data); -static int hash_func(void *element, void *user_data); - -void *user_data; -<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew3'>cupsArrayNew3</a>(compare_func, user_data, NULL, 0, copy_func, free_func); - -<a href='#cups_array_t'>cups_array_t</a> *hash_array = <a href='#cupsArrayNew3'>cupsArrayNew3</a>(compare_func, user_data, hash_func, HASH_SIZE, copy_func, free_func); -</pre> - -<p>Once you have created the array, you add elements using the -<a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> -<a href='#cupsArrayInsert'><code>cupsArrayInsert</code></a> functions. -The first function adds an element to the array, adding the new element -after any elements that have the same order, while the second inserts the -element before others with the same order. For unsorted arrays, -<a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> appends the element to -the end of the array while -<a href='#cupsArrayInsert'><code>cupsArrayInsert</code></a> inserts the -element at the beginning of the array. For example, the following code -creates a sorted array of character strings:</p> - -<pre class='example'> -#include <cups/array.h> - -/* Use strcmp() to compare strings - it will ignore the user_data pointer */ -<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew'>cupsArrayNew</a>((<a href='#cups_array_func_t'>cups_array_func_t</a>)strcmp, NULL); - -/* Add four strings to the array */ -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "One Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Two Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Red Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Blue Fish"); -</pre> - -<p>Elements are removed using the -<a href='#cupsArrayRemove'><code>cupsArrayRemove</code></a> function, for -example:</p> - -<pre class='example'> -#include <cups/array.h> - -/* Use strcmp() to compare strings - it will ignore the user_data pointer */ -<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew'>cupsArrayNew</a>((<a href='#cups_array_func_t'>cups_array_func_t</a>)strcmp, NULL); - -/* Add four strings to the array */ -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "One Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Two Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Red Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Blue Fish"); - -/* Remove "Red Fish" */ -<a href='#cupsArrayRemove'>cupsArrayRemove</a>(array, "Red Fish"); -</pre> - -<p>Finally, you free the memory used by the array using the -<a href='#cupsArrayDelete'><code>cupsArrayDelete</code></a> function. All -of the memory for the array and hash table (if any) is freed, however <em>CUPS -does not free the elements unless you provide copy and free functions</em>.</p> - -<h3><a name='FINDING_AND_ENUMERATING'>Finding and Enumerating Elements</a></h3> - -<p>CUPS provides several functions to find and enumerate elements in an -array. Each one sets or updates a "current index" into the array, such that -future lookups will start where the last one left off:</p> - -<dl> - <dt><a href='#cupsArrayFind'><code>cupsArrayFind</code></a></dt> - <dd>Returns the first matching element.</dd> - <dt><a href='#cupsArrayFirst'><code>cupsArrayFirst</code></a></dt> - <dd>Returns the first element in the array.</dd> - <dt><a href='#cupsArrayIndex'><code>cupsArrayIndex</code></a></dt> - <dd>Returns the Nth element in the array, starting at 0.</dd> - <dt><a href='#cupsArrayLast'><code>cupsArrayLast</code></a></dt> - <dd>Returns the last element in the array.</dd> - <dt><a href='#cupsArrayNext'><code>cupsArrayNext</code></a></dt> - <dd>Returns the next element in the array.</dd> - <dt><a href='#cupsArrayPrev'><code>cupsArrayPrev</code></a></dt> - <dd>Returns the previous element in the array.</dd> -</dl> - -<p>Each of these functions returns <code>NULL</code> when there is no -corresponding element. For example, a simple <code>for</code> loop using the -<a href='#cupsArrayFirst'><code>cupsArrayFirst</code></a> and -<a href='#cupsArrayNext'><code>cupsArrayNext</code></a> functions will -enumerate all of the strings in our previous example:</p> - -<pre class='example'> -#include <cups/array.h> - -/* Use strcmp() to compare strings - it will ignore the user_data pointer */ -<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew'>cupsArrayNew</a>((<a href='#cups_array_func_t'>cups_array_func_t</a>)strcmp, NULL); - -/* Add four strings to the array */ -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "One Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Two Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Red Fish"); -<a href='#cupsArrayAdd'>cupsArrayAdd</a>(array, "Blue Fish"); - -/* Show all of the strings in the array */ -char *s; -for (s = (char *)<a href='#cupsArrayFirst'>cupsArrayFirst</a>(array); s != NULL; s = (char *)<a href='#cupsArrayNext'>cupsArrayNext</a>(array)) - puts(s); -</pre> - <h2 class="title"><a id="FUNCTIONS">Functions</a></h2> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayAdd">cupsArrayAdd</a></h3> - <p class="description">Add an element to the array.</p> -<p class="code"> -int cupsArrayAdd (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a,<br /> -    void *e<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -<dt>e</dt> - <dd class="description">Element</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">When adding an element to a sorted array, non-unique elements are -appended at the end of the run of identical elements. For unsorted arrays, -the element is appended to the end of the array. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayClear">cupsArrayClear</a></h3> - <p class="description">Clear the array.</p> -<p class="code"> -void cupsArrayClear (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is equivalent to removing all elements in the array. -The caller is responsible for freeing the memory used by the -elements themselves. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayCount">cupsArrayCount</a></h3> - <p class="description">Get the number of elements in the array.</p> -<p class="code"> -int cupsArrayCount (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of elements</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayCurrent">cupsArrayCurrent</a></h3> - <p class="description">Return the current element in the array.</p> -<p class="code"> -void *cupsArrayCurrent (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Element</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>, -<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayDelete">cupsArrayDelete</a></h3> - <p class="description">Free all memory used by the array.</p> -<p class="code"> -void cupsArrayDelete (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The caller is responsible for freeing the memory used by the -elements themselves. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayDup">cupsArrayDup</a></h3> - <p class="description">Duplicate the array.</p> -<p class="code"> -<a href="#cups_array_t">cups_array_t</a> *cupsArrayDup (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Duplicate array</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayFind">cupsArrayFind</a></h3> - <p class="description">Find an element in the array.</p> -<p class="code"> -void *cupsArrayFind (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a,<br /> -    void *e<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -<dt>e</dt> - <dd class="description">Element</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Element found or <code>NULL</code></p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayFirst">cupsArrayFirst</a></h3> - <p class="description">Get the first element in the array.</p> -<p class="code"> -void *cupsArrayFirst (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">First element or <code>NULL</code> if the array is empty</p> -<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsArrayGetIndex">cupsArrayGetIndex</a></h3> - <p class="description">Get the index of the current element.</p> -<p class="code"> -int cupsArrayGetIndex (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Index of the current element, starting at 0</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>, -<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsArrayGetInsert">cupsArrayGetInsert</a></h3> - <p class="description">Get the index of the last inserted element.</p> -<p class="code"> -int cupsArrayGetInsert (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Index of the last inserted element, starting at 0</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayIndex">cupsArrayIndex</a></h3> - <p class="description">Get the N-th element in the array.</p> -<p class="code"> -void *cupsArrayIndex (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a,<br /> -    int n<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -<dt>n</dt> - <dd class="description">Index into array, starting at 0</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">N-th element or <code>NULL</code></p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayInsert">cupsArrayInsert</a></h3> - <p class="description">Insert an element in the array.</p> -<p class="code"> -int cupsArrayInsert (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a,<br /> -    void *e<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -<dt>e</dt> - <dd class="description">Element</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on failure, 1 on success</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">When inserting an element in a sorted array, non-unique elements are -inserted at the beginning of the run of identical elements. For unsorted -arrays, the element is inserted at the beginning of the array. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayLast">cupsArrayLast</a></h3> - <p class="description">Get the last element in the array.</p> -<p class="code"> -void *cupsArrayLast (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Last element or <code>NULL</code> if the array is empty</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayNew">cupsArrayNew</a></h3> - <p class="description">Create a new array.</p> -<p class="code"> -<a href="#cups_array_t">cups_array_t</a> *cupsArrayNew (<br /> -    <a href="#cups_array_func_t">cups_array_func_t</a> f,<br /> -    void *d<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>f</dt> - <dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd> -<dt>d</dt> - <dd class="description">User data pointer or <code>NULL</code></dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Array</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The comparison function ("f") is used to create a sorted array. The function -receives pointers to two elements and the user data pointer ("d") - the user -data pointer argument can safely be omitted when not required so functions -like <code>strcmp</code> can be used for sorted string arrays. - -</p> -<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsArrayNew2">cupsArrayNew2</a></h3> - <p class="description">Create a new array with hash.</p> -<p class="code"> -<a href="#cups_array_t">cups_array_t</a> *cupsArrayNew2 (<br /> -    <a href="#cups_array_func_t">cups_array_func_t</a> f,<br /> -    void *d,<br /> -    <a href="#cups_ahash_func_t">cups_ahash_func_t</a> h,<br /> -    int hsize<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>f</dt> - <dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd> -<dt>d</dt> - <dd class="description">User data or <code>NULL</code></dd> -<dt>h</dt> - <dd class="description">Hash function or <code>NULL</code> for unhashed lookups</dd> -<dt>hsize</dt> - <dd class="description">Hash size (>= 0)</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Array</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The comparison function ("f") is used to create a sorted array. The function -receives pointers to two elements and the user data pointer ("d") - the user -data pointer argument can safely be omitted when not required so functions -like <code>strcmp</code> can be used for sorted string arrays.<br> -<br> -The hash function ("h") is used to implement cached lookups with the -specified hash size ("hsize"). - -</p> -<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="cupsArrayNew3">cupsArrayNew3</a></h3> - <p class="description">Create a new array with hash and/or free function.</p> -<p class="code"> -<a href="#cups_array_t">cups_array_t</a> *cupsArrayNew3 (<br /> -    <a href="#cups_array_func_t">cups_array_func_t</a> f,<br /> -    void *d,<br /> -    <a href="#cups_ahash_func_t">cups_ahash_func_t</a> h,<br /> -    int hsize,<br /> -    <a href="#cups_acopy_func_t">cups_acopy_func_t</a> cf,<br /> -    <a href="#cups_afree_func_t">cups_afree_func_t</a> ff<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>f</dt> - <dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd> -<dt>d</dt> - <dd class="description">User data or <code>NULL</code></dd> -<dt>h</dt> - <dd class="description">Hash function or <code>NULL</code> for unhashed lookups</dd> -<dt>hsize</dt> - <dd class="description">Hash size (>= 0)</dd> -<dt>cf</dt> - <dd class="description">Copy function</dd> -<dt>ff</dt> - <dd class="description">Free function</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Array</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The comparison function ("f") is used to create a sorted array. The function -receives pointers to two elements and the user data pointer ("d") - the user -data pointer argument can safely be omitted when not required so functions -like <code>strcmp</code> can be used for sorted string arrays.<br> -<br> -The hash function ("h") is used to implement cached lookups with the -specified hash size ("hsize").<br> -<br> -The copy function ("cf") is used to automatically copy/retain elements when -added or the array is copied.<br> -<br> -The free function ("cf") is used to automatically free/release elements when -removed or the array is deleted. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayNext">cupsArrayNext</a></h3> - <p class="description">Get the next element in the array.</p> -<p class="code"> -void *cupsArrayNext (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Next element or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) + 1)".<br> -<br> -The next element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>, -<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a> -to set the current element. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayPrev">cupsArrayPrev</a></h3> - <p class="description">Get the previous element in the array.</p> -<p class="code"> -void *cupsArrayPrev (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Previous element or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) - 1)".<br> -<br> -The previous element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>, -<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a> -to set the current element. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayRemove">cupsArrayRemove</a></h3> - <p class="description">Remove an element from the array.</p> -<p class="code"> -int cupsArrayRemove (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a,<br /> -    void *e<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -<dt>e</dt> - <dd class="description">Element</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">If more than one element matches "e", only the first matching element is -removed.<br> -<br> -The caller is responsible for freeing the memory used by the -removed element. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayRestore">cupsArrayRestore</a></h3> - <p class="description">Reset the current element to the last <a href="#cupsArraySave"><code>cupsArraySave</code></a>.</p> -<p class="code"> -void *cupsArrayRestore (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New current element</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArraySave">cupsArraySave</a></h3> - <p class="description">Mark the current element for a later <a href="#cupsArrayRestore"><code>cupsArrayRestore</code></a>.</p> -<p class="code"> -int cupsArraySave (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>, -<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a> -to set the current element.<br> -<br> -The save/restore stack is guaranteed to be at least 32 elements deep. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayUserData">cupsArrayUserData</a></h3> - <p class="description">Return the user data for an array.</p> -<p class="code"> -void *cupsArrayUserData (<br /> -    <a href="#cups_array_t">cups_array_t</a> *a<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>a</dt> - <dd class="description">Array</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">User data</p> - <h2 class="title"><a id="TYPES">Data Types</a></h2> - <h3 class="typedef"><a id="cups_acopy_func_t">cups_acopy_func_t</a></h3> - <p class="description">Array element copy function</p> - <p class="code"> -typedef void *(*cups_acopy_func_t)(void *element, void *data); -</p> - <h3 class="typedef"><a id="cups_afree_func_t">cups_afree_func_t</a></h3> - <p class="description">Array element free function</p> - <p class="code"> -typedef void (*cups_afree_func_t)(void *element, void *data); -</p> - <h3 class="typedef"><a id="cups_ahash_func_t">cups_ahash_func_t</a></h3> - <p class="description">Array hash function</p> - <p class="code"> -typedef int (*cups_ahash_func_t)(void *element, void *data); -</p> - <h3 class="typedef"><a id="cups_array_func_t">cups_array_func_t</a></h3> - <p class="description">Array comparison function</p> - <p class="code"> -typedef int (*cups_array_func_t)(void *first, void *second, void *data); -</p> - <h3 class="typedef"><a id="cups_array_t">cups_array_t</a></h3> - <p class="description">CUPS array type</p> - <p class="code"> -typedef struct _cups_array_s cups_array_t; -</p> - </div> - </body> -</html> diff --git a/doc/help/api-cups.html b/doc/help/api-cups.html deleted file mode 100644 index 19039b2cf..000000000 --- a/doc/help/api-cups.html +++ /dev/null @@ -1,3587 +0,0 @@ -<!doctype html> -<html> -<!-- SECTION: Programming --> - <head> - <title>CUPS API</title> - <meta name="keywords" content="Programming"> - <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> - <meta name="creator" content="Mini-XML v2.11"> - <meta name="author" content="Unknown"> - <meta name="copyright" content="Unknown"> - <style type="text/css"><!-- -BODY { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -H1, H2, H3, H4, H5, H6, P, TD, TH { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -KBD { - font-family: monaco, courier, monospace; - font-weight: bold; -} - -PRE { - font-family: monaco, courier, monospace; -} - -PRE.command { - border: dotted thin #7f7f7f; - margin-left: 36pt; - padding: 10px; -} - -P.compact { - margin: 0; -} - -P.example { - font-style: italic; - margin-left: 36pt; -} - -DL.man DD { - margin-left: 5em; -} - -DL.man DT { - margin-left: 0; -} - -PRE.man { - margin: 0; -} - -PRE.example { - background: #eeeeee; - border: dotted thin #999999; - margin-left: 36pt; - padding: 10pt; -} - -PRE.command EM, PRE.example EM { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -P.command { - font-family: monaco, courier, monospace; - margin-left: 36pt; -} - -P.formula { - font-style: italic; - margin-left: 36pt; -} - -BLOCKQUOTE { - background: #eeeeee; - border: solid thin #999999; - padding: 10pt; -} - -A IMG { - border: none; -} - -A:link:hover IMG { - background: #f0f0f0; - border-radius: 10px; - -moz-border-radius: 10px; -} - -A:link, A:visited { - font-weight: inherit; - text-decoration: none; -} - -A:link:hover, A:visited:hover, A:active { - text-decoration: underline; -} - -SUB, SUP { - font-size: 50%; -} - -TR.data, TD.data, TR.data TD { - margin-top: 10pt; - padding: 5pt; - border-bottom: solid 1pt #999999; -} - -TR.data TH { - border-bottom: solid 1pt #999999; - padding-top: 10pt; - padding-left: 5pt; - text-align: left; -} - -DIV.table TABLE { - border: solid thin #999999; - border-collapse: collapse; - border-spacing: 0; - margin-left: auto; - margin-right: auto; -} - -DIV.table CAPTION { - caption-side: top; - font-size: 120%; - font-style: italic; - font-weight: bold; - margin-left: auto; - margin-right: auto; -} - -DIV.table TABLE TD { - border: solid thin #cccccc; - padding-top: 5pt; -} - -DIV.table TABLE TH { - background: #cccccc; - border: none; - border-bottom: solid thin #999999; -} - -DIV.figure TABLE { - margin-left: auto; - margin-right: auto; -} - -DIV.figure CAPTION { - caption-side: bottom; - font-size: 120%; - font-style: italic; - font-weight: bold; - margin-left: auto; - margin-right: auto; -} - -TH.label { - text-align: right; - vertical-align: top; -} - -TH.sublabel { - text-align: right; - font-weight: normal; -} - -HR { - border: solid thin; -} - -SPAN.info { - background: black; - border: thin solid black; - color: white; - font-size: 80%; - font-style: italic; - font-weight: bold; - white-space: nowrap; -} - -H2 SPAN.info, H3 SPAN.info, H4 SPAN.info { - float: right; - font-size: 100%; -} - -H1.title { -} - -H2.title, H3.title { - border-bottom: solid 2pt #000000; -} - -DIV.indent, TABLE.indent { - margin-top: 2em; - margin-left: auto; - margin-right: auto; - width: 90%; -} - -TABLE.indent { - border-collapse: collapse; -} - -TABLE.indent TD, TABLE.indent TH { - padding: 0; -} - -TABLE.list { - border-collapse: collapse; - margin-left: auto; - margin-right: auto; - width: 90%; -} - -TABLE.list TH { - background: white; - border-bottom: solid thin #cccccc; - color: #444444; - padding-top: 10pt; - padding-left: 5pt; - text-align: left; - vertical-align: bottom; - white-space: nowrap; -} - -TABLE.list TH A { - color: #4444cc; -} - -TABLE.list TD { - border-bottom: solid thin #eeeeee; - padding-top: 5pt; - padding-left: 5pt; -} - -TABLE.list TR:nth-child(even) { - background: #f8f8f8; -} - -TABLE.list TR:nth-child(odd) { - background: #f4f4f4; -} - -DT { - margin-left: 36pt; - margin-top: 12pt; -} - -DD { - margin-left: 54pt; -} - -DL.category DT { - font-weight: bold; -} - -P.summary { - margin-left: 36pt; - font-family: monaco, courier, monospace; -} - -DIV.summary TABLE { - border: solid thin #999999; - border-collapse: collapse; - border-spacing: 0; - margin: 10px; -} - -DIV.summary TABLE TD, DIV.summary TABLE TH { - border: solid thin #999999; - padding: 5px; - text-align: left; - vertical-align: top; -} - -DIV.summary TABLE THEAD TH { - background: #eeeeee; -} - -/* API documentation styles... */ -div.body h1 { - margin: 0; -} -div.body h2 { - margin-top: 1.5em; -} -div.body h3, div.body h4, div.body h5 { - margin-bottom: 0.5em; - margin-top: 1.5em; -} -.class, .enumeration, .function, .struct, .typedef, .union { - border-bottom: solid thin #999999; - margin-bottom: 0; - margin-top: 2em; -} -.description { - margin-top: 0.5em; -} -code, p.code, pre, ul.code li { - font-family: monaco, courier, monospace; - font-size: 90%; -} -ul.code, ul.contents, ul.subcontents { - list-style-type: none; - margin: 0; - padding-left: 0; -} -ul.code li { - margin: 0; -} -ul.contents > li { - margin-top: 1em; -} -ul.contents li ul.code, ul.contents li ul.subcontents { - padding-left: 2em; -} -div.body dl { - margin-left: 0; - margin-top: 0; -} -div.body dt { - font-style: italic; - margin-left: 0; - margin-top: 0; -} -div.body dd { - margin-bottom: 0.5em; -} - -/* This is just for the HTML files generated with the framedhelp target */ -div.contents { - background: #e8e8e8; - border: solid thin black; - padding: 10px; -} -div.contents h1 { - font-size: 110%; -} -div.contents h2 { - font-size: 100%; -} -div.contents ul.contents { - font-size: 80%; -} -div.contents ul.subcontents li { - margin-left: 1em; - text-indent: -1em; -} ---></style> - </head> - <body> -<!-- - CUPS API header for CUPS. - - Copyright 2008-2011 by Apple Inc. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h1 class='title'>CUPS API</h1> - -<div class='summary'><table summary='General Information'> -<thead> -<tr> - <th>Header</th> - <th>cups/cups.h</th> -</tr> -</thead> -<tbody> -<tr> - <th>Library</th> - <td>-lcups</td> -</tr> -<tr> - <th>See Also</th> - <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br> - Programming: <a href='api-array.html' target='_top'>Array API</a><br> - Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br> - Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br> - Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br> - Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br> - Programming: <a href='api-raster.html' target='_top'>Raster API</a></td> -</tr> -</tbody> -</table></div> - <div class="contents"> - <h2 class="title">Contents</h2> - <ul class="contents"> - <li><a href="#OVERVIEW">Overview</a><ul class="subcontents"> - <li><a href="#CLIENTS_AND_SERVERS">Clients and Servers</a></li> - <li><a href="#PRINTERS_AND_CLASSES">Printers and Classes</a></li> - <li><a href="#OPTIONS">Options</a></li> - <li><a href="#PRINT_JOBS">Print Jobs</a></li> - <li><a href="#ERROR_HANDLING">Error Handling</a></li> - <li><a href="#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication</a></li> - </ul></li> - <li><a href="#FUNCTIONS">Functions</a><ul class="subcontents"> - <li><a href="#cupsAddDest">cupsAddDest</a></li> - <li><a href="#cupsAddOption">cupsAddOption</a></li> - <li><a href="#cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></li> - <li><a href="#cupsAdminExportSamba">cupsAdminExportSamba</a></li> - <li><a href="#cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></li> - <li><a href="#cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></li> - <li><a href="#cupsCancelDestJob">cupsCancelDestJob</a></li> - <li><a href="#cupsCancelJob">cupsCancelJob</a></li> - <li><a href="#cupsCancelJob2">cupsCancelJob2</a></li> - <li><a href="#cupsCheckDestSupported">cupsCheckDestSupported</a></li> - <li><a href="#cupsCloseDestJob">cupsCloseDestJob</a></li> - <li><a href="#cupsConnectDest">cupsConnectDest</a></li> - <li><a href="#cupsConnectDestBlock">cupsConnectDestBlock</a></li> - <li><a href="#cupsCopyDest">cupsCopyDest</a></li> - <li><a href="#cupsCopyDestConflicts">cupsCopyDestConflicts</a></li> - <li><a href="#cupsCopyDestInfo">cupsCopyDestInfo</a></li> - <li><a href="#cupsCreateDestJob">cupsCreateDestJob</a></li> - <li><a href="#cupsCreateJob">cupsCreateJob</a></li> - <li><a href="#cupsEncryption">cupsEncryption</a></li> - <li><a href="#cupsEnumDests">cupsEnumDests</a></li> - <li><a href="#cupsEnumDestsBlock">cupsEnumDestsBlock</a></li> - <li><a href="#cupsFindDestDefault">cupsFindDestDefault</a></li> - <li><a href="#cupsFindDestReady">cupsFindDestReady</a></li> - <li><a href="#cupsFindDestSupported">cupsFindDestSupported</a></li> - <li><a href="#cupsFinishDestDocument">cupsFinishDestDocument</a></li> - <li><a href="#cupsFinishDocument">cupsFinishDocument</a></li> - <li><a href="#cupsFreeDestInfo">cupsFreeDestInfo</a></li> - <li><a href="#cupsFreeDests">cupsFreeDests</a></li> - <li><a href="#cupsFreeJobs">cupsFreeJobs</a></li> - <li><a href="#cupsFreeOptions">cupsFreeOptions</a></li> - <li><a href="#cupsGetClasses">cupsGetClasses</a></li> - <li><a href="#cupsGetDefault">cupsGetDefault</a></li> - <li><a href="#cupsGetDefault2">cupsGetDefault2</a></li> - <li><a href="#cupsGetDest">cupsGetDest</a></li> - <li><a href="#cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></li> - <li><a href="#cupsGetDestMediaByName">cupsGetDestMediaByName</a></li> - <li><a href="#cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></li> - <li><a href="#cupsGetDestMediaCount">cupsGetDestMediaCount</a></li> - <li><a href="#cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></li> - <li><a href="#cupsGetDestWithURI">cupsGetDestWithURI</a></li> - <li><a href="#cupsGetDests">cupsGetDests</a></li> - <li><a href="#cupsGetDests2">cupsGetDests2</a></li> - <li><a href="#cupsGetJobs">cupsGetJobs</a></li> - <li><a href="#cupsGetJobs2">cupsGetJobs2</a></li> - <li><a href="#cupsGetNamedDest">cupsGetNamedDest</a></li> - <li><a href="#cupsGetOption">cupsGetOption</a></li> - <li><a href="#cupsGetPassword">cupsGetPassword</a></li> - <li><a href="#cupsGetPassword2">cupsGetPassword2</a></li> - <li><a href="#cupsGetPrinters">cupsGetPrinters</a></li> - <li><a href="#cupsLangDefault">cupsLangDefault</a></li> - <li><a href="#cupsLangEncoding">cupsLangEncoding</a></li> - <li><a href="#cupsLangFlush">cupsLangFlush</a></li> - <li><a href="#cupsLangFree">cupsLangFree</a></li> - <li><a href="#cupsLangGet">cupsLangGet</a></li> - <li><a href="#cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></li> - <li><a href="#cupsLocalizeDestOption">cupsLocalizeDestOption</a></li> - <li><a href="#cupsLocalizeDestValue">cupsLocalizeDestValue</a></li> - <li><a href="#cupsNotifySubject">cupsNotifySubject</a></li> - <li><a href="#cupsNotifyText">cupsNotifyText</a></li> - <li><a href="#cupsParseOptions">cupsParseOptions</a></li> - <li><a href="#cupsPrintFile">cupsPrintFile</a></li> - <li><a href="#cupsPrintFile2">cupsPrintFile2</a></li> - <li><a href="#cupsPrintFiles">cupsPrintFiles</a></li> - <li><a href="#cupsPrintFiles2">cupsPrintFiles2</a></li> - <li><a href="#cupsRemoveDest">cupsRemoveDest</a></li> - <li><a href="#cupsRemoveOption">cupsRemoveOption</a></li> - <li><a href="#cupsServer">cupsServer</a></li> - <li><a href="#cupsSetClientCertCB">cupsSetClientCertCB</a></li> - <li><a href="#cupsSetCredentials">cupsSetCredentials</a></li> - <li><a href="#cupsSetDefaultDest">cupsSetDefaultDest</a></li> - <li><a href="#cupsSetDests">cupsSetDests</a></li> - <li><a href="#cupsSetDests2">cupsSetDests2</a></li> - <li><a href="#cupsSetEncryption">cupsSetEncryption</a></li> - <li><a href="#cupsSetPasswordCB">cupsSetPasswordCB</a></li> - <li><a href="#cupsSetPasswordCB2">cupsSetPasswordCB2</a></li> - <li><a href="#cupsSetServer">cupsSetServer</a></li> - <li><a href="#cupsSetServerCertCB">cupsSetServerCertCB</a></li> - <li><a href="#cupsSetUser">cupsSetUser</a></li> - <li><a href="#cupsSetUserAgent">cupsSetUserAgent</a></li> - <li><a href="#cupsStartDestDocument">cupsStartDestDocument</a></li> - <li><a href="#cupsStartDocument">cupsStartDocument</a></li> - <li><a href="#cupsTempFd">cupsTempFd</a></li> - <li><a href="#cupsTempFile">cupsTempFile</a></li> - <li><a href="#cupsTempFile2">cupsTempFile2</a></li> - <li><a href="#cupsUser">cupsUser</a></li> - <li><a href="#cupsUserAgent">cupsUserAgent</a></li> - <li><a href="#pwgFormatSizeName">pwgFormatSizeName</a></li> - <li><a href="#pwgInitSize">pwgInitSize</a></li> - <li><a href="#pwgMediaForLegacy">pwgMediaForLegacy</a></li> - <li><a href="#pwgMediaForPPD">pwgMediaForPPD</a></li> - <li><a href="#pwgMediaForPWG">pwgMediaForPWG</a></li> - <li><a href="#pwgMediaForSize">pwgMediaForSize</a></li> - </ul></li> - <li><a href="#TYPES">Data Types</a><ul class="subcontents"> - <li><a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a></li> - <li><a href="#cups_dest_block_t">cups_dest_block_t</a></li> - <li><a href="#cups_dest_cb_t">cups_dest_cb_t</a></li> - <li><a href="#cups_dest_t">cups_dest_t</a></li> - <li><a href="#cups_dinfo_t">cups_dinfo_t</a></li> - <li><a href="#cups_job_t">cups_job_t</a></li> - <li><a href="#cups_option_t">cups_option_t</a></li> - <li><a href="#cups_password_cb2_t">cups_password_cb2_t</a></li> - <li><a href="#cups_password_cb_t">cups_password_cb_t</a></li> - <li><a href="#cups_ptype_t">cups_ptype_t</a></li> - <li><a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a></li> - <li><a href="#cups_size_t">cups_size_t</a></li> - <li><a href="#pwg_map_t">pwg_map_t</a></li> - <li><a href="#pwg_media_t">pwg_media_t</a></li> - <li><a href="#pwg_size_t">pwg_size_t</a></li> - </ul></li> - <li><a href="#STRUCTURES">Structures</a><ul class="subcontents"> - <li><a href="#cups_dest_s">cups_dest_s</a></li> - <li><a href="#cups_job_s">cups_job_s</a></li> - <li><a href="#cups_option_s">cups_option_s</a></li> - <li><a href="#cups_size_s">cups_size_s</a></li> - <li><a href="#pollfd">pollfd</a></li> - <li><a href="#pwg_map_s">pwg_map_s</a></li> - <li><a href="#pwg_media_s">pwg_media_s</a></li> - <li><a href="#pwg_size_s">pwg_size_s</a></li> - </ul></li> - <li><a href="#VARIABLES">Variables</a><ul class="subcontents"> - <li><a href="#CF_RETURNS_RETAINED">CF_RETURNS_RETAINED</a></li> - </ul></li> - <li><a href="#ENUMERATIONS">Enumerations</a><ul class="subcontents"> - <li><a href="#cups_ptype_e">cups_ptype_e</a></li> - </ul></li> - </ul> - </div> - <div class="body"> -<!-- - API introduction for CUPS. - - Copyright 2007-2013 by Apple Inc. - Copyright 1997-2006 by Easy Software Products, all rights reserved. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h2 class='title'><a name='OVERVIEW'>Overview</a></h2> - -<p>The CUPS API provides the convenience functions needed to support -applications, filters, printer drivers, and backends that need to interface -with the CUPS scheduler.</p> - -<h3><a name='CLIENTS_AND_SERVERS'>Clients and Servers</a></h3> - -<p>CUPS is based on the Internet Printing Protocol ("IPP"), which allows -clients (applications) to communicate with a server (the scheduler) to get a -list of printers, send print jobs, and so forth. You identify which server -you want to communicate with using a pointer to the opaque structure -<code>http_t</code>. All of the examples in this document use the -<code>CUPS_HTTP_DEFAULT</code> constant, referring to the default connection -to the scheduler. The <a href='api-httpipp.html' target='_top'>HTTP and IPP -APIs</a> document provides more information on server connections.</p> - -<h3><a name='PRINTERS_AND_CLASSES'>Printers and Classes</a></h3> - -<p>Printers and classes (collections of printers) are accessed through -the <a href="#cups_dest_t"><code>cups_dest_t</code></a> structure which -includes the name (<code>name</code>), instance (<code>instance</code> - -a way of selecting certain saved options/settings), and the options and -attributes associated with that destination (<code>num_options</code> and -<code>options</code>). Destinations are created using the -<a href="#cupsGetDests"><code>cupsGetDests</code></a> function and freed -using the <a href='#cupsFreeDests'><code>cupsFreeDests</code></a> function. -The <a href='#cupsGetDest'><code>cupsGetDest</code></a> function finds a -specific destination for printing:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dests; -int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests); -<a href='#cups_dest_t'>cups_dest_t</a> *dest = <a href='#cupsGetDest'>cupsGetDest</a>("name", NULL, num_dests, dests); - -/* do something with dest */ - -<a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests); -</pre> - -<p>Passing <code>NULL</code> to -<a href='#cupsGetDest'><code>cupsGetDest</code></a> for the destination name -will return the default destination. Similarly, passing a <code>NULL</code> -instance will return the default instance for that destination.</p> - -<div class='table'><table summary='Table 1: Printer Attributes' width='80%'> -<caption>Table 1: <a name='TABLE1'>Printer Attributes</a></caption> -<thead> -<tr> - <th>Attribute Name</th> - <th>Description</th> -</tr> -</thead> -<tbody> -<tr> - <td>"auth-info-required"</td> - <td>The type of authentication required for printing to this - destination: "none", "username,password", "domain,username,password", - or "negotiate" (Kerberos)</td> -</tr> -<tr> - <td>"printer-info"</td> - <td>The human-readable description of the destination such as "My - Laser Printer".</td> -</tr> -<tr> - <td>"printer-is-accepting-jobs"</td> - <td>"true" if the destination is accepting new jobs, "false" if - not.</td> -</tr> -<tr> - <td>"printer-is-shared"</td> - <td>"true" if the destination is being shared with other computers, - "false" if not.</td> -</tr> -<tr> - <td>"printer-location"</td> - <td>The human-readable location of the destination such as "Lab 4".</td> -</tr> -<tr> - <td>"printer-make-and-model"</td> - <td>The human-readable make and model of the destination such as "HP - LaserJet 4000 Series".</td> -</tr> -<tr> - <td>"printer-state"</td> - <td>"3" if the destination is idle, "4" if the destination is printing - a job, and "5" if the destination is stopped.</td> -</tr> -<tr> - <td>"printer-state-change-time"</td> - <td>The UNIX time when the destination entered the current state.</td> -</tr> -<tr> - <td>"printer-state-reasons"</td> - <td>Additional comma-delimited state keywords for the destination - such as "media-tray-empty-error" and "toner-low-warning".</td> -</tr> -<tr> - <td>"printer-type"</td> - <td>The <a href='#cups_printer_t'><code>cups_printer_t</code></a> - value associated with the destination.</td> -</tr> -</tbody> -</table></div> - -<h3><a name='OPTIONS'>Options</a></h3> - -<p>Options are stored in arrays of -<a href='#cups_option_t'><code>cups_option_t</code></a> structures. Each -option has a name (<code>name</code>) and value (<code>value</code>) -associated with it. The <a href='#cups_dest_t'><code>cups_dest_t</code></a> -<code>num_options</code> and <code>options</code> members contain the -default options for a particular destination, along with several informational -attributes about the destination as shown in <a href='#TABLE1'>Table 1</a>. -The <a href='#cupsGetOption'><code>cupsGetOption</code></a> function gets -the value for the named option. For example, the following code lists the -available destinations and their human-readable descriptions:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dests; -int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests); -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int i; -const char *value; - -for (i = num_dests, dest = dests; i > 0; i --, dest ++) - if (dest->instance == NULL) - { - value = <a href='#cupsGetOption'>cupsGetOption</a>("printer-info", dest->num_options, dest->options); - printf("%s (%s)\n", dest->name, value ? value : "no description"); - } - -<a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests); -</pre> - -<p>You can create your own option arrays using the -<a href='#cupsAddOption'><code>cupsAddOption</code></a> function, which -adds a single named option to an array:</p> - -<pre class='example'> -#include <cups/cups.h> - -int num_options = 0; -<a href='#cups_option_t'>cups_option_t</a> *options = NULL; - -/* The returned num_options value is updated as needed */ -num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "value", num_options, &options); - -/* This adds a second option value */ -num_options = <a href='#cupsAddOption'>cupsAddOption</a>("second", "value", num_options, &options); - -/* This replaces the first option we added */ -num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "new value", num_options, &options); -</pre> - -<p>Use a <code>for</code> loop to copy the options from a destination:</p> - -<pre class='example'> -#include <cups/cups.h> - -int i; -int num_options = 0; -<a href='#cups_option_t'>cups_option_t</a> *options = NULL; -<a href='#cups_dest_t'>cups_dest_t</a> *dest; - -for (i = 0; i < dest->num_options; i ++) - num_options = <a href='#cupsAddOption'>cupsAddOption</a>(dest->options[i].name, dest->options[i].value, - num_options, &options); -</pre> - -<p>Use the <a href='#cupsFreeOptions'><code>cupsFreeOptions</code></a> -function to free the options array when you are done using it:</p> - -<pre class='example'> -<a href='#cupsFreeOptions'>cupsFreeOptions</a>(num_options, options); -</pre> - -<h3><a name='PRINT_JOBS'>Print Jobs</a></h3> - -<p>Print jobs are identified by a locally-unique job ID number from 1 to -2<sup>31</sup>-1 and have options and one or more files for printing to a -single destination. The <a href='#cupsPrintFile'><code>cupsPrintFile</code></a> -function creates a new job with one file. The following code prints the CUPS -test page file:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int num_options; -<a href='#cups_option_t'>cups_option_t</a> *options; -int job_id; - -/* Print a single file */ -job_id = <a href='#cupsPrintFile'>cupsPrintFile</a>(dest->name, "/usr/share/cups/data/testprint.ps", - "Test Print", num_options, options); -</pre> - -<p>The <a href='#cupsPrintFiles'><code>cupsPrintFiles</code></a> function -creates a job with multiple files. The files are provided in a -<code>char *</code> array:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int num_options; -<a href='#cups_option_t'>cups_option_t</a> *options; -int job_id; -char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" }; - -/* Print three files */ -job_id = <a href='#cupsPrintFiles'>cupsPrintFiles</a>(dest->name, 3, files, "Test Print", num_options, options); -</pre> - -<p>Finally, the <a href='#cupsCreateJob'><code>cupsCreateJob</code></a> -function creates a new job with no files in it. Files are added using the -<a href='#cupsStartDocument'><code>cupsStartDocument</code></a>, -<a href='api-httpipp.html#cupsWriteRequestData'><code>cupsWriteRequestData</code></a>, -and <a href='#cupsFinishDocument'><code>cupsFinishDocument</code></a> functions. -The following example creates a job with 10 text files for printing:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int num_options; -<a href='#cups_option_t'>cups_option_t</a> *options; -int job_id; -int i; -char buffer[1024]; - -/* Create the job */ -job_id = <a href='#cupsCreateJob'>cupsCreateJob</a>(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files", - num_options, options); - -/* If the job is created, add 10 files */ -if (job_id > 0) -{ - for (i = 1; i <= 10; i ++) - { - snprintf(buffer, sizeof(buffer), "file%d.txt", i); - - <a href='#cupsStartDocument'>cupsStartDocument</a>(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer, - CUPS_FORMAT_TEXT, i == 10); - - snprintf(buffer, sizeof(buffer), - "File %d\n" - "\n" - "One fish,\n" - "Two fish,\n - "Red fish,\n - "Blue fish\n", i); - - /* cupsWriteRequestData can be called as many times as needed */ - <a href='#cupsWriteRequestData'>cupsWriteRequestData</a>(CUPS_HTTP_DEFAULT, buffer, strlen(buffer)); - - <a href='#cupsFinishDocument'>cupsFinishDocument</a>(CUPS_HTTP_DEFAULT, dest->name); - } -} -</pre> - -<p>Once you have created a job, you can monitor its status using the -<a href='#cupsGetJobs'><code>cupsGetJobs</code></a> function, which returns -an array of <a href='#cups_job_t'><code>cups_job_t</code></a> structures. -Each contains the job ID (<code>id</code>), destination name -(<code>dest</code>), title (<code>title</code>), and other information -associated with the job. The job array is freed using the -<a href='#cupsFreeJobs'><code>cupsFreeJobs</code></a> function. The following -example monitors a specific job ID, showing the current job state once every -5 seconds until the job is completed:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int job_id; -int num_jobs; -<a href='#cups_job_t'>cups_job_t</a> *jobs; -int i; -ipp_jstate_t job_state = IPP_JOB_PENDING; - -while (job_state < IPP_JOB_STOPPED) -{ - /* Get my jobs (1) with any state (-1) */ - num_jobs = <a href='#cupsGetJobs'>cupsGetJobs</a>(&jobs, dest->name, 1, -1); - - /* Loop to find my job */ - job_state = IPP_JOB_COMPLETED; - - for (i = 0; i < num_jobs; i ++) - if (jobs[i].id == job_id) - { - job_state = jobs[i].state; - break; - } - - /* Free the job array */ - <a href='#cupsFreeJobs'>cupsFreeJobs</a>(num_jobs, jobs); - - /* Show the current state */ - switch (job_state) - { - case IPP_JOB_PENDING : - printf("Job %d is pending.\n", job_id); - break; - case IPP_JOB_HELD : - printf("Job %d is held.\n", job_id); - break; - case IPP_JOB_PROCESSING : - printf("Job %d is processing.\n", job_id); - break; - case IPP_JOB_STOPPED : - printf("Job %d is stopped.\n", job_id); - break; - case IPP_JOB_CANCELED : - printf("Job %d is canceled.\n", job_id); - break; - case IPP_JOB_ABORTED : - printf("Job %d is aborted.\n", job_id); - break; - case IPP_JOB_COMPLETED : - printf("Job %d is completed.\n", job_id); - break; - } - - /* Sleep if the job is not finished */ - if (job_state < IPP_JOB_STOPPED) - sleep(5); -} -</pre> - -<p>To cancel a job, use the -<a href='#cupsCancelJob'><code>cupsCancelJob</code></a> function with the -job ID:</p> - -<pre class='example'> -#include <cups/cups.h> - -<a href='#cups_dest_t'>cups_dest_t</a> *dest; -int job_id; - -<a href='#cupsCancelJob'>cupsCancelJob</a>(dest->name, job_id); -</pre> - -<h3><a name='ERROR_HANDLING'>Error Handling</a></h3> - -<p>If any of the CUPS API printing functions returns an error, the reason for -that error can be found by calling the -<a href='#cupsLastError'><code>cupsLastError</code></a> and -<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> functions. -<a href='#cupsLastError'><code>cupsLastError</code></a> returns the last IPP -error code -(<a href='api-httpipp.html#ipp_status_t'><code>ipp_status_t</code></a>) -that was encountered, while -<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> returns -a (localized) human-readable string that can be shown to the user. For example, -if any of the job creation functions returns a job ID of 0, you can use -<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> to show -the reason why the job could not be created:</p> - -<pre class='example'> -#include <cups/cups.h> - -int job_id; - -if (job_id == 0) - puts(cupsLastErrorString()); -</pre> - -<h3><a name='PASSWORDS_AND_AUTHENTICATION'>Passwords and Authentication</a></h3> - -<p>CUPS supports authentication of any request, including submission of print -jobs. The default mechanism for getting the username and password is to use the -login user and a password from the console.</p> - -<p>To support other types of applications, in particular Graphical User -Interfaces ("GUIs"), the CUPS API provides functions to set the default -username and to register a callback function that returns a password string.</p> - -<p>The <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> -function is used to set a password callback in your program. Only one -function can be used at any time.</p> - -<p>The <a href="#cupsSetUser"><code>cupsSetUser</code></a> function sets the -current username for authentication. This function can be called by your -password callback function to change the current username as needed.</p> - -<p>The following example shows a simple password callback that gets a -username and password from the user:</p> - -<pre class='example'> -#include <cups/cups.h> - -const char * -my_password_cb(const char *prompt) -{ - char user[65]; - - - puts(prompt); - - /* Get a username from the user */ - printf("Username: "); - if (fgets(user, sizeof(user), stdin) == NULL) - return (NULL); - - /* Strip the newline from the string and set the user */ - user[strlen(user) - 1] = '\0'; - - <a href='#cupsSetUser'>cupsSetUser</a>(user); - - /* Use getpass() to ask for the password... */ - return (getpass("Password: ")); -} - -<a href='#cupsSetPasswordCB'>cupsSetPasswordCB</a>(my_password_cb); -</pre> - -<p>Similarly, a GUI could display the prompt string in a window with input -fields for the username and password. The username should default to the -string returned by the <a href="#cupsUser"><code>cupsUser</code></a> -function.</p> - <h2 class="title"><a id="FUNCTIONS">Functions</a></h2> -<h3 class="function"><a id="cupsAddDest">cupsAddDest</a></h3> - <p class="description">Add a destination to the list of destinations.</p> -<p class="code"> -int cupsAddDest (<br /> -    const char *name,<br /> -    const char *instance,<br /> -    int num_dests,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> **dests<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Destination name</dd> -<dt>instance</dt> - <dd class="description">Instance name or <code>NULL</code> for none/primary</dd> -<dt>num_dests</dt> - <dd class="description">Number of destinations</dd> -<dt>dests</dt> - <dd class="description">Destinations</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New number of destinations</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function cannot be used to add a new class or printer queue, -it only adds a new container of saved options for the named -destination or instance.<br> -<br> -If the named destination already exists, the destination list is -returned unchanged. Adding a new instance of a destination creates -a copy of that destination's options.<br> -<br> -Use the <a href="#cupsSaveDests"><code>cupsSaveDests</code></a> function to save the updated list of -destinations to the user's lpoptions file.</p> -<h3 class="function"><a id="cupsAddOption">cupsAddOption</a></h3> - <p class="description">Add an option to an option array.</p> -<p class="code"> -int cupsAddOption (<br /> -    const char *name,<br /> -    const char *value,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> **options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Name of option</dd> -<dt>value</dt> - <dd class="description">Value of option</dd> -<dt>num_options</dt> - <dd class="description">Number of options</dd> -<dt>options</dt> - <dd class="description">Pointer to options</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of options</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">New option arrays can be initialized simply by passing 0 for the -"num_options" parameter.</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></h3> - <p class="description">Create the Windows PPD file for a printer.</p> -<p class="code"> -char *cupsAdminCreateWindowsPPD (<br /> -    http_t *http,<br /> -    const char *dest,<br /> -    char *buffer,<br /> -    int bufsize<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>dest</dt> - <dd class="description">Printer or class</dd> -<dt>buffer</dt> - <dd class="description">Filename buffer</dd> -<dt>bufsize</dt> - <dd class="description">Size of filename buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">PPD file or NULL</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="cupsAdminExportSamba">cupsAdminExportSamba</a></h3> - <p class="description">Export a printer to Samba.</p> -<p class="code"> -int cupsAdminExportSamba (<br /> -    const char *dest,<br /> -    const char *ppd,<br /> -    const char *samba_server,<br /> -    const char *samba_user,<br /> -    const char *samba_password,<br /> -    FILE *logfile<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dest</dt> - <dd class="description">Destination to export</dd> -<dt>ppd</dt> - <dd class="description">PPD file</dd> -<dt>samba_server</dt> - <dd class="description">Samba server</dd> -<dt>samba_user</dt> - <dd class="description">Samba username</dd> -<dt>samba_password</dt> - <dd class="description">Samba password</dd> -<dt>logfile</dt> - <dd class="description">Log file, if any</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3> - <p class="description">Get settings from the server.</p> -<p class="code"> -int cupsAdminGetServerSettings (<br /> -    http_t *http,<br /> -    int *num_settings,<br /> -    <a href="#cups_option_t">cups_option_t</a> **settings<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>num_settings</dt> - <dd class="description">Number of settings</dd> -<dt>settings</dt> - <dd class="description">Settings</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The returned settings should be freed with cupsFreeOptions() when -you are done with them. - -</p> -<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3> - <p class="description">Set settings on the server.</p> -<p class="code"> -int cupsAdminSetServerSettings (<br /> -    http_t *http,<br /> -    int num_settings,<br /> -    <a href="#cups_option_t">cups_option_t</a> *settings<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>num_settings</dt> - <dd class="description">Number of settings</dd> -<dt>settings</dt> - <dd class="description">Settings</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h3 class="function"><a id="cupsCancelDestJob">cupsCancelDestJob</a></h3> - <p class="description">Include necessary headers...</p> -<p class="code"> -ipp_status_t cupsCancelDestJob (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    int job_id<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>job_id</dt> - <dd class="description">Job ID</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Cancel a job on a destination.</p> - <p class="discussion">The "job_id" is the number returned by cupsCreateDestJob.<br> -<br> -Returns <code>IPP_STATUS_OK</code> on success and -<code>IPP_STATUS_ERRPR_NOT_AUTHORIZED</code> or -<code>IPP_STATUS_ERROR_FORBIDDEN</code> on failure. - -</p> -<h3 class="function"><a id="cupsCancelJob">cupsCancelJob</a></h3> - <p class="description">Cancel a print job on the default server.</p> -<p class="code"> -int cupsCancelJob (<br /> -    const char *name,<br /> -    int job_id<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Name of printer or class</dd> -<dt>job_id</dt> - <dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code> -to cancel the current job on the named destination.<br> -<br> -Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get -the cause of any failure.</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsCancelJob2">cupsCancelJob2</a></h3> - <p class="description">Cancel or purge a print job.</p> -<p class="code"> -ipp_status_t cupsCancelJob2 (<br /> -    http_t *http,<br /> -    const char *name,<br /> -    int job_id,<br /> -    int purge<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>name</dt> - <dd class="description">Name of printer or class</dd> -<dt>job_id</dt> - <dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd> -<dt>purge</dt> - <dd class="description">1 to purge, 0 to cancel</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">IPP status</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Canceled jobs remain in the job history while purged jobs are removed -from the job history.<br> -<br> -Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code> -to cancel the current job on the named destination.<br> -<br> -Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get -the cause of any failure. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsCheckDestSupported">cupsCheckDestSupported</a></h3> - <p class="description">Check that the option and value are supported -by the destination.</p> -<p class="code"> -int cupsCheckDestSupported (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    const char *option,<br /> -    const char *value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>option</dt> - <dd class="description">Option</dd> -<dt>value</dt> - <dd class="description">Value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if supported, 0 otherwise</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Returns 1 if supported, 0 otherwise. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsCloseDestJob">cupsCloseDestJob</a></h3> - <p class="description">Close a job and start printing.</p> -<p class="code"> -ipp_status_t cupsCloseDestJob (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br /> -    int job_id<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>info</dt> - <dd class="description">Destination information</dd> -<dt>job_id</dt> - <dd class="description">Job ID</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">IPP status code</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Use when the last call to cupsStartDocument passed 0 for "last_document". -"job_id" is the job ID returned by cupsCreateDestJob. Returns <code>IPP_STATUS_OK</code> -on success. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsConnectDest">cupsConnectDest</a></h3> - <p class="description">Connect to the server for a destination.</p> -<p class="code"> -http_t *cupsConnectDest (<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    unsigned flags,<br /> -    int msec,<br /> -    int *cancel,<br /> -    char *resource,<br /> -    size_t resourcesize,<br /> -    <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br /> -    void *user_data<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>flags</dt> - <dd class="description">Connection flags</dd> -<dt>msec</dt> - <dd class="description">Timeout in milliseconds</dd> -<dt>cancel</dt> - <dd class="description">Pointer to "cancel" variable</dd> -<dt>resource</dt> - <dd class="description">Resource buffer</dd> -<dt>resourcesize</dt> - <dd class="description">Size of resource buffer</dd> -<dt>cb</dt> - <dd class="description">Callback function</dd> -<dt>user_data</dt> - <dd class="description">User data pointer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Connection to server or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Connect to the destination, returning a new http_t connection object and -optionally the resource path to use for the destination. These calls will -block until a connection is made, the timeout expires, the integer pointed -to by "cancel" is non-zero, or the callback function (or block) returns 0, -The caller is responsible for calling httpClose() on the returned object. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsConnectDestBlock">cupsConnectDestBlock</a></h3> - <p class="description">Connect to the server for a destination.</p> -<p class="code"> -http_t *cupsConnectDestBlock (<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    unsigned flags,<br /> -    int msec,<br /> -    int *cancel,<br /> -    char *resource,<br /> -    size_t resourcesize,<br /> -    <a href="#cups_dest_block_t">cups_dest_block_t</a> block<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>flags</dt> - <dd class="description">Connection flags</dd> -<dt>msec</dt> - <dd class="description">Timeout in milliseconds</dd> -<dt>cancel</dt> - <dd class="description">Pointer to "cancel" variable</dd> -<dt>resource</dt> - <dd class="description">Resource buffer</dd> -<dt>resourcesize</dt> - <dd class="description">Size of resource buffer</dd> -<dt>block</dt> - <dd class="description">Callback block</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Connection to server or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Connect to the destination, returning a new http_t connection object and -optionally the resource path to use for the destination. These calls will -block until a connection is made, the timeout expires, the integer pointed -to by "cancel" is non-zero, or the callback function (or block) returns 0, -The caller is responsible for calling httpClose() on the returned object. - -</p> -<h3 class="function"><a id="cupsCopyDest">cupsCopyDest</a></h3> - <p class="description">Callback block</p> -<p class="code"> -int cupsCopyDest (<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    int num_dests,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> **dests<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dest</dt> -<dt>num_dests</dt> -<dt>dests</dt> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Copy a destination.</p> - <p class="discussion">Make a copy of the destination to an array of destinations (or just a single -copy) - for use with the cupsEnumDests* functions. The caller is responsible -for calling cupsFreeDests() on the returned object(s). - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsCopyDestConflicts">cupsCopyDestConflicts</a></h3> - <p class="description">Get conflicts and resolutions for a new -option/value pair.</p> -<p class="code"> -int cupsCopyDestConflicts (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> *options,<br /> -    const char *new_option,<br /> -    const char *new_value,<br /> -    int *num_conflicts,<br /> -    <a href="#cups_option_t">cups_option_t</a> **conflicts,<br /> -    int *num_resolved,<br /> -    <a href="#cups_option_t">cups_option_t</a> **resolved<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>num_options</dt> - <dd class="description">Number of current options</dd> -<dt>options</dt> - <dd class="description">Current options</dd> -<dt>new_option</dt> - <dd class="description">New option</dd> -<dt>new_value</dt> - <dd class="description">New value</dd> -<dt>num_conflicts</dt> - <dd class="description">Number of conflicting options</dd> -<dt>conflicts</dt> - <dd class="description">Conflicting options</dd> -<dt>num_resolved</dt> - <dd class="description">Number of options to resolve</dd> -<dt>resolved</dt> - <dd class="description">Resolved options</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if there is a conflict, 0 if none, -1 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">"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.<br> -<br> -Returns 1 if there is a conflict, 0 if there are no conflicts, and -1 if -there was an unrecoverable error such as a resolver loop.<br> -<br> -If "num_conflicts" and "conflicts" are not <code>NULL</code>, they are set to -contain the list of conflicting option/value pairs. Similarly, if -"num_resolved" and "resolved" are not <code>NULL</code> they will be set to the -list of changes needed to resolve the conflict.<br> -<br> -If cupsCopyDestConflicts returns 1 but "num_resolved" and "resolved" are set -to 0 and <code>NULL</code>, respectively, then the conflict cannot be resolved. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsCopyDestInfo">cupsCopyDestInfo</a></h3> - <p class="description">Get the supported values/capabilities for the -destination.</p> -<p class="code"> -<a href="#cups_dinfo_t">cups_dinfo_t</a> *cupsCopyDestInfo (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Destination information</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The caller is responsible for calling <a href="#cupsFreeDestInfo"><code>cupsFreeDestInfo</code></a> on the return -value. <code>NULL</code> is returned on error. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsCreateDestJob">cupsCreateDestJob</a></h3> - <p class="description">Create a job on a destination.</p> -<p class="code"> -ipp_status_t cupsCreateDestJob (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br /> -    int *job_id,<br /> -    const char *title,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> *options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>info</dt> - <dd class="description">Destination information</dd> -<dt>job_id</dt> - <dd class="description">Job ID or 0 on error</dd> -<dt>title</dt> - <dd class="description">Job name</dd> -<dt>num_options</dt> - <dd class="description">Number of job options</dd> -<dt>options</dt> - <dd class="description">Job options</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">IPP status code</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success, saving the job ID -in the variable pointed to by "job_id". - -</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsCreateJob">cupsCreateJob</a></h3> - <p class="description">Create an empty job for streaming.</p> -<p class="code"> -int cupsCreateJob (<br /> -    http_t *http,<br /> -    const char *name,<br /> -    const char *title,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> *options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>name</dt> - <dd class="description">Destination name</dd> -<dt>title</dt> - <dd class="description">Title of job</dd> -<dt>num_options</dt> - <dd class="description">Number of options</dd> -<dt>options</dt> - <dd class="description">Options</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Job ID or 0 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Use this function when you want to stream print data using the -<a href="#cupsStartDocument"><code>cupsStartDocument</code></a>, <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a>, and -<a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> functions. If you have one or more files to -print, use the <a href="#cupsPrintFile2"><code>cupsPrintFile2</code></a> or <a href="#cupsPrintFiles2"><code>cupsPrintFiles2</code></a> function -instead. - -</p> -<h3 class="function"><a id="cupsEncryption">cupsEncryption</a></h3> - <p class="description">Get the current encryption settings.</p> -<p class="code"> -http_encryption_t cupsEncryption (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Encryption settings</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION -environment variable, then the ~/.cups/client.conf file, and finally the -/etc/cups/client.conf file. If not set, the default is -<code>HTTP_ENCRYPTION_IF_REQUESTED</code>.<br> -<br> -Note: The current encryption setting is tracked separately for each thread -in a program. Multi-threaded programs that override the setting via the -<a href="#cupsSetEncryption"><code>cupsSetEncryption</code></a> function need to do so in each thread for the same -setting to be used.</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsEnumDests">cupsEnumDests</a></h3> - <p class="description">Enumerate available destinations with a callback function.</p> -<p class="code"> -int cupsEnumDests (<br /> -    unsigned flags,<br /> -    int msec,<br /> -    int *cancel,<br /> -    <a href="#cups_ptype_t">cups_ptype_t</a> type,<br /> -    <a href="#cups_ptype_t">cups_ptype_t</a> mask,<br /> -    <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br /> -    void *user_data<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>flags</dt> - <dd class="description">Enumeration flags</dd> -<dt>msec</dt> - <dd class="description">Timeout in milliseconds, --1 for indefinite</dd> -<dt>cancel</dt> - <dd class="description">Pointer to "cancel" variable</dd> -<dt>type</dt> - <dd class="description">Printer type bits</dd> -<dt>mask</dt> - <dd class="description">Mask for printer type bits</dd> -<dt>cb</dt> - <dd class="description">Callback function</dd> -<dt>user_data</dt> - <dd class="description">User data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Destinations are enumerated from one or more sources. The callback function -receives the <code>user_data</code> pointer, destination name, instance, number of -options, and options which can be used as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a> -function. The function must return 1 to continue enumeration or 0 to stop.<br> -<br> -Enumeration happens on the current thread and does not return until all -destinations have been enumerated or the callback function returns 0. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsEnumDestsBlock">cupsEnumDestsBlock</a></h3> - <p class="description">Enumerate available destinations with a block.</p> -<p class="code"> -int cupsEnumDestsBlock (<br /> -    unsigned flags,<br /> -    int timeout,<br /> -    int *cancel,<br /> -    <a href="#cups_ptype_t">cups_ptype_t</a> type,<br /> -    <a href="#cups_ptype_t">cups_ptype_t</a> mask,<br /> -    <a href="#cups_dest_block_t">cups_dest_block_t</a> block<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>flags</dt> - <dd class="description">Enumeration flags</dd> -<dt>timeout</dt> - <dd class="description">Timeout in milliseconds, 0 for indefinite</dd> -<dt>cancel</dt> - <dd class="description">Pointer to "cancel" variable</dd> -<dt>type</dt> - <dd class="description">Printer type bits</dd> -<dt>mask</dt> - <dd class="description">Mask for printer type bits</dd> -<dt>block</dt> - <dd class="description">Block</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Destinations are enumerated from one or more sources. The block receives the -destination name, instance, number of options, and options which can be used -as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a> function. The block must return 1 to -continue enumeration or 0 to stop.<br> -<br> -Enumeration happens on the current thread and does not return until all -destinations have been enumerated or the block returns 0. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsFindDestDefault">cupsFindDestDefault</a></h3> - <p class="description">Find the default value(s) for the given option.</p> -<p class="code"> -ipp_attribute_t *cupsFindDestDefault (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    const char *option<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>option</dt> - <dd class="description">Option/attribute name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Default attribute or <code>NULL</code> for none</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>, -<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>, -<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>, -<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code> -functions to inspect the default value(s) as needed. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsFindDestReady">cupsFindDestReady</a></h3> - <p class="description">Find the default value(s) for the given option.</p> -<p class="code"> -ipp_attribute_t *cupsFindDestReady (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    const char *option<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>option</dt> - <dd class="description">Option/attribute name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Default attribute or <code>NULL</code> for none</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>, -<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>, -<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>, -<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code> -functions to inspect the default value(s) as needed. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsFindDestSupported">cupsFindDestSupported</a></h3> - <p class="description">Find the default value(s) for the given option.</p> -<p class="code"> -ipp_attribute_t *cupsFindDestSupported (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    const char *option<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>option</dt> - <dd class="description">Option/attribute name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Default attribute or <code>NULL</code> for none</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>, -<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>, -<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>, -<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code> -functions to inspect the default value(s) as needed. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsFinishDestDocument">cupsFinishDestDocument</a></h3> - <p class="description">Finish the current document.</p> -<p class="code"> -ipp_status_t cupsFinishDestDocument (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *info<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>info</dt> - <dd class="description">Destination information</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of document submission</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success. - -</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsFinishDocument">cupsFinishDocument</a></h3> - <p class="description">Finish sending a document.</p> -<p class="code"> -ipp_status_t cupsFinishDocument (<br /> -    http_t *http,<br /> -    const char *name<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>name</dt> - <dd class="description">Destination name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of document submission</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The document must have been started using <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>. - -</p> -<h3 class="function"><a id="cupsFreeDestInfo">cupsFreeDestInfo</a></h3> - <p class="description">Free destination information obtained using -<a href="#cupsCopyDestInfo"><code>cupsCopyDestInfo</code></a>.</p> -<p class="code"> -void cupsFreeDestInfo (<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -</dl> -<h3 class="function"><a id="cupsFreeDests">cupsFreeDests</a></h3> - <p class="description">Free the memory used by the list of destinations.</p> -<p class="code"> -void cupsFreeDests (<br /> -    int num_dests,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dests<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>num_dests</dt> - <dd class="description">Number of destinations</dd> -<dt>dests</dt> - <dd class="description">Destinations</dd> -</dl> -<h3 class="function"><a id="cupsFreeJobs">cupsFreeJobs</a></h3> - <p class="description">Free memory used by job data.</p> -<p class="code"> -void cupsFreeJobs (<br /> -    int num_jobs,<br /> -    <a href="#cups_job_t">cups_job_t</a> *jobs<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>num_jobs</dt> - <dd class="description">Number of jobs</dd> -<dt>jobs</dt> - <dd class="description">Jobs</dd> -</dl> -<h3 class="function"><a id="cupsFreeOptions">cupsFreeOptions</a></h3> - <p class="description">Free all memory used by options.</p> -<p class="code"> -void cupsFreeOptions (<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> *options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>num_options</dt> - <dd class="description">Number of options</dd> -<dt>options</dt> - <dd class="description">Pointer to options</dd> -</dl> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="cupsGetClasses">cupsGetClasses</a></h3> - <p class="description">Get a list of printer classes from the default server.</p> -<p class="code"> -int cupsGetClasses (<br /> -    char ***classes<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>classes</dt> - <dd class="description">Classes</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of classes</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is deprecated and no longer returns a list of printer -classes - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead. - -</p> -<h3 class="function"><a id="cupsGetDefault">cupsGetDefault</a></h3> - <p class="description">Get the default printer or class for the default server.</p> -<p class="code"> -const char *cupsGetDefault (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Default printer or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function returns the default printer or class as defined by -the LPDEST or PRINTER environment variables. If these environment -variables are not set, the server default destination is returned. -Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> -functions to get the user-defined default printer, as this function does -not support the lpoptions-defined default printer.</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsGetDefault2">cupsGetDefault2</a></h3> - <p class="description">Get the default printer or class for the specified server.</p> -<p class="code"> -const char *cupsGetDefault2 (<br /> -    http_t *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Default printer or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function returns the default printer or class as defined by -the LPDEST or PRINTER environment variables. If these environment -variables are not set, the server default destination is returned. -Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> -functions to get the user-defined default printer, as this function does -not support the lpoptions-defined default printer. - -</p> -<h3 class="function"><a id="cupsGetDest">cupsGetDest</a></h3> - <p class="description">Get the named destination from the list.</p> -<p class="code"> -<a href="#cups_dest_t">cups_dest_t</a> *cupsGetDest (<br /> -    const char *name,<br /> -    const char *instance,<br /> -    int num_dests,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dests<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Destination name or <code>NULL</code> for the default destination</dd> -<dt>instance</dt> - <dd class="description">Instance name or <code>NULL</code></dd> -<dt>num_dests</dt> - <dd class="description">Number of destinations</dd> -<dt>dests</dt> - <dd class="description">Destinations</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Destination pointer or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> or <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> functions to get a -list of supported destinations for the current user.</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></h3> - <p class="description">Get a media name, dimension, and margins for a -specific size.</p> -<p class="code"> -int cupsGetDestMediaByIndex (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    int n,<br /> -    unsigned flags,<br /> -    <a href="#cups_size_t">cups_size_t</a> *size<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>n</dt> - <dd class="description">Media size number (0-based)</dd> -<dt>flags</dt> - <dd class="description">Media flags</dd> -<dt>size</dt> - <dd class="description">Media size information</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>flags</code> parameter determines which set of media are indexed. For -example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will get the Nth -borderless size supported by the printer. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsGetDestMediaByName">cupsGetDestMediaByName</a></h3> - <p class="description">Get media names, dimensions, and margins.</p> -<p class="code"> -int cupsGetDestMediaByName (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    const char *media,<br /> -    unsigned flags,<br /> -    <a href="#cups_size_t">cups_size_t</a> *size<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>media</dt> - <dd class="description">Media name</dd> -<dt>flags</dt> - <dd class="description">Media matching flags</dd> -<dt>size</dt> - <dd class="description">Media size information</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on match, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The "media" string is a PWG media name. "Flags" provides some matching -guidance (multiple flags can be combined):<br> -<br> -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, and -CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the -size amongst the "ready" media.<br> -<br> -The matching result (if any) is returned in the "cups_size_t" structure.<br> -<br> -Returns 1 when there is a match and 0 if there is not a match. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></h3> - <p class="description">Get media names, dimensions, and margins.</p> -<p class="code"> -int cupsGetDestMediaBySize (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    int width,<br /> -    int length,<br /> -    unsigned flags,<br /> -    <a href="#cups_size_t">cups_size_t</a> *size<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>width</dt> - <dd class="description">Media width in hundredths of -of millimeters</dd> -<dt>length</dt> - <dd class="description">Media length in hundredths of -of millimeters</dd> -<dt>flags</dt> - <dd class="description">Media matching flags</dd> -<dt>size</dt> - <dd class="description">Media size information</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on match, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">"Width" and "length" are the dimensions in hundredths of millimeters. -"Flags" provides some matching guidance (multiple flags can be combined):<br> -<br> -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, and -CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the -size amongst the "ready" media.<br> -<br> -The matching result (if any) is returned in the "cups_size_t" structure.<br> -<br> -Returns 1 when there is a match and 0 if there is not a match. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsGetDestMediaCount">cupsGetDestMediaCount</a></h3> - <p class="description">Get the number of sizes supported by a -destination.</p> -<p class="code"> -int cupsGetDestMediaCount (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    unsigned flags<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>flags</dt> - <dd class="description">Media flags</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of sizes</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>flags</code> parameter determines the set of media sizes that are -counted. For example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return -the number of borderless sizes. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></h3> - <p class="description">Get the default size for a destination.</p> -<p class="code"> -int cupsGetDestMediaDefault (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    unsigned flags,<br /> -    <a href="#cups_size_t">cups_size_t</a> *size<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>flags</dt> - <dd class="description">Media flags</dd> -<dt>size</dt> - <dd class="description">Media size information</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>flags</code> parameter determines which default size is returned. For -example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return the default -borderless size, typically US Letter or A4, but sometimes 4x6 photo media. - -</p> -<h3 class="function"><span class="info"> CUPS 2.0/macOS 10.10 </span><a id="cupsGetDestWithURI">cupsGetDestWithURI</a></h3> - <p class="description">Get a destination associated with a URI.</p> -<p class="code"> -<a href="#cups_dest_t">cups_dest_t</a> *cupsGetDestWithURI (<br /> -    const char *name,<br /> -    const char *uri<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Desired printer name or <code>NULL</code></dd> -<dt>uri</dt> - <dd class="description">URI for the printer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Destination or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">"name" is the desired name for the printer. If <code>NULL</code>, a name will be -created using the URI.<br> -<br> -"uri" is the "ipp" or "ipps" URI for the printer. - -</p> -<h3 class="function"><a id="cupsGetDests">cupsGetDests</a></h3> - <p class="description">Get the list of destinations from the default server.</p> -<p class="code"> -int cupsGetDests (<br /> -    <a href="#cups_dest_t">cups_dest_t</a> **dests<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dests</dt> - <dd class="description">Destinations</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of destinations</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the -printer-info, printer-is-accepting-jobs, printer-is-shared, -printer-make-and-model, printer-state, printer-state-change-time, -printer-state-reasons, and printer-type attributes as options. CUPS 1.4 -adds the marker-change-time, marker-colors, marker-high-levels, -marker-levels, marker-low-levels, marker-message, marker-names, -marker-types, and printer-commands attributes as well.<br> -<br> -Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and -the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsGetDests2">cupsGetDests2</a></h3> - <p class="description">Get the list of destinations from the specified server.</p> -<p class="code"> -int cupsGetDests2 (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> **dests<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>dests</dt> - <dd class="description">Destinations</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of destinations</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the -printer-info, printer-is-accepting-jobs, printer-is-shared, -printer-make-and-model, printer-state, printer-state-change-time, -printer-state-reasons, and printer-type attributes as options. CUPS 1.4 -adds the marker-change-time, marker-colors, marker-high-levels, -marker-levels, marker-low-levels, marker-message, marker-names, -marker-types, and printer-commands attributes as well.<br> -<br> -Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and -the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination. - -</p> -<h3 class="function"><a id="cupsGetJobs">cupsGetJobs</a></h3> - <p class="description">Get the jobs from the default server.</p> -<p class="code"> -int cupsGetJobs (<br /> -    <a href="#cups_job_t">cups_job_t</a> **jobs,<br /> -    const char *name,<br /> -    int myjobs,<br /> -    int whichjobs<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>jobs</dt> - <dd class="description">Job data</dd> -<dt>name</dt> - <dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd> -<dt>myjobs</dt> - <dd class="description">0 = all users, 1 = mine</dd> -<dt>whichjobs</dt> - <dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of jobs</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless -of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are -pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns -jobs that are stopped, canceled, aborted, or completed.</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsGetJobs2">cupsGetJobs2</a></h3> - <p class="description">Get the jobs from the specified server.</p> -<p class="code"> -int cupsGetJobs2 (<br /> -    http_t *http,<br /> -    <a href="#cups_job_t">cups_job_t</a> **jobs,<br /> -    const char *name,<br /> -    int myjobs,<br /> -    int whichjobs<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>jobs</dt> - <dd class="description">Job data</dd> -<dt>name</dt> - <dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd> -<dt>myjobs</dt> - <dd class="description">0 = all users, 1 = mine</dd> -<dt>whichjobs</dt> - <dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of jobs</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless -of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are -pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns -jobs that are stopped, canceled, aborted, or completed. - -</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsGetNamedDest">cupsGetNamedDest</a></h3> - <p class="description">Get options for the named destination.</p> -<p class="code"> -<a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest (<br /> -    http_t *http,<br /> -    const char *name,<br /> -    const char *instance<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>name</dt> - <dd class="description">Destination name or <code>NULL</code> for the default destination</dd> -<dt>instance</dt> - <dd class="description">Instance name or <code>NULL</code></dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Destination or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is optimized for retrieving a single destination and should -be used instead of <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> when you either -know the name of the destination or want to print to the default destination. -If <code>NULL</code> is returned, the destination does not exist or there is no -default destination.<br> -<br> -If "http" is <code>CUPS_HTTP_DEFAULT</code>, the connection to the default print -server will be used.<br> -<br> -If "name" is <code>NULL</code>, the default printer for the current user will be -returned.<br> -<br> -The returned destination must be freed using <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> with a -"num_dests" value of 1. - -</p> -<h3 class="function"><a id="cupsGetOption">cupsGetOption</a></h3> - <p class="description">Get an option value.</p> -<p class="code"> -const char *cupsGetOption (<br /> -    const char *name,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> *options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Name of option</dd> -<dt>num_options</dt> - <dd class="description">Number of options</dd> -<dt>options</dt> - <dd class="description">Options</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Option value or <code>NULL</code></p> -<h3 class="function"><a id="cupsGetPassword">cupsGetPassword</a></h3> - <p class="description">Get a password from the user.</p> -<p class="code"> -const char *cupsGetPassword (<br /> -    const char *prompt<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>prompt</dt> - <dd class="description">Prompt string</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Password</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the -user does not provide a password.<br> -<br> -Note: The current password callback function is tracked separately for each -thread in a program. Multi-threaded programs that override the setting via -the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to -do so in each thread for the same function to be used.</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsGetPassword2">cupsGetPassword2</a></h3> - <p class="description">Get a password from the user using the advanced -password callback.</p> -<p class="code"> -const char *cupsGetPassword2 (<br /> -    const char *prompt,<br /> -    http_t *http,<br /> -    const char *method,<br /> -    const char *resource<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>prompt</dt> - <dd class="description">Prompt string</dd> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>method</dt> - <dd class="description">Request method ("GET", "POST", "PUT")</dd> -<dt>resource</dt> - <dd class="description">Resource path</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Password</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the -user does not provide a password.<br> -<br> -Note: The current password callback function is tracked separately for each -thread in a program. Multi-threaded programs that override the setting via -the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to -do so in each thread for the same function to be used. - -</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="cupsGetPrinters">cupsGetPrinters</a></h3> - <p class="description">Get a list of printers from the default server.</p> -<p class="code"> -int cupsGetPrinters (<br /> -    char ***printers<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>printers</dt> - <dd class="description">Printers</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of printers</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is deprecated and no longer returns a list of printers - use -<a href="#cupsGetDests"><code>cupsGetDests</code></a> instead. - -</p> -<h3 class="function"><a id="cupsLangDefault">cupsLangDefault</a></h3> - <p class="description">Return the default language.</p> -<p class="code"> -cups_lang_t *cupsLangDefault (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Language data</p> -<h3 class="function"><a id="cupsLangEncoding">cupsLangEncoding</a></h3> - <p class="description">Return the character encoding (us-ascii, etc.) -for the given language.</p> -<p class="code"> -const char *cupsLangEncoding (<br /> -    cups_lang_t *lang<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>lang</dt> - <dd class="description">Language data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Character encoding</p> -<h3 class="function"><a id="cupsLangFlush">cupsLangFlush</a></h3> - <p class="description">Flush all language data out of the cache.</p> -<p class="code"> -void cupsLangFlush (void);</p> -<h3 class="function"><a id="cupsLangFree">cupsLangFree</a></h3> - <p class="description">Free language data.</p> -<p class="code"> -void cupsLangFree (<br /> -    cups_lang_t *lang<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>lang</dt> - <dd class="description">Language to free</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This does not actually free anything; use <a href="#cupsLangFlush"><code>cupsLangFlush</code></a> for that.</p> -<h3 class="function"><a id="cupsLangGet">cupsLangGet</a></h3> - <p class="description">Get a language.</p> -<p class="code"> -cups_lang_t *cupsLangGet (<br /> -    const char *language<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>language</dt> - <dd class="description">Language or locale</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Language data</p> -<h3 class="function"><span class="info"> CUPS 2.0/macOS 10.10 </span><a id="cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></h3> - <p class="description">Get the localized string for a destination media -size.</p> -<p class="code"> -const char *cupsLocalizeDestMedia (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    unsigned flags,<br /> -    <a href="#cups_size_t">cups_size_t</a> *size<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>flags</dt> - <dd class="description">Media flags</dd> -<dt>size</dt> - <dd class="description">Media size</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Localized string</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The returned string is stored in the destination information and will become -invalid if the destination information is deleted. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsLocalizeDestOption">cupsLocalizeDestOption</a></h3> - <p class="description">Get the localized string for a destination -option.</p> -<p class="code"> -const char *cupsLocalizeDestOption (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    const char *option<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>option</dt> - <dd class="description">Option to localize</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Localized string</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The returned string is stored in the destination information and will become -invalid if the destination information is deleted. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsLocalizeDestValue">cupsLocalizeDestValue</a></h3> - <p class="description">Get the localized string for a destination -option+value pair.</p> -<p class="code"> -const char *cupsLocalizeDestValue (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br /> -    const char *option,<br /> -    const char *value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>dinfo</dt> - <dd class="description">Destination information</dd> -<dt>option</dt> - <dd class="description">Option to localize</dd> -<dt>value</dt> - <dd class="description">Value to localize</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Localized string</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The returned string is stored in the destination information and will become -invalid if the destination information is deleted. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsNotifySubject">cupsNotifySubject</a></h3> - <p class="description">Return the subject for the given notification message.</p> -<p class="code"> -char *cupsNotifySubject (<br /> -    cups_lang_t *lang,<br /> -    ipp_t *event<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>lang</dt> - <dd class="description">Language data</dd> -<dt>event</dt> - <dd class="description">Event data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Subject string or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The returned string must be freed by the caller using <code>free</code>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsNotifyText">cupsNotifyText</a></h3> - <p class="description">Return the text for the given notification message.</p> -<p class="code"> -char *cupsNotifyText (<br /> -    cups_lang_t *lang,<br /> -    ipp_t *event<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>lang</dt> - <dd class="description">Language data</dd> -<dt>event</dt> - <dd class="description">Event data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Message text or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The returned string must be freed by the caller using <code>free</code>. - -</p> -<h3 class="function"><a id="cupsParseOptions">cupsParseOptions</a></h3> - <p class="description">Parse options from a command-line argument.</p> -<p class="code"> -int cupsParseOptions (<br /> -    const char *arg,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> **options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>arg</dt> - <dd class="description">Argument to parse</dd> -<dt>num_options</dt> - <dd class="description">Number of options</dd> -<dt>options</dt> - <dd class="description">Options found</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of options found</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function converts space-delimited name/value pairs according -to the PAPI text option ABNF specification. Collection values -("name={a=... b=... c=...}") are stored with the curley brackets -intact - use <code>cupsParseOptions</code> on the value to extract the -collection attributes.</p> -<h3 class="function"><a id="cupsPrintFile">cupsPrintFile</a></h3> - <p class="description">Print a file to a printer or class on the default server.</p> -<p class="code"> -int cupsPrintFile (<br /> -    const char *name,<br /> -    const char *filename,<br /> -    const char *title,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> *options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Destination name</dd> -<dt>filename</dt> - <dd class="description">File to print</dd> -<dt>title</dt> - <dd class="description">Title of job</dd> -<dt>num_options</dt> - <dd class="description">Number of options</dd> -<dt>options</dt> - <dd class="description">Options</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Job ID or 0 on error</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsPrintFile2">cupsPrintFile2</a></h3> - <p class="description">Print a file to a printer or class on the specified -server.</p> -<p class="code"> -int cupsPrintFile2 (<br /> -    http_t *http,<br /> -    const char *name,<br /> -    const char *filename,<br /> -    const char *title,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> *options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server</dd> -<dt>name</dt> - <dd class="description">Destination name</dd> -<dt>filename</dt> - <dd class="description">File to print</dd> -<dt>title</dt> - <dd class="description">Title of job</dd> -<dt>num_options</dt> - <dd class="description">Number of options</dd> -<dt>options</dt> - <dd class="description">Options</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Job ID or 0 on error</p> -<h3 class="function"><a id="cupsPrintFiles">cupsPrintFiles</a></h3> - <p class="description">Print one or more files to a printer or class on the -default server.</p> -<p class="code"> -int cupsPrintFiles (<br /> -    const char *name,<br /> -    int num_files,<br /> -    const char **files,<br /> -    const char *title,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> *options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Destination name</dd> -<dt>num_files</dt> - <dd class="description">Number of files</dd> -<dt>files</dt> - <dd class="description">File(s) to print</dd> -<dt>title</dt> - <dd class="description">Title of job</dd> -<dt>num_options</dt> - <dd class="description">Number of options</dd> -<dt>options</dt> - <dd class="description">Options</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Job ID or 0 on error</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsPrintFiles2">cupsPrintFiles2</a></h3> - <p class="description">Print one or more files to a printer or class on the -specified server.</p> -<p class="code"> -int cupsPrintFiles2 (<br /> -    http_t *http,<br /> -    const char *name,<br /> -    int num_files,<br /> -    const char **files,<br /> -    const char *title,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> *options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>name</dt> - <dd class="description">Destination name</dd> -<dt>num_files</dt> - <dd class="description">Number of files</dd> -<dt>files</dt> - <dd class="description">File(s) to print</dd> -<dt>title</dt> - <dd class="description">Title of job</dd> -<dt>num_options</dt> - <dd class="description">Number of options</dd> -<dt>options</dt> - <dd class="description">Options</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Job ID or 0 on error</p> -<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsRemoveDest">cupsRemoveDest</a></h3> - <p class="description">Remove a destination from the destination list.</p> -<p class="code"> -int cupsRemoveDest (<br /> -    const char *name,<br /> -    const char *instance,<br /> -    int num_dests,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> **dests<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Destination name</dd> -<dt>instance</dt> - <dd class="description">Instance name or <code>NULL</code></dd> -<dt>num_dests</dt> - <dd class="description">Number of destinations</dd> -<dt>dests</dt> - <dd class="description">Destinations</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New number of destinations</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Removing a destination/instance does not delete the class or printer -queue, merely the lpoptions for that destination/instance. Use the -<a href="#cupsSetDests"><code>cupsSetDests</code></a> or <a href="#cupsSetDests2"><code>cupsSetDests2</code></a> functions to save the new -options for the user. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsRemoveOption">cupsRemoveOption</a></h3> - <p class="description">Remove an option from an option array.</p> -<p class="code"> -int cupsRemoveOption (<br /> -    const char *name,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> **options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Option name</dd> -<dt>num_options</dt> - <dd class="description">Current number of options</dd> -<dt>options</dt> - <dd class="description">Options</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New number of options</p> -<h3 class="function"><a id="cupsServer">cupsServer</a></h3> - <p class="description">Return the hostname/address of the current server.</p> -<p class="code"> -const char *cupsServer (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Server name</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The default server comes from the CUPS_SERVER environment variable, then the -~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not -set, the default is the local system - either "localhost" or a domain socket -path.<br> -<br> -The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6 -address, or a domain socket pathname.<br> -<br> -Note: The current server is tracked separately for each thread in a program. -Multi-threaded programs that override the server via the -<a href="#cupsSetServer"><code>cupsSetServer</code></a> function need to do so in each thread for the same -server to be used.</p> -<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="cupsSetClientCertCB">cupsSetClientCertCB</a></h3> - <p class="description">Set the client certificate callback.</p> -<p class="code"> -void cupsSetClientCertCB (<br /> -    <a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a> cb,<br /> -    void *user_data<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>cb</dt> - <dd class="description">Callback function</dd> -<dt>user_data</dt> - <dd class="description">User data pointer</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Pass <code>NULL</code> to restore the default callback.<br> -<br> -Note: The current certificate callback is tracked separately for each thread -in a program. Multi-threaded programs that override the callback need to do -so in each thread for the same callback to be used. - -</p> -<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="cupsSetCredentials">cupsSetCredentials</a></h3> - <p class="description">Set the default credentials to be used for SSL/TLS -connections.</p> -<p class="code"> -int cupsSetCredentials (<br /> -    cups_array_t *credentials<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>credentials</dt> - <dd class="description">Array of credentials</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of call (0 = success)</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Note: The default credentials are tracked separately for each thread in a -program. Multi-threaded programs that override the setting need to do so in -each thread for the same setting to be used. - -</p> -<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsSetDefaultDest">cupsSetDefaultDest</a></h3> - <p class="description">Set the default destination.</p> -<p class="code"> -void cupsSetDefaultDest (<br /> -    const char *name,<br /> -    const char *instance,<br /> -    int num_dests,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dests<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Destination name</dd> -<dt>instance</dt> - <dd class="description">Instance name or <code>NULL</code></dd> -<dt>num_dests</dt> - <dd class="description">Number of destinations</dd> -<dt>dests</dt> - <dd class="description">Destinations</dd> -</dl> -<h3 class="function"><a id="cupsSetDests">cupsSetDests</a></h3> - <p class="description">Save the list of destinations for the default server.</p> -<p class="code"> -void cupsSetDests (<br /> -    int num_dests,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dests<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>num_dests</dt> - <dd class="description">Number of destinations</dd> -<dt>dests</dt> - <dd class="description">Destinations</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run -as root and ~/.cups/lpoptions when run as a normal user.</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsSetDests2">cupsSetDests2</a></h3> - <p class="description">Save the list of destinations for the specified server.</p> -<p class="code"> -int cupsSetDests2 (<br /> -    http_t *http,<br /> -    int num_dests,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dests<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>num_dests</dt> - <dd class="description">Number of destinations</dd> -<dt>dests</dt> - <dd class="description">Destinations</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, -1 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run -as root and ~/.cups/lpoptions when run as a normal user. - -</p> -<h3 class="function"><a id="cupsSetEncryption">cupsSetEncryption</a></h3> - <p class="description">Set the encryption preference.</p> -<p class="code"> -void cupsSetEncryption (<br /> -    http_encryption_t e<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>e</dt> - <dd class="description">New encryption preference</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION -environment variable, then the ~/.cups/client.conf file, and finally the -/etc/cups/client.conf file. If not set, the default is -<code>HTTP_ENCRYPTION_IF_REQUESTED</code>.<br> -<br> -Note: The current encryption setting is tracked separately for each thread -in a program. Multi-threaded programs that override the setting need to do -so in each thread for the same setting to be used.</p> -<h3 class="function"><a id="cupsSetPasswordCB">cupsSetPasswordCB</a></h3> - <p class="description">Set the password callback for CUPS.</p> -<p class="code"> -void cupsSetPasswordCB (<br /> -    <a href="#cups_password_cb_t">cups_password_cb_t</a> cb<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>cb</dt> - <dd class="description">Callback function</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which -reads the password from the console. Programs should call either this -function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered -by a program per thread.<br> -<br> -Note: The current password callback is tracked separately for each thread -in a program. Multi-threaded programs that override the callback need to do -so in each thread for the same callback to be used.</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3> - <p class="description">Set the advanced password callback for CUPS.</p> -<p class="code"> -void cupsSetPasswordCB2 (<br /> -    <a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb,<br /> -    void *user_data<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>cb</dt> - <dd class="description">Callback function</dd> -<dt>user_data</dt> - <dd class="description">User data pointer</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which -reads the password from the console. Programs should call either this -function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered -by a program per thread.<br> -<br> -Note: The current password callback is tracked separately for each thread -in a program. Multi-threaded programs that override the callback need to do -so in each thread for the same callback to be used. - -</p> -<h3 class="function"><a id="cupsSetServer">cupsSetServer</a></h3> - <p class="description">Set the default server name and port.</p> -<p class="code"> -void cupsSetServer (<br /> -    const char *server<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>server</dt> - <dd class="description">Server name</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The "server" string can be a fully-qualified hostname, a numeric -IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP -addresses can be optionally followed by a colon and port number to override -the default port 631, e.g. "hostname:8631". Pass <code>NULL</code> to restore the -default server name and port.<br> -<br> -Note: The current server is tracked separately for each thread in a program. -Multi-threaded programs that override the server need to do so in each -thread for the same server to be used.</p> -<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="cupsSetServerCertCB">cupsSetServerCertCB</a></h3> - <p class="description">Set the server certificate callback.</p> -<p class="code"> -void cupsSetServerCertCB (<br /> -    <a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a> cb,<br /> -    void *user_data<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>cb</dt> - <dd class="description">Callback function</dd> -<dt>user_data</dt> - <dd class="description">User data pointer</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Pass <code>NULL</code> to restore the default callback.<br> -<br> -Note: The current credentials callback is tracked separately for each thread -in a program. Multi-threaded programs that override the callback need to do -so in each thread for the same callback to be used. - -</p> -<h3 class="function"><a id="cupsSetUser">cupsSetUser</a></h3> - <p class="description">Set the default user name.</p> -<p class="code"> -void cupsSetUser (<br /> -    const char *user<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>user</dt> - <dd class="description">User name</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Pass <code>NULL</code> to restore the default user name.<br> -<br> -Note: The current user name is tracked separately for each thread in a -program. Multi-threaded programs that override the user name need to do so -in each thread for the same user name to be used.</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsSetUserAgent">cupsSetUserAgent</a></h3> - <p class="description">Set the default HTTP User-Agent string.</p> -<p class="code"> -void cupsSetUserAgent (<br /> -    const char *user_agent<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>user_agent</dt> - <dd class="description">User-Agent string or <code>NULL</code></dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Setting the string to NULL forces the default value containing the CUPS -version, IPP version, and operating system version and architecture. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsStartDestDocument">cupsStartDestDocument</a></h3> - <p class="description">Start a new document.</p> -<p class="code"> -http_status_t cupsStartDestDocument (<br /> -    http_t *http,<br /> -    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br /> -    <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br /> -    int job_id,<br /> -    const char *docname,<br /> -    const char *format,<br /> -    int num_options,<br /> -    <a href="#cups_option_t">cups_option_t</a> *options,<br /> -    int last_document<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to destination</dd> -<dt>dest</dt> - <dd class="description">Destination</dd> -<dt>info</dt> - <dd class="description">Destination information</dd> -<dt>job_id</dt> - <dd class="description">Job ID</dd> -<dt>docname</dt> - <dd class="description">Document name</dd> -<dt>format</dt> - <dd class="description">Document format</dd> -<dt>num_options</dt> - <dd class="description">Number of document options</dd> -<dt>options</dt> - <dd class="description">Document options</dd> -<dt>last_document</dt> - <dd class="description">1 if this is the last document</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of document creation</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">"job_id" is the job ID returned by cupsCreateDestJob. "docname" is the name -of the document/file being printed, "format" is the MIME media type for the -document (see CUPS_FORMAT_xxx constants), and "num_options" and "options" -are the options do be applied to the document. "last_document" should be 1 -if this is the last document to be submitted in the job. Returns -<code>HTTP_CONTINUE</code> on success. - -</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsStartDocument">cupsStartDocument</a></h3> - <p class="description">Add a document to a job created with cupsCreateJob().</p> -<p class="code"> -http_status_t cupsStartDocument (<br /> -    http_t *http,<br /> -    const char *name,<br /> -    int job_id,<br /> -    const char *docname,<br /> -    const char *format,<br /> -    int last_document<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>name</dt> - <dd class="description">Destination name</dd> -<dt>job_id</dt> - <dd class="description">Job ID from <a href="#cupsCreateJob"><code>cupsCreateJob</code></a></dd> -<dt>docname</dt> - <dd class="description">Name of document</dd> -<dt>format</dt> - <dd class="description">MIME type or <code>CUPS_FORMAT_foo</code></dd> -<dt>last_document</dt> - <dd class="description">1 for last document in job, 0 otherwise</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">HTTP status of request</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write data for the document and -<a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> to finish the document and get the submission status.<br> -<br> -The MIME type constants <code>CUPS_FORMAT_AUTO</code>, <code>CUPS_FORMAT_PDF</code>, -<code>CUPS_FORMAT_POSTSCRIPT</code>, <code>CUPS_FORMAT_RAW</code>, and -<code>CUPS_FORMAT_TEXT</code> are provided for the "format" argument, although -any supported MIME type string can be supplied. - -</p> -<h3 class="function"><a id="cupsTempFd">cupsTempFd</a></h3> - <p class="description">Creates a temporary file.</p> -<p class="code"> -int cupsTempFd (<br /> -    char *filename,<br /> -    int len<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>filename</dt> - <dd class="description">Pointer to buffer</dd> -<dt>len</dt> - <dd class="description">Size of buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New file descriptor or -1 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The temporary filename is returned in the filename buffer. -The temporary file is opened for reading and writing.</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="cupsTempFile">cupsTempFile</a></h3> - <p class="description">Generates a temporary filename.</p> -<p class="code"> -char *cupsTempFile (<br /> -    char *filename,<br /> -    int len<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>filename</dt> - <dd class="description">Pointer to buffer</dd> -<dt>len</dt> - <dd class="description">Size of buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Filename or <code>NULL</code> on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The temporary filename is returned in the filename buffer. -This function is deprecated and will no longer generate a temporary -filename - use <a href="#cupsTempFd"><code>cupsTempFd</code></a> or <a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsTempFile2">cupsTempFile2</a></h3> - <p class="description">Creates a temporary CUPS file.</p> -<p class="code"> -cups_file_t *cupsTempFile2 (<br /> -    char *filename,<br /> -    int len<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>filename</dt> - <dd class="description">Pointer to buffer</dd> -<dt>len</dt> - <dd class="description">Size of buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">CUPS file or <code>NULL</code> on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The temporary filename is returned in the filename buffer. -The temporary file is opened for writing. - -</p> -<h3 class="function"><a id="cupsUser">cupsUser</a></h3> - <p class="description">Return the current user's name.</p> -<p class="code"> -const char *cupsUser (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">User name</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Note: The current user name is tracked separately for each thread in a -program. Multi-threaded programs that override the user name with the -<a href="#cupsSetUser"><code>cupsSetUser</code></a> function need to do so in each thread for the same user -name to be used.</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsUserAgent">cupsUserAgent</a></h3> - <p class="description">Return the default HTTP User-Agent string.</p> -<p class="code"> -const char *cupsUserAgent (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">User-Agent string</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgFormatSizeName">pwgFormatSizeName</a></h3> - <p class="description">Generate a PWG self-describing media size name.</p> -<p class="code"> -int pwgFormatSizeName (<br /> -    char *keyword,<br /> -    size_t keysize,<br /> -    const char *prefix,<br /> -    const char *name,<br /> -    int width,<br /> -    int length,<br /> -    const char *units<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>keyword</dt> - <dd class="description">Keyword buffer</dd> -<dt>keysize</dt> - <dd class="description">Size of keyword buffer</dd> -<dt>prefix</dt> - <dd class="description">Prefix for PWG size or <code>NULL</code> for automatic</dd> -<dt>name</dt> - <dd class="description">Size name or <code>NULL</code></dd> -<dt>width</dt> - <dd class="description">Width of page in 2540ths</dd> -<dt>length</dt> - <dd class="description">Length of page in 2540ths</dd> -<dt>units</dt> - <dd class="description">Units - "in", "mm", or <code>NULL</code> for automatic</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function generates a PWG self-describing media size name of the form -"prefix_name_WIDTHxLENGTHunits". The prefix is typically "custom" or "roll" -for user-supplied sizes but can also be "disc", "iso", "jis", "jpn", "na", -"oe", "om", "prc", or "roc". A value of <code>NULL</code> automatically chooses -"oe" or "om" depending on the units.<br> -<br> -The size name may only contain lowercase letters, numbers, "-", and ".". If -<code>NULL</code> is passed, the size name will contain the formatted dimensions.<br> -<br> -The width and length are specified in hundredths of millimeters, equivalent -to 1/100000th of a meter or 1/2540th of an inch. The width, length, and -units used for the generated size name are calculated automatically if the -units string is <code>NULL</code>, otherwise inches ("in") or millimeters ("mm") -are used. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgInitSize">pwgInitSize</a></h3> - <p class="description">Initialize a pwg_size_t structure using IPP Job Template -attributes.</p> -<p class="code"> -int pwgInitSize (<br /> -    <a href="#pwg_size_t">pwg_size_t</a> *size,<br /> -    ipp_t *job,<br /> -    int *margins_set<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>size</dt> - <dd class="description">Size to initialize</dd> -<dt>job</dt> - <dd class="description">Job template attributes</dd> -<dt>margins_set</dt> - <dd class="description">1 if margins were set, 0 otherwise</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if size was initialized, 0 otherwise</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function initializes a pwg_size_t structure from an IPP "media" or -"media-col" attribute in the specified IPP message. 0 is returned if neither -attribute is found in the message or the values are not valid.<br> -<br> -The "margins_set" variable is initialized to 1 if any "media-xxx-margin" -member attribute was specified in the "media-col" Job Template attribute, -otherwise it is initialized to 0. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgMediaForLegacy">pwgMediaForLegacy</a></h3> - <p class="description">Find a PWG media size by ISO/IPP legacy name.</p> -<p class="code"> -<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForLegacy (<br /> -    const char *legacy<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>legacy</dt> - <dd class="description">Legacy size name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Matching size or NULL</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The "name" argument specifies the legacy ISO media size name, for example -"iso-a4" or "na-letter". - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgMediaForPPD">pwgMediaForPPD</a></h3> - <p class="description">Find a PWG media size by Adobe PPD name.</p> -<p class="code"> -<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForPPD (<br /> -    const char *ppd<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ppd</dt> - <dd class="description">PPD size name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Matching size or NULL</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The "ppd" argument specifies an Adobe page size name as defined in Table B.1 -of the Adobe PostScript Printer Description File Format Specification Version -4.3.<br> -<br> -If the name is non-standard, the returned PWG media size is stored in -thread-local storage and is overwritten by each call to the function in the -thread. Custom names can be of the form "Custom.WIDTHxLENGTH[units]" or -"WIDTHxLENGTH[units]". - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgMediaForPWG">pwgMediaForPWG</a></h3> - <p class="description">Find a PWG media size by 5101.1 self-describing name.</p> -<p class="code"> -<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForPWG (<br /> -    const char *pwg<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>pwg</dt> - <dd class="description">PWG size name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Matching size or NULL</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The "pwg" argument specifies a self-describing media size name of the form -"prefix_name_WIDTHxLENGTHunits" as defined in PWG 5101.1.<br> -<br> -If the name is non-standard, the returned PWG media size is stored in -thread-local storage and is overwritten by each call to the function in the -thread. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgMediaForSize">pwgMediaForSize</a></h3> - <p class="description">Get the PWG media size for the given dimensions.</p> -<p class="code"> -<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForSize (<br /> -    int width,<br /> -    int length<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>width</dt> - <dd class="description">Width in hundredths of millimeters</dd> -<dt>length</dt> - <dd class="description">Length in hundredths of millimeters</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">PWG media name</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The "width" and "length" are in hundredths of millimeters, equivalent to -1/100000th of a meter or 1/2540th of an inch.<br> -<br> -If the dimensions are non-standard, the returned PWG media size is stored in -thread-local storage and is overwritten by each call to the function in the -thread. - -</p> - <h2 class="title"><a id="TYPES">Data Types</a></h2> - <h3 class="typedef"><a id="cups_client_cert_cb_t"><span class="info"> CUPS 1.5/macOS 10.7 </span>cups_client_cert_cb_t</a></h3> - <p class="description">Client credentials callback -</p> - <p class="code"> -typedef int (*cups_client_cert_cb_t)(http_t *http, void *tls, cups_array_t *distinguished_names, void *user_data); -</p> - <h3 class="typedef"><a id="cups_dest_block_t"><span class="info"> CUPS 1.6/macOS 10.8 </span>cups_dest_block_t</a></h3> - <p class="description">Destination enumeration block -</p> - <p class="code"> -typedef int (*cups_dest_block_t(unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest); -</p> - <h3 class="typedef"><a id="cups_dest_cb_t"><span class="info"> CUPS 1.6/macOS 10.8 </span>cups_dest_cb_t</a></h3> - <p class="description">Destination enumeration callback -</p> - <p class="code"> -typedef int (*cups_dest_cb_t)(void *user_data, unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest); -</p> - <h3 class="typedef"><a id="cups_dest_t">cups_dest_t</a></h3> - <p class="description">Destination</p> - <p class="code"> -typedef struct <a href="#cups_dest_s">cups_dest_s</a> cups_dest_t; -</p> - <h3 class="typedef"><a id="cups_dinfo_t"><span class="info"> CUPS 1.6/macOS 10.8 </span>cups_dinfo_t</a></h3> - <p class="description">Destination capability and status -information </p> - <p class="code"> -typedef struct _cups_dinfo_s cups_dinfo_t; -</p> - <h3 class="typedef"><a id="cups_job_t">cups_job_t</a></h3> - <p class="description">Job</p> - <p class="code"> -typedef struct <a href="#cups_job_s">cups_job_s</a> cups_job_t; -</p> - <h3 class="typedef"><a id="cups_option_t">cups_option_t</a></h3> - <p class="description">Printer Options</p> - <p class="code"> -typedef struct <a href="#cups_option_s">cups_option_s</a> cups_option_t; -</p> - <h3 class="typedef"><a id="cups_password_cb2_t"><span class="info"> CUPS 1.4/macOS 10.6 </span>cups_password_cb2_t</a></h3> - <p class="description">New password callback -</p> - <p class="code"> -typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data); -</p> - <h3 class="typedef"><a id="cups_password_cb_t">cups_password_cb_t</a></h3> - <p class="description">Password callback</p> - <p class="code"> -typedef const char *(*cups_password_cb_t)(const char *prompt); -</p> - <h3 class="typedef"><a id="cups_ptype_t">cups_ptype_t</a></h3> - <p class="description">Printer type/capability bits</p> - <p class="code"> -typedef unsigned cups_ptype_t; -</p> - <h3 class="typedef"><a id="cups_server_cert_cb_t"><span class="info"> CUPS 1.5/macOS 10.7 </span>cups_server_cert_cb_t</a></h3> - <p class="description">Server credentials callback -</p> - <p class="code"> -typedef int (*cups_server_cert_cb_t)(http_t *http, void *tls, cups_array_t *certs, void *user_data); -</p> - <h3 class="typedef"><a id="cups_size_t"><span class="info"> CUPS 1.6/macOS 10.8 </span>cups_size_t</a></h3> - <p class="description">Media Size </p> - <p class="code"> -typedef struct <a href="#cups_size_s">cups_size_s</a> cups_size_t; -</p> - <h3 class="typedef"><a id="pwg_map_t">pwg_map_t</a></h3> - <p class="description">Map element - PPD to/from PWG</p> - <p class="code"> -typedef struct <a href="#pwg_map_s">pwg_map_s</a> pwg_map_t; -</p> - <h3 class="typedef"><a id="pwg_media_t">pwg_media_t</a></h3> - <p class="description">Common media size data</p> - <p class="code"> -typedef struct <a href="#pwg_media_s">pwg_media_s</a> pwg_media_t; -</p> - <h3 class="typedef"><a id="pwg_size_t">pwg_size_t</a></h3> - <p class="description">Size element - PPD to/from PWG</p> - <p class="code"> -typedef struct <a href="#pwg_size_s">pwg_size_s</a> pwg_size_t; -</p> - <h2 class="title"><a id="STRUCTURES">Structures</a></h2> -<h3 class="struct"><a id="cups_dest_s">cups_dest_s</a></h3> - <p class="description">Destination</p> -<p class="code">struct cups_dest_s {<br /> -    char *name, *instance;<br /> -    int is_default;<br /> -    int num_options;<br /> -    <a href="#cups_option_t">cups_option_t</a> *options;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>instance </dt> - <dd class="description">Local instance name or NULL</dd> -<dt>is_default </dt> - <dd class="description">Is this printer the default?</dd> -<dt>num_options </dt> - <dd class="description">Number of options</dd> -<dt>options </dt> - <dd class="description">Options</dd> -</dl> -<h3 class="struct"><a id="cups_job_s">cups_job_s</a></h3> - <p class="description">Job</p> -<p class="code">struct cups_job_s {<br /> -    time_t completed_time;<br /> -    time_t creation_time;<br /> -    char *dest;<br /> -    char *format;<br /> -    int id;<br /> -    int priority;<br /> -    time_t processing_time;<br /> -    int size;<br /> -    ipp_jstate_t state;<br /> -    char *title;<br /> -    char *user;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>completed_time </dt> - <dd class="description">Time the job was completed</dd> -<dt>creation_time </dt> - <dd class="description">Time the job was created</dd> -<dt>dest </dt> - <dd class="description">Printer or class name</dd> -<dt>format </dt> - <dd class="description">Document format</dd> -<dt>id </dt> - <dd class="description">The job ID</dd> -<dt>priority </dt> - <dd class="description">Priority (1-100)</dd> -<dt>processing_time </dt> - <dd class="description">Time the job was processed</dd> -<dt>size </dt> - <dd class="description">Size in kilobytes</dd> -<dt>state </dt> - <dd class="description">Job state</dd> -<dt>title </dt> - <dd class="description">Title/job name</dd> -<dt>user </dt> - <dd class="description">User the submitted the job</dd> -</dl> -<h3 class="struct"><a id="cups_option_s">cups_option_s</a></h3> - <p class="description">Printer Options</p> -<p class="code">struct cups_option_s {<br /> -    char *name;<br /> -    char *value;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>name </dt> - <dd class="description">Name of option</dd> -<dt>value </dt> - <dd class="description">Value of option</dd> -</dl> -<h3 class="struct"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cups_size_s">cups_size_s</a></h3> - <p class="description">Media Size </p> -<p class="code">struct cups_size_s {<br /> -    char media[128];<br /> -    int width, length, bottom, left, right, top;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>media[128] </dt> - <dd class="description">Media name to use</dd> -<dt>top </dt> - <dd class="description">Top margin in hundredths of -millimeters</dd> -</dl> -<h3 class="struct"><a id="pollfd">pollfd</a></h3> - <p class="description">User data (unused)</p> -<p class="code">struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {<br /> -    _cups_dnssd_data_t *data;<br /> -    else if(val 0) data - got_data;<br /> -    void) timeout;<br /> -    int val;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>data </dt> - <dd class="description">Enumeration data</dd> -<dt>got_data </dt> -<dt>timeout </dt> -<dt>val </dt> - <dd class="description">Return value</dd> -</dl> -<h3 class="struct"><a id="pwg_map_s">pwg_map_s</a></h3> - <p class="description">Map element - PPD to/from PWG</p> -<p class="code">struct pwg_map_s {<br /> -    char *pwg, *ppd;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>ppd </dt> - <dd class="description">PPD option keyword</dd> -</dl> -<h3 class="struct"><a id="pwg_media_s">pwg_media_s</a></h3> - <p class="description">Common media size data</p> -<p class="code">struct pwg_media_s {<br /> -    int width, length;<br /> -    const char *pwg, *legacy, *ppd;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>length </dt> - <dd class="description">Length in 2540ths</dd> -<dt>ppd </dt> - <dd class="description">Standard Adobe PPD name</dd> -</dl> -<h3 class="struct"><a id="pwg_size_s">pwg_size_s</a></h3> - <p class="description">Size element - PPD to/from PWG</p> -<p class="code">struct pwg_size_s {<br /> -    <a href="#pwg_map_t">pwg_map_t</a> map;<br /> -    int width, length, left, bottom, right, top;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>map </dt> - <dd class="description">Map element</dd> -<dt>top </dt> - <dd class="description">Top margin in 2540ths</dd> -</dl> - <h2 class="title"><a id="VARIABLES">Variables</a></h2> - <h3 class="variable"><a id="CF_RETURNS_RETAINED">CF_RETURNS_RETAINED</a></h3> - <p class="description">Get the Apple language identifier associated with a -locale ID.</p> - <p class="code">const char *locale) CF_RETURNS_RETAINED;</p> - <h2 class="title"><a id="ENUMERATIONS">Constants</a></h2> - <h3 class="enumeration"><a id="cups_ptype_e">cups_ptype_e</a></h3> - <p class="description">Printer type/capability bit -constants</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Printer requires authentication -</dd> - <dt>CUPS_PRINTER_BIND </dt> - <dd class="description">Can bind output</dd> - <dt>CUPS_PRINTER_BW </dt> - <dd class="description">Can do B&W printing</dd> - <dt>CUPS_PRINTER_CLASS </dt> - <dd class="description">Printer class</dd> - <dt>CUPS_PRINTER_COLLATE </dt> - <dd class="description">Can collage copies</dd> - <dt>CUPS_PRINTER_COLOR </dt> - <dd class="description">Can do color printing</dd> - <dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Printer supports maintenance commands -</dd> - <dt>CUPS_PRINTER_COPIES </dt> - <dd class="description">Can do copies</dd> - <dt>CUPS_PRINTER_COVER </dt> - <dd class="description">Can cover output</dd> - <dt>CUPS_PRINTER_DEFAULT </dt> - <dd class="description">Default printer on network</dd> - <dt>CUPS_PRINTER_DELETE <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Delete printer -</dd> - <dt>CUPS_PRINTER_DUPLEX </dt> - <dd class="description">Can do duplexing</dd> - <dt>CUPS_PRINTER_FAX </dt> - <dd class="description">Fax queue</dd> - <dt>CUPS_PRINTER_LARGE </dt> - <dd class="description">Can do D/E/A1/A0</dd> - <dt>CUPS_PRINTER_LOCAL </dt> - <dd class="description">Local printer or class</dd> - <dt>CUPS_PRINTER_MEDIUM </dt> - <dd class="description">Can do Tabloid/B/C/A3/A2</dd> - <dt>CUPS_PRINTER_MFP <span class="info"> CUPS 1.4/macOS 10.6 </span></dt> - <dd class="description">Printer with scanning capabilities -</dd> - <dt>CUPS_PRINTER_NOT_SHARED <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Printer is not shared -</dd> - <dt>CUPS_PRINTER_PUNCH </dt> - <dd class="description">Can punch output</dd> - <dt>CUPS_PRINTER_REJECTING </dt> - <dd class="description">Printer is rejecting jobs</dd> - <dt>CUPS_PRINTER_REMOTE </dt> - <dd class="description">Remote printer or class</dd> - <dt>CUPS_PRINTER_SCANNER <span class="info"> CUPS 1.4/macOS 10.6 </span></dt> - <dd class="description">Scanner-only device -</dd> - <dt>CUPS_PRINTER_SMALL </dt> - <dd class="description">Can do Letter/Legal/A4</dd> - <dt>CUPS_PRINTER_SORT </dt> - <dd class="description">Can sort output</dd> - <dt>CUPS_PRINTER_STAPLE </dt> - <dd class="description">Can staple output</dd> - <dt>CUPS_PRINTER_VARIABLE </dt> - <dd class="description">Can do variable sizes</dd> -</dl> - </div> - </body> -</html> diff --git a/doc/help/api-filedir.html b/doc/help/api-filedir.html deleted file mode 100644 index 46748a5b3..000000000 --- a/doc/help/api-filedir.html +++ /dev/null @@ -1,1005 +0,0 @@ -<!doctype html> -<html> -<!-- SECTION: Programming --> - <head> - <title>File and Directory APIs</title> - <meta name="keywords" content="Programming"> - <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> - <meta name="creator" content="Mini-XML v2.11"> - <meta name="author" content="Unknown"> - <meta name="copyright" content="Unknown"> - <style type="text/css"><!-- -BODY { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -H1, H2, H3, H4, H5, H6, P, TD, TH { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -KBD { - font-family: monaco, courier, monospace; - font-weight: bold; -} - -PRE { - font-family: monaco, courier, monospace; -} - -PRE.command { - border: dotted thin #7f7f7f; - margin-left: 36pt; - padding: 10px; -} - -P.compact { - margin: 0; -} - -P.example { - font-style: italic; - margin-left: 36pt; -} - -DL.man DD { - margin-left: 5em; -} - -DL.man DT { - margin-left: 0; -} - -PRE.man { - margin: 0; -} - -PRE.example { - background: #eeeeee; - border: dotted thin #999999; - margin-left: 36pt; - padding: 10pt; -} - -PRE.command EM, PRE.example EM { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -P.command { - font-family: monaco, courier, monospace; - margin-left: 36pt; -} - -P.formula { - font-style: italic; - margin-left: 36pt; -} - -BLOCKQUOTE { - background: #eeeeee; - border: solid thin #999999; - padding: 10pt; -} - -A IMG { - border: none; -} - -A:link:hover IMG { - background: #f0f0f0; - border-radius: 10px; - -moz-border-radius: 10px; -} - -A:link, A:visited { - font-weight: inherit; - text-decoration: none; -} - -A:link:hover, A:visited:hover, A:active { - text-decoration: underline; -} - -SUB, SUP { - font-size: 50%; -} - -TR.data, TD.data, TR.data TD { - margin-top: 10pt; - padding: 5pt; - border-bottom: solid 1pt #999999; -} - -TR.data TH { - border-bottom: solid 1pt #999999; - padding-top: 10pt; - padding-left: 5pt; - text-align: left; -} - -DIV.table TABLE { - border: solid thin #999999; - border-collapse: collapse; - border-spacing: 0; - margin-left: auto; - margin-right: auto; -} - -DIV.table CAPTION { - caption-side: top; - font-size: 120%; - font-style: italic; - font-weight: bold; - margin-left: auto; - margin-right: auto; -} - -DIV.table TABLE TD { - border: solid thin #cccccc; - padding-top: 5pt; -} - -DIV.table TABLE TH { - background: #cccccc; - border: none; - border-bottom: solid thin #999999; -} - -DIV.figure TABLE { - margin-left: auto; - margin-right: auto; -} - -DIV.figure CAPTION { - caption-side: bottom; - font-size: 120%; - font-style: italic; - font-weight: bold; - margin-left: auto; - margin-right: auto; -} - -TH.label { - text-align: right; - vertical-align: top; -} - -TH.sublabel { - text-align: right; - font-weight: normal; -} - -HR { - border: solid thin; -} - -SPAN.info { - background: black; - border: thin solid black; - color: white; - font-size: 80%; - font-style: italic; - font-weight: bold; - white-space: nowrap; -} - -H2 SPAN.info, H3 SPAN.info, H4 SPAN.info { - float: right; - font-size: 100%; -} - -H1.title { -} - -H2.title, H3.title { - border-bottom: solid 2pt #000000; -} - -DIV.indent, TABLE.indent { - margin-top: 2em; - margin-left: auto; - margin-right: auto; - width: 90%; -} - -TABLE.indent { - border-collapse: collapse; -} - -TABLE.indent TD, TABLE.indent TH { - padding: 0; -} - -TABLE.list { - border-collapse: collapse; - margin-left: auto; - margin-right: auto; - width: 90%; -} - -TABLE.list TH { - background: white; - border-bottom: solid thin #cccccc; - color: #444444; - padding-top: 10pt; - padding-left: 5pt; - text-align: left; - vertical-align: bottom; - white-space: nowrap; -} - -TABLE.list TH A { - color: #4444cc; -} - -TABLE.list TD { - border-bottom: solid thin #eeeeee; - padding-top: 5pt; - padding-left: 5pt; -} - -TABLE.list TR:nth-child(even) { - background: #f8f8f8; -} - -TABLE.list TR:nth-child(odd) { - background: #f4f4f4; -} - -DT { - margin-left: 36pt; - margin-top: 12pt; -} - -DD { - margin-left: 54pt; -} - -DL.category DT { - font-weight: bold; -} - -P.summary { - margin-left: 36pt; - font-family: monaco, courier, monospace; -} - -DIV.summary TABLE { - border: solid thin #999999; - border-collapse: collapse; - border-spacing: 0; - margin: 10px; -} - -DIV.summary TABLE TD, DIV.summary TABLE TH { - border: solid thin #999999; - padding: 5px; - text-align: left; - vertical-align: top; -} - -DIV.summary TABLE THEAD TH { - background: #eeeeee; -} - -/* API documentation styles... */ -div.body h1 { - margin: 0; -} -div.body h2 { - margin-top: 1.5em; -} -div.body h3, div.body h4, div.body h5 { - margin-bottom: 0.5em; - margin-top: 1.5em; -} -.class, .enumeration, .function, .struct, .typedef, .union { - border-bottom: solid thin #999999; - margin-bottom: 0; - margin-top: 2em; -} -.description { - margin-top: 0.5em; -} -code, p.code, pre, ul.code li { - font-family: monaco, courier, monospace; - font-size: 90%; -} -ul.code, ul.contents, ul.subcontents { - list-style-type: none; - margin: 0; - padding-left: 0; -} -ul.code li { - margin: 0; -} -ul.contents > li { - margin-top: 1em; -} -ul.contents li ul.code, ul.contents li ul.subcontents { - padding-left: 2em; -} -div.body dl { - margin-left: 0; - margin-top: 0; -} -div.body dt { - font-style: italic; - margin-left: 0; - margin-top: 0; -} -div.body dd { - margin-bottom: 0.5em; -} - -/* This is just for the HTML files generated with the framedhelp target */ -div.contents { - background: #e8e8e8; - border: solid thin black; - padding: 10px; -} -div.contents h1 { - font-size: 110%; -} -div.contents h2 { - font-size: 100%; -} -div.contents ul.contents { - font-size: 80%; -} -div.contents ul.subcontents li { - margin-left: 1em; - text-indent: -1em; -} ---></style> - </head> - <body> -<!-- - File and Directory API header for CUPS. - - Copyright 2008-2011 by Apple Inc. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h1 class='title'>File and Directory APIs</h1> - -<div class='summary'><table summary='General Information'> -<thead> -<tr> - <th>Headers</th> - <th>cups/file.h<br> - cups/dir.h</th> -</tr> -</thead> -<tbody> -<tr> - <th>Library</th> - <td>-lcups</td> -</tr> -<tr> - <th>See Also</th> - <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br> - Programming: <a href='api-cups.html' target='_top'>CUPS API</a></td> -</tr> -</tbody> -</table></div> - <div class="contents"> - <h2 class="title">Contents</h2> - <ul class="contents"> - <li><a href="#OVERVIEW">Overview</a></li> - <li><a href="#FUNCTIONS">Functions</a><ul class="subcontents"> - <li><a href="#cupsDirClose">cupsDirClose</a></li> - <li><a href="#cupsDirOpen">cupsDirOpen</a></li> - <li><a href="#cupsDirRead">cupsDirRead</a></li> - <li><a href="#cupsDirRewind">cupsDirRewind</a></li> - <li><a href="#cupsFileClose">cupsFileClose</a></li> - <li><a href="#cupsFileCompression">cupsFileCompression</a></li> - <li><a href="#cupsFileEOF">cupsFileEOF</a></li> - <li><a href="#cupsFileFind">cupsFileFind</a></li> - <li><a href="#cupsFileFlush">cupsFileFlush</a></li> - <li><a href="#cupsFileGetChar">cupsFileGetChar</a></li> - <li><a href="#cupsFileGetConf">cupsFileGetConf</a></li> - <li><a href="#cupsFileGetLine">cupsFileGetLine</a></li> - <li><a href="#cupsFileGets">cupsFileGets</a></li> - <li><a href="#cupsFileLock">cupsFileLock</a></li> - <li><a href="#cupsFileNumber">cupsFileNumber</a></li> - <li><a href="#cupsFileOpen">cupsFileOpen</a></li> - <li><a href="#cupsFileOpenFd">cupsFileOpenFd</a></li> - <li><a href="#cupsFilePeekChar">cupsFilePeekChar</a></li> - <li><a href="#cupsFilePrintf">cupsFilePrintf</a></li> - <li><a href="#cupsFilePutChar">cupsFilePutChar</a></li> - <li><a href="#cupsFilePutConf">cupsFilePutConf</a></li> - <li><a href="#cupsFilePuts">cupsFilePuts</a></li> - <li><a href="#cupsFileRead">cupsFileRead</a></li> - <li><a href="#cupsFileRewind">cupsFileRewind</a></li> - <li><a href="#cupsFileSeek">cupsFileSeek</a></li> - <li><a href="#cupsFileStderr">cupsFileStderr</a></li> - <li><a href="#cupsFileStdin">cupsFileStdin</a></li> - <li><a href="#cupsFileStdout">cupsFileStdout</a></li> - <li><a href="#cupsFileTell">cupsFileTell</a></li> - <li><a href="#cupsFileUnlock">cupsFileUnlock</a></li> - <li><a href="#cupsFileWrite">cupsFileWrite</a></li> - </ul></li> - <li><a href="#TYPES">Data Types</a><ul class="subcontents"> - <li><a href="#cups_dentry_t">cups_dentry_t</a></li> - <li><a href="#cups_dir_t">cups_dir_t</a></li> - <li><a href="#cups_file_t">cups_file_t</a></li> - </ul></li> - <li><a href="#STRUCTURES">Structures</a><ul class="subcontents"> - <li><a href="#cups_dentry_s">cups_dentry_s</a></li> - </ul></li> - </ul> - </div> - <div class="body"> -<!-- - File and directory API introduction for CUPS. - - Copyright 2007-2011 by Apple Inc. - Copyright 1997-2005 by Easy Software Products, all rights reserved. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h2 class='title'><a name="OVERVIEW">Overview</a></h2> - -<p>The CUPS file and directory APIs provide portable interfaces -for manipulating files and listing files and directories. Unlike -stdio <code>FILE</code> streams, the <code>cupsFile</code> functions -allow you to open more than 256 files at any given time. They -also manage the platform-specific details of locking, large file -support, line endings (CR, LF, or CR LF), and reading and writing -files using Flate ("gzip") compression. Finally, you can also -connect, read from, and write to network connections using the -<code>cupsFile</code> functions.</p> - -<p>The <code>cupsDir</code> functions manage the platform-specific -details of directory access/listing and provide a convenient way -to get both a list of files and the information (permissions, -size, timestamp, etc.) for each of those files.</p> - <h2 class="title"><a id="FUNCTIONS">Functions</a></h2> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsDirClose">cupsDirClose</a></h3> - <p class="description">Close a directory.</p> -<p class="code"> -void cupsDirClose (<br /> -    <a href="#cups_dir_t">cups_dir_t</a> *dp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dp</dt> - <dd class="description">Directory pointer</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsDirOpen">cupsDirOpen</a></h3> - <p class="description">Open a directory.</p> -<p class="code"> -<a href="#cups_dir_t">cups_dir_t</a> *cupsDirOpen (<br /> -    const char *directory<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>directory</dt> - <dd class="description">Directory name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Directory pointer or <code>NULL</code> if the directory could not be opened.</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsDirRead">cupsDirRead</a></h3> - <p class="description">Read the next directory entry.</p> -<p class="code"> -<a href="#cups_dentry_t">cups_dentry_t</a> *cupsDirRead (<br /> -    <a href="#cups_dir_t">cups_dir_t</a> *dp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dp</dt> - <dd class="description">Directory pointer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Directory entry or <code>NULL</code> when there are no more</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsDirRewind">cupsDirRewind</a></h3> - <p class="description">Rewind to the start of the directory.</p> -<p class="code"> -void cupsDirRewind (<br /> -    <a href="#cups_dir_t">cups_dir_t</a> *dp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dp</dt> - <dd class="description">Directory pointer</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileClose">cupsFileClose</a></h3> - <p class="description">Close a CUPS file.</p> -<p class="code"> -int cupsFileClose (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileCompression">cupsFileCompression</a></h3> - <p class="description">Return whether a file is compressed.</p> -<p class="code"> -int cupsFileCompression (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description"><code>CUPS_FILE_NONE</code> or <code>CUPS_FILE_GZIP</code></p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileEOF">cupsFileEOF</a></h3> - <p class="description">Return the end-of-file status.</p> -<p class="code"> -int cupsFileEOF (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on end of file, 0 otherwise</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileFind">cupsFileFind</a></h3> - <p class="description">Find a file using the specified path.</p> -<p class="code"> -const char *cupsFileFind (<br /> -    const char *filename,<br /> -    const char *path,<br /> -    int executable,<br /> -    char *buffer,<br /> -    int bufsize<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>filename</dt> - <dd class="description">File to find</dd> -<dt>path</dt> - <dd class="description">Colon/semicolon-separated path</dd> -<dt>executable</dt> - <dd class="description">1 = executable files, 0 = any file/dir</dd> -<dt>buffer</dt> - <dd class="description">Filename buffer</dd> -<dt>bufsize</dt> - <dd class="description">Size of filename buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Full path to file or <code>NULL</code> if not found</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function allows the paths in the path string to be separated by -colons (UNIX standard) or semicolons (Windows standard) and stores the -result in the buffer supplied. If the file cannot be found in any of -the supplied paths, <code>NULL</code> is returned. A <code>NULL</code> path only -matches the current directory. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileFlush">cupsFileFlush</a></h3> - <p class="description">Flush pending output.</p> -<p class="code"> -int cupsFileFlush (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileGetChar">cupsFileGetChar</a></h3> - <p class="description">Get a single character from a file.</p> -<p class="code"> -int cupsFileGetChar (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Character or -1 on end of file</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileGetConf">cupsFileGetConf</a></h3> - <p class="description">Get a line from a configuration file.</p> -<p class="code"> -char *cupsFileGetConf (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp,<br /> -    char *buf,<br /> -    size_t buflen,<br /> -    char **value,<br /> -    int *linenum<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -<dt>buf</dt> - <dd class="description">String buffer</dd> -<dt>buflen</dt> - <dd class="description">Size of string buffer</dd> -<dt>value</dt> - <dd class="description">Pointer to value</dd> -<dt>linenum</dt> - <dd class="description">Current line number</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Line read or <code>NULL</code> on end of file or error</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileGetLine">cupsFileGetLine</a></h3> - <p class="description">Get a CR and/or LF-terminated line that may -contain binary data.</p> -<p class="code"> -size_t cupsFileGetLine (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp,<br /> -    char *buf,<br /> -    size_t buflen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">File to read from</dd> -<dt>buf</dt> - <dd class="description">Buffer</dd> -<dt>buflen</dt> - <dd class="description">Size of buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes on line or 0 on end of file</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function differs from <a href="#cupsFileGets"><code>cupsFileGets</code></a> in that the trailing CR -and LF are preserved, as is any binary data on the line. The buffer is -nul-terminated, however you should use the returned length to determine -the number of bytes on the line. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileGets">cupsFileGets</a></h3> - <p class="description">Get a CR and/or LF-terminated line.</p> -<p class="code"> -char *cupsFileGets (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp,<br /> -    char *buf,<br /> -    size_t buflen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -<dt>buf</dt> - <dd class="description">String buffer</dd> -<dt>buflen</dt> - <dd class="description">Size of string buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Line read or <code>NULL</code> on end of file or error</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileLock">cupsFileLock</a></h3> - <p class="description">Temporarily lock access to a file.</p> -<p class="code"> -int cupsFileLock (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp,<br /> -    int block<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -<dt>block</dt> - <dd class="description">1 to wait for the lock, 0 to fail right away</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileNumber">cupsFileNumber</a></h3> - <p class="description">Return the file descriptor associated with a CUPS file.</p> -<p class="code"> -int cupsFileNumber (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">File descriptor</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileOpen">cupsFileOpen</a></h3> - <p class="description">Open a CUPS file.</p> -<p class="code"> -<a href="#cups_file_t">cups_file_t</a> *cupsFileOpen (<br /> -    const char *filename,<br /> -    const char *mode<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>filename</dt> - <dd class="description">Name of file</dd> -<dt>mode</dt> - <dd class="description">Open mode</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">CUPS file or <code>NULL</code> if the file or socket cannot be opened</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The "mode" parameter can be "r" to read, "w" to write, overwriting any -existing file, "a" to append to an existing file or create a new file, -or "s" to open a socket connection.<br> -<br> -When opening for writing ("w"), an optional number from 1 to 9 can be -supplied which enables Flate compression of the file. Compression is -not supported for the "a" (append) mode.<br> -<br> -When opening a socket connection, the filename is a string of the form -"address:port" or "hostname:port". The socket will make an IPv4 or IPv6 -connection as needed, generally preferring IPv6 connections when there is -a choice. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileOpenFd">cupsFileOpenFd</a></h3> - <p class="description">Open a CUPS file using a file descriptor.</p> -<p class="code"> -<a href="#cups_file_t">cups_file_t</a> *cupsFileOpenFd (<br /> -    int fd,<br /> -    const char *mode<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fd</dt> - <dd class="description">File descriptor</dd> -<dt>mode</dt> - <dd class="description">Open mode</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">CUPS file or <code>NULL</code> if the file could not be opened</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The "mode" parameter can be "r" to read, "w" to write, "a" to append, -or "s" to treat the file descriptor as a bidirectional socket connection.<br> -<br> -When opening for writing ("w"), an optional number from 1 to 9 can be -supplied which enables Flate compression of the file. Compression is -not supported for the "a" (append) mode. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFilePeekChar">cupsFilePeekChar</a></h3> - <p class="description">Peek at the next character from a file.</p> -<p class="code"> -int cupsFilePeekChar (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Character or -1 on end of file</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFilePrintf">cupsFilePrintf</a></h3> - <p class="description">Write a formatted string.</p> -<p class="code"> -int cupsFilePrintf (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp,<br /> -    const char *format,<br /> -    ...<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -<dt>format</dt> - <dd class="description">Printf-style format string</dd> -<dt>...</dt> - <dd class="description">Additional args as necessary</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes written or -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFilePutChar">cupsFilePutChar</a></h3> - <p class="description">Write a character.</p> -<p class="code"> -int cupsFilePutChar (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp,<br /> -    int c<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -<dt>c</dt> - <dd class="description">Character to write</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsFilePutConf">cupsFilePutConf</a></h3> - <p class="description">Write a configuration line.</p> -<p class="code"> -ssize_t cupsFilePutConf (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp,<br /> -    const char *directive,<br /> -    const char *value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -<dt>directive</dt> - <dd class="description">Directive</dd> -<dt>value</dt> - <dd class="description">Value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes written or -1 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function handles any comment escaping of the value. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFilePuts">cupsFilePuts</a></h3> - <p class="description">Write a string.</p> -<p class="code"> -int cupsFilePuts (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp,<br /> -    const char *s<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -<dt>s</dt> - <dd class="description">String to write</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes written or -1 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Like the <code>fputs</code> function, no newline is appended to the string. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileRead">cupsFileRead</a></h3> - <p class="description">Read from a file.</p> -<p class="code"> -ssize_t cupsFileRead (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp,<br /> -    char *buf,<br /> -    size_t bytes<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -<dt>buf</dt> - <dd class="description">Buffer</dd> -<dt>bytes</dt> - <dd class="description">Number of bytes to read</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes read or -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileRewind">cupsFileRewind</a></h3> - <p class="description">Set the current file position to the beginning of the -file.</p> -<p class="code"> -off_t cupsFileRewind (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New file position or -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileSeek">cupsFileSeek</a></h3> - <p class="description">Seek in a file.</p> -<p class="code"> -off_t cupsFileSeek (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp,<br /> -    off_t pos<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -<dt>pos</dt> - <dd class="description">Position in file</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New file position or -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileStderr">cupsFileStderr</a></h3> - <p class="description">Return a CUPS file associated with stderr.</p> -<p class="code"> -<a href="#cups_file_t">cups_file_t</a> *cupsFileStderr (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">CUPS file</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileStdin">cupsFileStdin</a></h3> - <p class="description">Return a CUPS file associated with stdin.</p> -<p class="code"> -<a href="#cups_file_t">cups_file_t</a> *cupsFileStdin (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">CUPS file</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileStdout">cupsFileStdout</a></h3> - <p class="description">Return a CUPS file associated with stdout.</p> -<p class="code"> -<a href="#cups_file_t">cups_file_t</a> *cupsFileStdout (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">CUPS file</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileTell">cupsFileTell</a></h3> - <p class="description">Return the current file position.</p> -<p class="code"> -off_t cupsFileTell (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">File position</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileUnlock">cupsFileUnlock</a></h3> - <p class="description">Unlock access to a file.</p> -<p class="code"> -int cupsFileUnlock (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileWrite">cupsFileWrite</a></h3> - <p class="description">Write to a file.</p> -<p class="code"> -ssize_t cupsFileWrite (<br /> -    <a href="#cups_file_t">cups_file_t</a> *fp,<br /> -    const char *buf,<br /> -    size_t bytes<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fp</dt> - <dd class="description">CUPS file</dd> -<dt>buf</dt> - <dd class="description">Buffer</dd> -<dt>bytes</dt> - <dd class="description">Number of bytes to write</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes written or -1 on error</p> - <h2 class="title"><a id="TYPES">Data Types</a></h2> - <h3 class="typedef"><a id="cups_dentry_t">cups_dentry_t</a></h3> - <p class="description">Directory entry type</p> - <p class="code"> -typedef struct <a href="#cups_dentry_s">cups_dentry_s</a> cups_dentry_t; -</p> - <h3 class="typedef"><a id="cups_dir_t">cups_dir_t</a></h3> - <p class="description">Directory type</p> - <p class="code"> -typedef struct _cups_dir_s cups_dir_t; -</p> - <h3 class="typedef"><a id="cups_file_t">cups_file_t</a></h3> - <p class="description">CUPS file type</p> - <p class="code"> -typedef struct _cups_file_s cups_file_t; -</p> - <h2 class="title"><a id="STRUCTURES">Structures</a></h2> -<h3 class="struct"><a id="cups_dentry_s">cups_dentry_s</a></h3> - <p class="description">Directory entry type</p> -<p class="code">struct cups_dentry_s {<br /> -    struct stat fileinfo;<br /> -    char filename[260];<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>fileinfo </dt> - <dd class="description">File information</dd> -<dt>filename[260] </dt> - <dd class="description">File name</dd> -</dl> - </div> - </body> -</html> diff --git a/doc/help/api-filter.html b/doc/help/api-filter.html index 63b223608..0880e9272 100644 --- a/doc/help/api-filter.html +++ b/doc/help/api-filter.html @@ -8,6 +8,7 @@ <meta name="creator" content="Mini-XML v2.11"> <meta name="author" content="Unknown"> <meta name="copyright" content="Unknown"> + <meta name="version" content="0.0"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -1319,10 +1320,10 @@ void *my_data; <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsBackChannelRead">cupsBackChannelRead</a></h3> <p class="description">Read data from the backchannel.</p> <p class="code"> -ssize_t cupsBackChannelRead (<br /> -    char *buffer,<br /> -    size_t bytes,<br /> -    double timeout<br /> +ssize_t cupsBackChannelRead (<br> +    char *buffer,<br> +    size_t bytes,<br> +    double timeout<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1344,10 +1345,10 @@ return immediately if there is no data, -1.0 to wait for data indefinitely. <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsBackChannelWrite">cupsBackChannelWrite</a></h3> <p class="description">Write data to the backchannel.</p> <p class="code"> -ssize_t cupsBackChannelWrite (<br /> -    const char *buffer,<br /> -    size_t bytes,<br /> -    double timeout<br /> +ssize_t cupsBackChannelWrite (<br> +    const char *buffer,<br> +    size_t bytes,<br> +    double timeout<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1370,8 +1371,8 @@ indefinitely. <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsBackendDeviceURI">cupsBackendDeviceURI</a></h3> <p class="description">Get the device URI for a backend.</p> <p class="code"> -const char *cupsBackendDeviceURI (<br /> -    char **argv<br /> +const char *cupsBackendDeviceURI (<br> +    char **argv<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1390,13 +1391,13 @@ first. <h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsBackendReport">cupsBackendReport</a></h3> <p class="description">Write a device line from a backend.</p> <p class="code"> -void cupsBackendReport (<br /> -    const char *device_scheme,<br /> -    const char *device_uri,<br /> -    const char *device_make_and_model,<br /> -    const char *device_info,<br /> -    const char *device_id,<br /> -    const char *device_location<br /> +void cupsBackendReport (<br> +    const char *device_scheme,<br> +    const char *device_uri,<br> +    const char *device_make_and_model,<br> +    const char *device_info,<br> +    const char *device_id,<br> +    const char *device_location<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1422,11 +1423,11 @@ device-info, device-id, and device-location strings. <h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsSideChannelDoRequest">cupsSideChannelDoRequest</a></h3> <p class="description">Send a side-channel command to a backend and wait for a response.</p> <p class="code"> -<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelDoRequest (<br /> -    <a href="#cups_sc_command_t">cups_sc_command_t</a> command,<br /> -    char *data,<br /> -    int *datalen,<br /> -    double timeout<br /> +<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelDoRequest (<br> +    <a href="#cups_sc_command_t">cups_sc_command_t</a> command,<br> +    char *data,<br> +    int *datalen,<br> +    double timeout<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1456,12 +1457,12 @@ update the value to contain the number of data bytes in the buffer. <h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsSideChannelRead">cupsSideChannelRead</a></h3> <p class="description">Read a side-channel message.</p> <p class="code"> -int cupsSideChannelRead (<br /> -    <a href="#cups_sc_command_t">cups_sc_command_t</a> *command,<br /> -    <a href="#cups_sc_status_t">cups_sc_status_t</a> *status,<br /> -    char *data,<br /> -    int *datalen,<br /> -    double timeout<br /> +int cupsSideChannelRead (<br> +    <a href="#cups_sc_command_t">cups_sc_command_t</a> *command,<br> +    <a href="#cups_sc_status_t">cups_sc_status_t</a> *status,<br> +    char *data,<br> +    int *datalen,<br> +    double timeout<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1492,11 +1493,11 @@ update the value to contain the number of data bytes in the buffer. <h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsSideChannelSNMPGet">cupsSideChannelSNMPGet</a></h3> <p class="description">Query a SNMP OID's value.</p> <p class="code"> -<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPGet (<br /> -    const char *oid,<br /> -    char *data,<br /> -    int *datalen,<br /> -    double timeout<br /> +<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPGet (<br> +    const char *oid,<br> +    char *data,<br> +    int *datalen,<br> +    double timeout<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1533,11 +1534,11 @@ the printer does not respond to the SNMP query. <h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsSideChannelSNMPWalk">cupsSideChannelSNMPWalk</a></h3> <p class="description">Query multiple SNMP OID values.</p> <p class="code"> -<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPWalk (<br /> -    const char *oid,<br /> -    double timeout,<br /> -    <a href="#cups_sc_walk_func_t">cups_sc_walk_func_t</a> cb,<br /> -    void *context<br /> +<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPWalk (<br> +    const char *oid,<br> +    double timeout,<br> +    <a href="#cups_sc_walk_func_t">cups_sc_walk_func_t</a> cb,<br> +    void *context<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1579,12 +1580,12 @@ the printer does not respond to the first SNMP query. <h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsSideChannelWrite">cupsSideChannelWrite</a></h3> <p class="description">Write a side-channel message.</p> <p class="code"> -int cupsSideChannelWrite (<br /> -    <a href="#cups_sc_command_t">cups_sc_command_t</a> command,<br /> -    <a href="#cups_sc_status_t">cups_sc_status_t</a> status,<br /> -    const char *data,<br /> -    int datalen,<br /> -    double timeout<br /> +int cupsSideChannelWrite (<br> +    <a href="#cups_sc_command_t">cups_sc_command_t</a> command,<br> +    <a href="#cups_sc_status_t">cups_sc_status_t</a> status,<br> +    const char *data,<br> +    int datalen,<br> +    double timeout<br> );</p> <h4 class="parameters">Parameters</h4> <dl> diff --git a/doc/help/api-httpipp.html b/doc/help/api-httpipp.html deleted file mode 100644 index 6b7941ce3..000000000 --- a/doc/help/api-httpipp.html +++ /dev/null @@ -1,6742 +0,0 @@ -<!doctype html> -<html> -<!-- SECTION: Programming --> - <head> - <title>HTTP and IPP APIs</title> - <meta name="keywords" content="Programming"> - <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> - <meta name="creator" content="Mini-XML v2.11"> - <meta name="author" content="Unknown"> - <meta name="copyright" content="Unknown"> - <style type="text/css"><!-- -BODY { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -H1, H2, H3, H4, H5, H6, P, TD, TH { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -KBD { - font-family: monaco, courier, monospace; - font-weight: bold; -} - -PRE { - font-family: monaco, courier, monospace; -} - -PRE.command { - border: dotted thin #7f7f7f; - margin-left: 36pt; - padding: 10px; -} - -P.compact { - margin: 0; -} - -P.example { - font-style: italic; - margin-left: 36pt; -} - -DL.man DD { - margin-left: 5em; -} - -DL.man DT { - margin-left: 0; -} - -PRE.man { - margin: 0; -} - -PRE.example { - background: #eeeeee; - border: dotted thin #999999; - margin-left: 36pt; - padding: 10pt; -} - -PRE.command EM, PRE.example EM { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -P.command { - font-family: monaco, courier, monospace; - margin-left: 36pt; -} - -P.formula { - font-style: italic; - margin-left: 36pt; -} - -BLOCKQUOTE { - background: #eeeeee; - border: solid thin #999999; - padding: 10pt; -} - -A IMG { - border: none; -} - -A:link:hover IMG { - background: #f0f0f0; - border-radius: 10px; - -moz-border-radius: 10px; -} - -A:link, A:visited { - font-weight: inherit; - text-decoration: none; -} - -A:link:hover, A:visited:hover, A:active { - text-decoration: underline; -} - -SUB, SUP { - font-size: 50%; -} - -TR.data, TD.data, TR.data TD { - margin-top: 10pt; - padding: 5pt; - border-bottom: solid 1pt #999999; -} - -TR.data TH { - border-bottom: solid 1pt #999999; - padding-top: 10pt; - padding-left: 5pt; - text-align: left; -} - -DIV.table TABLE { - border: solid thin #999999; - border-collapse: collapse; - border-spacing: 0; - margin-left: auto; - margin-right: auto; -} - -DIV.table CAPTION { - caption-side: top; - font-size: 120%; - font-style: italic; - font-weight: bold; - margin-left: auto; - margin-right: auto; -} - -DIV.table TABLE TD { - border: solid thin #cccccc; - padding-top: 5pt; -} - -DIV.table TABLE TH { - background: #cccccc; - border: none; - border-bottom: solid thin #999999; -} - -DIV.figure TABLE { - margin-left: auto; - margin-right: auto; -} - -DIV.figure CAPTION { - caption-side: bottom; - font-size: 120%; - font-style: italic; - font-weight: bold; - margin-left: auto; - margin-right: auto; -} - -TH.label { - text-align: right; - vertical-align: top; -} - -TH.sublabel { - text-align: right; - font-weight: normal; -} - -HR { - border: solid thin; -} - -SPAN.info { - background: black; - border: thin solid black; - color: white; - font-size: 80%; - font-style: italic; - font-weight: bold; - white-space: nowrap; -} - -H2 SPAN.info, H3 SPAN.info, H4 SPAN.info { - float: right; - font-size: 100%; -} - -H1.title { -} - -H2.title, H3.title { - border-bottom: solid 2pt #000000; -} - -DIV.indent, TABLE.indent { - margin-top: 2em; - margin-left: auto; - margin-right: auto; - width: 90%; -} - -TABLE.indent { - border-collapse: collapse; -} - -TABLE.indent TD, TABLE.indent TH { - padding: 0; -} - -TABLE.list { - border-collapse: collapse; - margin-left: auto; - margin-right: auto; - width: 90%; -} - -TABLE.list TH { - background: white; - border-bottom: solid thin #cccccc; - color: #444444; - padding-top: 10pt; - padding-left: 5pt; - text-align: left; - vertical-align: bottom; - white-space: nowrap; -} - -TABLE.list TH A { - color: #4444cc; -} - -TABLE.list TD { - border-bottom: solid thin #eeeeee; - padding-top: 5pt; - padding-left: 5pt; -} - -TABLE.list TR:nth-child(even) { - background: #f8f8f8; -} - -TABLE.list TR:nth-child(odd) { - background: #f4f4f4; -} - -DT { - margin-left: 36pt; - margin-top: 12pt; -} - -DD { - margin-left: 54pt; -} - -DL.category DT { - font-weight: bold; -} - -P.summary { - margin-left: 36pt; - font-family: monaco, courier, monospace; -} - -DIV.summary TABLE { - border: solid thin #999999; - border-collapse: collapse; - border-spacing: 0; - margin: 10px; -} - -DIV.summary TABLE TD, DIV.summary TABLE TH { - border: solid thin #999999; - padding: 5px; - text-align: left; - vertical-align: top; -} - -DIV.summary TABLE THEAD TH { - background: #eeeeee; -} - -/* API documentation styles... */ -div.body h1 { - margin: 0; -} -div.body h2 { - margin-top: 1.5em; -} -div.body h3, div.body h4, div.body h5 { - margin-bottom: 0.5em; - margin-top: 1.5em; -} -.class, .enumeration, .function, .struct, .typedef, .union { - border-bottom: solid thin #999999; - margin-bottom: 0; - margin-top: 2em; -} -.description { - margin-top: 0.5em; -} -code, p.code, pre, ul.code li { - font-family: monaco, courier, monospace; - font-size: 90%; -} -ul.code, ul.contents, ul.subcontents { - list-style-type: none; - margin: 0; - padding-left: 0; -} -ul.code li { - margin: 0; -} -ul.contents > li { - margin-top: 1em; -} -ul.contents li ul.code, ul.contents li ul.subcontents { - padding-left: 2em; -} -div.body dl { - margin-left: 0; - margin-top: 0; -} -div.body dt { - font-style: italic; - margin-left: 0; - margin-top: 0; -} -div.body dd { - margin-bottom: 0.5em; -} - -/* This is just for the HTML files generated with the framedhelp target */ -div.contents { - background: #e8e8e8; - border: solid thin black; - padding: 10px; -} -div.contents h1 { - font-size: 110%; -} -div.contents h2 { - font-size: 100%; -} -div.contents ul.contents { - font-size: 80%; -} -div.contents ul.subcontents li { - margin-left: 1em; - text-indent: -1em; -} ---></style> - </head> - <body> -<!-- - HTTP and IPP API header for CUPS. - - Copyright 2007-2016 by Apple Inc. - Copyright 1997-2006 by Easy Software Products, all rights reserved. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h1 class='title'>HTTP and IPP APIs</h1> - -<div class='summary'><table summary='General Information'> -<thead> -<tr> - <th>Headers</th> - <th>cups/cups.h<br> - cups/http.h<br> - cups/ipp.h</th> -</tr> -</thead> -<tbody> -<tr> - <th>Library</th> - <td>-lcups</td> -</tr> -<tr> - <th>See Also</th> - <td>Programming: <a href='api-overview.html'>Introduction to CUPS Programming</a><br> - Programming: <a href='api-cups.html'>CUPS API</a><br> - References: <a href='spec-ipp.html'>CUPS Implementation of IPP</a></td> -</tr> -</tbody> -</table></div> - <div class="contents"> - <h2 class="title">Contents</h2> - <ul class="contents"> - <li><a href="#OVERVIEW">Overview</a><ul class="subcontents"> - <li><a href="#CREATING_URI_STRINGS">Creating URI Strings</a></li> - <li><a href="#SENDING_REQUESTS_WITH_FILES">Sending Requests with Files</a></li> - <li><a href="#ASYNCHRONOUS_REQUEST_PROCESSING">Asynchronous Request Processing</a></li> - </ul></li> - <li><a href="#FUNCTIONS">Functions</a><ul class="subcontents"> - <li><a href="#cupsDoAuthentication">cupsDoAuthentication</a></li> - <li><a href="#cupsDoFileRequest">cupsDoFileRequest</a></li> - <li><a href="#cupsDoIORequest">cupsDoIORequest</a></li> - <li><a href="#cupsDoRequest">cupsDoRequest</a></li> - <li><a href="#cupsEncodeOptions">cupsEncodeOptions</a></li> - <li><a href="#cupsEncodeOptions2">cupsEncodeOptions2</a></li> - <li><a href="#cupsGetDevices">cupsGetDevices</a></li> - <li><a href="#cupsGetFd">cupsGetFd</a></li> - <li><a href="#cupsGetFile">cupsGetFile</a></li> - <li><a href="#cupsGetResponse">cupsGetResponse</a></li> - <li><a href="#cupsLastError">cupsLastError</a></li> - <li><a href="#cupsLastErrorString">cupsLastErrorString</a></li> - <li><a href="#cupsPutFd">cupsPutFd</a></li> - <li><a href="#cupsPutFile">cupsPutFile</a></li> - <li><a href="#cupsReadResponseData">cupsReadResponseData</a></li> - <li><a href="#cupsSendRequest">cupsSendRequest</a></li> - <li><a href="#cupsWriteRequestData">cupsWriteRequestData</a></li> - <li><a href="#httpAcceptConnection">httpAcceptConnection</a></li> - <li><a href="#httpAddCredential">httpAddCredential</a></li> - <li><a href="#httpAddrAny">httpAddrAny</a></li> - <li><a href="#httpAddrClose">httpAddrClose</a></li> - <li><a href="#httpAddrEqual">httpAddrEqual</a></li> - <li><a href="#httpAddrFamily">httpAddrFamily</a></li> - <li><a href="#httpAddrLength">httpAddrLength</a></li> - <li><a href="#httpAddrListen">httpAddrListen</a></li> - <li><a href="#httpAddrLocalhost">httpAddrLocalhost</a></li> - <li><a href="#httpAddrLookup">httpAddrLookup</a></li> - <li><a href="#httpAddrPort">httpAddrPort</a></li> - <li><a href="#httpAddrString">httpAddrString</a></li> - <li><a href="#httpAssembleURI">httpAssembleURI</a></li> - <li><a href="#httpAssembleURIf">httpAssembleURIf</a></li> - <li><a href="#httpAssembleUUID">httpAssembleUUID</a></li> - <li><a href="#httpBlocking">httpBlocking</a></li> - <li><a href="#httpCheck">httpCheck</a></li> - <li><a href="#httpClearCookie">httpClearCookie</a></li> - <li><a href="#httpClearFields">httpClearFields</a></li> - <li><a href="#httpClose">httpClose</a></li> - <li><a href="#httpCompareCredentials">httpCompareCredentials</a></li> - <li><a href="#httpConnect">httpConnect</a></li> - <li><a href="#httpConnect2">httpConnect2</a></li> - <li><a href="#httpConnectEncrypt">httpConnectEncrypt</a></li> - <li><a href="#httpDecode64">httpDecode64</a></li> - <li><a href="#httpDecode64_2">httpDecode64_2</a></li> - <li><a href="#httpDelete">httpDelete</a></li> - <li><a href="#httpEncode64">httpEncode64</a></li> - <li><a href="#httpEncode64_2">httpEncode64_2</a></li> - <li><a href="#httpEncryption">httpEncryption</a></li> - <li><a href="#httpError">httpError</a></li> - <li><a href="#httpFieldValue">httpFieldValue</a></li> - <li><a href="#httpFlush">httpFlush</a></li> - <li><a href="#httpFlushWrite">httpFlushWrite</a></li> - <li><a href="#httpFreeCredentials">httpFreeCredentials</a></li> - <li><a href="#httpGet">httpGet</a></li> - <li><a href="#httpGetActivity">httpGetActivity</a></li> - <li><a href="#httpGetAddress">httpGetAddress</a></li> - <li><a href="#httpGetAuthString">httpGetAuthString</a></li> - <li><a href="#httpGetBlocking">httpGetBlocking</a></li> - <li><a href="#httpGetContentEncoding">httpGetContentEncoding</a></li> - <li><a href="#httpGetCookie">httpGetCookie</a></li> - <li><a href="#httpGetDateString">httpGetDateString</a></li> - <li><a href="#httpGetDateString2">httpGetDateString2</a></li> - <li><a href="#httpGetDateTime">httpGetDateTime</a></li> - <li><a href="#httpGetEncryption">httpGetEncryption</a></li> - <li><a href="#httpGetExpect">httpGetExpect</a></li> - <li><a href="#httpGetFd">httpGetFd</a></li> - <li><a href="#httpGetField">httpGetField</a></li> - <li><a href="#httpGetHostByName">httpGetHostByName</a></li> - <li><a href="#httpGetHostname">httpGetHostname</a></li> - <li><a href="#httpGetKeepAlive">httpGetKeepAlive</a></li> - <li><a href="#httpGetLength">httpGetLength</a></li> - <li><a href="#httpGetLength2">httpGetLength2</a></li> - <li><a href="#httpGetPending">httpGetPending</a></li> - <li><a href="#httpGetReady">httpGetReady</a></li> - <li><a href="#httpGetRemaining">httpGetRemaining</a></li> - <li><a href="#httpGetState">httpGetState</a></li> - <li><a href="#httpGetStatus">httpGetStatus</a></li> - <li><a href="#httpGetSubField">httpGetSubField</a></li> - <li><a href="#httpGetSubField2">httpGetSubField2</a></li> - <li><a href="#httpGetVersion">httpGetVersion</a></li> - <li><a href="#httpGets">httpGets</a></li> - <li><a href="#httpHead">httpHead</a></li> - <li><a href="#httpInitialize">httpInitialize</a></li> - <li><a href="#httpIsChunked">httpIsChunked</a></li> - <li><a href="#httpIsEncrypted">httpIsEncrypted</a></li> - <li><a href="#httpMD5">httpMD5</a></li> - <li><a href="#httpMD5Final">httpMD5Final</a></li> - <li><a href="#httpMD5String">httpMD5String</a></li> - <li><a href="#httpOptions">httpOptions</a></li> - <li><a href="#httpPeek">httpPeek</a></li> - <li><a href="#httpPost">httpPost</a></li> - <li><a href="#httpPut">httpPut</a></li> - <li><a href="#httpRead">httpRead</a></li> - <li><a href="#httpRead2">httpRead2</a></li> - <li><a href="#httpReadRequest">httpReadRequest</a></li> - <li><a href="#httpReconnect">httpReconnect</a></li> - <li><a href="#httpReconnect2">httpReconnect2</a></li> - <li><a href="#httpResolveHostname">httpResolveHostname</a></li> - <li><a href="#httpSeparate">httpSeparate</a></li> - <li><a href="#httpSeparate2">httpSeparate2</a></li> - <li><a href="#httpSeparateURI">httpSeparateURI</a></li> - <li><a href="#httpSetAuthString">httpSetAuthString</a></li> - <li><a href="#httpSetCookie">httpSetCookie</a></li> - <li><a href="#httpSetCredentials">httpSetCredentials</a></li> - <li><a href="#httpSetDefaultField">httpSetDefaultField</a></li> - <li><a href="#httpSetExpect">httpSetExpect</a></li> - <li><a href="#httpSetField">httpSetField</a></li> - <li><a href="#httpSetKeepAlive">httpSetKeepAlive</a></li> - <li><a href="#httpSetLength">httpSetLength</a></li> - <li><a href="#httpSetTimeout">httpSetTimeout</a></li> - <li><a href="#httpShutdown">httpShutdown</a></li> - <li><a href="#httpStateString">httpStateString</a></li> - <li><a href="#httpStatus">httpStatus</a></li> - <li><a href="#httpTrace">httpTrace</a></li> - <li><a href="#httpURIStatusString">httpURIStatusString</a></li> - <li><a href="#httpUpdate">httpUpdate</a></li> - <li><a href="#httpWait">httpWait</a></li> - <li><a href="#httpWrite">httpWrite</a></li> - <li><a href="#httpWrite2">httpWrite2</a></li> - <li><a href="#httpWriteResponse">httpWriteResponse</a></li> - <li><a href="#ippAddBoolean">ippAddBoolean</a></li> - <li><a href="#ippAddBooleans">ippAddBooleans</a></li> - <li><a href="#ippAddCollection">ippAddCollection</a></li> - <li><a href="#ippAddCollections">ippAddCollections</a></li> - <li><a href="#ippAddDate">ippAddDate</a></li> - <li><a href="#ippAddInteger">ippAddInteger</a></li> - <li><a href="#ippAddIntegers">ippAddIntegers</a></li> - <li><a href="#ippAddOctetString">ippAddOctetString</a></li> - <li><a href="#ippAddOutOfBand">ippAddOutOfBand</a></li> - <li><a href="#ippAddRange">ippAddRange</a></li> - <li><a href="#ippAddRanges">ippAddRanges</a></li> - <li><a href="#ippAddResolution">ippAddResolution</a></li> - <li><a href="#ippAddResolutions">ippAddResolutions</a></li> - <li><a href="#ippAddSeparator">ippAddSeparator</a></li> - <li><a href="#ippAddString">ippAddString</a></li> - <li><a href="#ippAddStringf">ippAddStringf</a></li> - <li><a href="#ippAddStringfv">ippAddStringfv</a></li> - <li><a href="#ippAddStrings">ippAddStrings</a></li> - <li><a href="#ippAttributeString">ippAttributeString</a></li> - <li><a href="#ippContainsInteger">ippContainsInteger</a></li> - <li><a href="#ippContainsString">ippContainsString</a></li> - <li><a href="#ippCopyAttribute">ippCopyAttribute</a></li> - <li><a href="#ippCopyAttributes">ippCopyAttributes</a></li> - <li><a href="#ippCreateRequestedArray">ippCreateRequestedArray</a></li> - <li><a href="#ippDateToTime">ippDateToTime</a></li> - <li><a href="#ippDelete">ippDelete</a></li> - <li><a href="#ippDeleteAttribute">ippDeleteAttribute</a></li> - <li><a href="#ippDeleteValues">ippDeleteValues</a></li> - <li><a href="#ippEnumString">ippEnumString</a></li> - <li><a href="#ippEnumValue">ippEnumValue</a></li> - <li><a href="#ippErrorString">ippErrorString</a></li> - <li><a href="#ippErrorValue">ippErrorValue</a></li> - <li><a href="#ippFindAttribute">ippFindAttribute</a></li> - <li><a href="#ippFindNextAttribute">ippFindNextAttribute</a></li> - <li><a href="#ippFirstAttribute">ippFirstAttribute</a></li> - <li><a href="#ippGetBoolean">ippGetBoolean</a></li> - <li><a href="#ippGetCollection">ippGetCollection</a></li> - <li><a href="#ippGetCount">ippGetCount</a></li> - <li><a href="#ippGetDate">ippGetDate</a></li> - <li><a href="#ippGetGroupTag">ippGetGroupTag</a></li> - <li><a href="#ippGetInteger">ippGetInteger</a></li> - <li><a href="#ippGetName">ippGetName</a></li> - <li><a href="#ippGetOctetString">ippGetOctetString</a></li> - <li><a href="#ippGetOperation">ippGetOperation</a></li> - <li><a href="#ippGetRange">ippGetRange</a></li> - <li><a href="#ippGetRequestId">ippGetRequestId</a></li> - <li><a href="#ippGetResolution">ippGetResolution</a></li> - <li><a href="#ippGetState">ippGetState</a></li> - <li><a href="#ippGetStatusCode">ippGetStatusCode</a></li> - <li><a href="#ippGetString">ippGetString</a></li> - <li><a href="#ippGetValueTag">ippGetValueTag</a></li> - <li><a href="#ippGetVersion">ippGetVersion</a></li> - <li><a href="#ippLength">ippLength</a></li> - <li><a href="#ippNew">ippNew</a></li> - <li><a href="#ippNewRequest">ippNewRequest</a></li> - <li><a href="#ippNewResponse">ippNewResponse</a></li> - <li><a href="#ippNextAttribute">ippNextAttribute</a></li> - <li><a href="#ippOpString">ippOpString</a></li> - <li><a href="#ippOpValue">ippOpValue</a></li> - <li><a href="#ippPort">ippPort</a></li> - <li><a href="#ippRead">ippRead</a></li> - <li><a href="#ippReadFile">ippReadFile</a></li> - <li><a href="#ippReadIO">ippReadIO</a></li> - <li><a href="#ippSetBoolean">ippSetBoolean</a></li> - <li><a href="#ippSetCollection">ippSetCollection</a></li> - <li><a href="#ippSetDate">ippSetDate</a></li> - <li><a href="#ippSetGroupTag">ippSetGroupTag</a></li> - <li><a href="#ippSetInteger">ippSetInteger</a></li> - <li><a href="#ippSetName">ippSetName</a></li> - <li><a href="#ippSetOctetString">ippSetOctetString</a></li> - <li><a href="#ippSetOperation">ippSetOperation</a></li> - <li><a href="#ippSetPort">ippSetPort</a></li> - <li><a href="#ippSetRange">ippSetRange</a></li> - <li><a href="#ippSetRequestId">ippSetRequestId</a></li> - <li><a href="#ippSetResolution">ippSetResolution</a></li> - <li><a href="#ippSetState">ippSetState</a></li> - <li><a href="#ippSetStatusCode">ippSetStatusCode</a></li> - <li><a href="#ippSetString">ippSetString</a></li> - <li><a href="#ippSetStringf">ippSetStringf</a></li> - <li><a href="#ippSetStringfv">ippSetStringfv</a></li> - <li><a href="#ippSetValueTag">ippSetValueTag</a></li> - <li><a href="#ippSetVersion">ippSetVersion</a></li> - <li><a href="#ippStateString">ippStateString</a></li> - <li><a href="#ippTagString">ippTagString</a></li> - <li><a href="#ippTagValue">ippTagValue</a></li> - <li><a href="#ippTimeToDate">ippTimeToDate</a></li> - <li><a href="#ippValidateAttribute">ippValidateAttribute</a></li> - <li><a href="#ippValidateAttributes">ippValidateAttributes</a></li> - <li><a href="#ippWrite">ippWrite</a></li> - <li><a href="#ippWriteFile">ippWriteFile</a></li> - <li><a href="#ippWriteIO">ippWriteIO</a></li> - </ul></li> - <li><a href="#TYPES">Data Types</a><ul class="subcontents"> - <li><a href="#gss_auth_identity_desc">gss_auth_identity_desc</a></li> - <li><a href="#http_addr_t">http_addr_t</a></li> - <li><a href="#http_addrlist_t">http_addrlist_t</a></li> - <li><a href="#http_auth_t">http_auth_t</a></li> - <li><a href="#http_credential_t">http_credential_t</a></li> - <li><a href="#http_encoding_t">http_encoding_t</a></li> - <li><a href="#http_encryption_t">http_encryption_t</a></li> - <li><a href="#http_field_t">http_field_t</a></li> - <li><a href="#http_keepalive_t">http_keepalive_t</a></li> - <li><a href="#http_state_t">http_state_t</a></li> - <li><a href="#http_t">http_t</a></li> - <li><a href="#http_timeout_cb_t">http_timeout_cb_t</a></li> - <li><a href="#http_trust_t">http_trust_t</a></li> - <li><a href="#http_uri_coding_t">http_uri_coding_t</a></li> - <li><a href="#http_uri_status_t">http_uri_status_t</a></li> - <li><a href="#http_version_t">http_version_t</a></li> - <li><a href="#ipp_attribute_t">ipp_attribute_t</a></li> - <li><a href="#ipp_copycb_t">ipp_copycb_t</a></li> - <li><a href="#ipp_dstate_t">ipp_dstate_t</a></li> - <li><a href="#ipp_finish_t">ipp_finish_t</a></li> - <li><a href="#ipp_iocb_t">ipp_iocb_t</a></li> - <li><a href="#ipp_jcollate_t">ipp_jcollate_t</a></li> - <li><a href="#ipp_orient_t">ipp_orient_t</a></li> - <li><a href="#ipp_pstate_t">ipp_pstate_t</a></li> - <li><a href="#ipp_quality_t">ipp_quality_t</a></li> - <li><a href="#ipp_res_t">ipp_res_t</a></li> - <li><a href="#ipp_state_t">ipp_state_t</a></li> - <li><a href="#ipp_t">ipp_t</a></li> - <li><a href="#ipp_uchar_t">ipp_uchar_t</a></li> - </ul></li> - <li><a href="#STRUCTURES">Structures</a><ul class="subcontents"> - <li><a href="#gss_auth_identity">gss_auth_identity</a></li> - <li><a href="#http_addrlist_s">http_addrlist_s</a></li> - <li><a href="#http_credential_s">http_credential_s</a></li> - <li><a href="#pollfd">pollfd</a></li> - </ul></li> - <li><a href="#ENUMERATIONS">Enumerations</a><ul class="subcontents"> - <li><a href="#http_auth_e">http_auth_e</a></li> - <li><a href="#http_encoding_e">http_encoding_e</a></li> - <li><a href="#http_encryption_e">http_encryption_e</a></li> - <li><a href="#http_field_e">http_field_e</a></li> - <li><a href="#http_keepalive_e">http_keepalive_e</a></li> - <li><a href="#http_state_e">http_state_e</a></li> - <li><a href="#http_status_e">http_status_e</a></li> - <li><a href="#http_trust_e">http_trust_e</a></li> - <li><a href="#http_uri_coding_e">http_uri_coding_e</a></li> - <li><a href="#http_uri_status_e">http_uri_status_e</a></li> - <li><a href="#http_version_e">http_version_e</a></li> - <li><a href="#ipp_dstate_e">ipp_dstate_e</a></li> - <li><a href="#ipp_finishings_e">ipp_finishings_e</a></li> - <li><a href="#ipp_jcollate_e">ipp_jcollate_e</a></li> - <li><a href="#ipp_jstate_e">ipp_jstate_e</a></li> - <li><a href="#ipp_op_e">ipp_op_e</a></li> - <li><a href="#ipp_orient_e">ipp_orient_e</a></li> - <li><a href="#ipp_pstate_e">ipp_pstate_e</a></li> - <li><a href="#ipp_quality_e">ipp_quality_e</a></li> - <li><a href="#ipp_res_e">ipp_res_e</a></li> - <li><a href="#ipp_state_e">ipp_state_e</a></li> - <li><a href="#ipp_status_e">ipp_status_e</a></li> - <li><a href="#ipp_tag_e">ipp_tag_e</a></li> - </ul></li> - </ul> - </div> - <div class="body"> -<!-- - HTTP and IPP API introduction for CUPS. - - Copyright 2007-2012 by Apple Inc. - Copyright 1997-2006 by Easy Software Products, all rights reserved. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h2 class='title'><a name='OVERVIEW'>Overview</a></h2> - -<p>The CUPS HTTP and IPP APIs provide low-level access to the HTTP and IPP -protocols and CUPS scheduler. They are typically used by monitoring and -administration programs to perform specific functions not supported by the -high-level CUPS API functions.</p> - -<p>The HTTP APIs use an opaque structure called -<a href='#http_t'><code>http_t</code></a> to manage connections to -a particular HTTP or IPP server. The -<a href='#httpConnectEncrypt'><code>httpConnectEncrypt</code></a> function is -used to create an instance of this structure for a particular server. -The constant <code>CUPS_HTTP_DEFAULT</code> can be used with all of the -<code>cups</code> functions to refer to the default CUPS server - the functions -create a per-thread <a href='#http_t'><code>http_t</code></a> as needed.</p> - -<p>The IPP APIs use two opaque structures for requests (messages sent to the CUPS scheduler) and responses (messages sent back to your application from the scheduler). The <a href='#ipp_t'><code>ipp_t</code></a> type holds a complete request or response and is allocated using the <a href='#ippNew'><code>ippNew</code></a> or <a href='#ippNewRequest'><code>ippNewRequest</code></a> functions and freed using the <a href='#ippDelete'><code>ippDelete</code></a> function.</p> - -<p>The second opaque structure is called <a href='#ipp_attribute_t'><code>ipp_attribute_t</code></a> and holds a single IPP attribute which consists of a group tag (<a href='#ippGetGroupTag'><code>ippGetGroupTag</code></a>), a value type tag (<a href='#ippGetValueTag'><code>ippGetValueTag</code></a>), the attribute name (<a href='#ippGetName'><code>ippGetName</code></a>), and 1 or more values (<a href='#ippGetCount'><code>ippGetCount</code></a>, <a href='#ippGetBoolean'><code>ippGetBoolean</code></a>, <a href='#ippGetCollection'><code>ippGetCollection</code></a>, <a href='#ippGetDate'><code>ippGetDate</code></a>, <a href='#ippGetInteger'><code>ippGetInteger</code></a>, <a href='#ippGetRange'><code>ippGetRange</code></a>, <a href='#ippGetResolution'><code>ippGetResolution</code></a>, and <a href='#ippGetString'><code>ippGetString</code></a>). Attributes are added to an <a href='#ipp_t'><code>ipp_t</code></a> pointer using one of the <code>ippAdd</code> functions. For example, use <a href='#ippAddString'><code>ippAddString</code></a> to add the "printer-uri" and "requesting-user-name" string attributes to a request:</p> - -<pre class='example'> -<a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_GET_JOBS); - -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", - NULL, "ipp://localhost/printers/"); -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", - NULL, cupsUser()); -</pre> - -<p>Once you have created an IPP request, use the <code>cups</code> functions to send the request to and read the response from the server. For example, the <a href='#cupsDoRequest'><code>cupsDoRequest</code></a> function can be used for simple query operations that do not involve files:</p> - -<pre class='example'> -#include <cups/cups.h> - - -<a href='#ipp_t'>ipp_t</a> *<a name='get_jobs'>get_jobs</a>(void) -{ - <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_GET_JOBS); - - <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", - NULL, "ipp://localhost/printers/"); - <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", - NULL, cupsUser()); - - return (<a href='#cupsDoRequest'>cupsDoRequest</a>(CUPS_HTTP_DEFAULT, request, "/")); -} -</pre> - -<p>The <a href='#cupsDoRequest'><code>cupsDoRequest</code></a> function frees the request and returns an IPP response or <code>NULL</code> pointer if the request could not be sent to the server. Once you have a response from the server, you can either use the <a href='#ippFindAttribute'><code>ippFindAttribute</code></a> and <a href='#ippFindNextAttribute'><code>ippFindNextAttribute</code></a> functions to find specific attributes, for example:</p> - -<pre class='example'> -<a href='#ipp_t'>ipp_t</a> *response; -<a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr; - -attr = <a href='#ippFindAttribute'>ippFindAttribute</a>(response, "printer-state", IPP_TAG_ENUM); -</pre> - -<p>You can also walk the list of attributes with a simple <code>for</code> loop like this:</p> - -<pre class='example'> -<a href='#ipp_t'>ipp_t</a> *response; -<a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr; - -for (attr = <a href='#ippFirstAttribute'>ippFirstAttribute</a>(response); attr != NULL; attr = <a href='#ippNextAttribute'>ippNextAttribute</a>(response)) - if (ippGetName(attr) == NULL) - puts("--SEPARATOR--"); - else - puts(ippGetName(attr)); -</pre> - -<p>The <code>for</code> loop approach is normally used when collecting attributes for multiple objects (jobs, printers, etc.) in a response. Attributes with <code>NULL</code> names indicate a separator between the attributes of each object. For example, the following code will list the jobs returned from our previous <a href='#get_jobs'><code>get_jobs</code></a> example code:</p> - -<pre class='example'> -<a href='#ipp_t'>ipp_t</a> *response = <a href='#get_jobs'>get_jobs</a>(); - -if (response != NULL) -{ - <a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr; - const char *attrname; - int job_id = 0; - const char *job_name = NULL; - const char *job_originating_user_name = NULL; - - puts("Job ID Owner Title"); - puts("------ ---------------- ---------------------------------"); - - for (attr = <a href='#ippFirstAttribute'>ippFirstAttribute</a>(response); attr != NULL; attr = <a href='#ippNextAttribute'>ippNextAttribute</a>(response)) - { - /* Attributes without names are separators between jobs */ - attrname = ippGetName(attr); - if (attrname == NULL) - { - if (job_id > 0) - { - if (job_name == NULL) - job_name = "(withheld)"; - - if (job_originating_user_name == NULL) - job_originating_user_name = "(withheld)"; - - printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); - } - - job_id = 0; - job_name = NULL; - job_originating_user_name = NULL; - continue; - } - else if (!strcmp(attrname, "job-id") && ippGetValueTag(attr) == IPP_TAG_INTEGER) - job_id = ippGetInteger(attr, 0); - else if (!strcmp(attrname, "job-name") && ippGetValueTag(attr) == IPP_TAG_NAME) - job_name = ippGetString(attr, 0, NULL); - else if (!strcmp(attrname, "job-originating-user-name") && - ippGetValueTag(attr) == IPP_TAG_NAME) - job_originating_user_name = ippGetString(attr, 0, NULL); - } - - if (job_id > 0) - { - if (job_name == NULL) - job_name = "(withheld)"; - - if (job_originating_user_name == NULL) - job_originating_user_name = "(withheld)"; - - printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); - } -} -</pre> - -<h3><a name='CREATING_URI_STRINGS'>Creating URI Strings</a></h3> - -<p>To ensure proper encoding, the -<a href='#httpAssembleURIf'><code>httpAssembleURIf</code></a> function must be -used to format a "printer-uri" string for all printer-based requests:</p> - -<pre class='example'> -const char *name = "Foo"; -char uri[1024]; -<a href='#ipp_t'>ipp_t</a> *request; - -<a href='#httpAssembleURIf'>httpAssembleURIf</a>(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(), - ippPort(), "/printers/%s", name); -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri); -</pre> - -<h3><a name='SENDING_REQUESTS_WITH_FILES'>Sending Requests with Files</a></h3> - -<p>The <a href='#cupsDoFileRequest'><code>cupsDoFileRequest</code></a> and -<a href='#cupsDoIORequest'><code>cupsDoIORequest</code></a> functions are -used for requests involving files. The -<a href='#cupsDoFileRequest'><code>cupsDoFileRequest</code></a> function -attaches the named file to a request and is typically used when sending a print -file or changing a printer's PPD file:</p> - -<pre class='example'> -const char *filename = "/usr/share/cups/data/testprint.ps"; -const char *name = "Foo"; -char uri[1024]; -char resource[1024]; -<a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_PRINT_JOB); -<a href='#ipp_t'>ipp_t</a> *response; - -/* Use httpAssembleURIf for the printer-uri string */ -<a href='#httpAssembleURIf'>httpAssembleURIf</a>(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(), - ippPort(), "/printers/%s", name); -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri); -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", - NULL, cupsUser()); -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name", - NULL, "testprint.ps"); - -/* Use snprintf for the resource path */ -snprintf(resource, sizeof(resource), "/printers/%s", name); - -response = <a href='#cupsDoFileRequest'>cupsDoFileRequest</a>(CUPS_HTTP_DEFAULT, request, resource, filename); -</pre> - -<p>The <a href='#cupsDoIORequest'><code>cupsDoIORequest</code></a> function -optionally attaches a file to the request and optionally saves a file in the -response from the server. It is used when using a pipe for the request -attachment or when using a request that returns a file, currently only -<code>CUPS_GET_DOCUMENT</code> and <code>CUPS_GET_PPD</code>. For example, -the following code will download the PPD file for the sample HP LaserJet -printer driver:</p> - -<pre class='example'> -char tempfile[1024]; -int tempfd; -<a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD); -<a href='#ipp_t'>ipp_t</a> *response; - -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", - NULL, "laserjet.ppd"); - -tempfd = cupsTempFd(tempfile, sizeof(tempfile)); - -response = <a href='#cupsDoIORequest'>cupsDoIORequest</a>(CUPS_HTTP_DEFAULT, request, "/", -1, tempfd); -</pre> - -<p>The example passes <code>-1</code> for the input file descriptor to specify -that no file is to be attached to the request. The PPD file attached to the -response is written to the temporary file descriptor we created using the -<code>cupsTempFd</code> function.</p> - -<h3><a name='ASYNCHRONOUS_REQUEST_PROCESSING'>Asynchronous Request Processing</a></h3> - -<p>The <a href='#cupsSendRequest'><code>cupsSendRequest</code></a> and -<a href='#cupsGetResponse'><code>cupsGetResponse</code></a> support -asynchronous communications with the server. Unlike the other request -functions, the IPP request is not automatically freed, so remember to -free your request with the <a href='#ippDelete'><code>ippDelete</code></a> -function.</p> - -<p>File data is attached to the request using the -<a href='#cupsWriteRequestData'><code>cupsWriteRequestData</code></a> -function, while file data returned from the server is read using the -<a href='#cupsReadResponseData'><code>cupsReadResponseData</code></a> -function. We can rewrite the previous <code>CUPS_GET_PPD</code> example -to use the asynchronous functions quite easily:</p> - -<pre class='example'> -char tempfile[1024]; -int tempfd; -<a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD); -<a href='#ipp_t'>ipp_t</a> *response; - -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", - NULL, "laserjet.ppd"); - -tempfd = cupsTempFd(tempfile, sizeof(tempfile)); - -if (<a href='#cupsSendRequest'>cupsSendRequest</a>(CUPS_HTTP_DEFAULT, request, "/") == HTTP_CONTINUE) -{ - response = <a href='#cupsGetResponse'>cupsGetResponse</a>(CUPS_HTTP_DEFAULT, "/"); - - if (response != NULL) - { - ssize_t bytes; - char buffer[8192]; - - while ((bytes = <a href='#cupsReadResponseData'>cupsReadResponseData</a>(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0) - write(tempfd, buffer, bytes); - } -} - -/* Free the request! */ -<a href='#ippDelete'>ippDelete</a>(request); -</pre> - -<p>The <a href='#cupsSendRequest'><code>cupsSendRequest</code></a> function -returns the initial HTTP request status, typically either -<code>HTTP_CONTINUE</code> or <code>HTTP_UNAUTHORIZED</code>. The latter status -is returned when the request requires authentication of some sort. The -<a href='#cupsDoAuthentication'><code>cupsDoAuthentication</code></a> function -must be called when your see <code>HTTP_UNAUTHORIZED</code> and the request -re-sent. We can add authentication support to our example code by using a -<code>do ... while</code> loop:</p> - -<pre class='example'> -char tempfile[1024]; -int tempfd; -<a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD); -<a href='#ipp_t'>ipp_t</a> *response; -http_status_t status; - -<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", - NULL, "laserjet.ppd"); - -tempfd = cupsTempFd(tempfile, sizeof(tempfile)); - -/* Loop for authentication */ -do -{ - status = <a href='#cupsSendRequest'>cupsSendRequest</a>(CUPS_HTTP_DEFAULT, request, "/"); - - if (status == HTTP_UNAUTHORIZED) - { - /* Try to authenticate, break out of the loop if that fails */ - if (<a href='#cupsDoAuthentication'>cupsDoAuthentication</a>(CUPS_HTTP_DEFAULT, "POST", "/")) - break; - } -} -while (status != HTTP_CONTINUE && status != HTTP_UNAUTHORIZED); - -if (status == HTTP_CONTINUE) -{ - response = <a href='#cupsGetResponse'>cupsGetResponse</a>(CUPS_HTTP_DEFAULT, "/"); - - if (response != NULL) - { - ssize_t bytes; - char buffer[8192]; - - while ((bytes = <a href='#cupsReadResponseData'>cupsReadResponseData</a>(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0) - write(tempfd, buffer, bytes); - } -} - -/* Free the request! */ -<a href='#ippDelete'>ippDelete</a>(request); -</pre> - <h2 class="title"><a id="FUNCTIONS">Functions</a></h2> -<h3 class="function"><span class="info"> CUPS 1.1.20/macOS 10.4 </span><a id="cupsDoAuthentication">cupsDoAuthentication</a></h3> - <p class="description">Authenticate a request.</p> -<p class="code"> -int cupsDoAuthentication (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *method,<br /> -    const char *resource<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>method</dt> - <dd class="description">Request method ("GET", "POST", "PUT")</dd> -<dt>resource</dt> - <dd class="description">Resource path</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, -1 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function should be called in response to a <code>HTTP_STATUS_UNAUTHORIZED</code> -status, prior to resubmitting your request. - -</p> -<h3 class="function"><a id="cupsDoFileRequest">cupsDoFileRequest</a></h3> - <p class="description">Do an IPP request with a file.</p> -<p class="code"> -<a href="#ipp_t">ipp_t</a> *cupsDoFileRequest (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#ipp_t">ipp_t</a> *request,<br /> -    const char *resource,<br /> -    const char *filename<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>request</dt> - <dd class="description">IPP request</dd> -<dt>resource</dt> - <dd class="description">HTTP resource for POST</dd> -<dt>filename</dt> - <dd class="description">File to send or <code>NULL</code> for none</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Response data</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function sends the IPP request and attached file to the specified -server, retrying and authenticating as necessary. The request is freed with -<a href="#ippDelete"><code>ippDelete</code></a>.</p> -<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsDoIORequest">cupsDoIORequest</a></h3> - <p class="description">Do an IPP request with file descriptors.</p> -<p class="code"> -<a href="#ipp_t">ipp_t</a> *cupsDoIORequest (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#ipp_t">ipp_t</a> *request,<br /> -    const char *resource,<br /> -    int infile,<br /> -    int outfile<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>request</dt> - <dd class="description">IPP request</dd> -<dt>resource</dt> - <dd class="description">HTTP resource for POST</dd> -<dt>infile</dt> - <dd class="description">File to read from or -1 for none</dd> -<dt>outfile</dt> - <dd class="description">File to write to or -1 for none</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Response data</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function sends the IPP request with the optional input file "infile" to -the specified server, retrying and authenticating as necessary. The request -is freed with <a href="#ippDelete"><code>ippDelete</code></a>.<br> -<br> -If "infile" is a valid file descriptor, <code>cupsDoIORequest</code> copies -all of the data from the file after the IPP request message.<br> -<br> -If "outfile" is a valid file descriptor, <code>cupsDoIORequest</code> copies -all of the data after the IPP response message to the file. - -</p> -<h3 class="function"><a id="cupsDoRequest">cupsDoRequest</a></h3> - <p class="description">Do an IPP request.</p> -<p class="code"> -<a href="#ipp_t">ipp_t</a> *cupsDoRequest (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#ipp_t">ipp_t</a> *request,<br /> -    const char *resource<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>request</dt> - <dd class="description">IPP request</dd> -<dt>resource</dt> - <dd class="description">HTTP resource for POST</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Response data</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function sends the IPP request to the specified server, retrying -and authenticating as necessary. The request is freed with <a href="#ippDelete"><code>ippDelete</code></a>.</p> -<h3 class="function"><a id="cupsEncodeOptions">cupsEncodeOptions</a></h3> - <p class="description">Encode printer options into IPP attributes.</p> -<p class="code"> -void cupsEncodeOptions (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    int num_options,<br /> -    cups_option_t *options<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">Request to add to</dd> -<dt>num_options</dt> - <dd class="description">Number of options</dd> -<dt>options</dt> - <dd class="description">Options</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function adds operation, job, and then subscription attributes, -in that order. Use the cupsEncodeOptions2() function to add attributes -for a single group.</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsEncodeOptions2">cupsEncodeOptions2</a></h3> - <p class="description">Encode printer options into IPP attributes for a group.</p> -<p class="code"> -void cupsEncodeOptions2 (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    int num_options,<br /> -    cups_option_t *options,<br /> -    ipp_tag_t group_tag<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">Request to add to</dd> -<dt>num_options</dt> - <dd class="description">Number of options</dd> -<dt>options</dt> - <dd class="description">Options</dd> -<dt>group_tag</dt> - <dd class="description">Group to encode</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function only adds attributes for a single group. Call this -function multiple times for each group, or use cupsEncodeOptions() -to add the standard groups. - -</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsGetDevices">cupsGetDevices</a></h3> - <p class="description">Get available printer devices.</p> -<p class="code"> -ipp_status_t cupsGetDevices (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    int timeout,<br /> -    const char *include_schemes,<br /> -    const char *exclude_schemes,<br /> -    cups_device_cb_t callback,<br /> -    void *user_data<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>timeout</dt> - <dd class="description">Timeout in seconds or <code>CUPS_TIMEOUT_DEFAULT</code></dd> -<dt>include_schemes</dt> - <dd class="description">Comma-separated URI schemes to include or <code>CUPS_INCLUDE_ALL</code></dd> -<dt>exclude_schemes</dt> - <dd class="description">Comma-separated URI schemes to exclude or <code>CUPS_EXCLUDE_NONE</code></dd> -<dt>callback</dt> - <dd class="description">Callback function</dd> -<dt>user_data</dt> - <dd class="description">User data pointer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Request status - <code>IPP_OK</code> on success.</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function sends a CUPS-Get-Devices request and streams the discovered -devices to the specified callback function. The "timeout" parameter controls -how long the request lasts, while the "include_schemes" and "exclude_schemes" -parameters provide comma-delimited lists of backends to include or omit from -the request respectively. - -</p> -<h3 class="function"><span class="info"> CUPS 1.1.20/macOS 10.4 </span><a id="cupsGetFd">cupsGetFd</a></h3> - <p class="description">Get a file from the server.</p> -<p class="code"> -http_status_t cupsGetFd (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *resource,<br /> -    int fd<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>resource</dt> - <dd class="description">Resource name</dd> -<dt>fd</dt> - <dd class="description">File descriptor</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">HTTP status</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function returns <code>HTTP_STATUS_OK</code> when the file is successfully retrieved. - -</p> -<h3 class="function"><span class="info"> CUPS 1.1.20/macOS 10.4 </span><a id="cupsGetFile">cupsGetFile</a></h3> - <p class="description">Get a file from the server.</p> -<p class="code"> -http_status_t cupsGetFile (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *resource,<br /> -    const char *filename<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>resource</dt> - <dd class="description">Resource name</dd> -<dt>filename</dt> - <dd class="description">Filename</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">HTTP status</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function returns <code>HTTP_STATUS_OK</code> when the file is successfully retrieved. - -</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsGetResponse">cupsGetResponse</a></h3> - <p class="description">Get a response to an IPP request.</p> -<p class="code"> -<a href="#ipp_t">ipp_t</a> *cupsGetResponse (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *resource<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>resource</dt> - <dd class="description">HTTP resource for POST</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Response or <code>NULL</code> on HTTP error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Use this function to get the response for an IPP request sent using -<a href="#cupsSendRequest"><code>cupsSendRequest</code></a>. For requests that return additional data, use -<a href="#cupsReadResponseData"><code>cupsReadResponseData</code></a> after getting a successful response, -otherwise call <a href="#httpFlush"><code>httpFlush</code></a> to complete the response processing. - -</p> -<h3 class="function"><a id="cupsLastError">cupsLastError</a></h3> - <p class="description">Return the last IPP status code received on the current -thread.</p> -<p class="code"> -ipp_status_t cupsLastError (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">IPP status code from last request</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsLastErrorString">cupsLastErrorString</a></h3> - <p class="description">Return the last IPP status-message received on the -current thread.</p> -<p class="code"> -const char *cupsLastErrorString (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">status-message text from last request</p> -<h3 class="function"><span class="info"> CUPS 1.1.20/macOS 10.4 </span><a id="cupsPutFd">cupsPutFd</a></h3> - <p class="description">Put a file on the server.</p> -<p class="code"> -http_status_t cupsPutFd (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *resource,<br /> -    int fd<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>resource</dt> - <dd class="description">Resource name</dd> -<dt>fd</dt> - <dd class="description">File descriptor</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">HTTP status</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function returns <code>HTTP_STATUS_CREATED</code> when the file is stored -successfully. - -</p> -<h3 class="function"><span class="info"> CUPS 1.1.20/macOS 10.4 </span><a id="cupsPutFile">cupsPutFile</a></h3> - <p class="description">Put a file on the server.</p> -<p class="code"> -http_status_t cupsPutFile (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *resource,<br /> -    const char *filename<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>resource</dt> - <dd class="description">Resource name</dd> -<dt>filename</dt> - <dd class="description">Filename</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">HTTP status</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function returns <code>HTTP_CREATED</code> when the file is stored -successfully. - -</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsReadResponseData">cupsReadResponseData</a></h3> - <p class="description">Read additional data after the IPP response.</p> -<p class="code"> -ssize_t cupsReadResponseData (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    char *buffer,<br /> -    size_t length<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>buffer</dt> - <dd class="description">Buffer to use</dd> -<dt>length</dt> - <dd class="description">Number of bytes to read</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Bytes read, 0 on EOF, -1 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is used after <a href="#cupsGetResponse"><code>cupsGetResponse</code></a> to read the PPD or document -files from <code>CUPS_GET_PPD</code> and <code>CUPS_GET_DOCUMENT</code> requests, -respectively. - -</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsSendRequest">cupsSendRequest</a></h3> - <p class="description">Send an IPP request.</p> -<p class="code"> -http_status_t cupsSendRequest (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#ipp_t">ipp_t</a> *request,<br /> -    const char *resource,<br /> -    size_t length<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>request</dt> - <dd class="description">IPP request</dd> -<dt>resource</dt> - <dd class="description">Resource path</dd> -<dt>length</dt> - <dd class="description">Length of data to follow or <code>CUPS_LENGTH_VARIABLE</code></dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Initial HTTP status</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write any additional data (document, PPD -file, etc.) for the request, <a href="#cupsGetResponse"><code>cupsGetResponse</code></a> to get the IPP response, -and <a href="#cupsReadResponseData"><code>cupsReadResponseData</code></a> to read any additional data following the -response. Only one request can be sent/queued at a time per <code>http_t</code> -connection.<br> -<br> -Returns the initial HTTP status code, which will be <code>HTTP_STATUS_CONTINUE</code> -on a successful send of the request.<br> -<br> -Note: Unlike <a href="#cupsDoFileRequest"><code>cupsDoFileRequest</code></a>, <a href="#cupsDoIORequest"><code>cupsDoIORequest</code></a>, and -<a href="#cupsDoRequest"><code>cupsDoRequest</code></a>, the request is NOT freed with <a href="#ippDelete"><code>ippDelete</code></a>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsWriteRequestData">cupsWriteRequestData</a></h3> - <p class="description">Write additional data after an IPP request.</p> -<p class="code"> -http_status_t cupsWriteRequestData (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *buffer,<br /> -    size_t length<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> -<dt>buffer</dt> - <dd class="description">Bytes to write</dd> -<dt>length</dt> - <dd class="description">Number of bytes to write</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description"><code>HTTP_STATUS_CONTINUE</code> if OK or HTTP status on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is used after <a href="#cupsSendRequest"><code>cupsSendRequest</code></a> to provide a PPD and -after <a href="#cupsStartDocument"><code>cupsStartDocument</code></a> to provide a document file. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpAcceptConnection">httpAcceptConnection</a></h3> - <p class="description">Accept a new HTTP client connection from the -specified listening socket.</p> -<p class="code"> -<a href="#http_t">http_t</a> *httpAcceptConnection (<br /> -    int fd,<br /> -    int blocking<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fd</dt> - <dd class="description">Listen socket file descriptor</dd> -<dt>blocking</dt> - <dd class="description">1 if the connection should be -blocking, 0 otherwise</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">HTTP connection or <code>NULL</code></p> -<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="httpAddCredential">httpAddCredential</a></h3> - <p class="description">Allocates and adds a single credential to an array.</p> -<p class="code"> -int httpAddCredential (<br /> -    cups_array_t *credentials,<br /> -    const void *data,<br /> -    size_t datalen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>credentials</dt> - <dd class="description">Credentials array</dd> -<dt>data</dt> - <dd class="description">PEM-encoded X.509 data</dd> -<dt>datalen</dt> - <dd class="description">Length of data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, -1 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Use <code>cupsArrayNew(NULL, NULL)</code> to create a credentials array. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrAny">httpAddrAny</a></h3> - <p class="description">Check for the "any" address.</p> -<p class="code"> -int httpAddrAny (<br /> -    const <a href="#http_addr_t">http_addr_t</a> *addr<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>addr</dt> - <dd class="description">Address to check</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if "any", 0 otherwise</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpAddrClose">httpAddrClose</a></h3> - <p class="description">Close a socket created by <a href="#httpAddrConnect"><code>httpAddrConnect</code></a> or -<a href="#httpAddrListen"><code>httpAddrListen</code></a>.</p> -<p class="code"> -int httpAddrClose (<br /> -    <a href="#http_addr_t">http_addr_t</a> *addr,<br /> -    int fd<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>addr</dt> - <dd class="description">Listen address or <code>NULL</code></dd> -<dt>fd</dt> - <dd class="description">Socket file descriptor</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, -1 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Pass <code>NULL</code> for sockets created with <a href="#httpAddrConnect"><code>httpAddrConnect</code></a> and the -listen address for sockets created with <a href="#httpAddrListen"><code>httpAddrListen</code></a>. This will -ensure that domain sockets are removed when closed. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrEqual">httpAddrEqual</a></h3> - <p class="description">Compare two addresses.</p> -<p class="code"> -int httpAddrEqual (<br /> -    const <a href="#http_addr_t">http_addr_t</a> *addr1,<br /> -    const <a href="#http_addr_t">http_addr_t</a> *addr2<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>addr1</dt> - <dd class="description">First address</dd> -<dt>addr2</dt> - <dd class="description">Second address</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if equal, 0 if not</p> -<h3 class="function"><a id="httpAddrFamily">httpAddrFamily</a></h3> - <p class="description">Get the address family of an address.</p> -<p class="code"> -int httpAddrFamily (<br /> -    <a href="#http_addr_t">http_addr_t</a> *addr<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>addr</dt> - <dd class="description">Address</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Address family</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrLength">httpAddrLength</a></h3> - <p class="description">Return the length of the address in bytes.</p> -<p class="code"> -int httpAddrLength (<br /> -    const <a href="#http_addr_t">http_addr_t</a> *addr<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>addr</dt> - <dd class="description">Address</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Length in bytes</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpAddrListen">httpAddrListen</a></h3> - <p class="description">Create a listening socket bound to the specified -address and port.</p> -<p class="code"> -int httpAddrListen (<br /> -    <a href="#http_addr_t">http_addr_t</a> *addr,<br /> -    int port<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>addr</dt> - <dd class="description">Address to bind to</dd> -<dt>port</dt> - <dd class="description">Port number to bind to</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Socket or -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrLocalhost">httpAddrLocalhost</a></h3> - <p class="description">Check for the local loopback address.</p> -<p class="code"> -int httpAddrLocalhost (<br /> -    const <a href="#http_addr_t">http_addr_t</a> *addr<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>addr</dt> - <dd class="description">Address to check</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if local host, 0 otherwise</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrLookup">httpAddrLookup</a></h3> - <p class="description">Lookup the hostname associated with the address.</p> -<p class="code"> -char *httpAddrLookup (<br /> -    const <a href="#http_addr_t">http_addr_t</a> *addr,<br /> -    char *name,<br /> -    int namelen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>addr</dt> - <dd class="description">Address to lookup</dd> -<dt>name</dt> - <dd class="description">Host name buffer</dd> -<dt>namelen</dt> - <dd class="description">Size of name buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Host name</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpAddrPort">httpAddrPort</a></h3> - <p class="description">Get the port number associated with an address.</p> -<p class="code"> -int httpAddrPort (<br /> -    <a href="#http_addr_t">http_addr_t</a> *addr<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>addr</dt> - <dd class="description">Address</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Port number</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrString">httpAddrString</a></h3> - <p class="description">Convert an address to a numeric string.</p> -<p class="code"> -char *httpAddrString (<br /> -    const <a href="#http_addr_t">http_addr_t</a> *addr,<br /> -    char *s,<br /> -    int slen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>addr</dt> - <dd class="description">Address to convert</dd> -<dt>s</dt> - <dd class="description">String buffer</dd> -<dt>slen</dt> - <dd class="description">Length of string</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Numeric address string</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAssembleURI">httpAssembleURI</a></h3> - <p class="description">Assemble a uniform resource identifier from its -components.</p> -<p class="code"> -<a href="#http_uri_status_t">http_uri_status_t</a> httpAssembleURI (<br /> -    <a href="#http_uri_coding_t">http_uri_coding_t</a> encoding,<br /> -    char *uri,<br /> -    int urilen,<br /> -    const char *scheme,<br /> -    const char *username,<br /> -    const char *host,<br /> -    int port,<br /> -    const char *resource<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>encoding</dt> - <dd class="description">Encoding flags</dd> -<dt>uri</dt> - <dd class="description">URI buffer</dd> -<dt>urilen</dt> - <dd class="description">Size of URI buffer</dd> -<dt>scheme</dt> - <dd class="description">Scheme name</dd> -<dt>username</dt> - <dd class="description">Username</dd> -<dt>host</dt> - <dd class="description">Hostname or address</dd> -<dt>port</dt> - <dd class="description">Port number</dd> -<dt>resource</dt> - <dd class="description">Resource</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">URI status</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function escapes reserved characters in the URI depending on the -value of the "encoding" argument. You should use this function in -place of traditional string functions whenever you need to create a -URI string. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAssembleURIf">httpAssembleURIf</a></h3> - <p class="description">Assemble a uniform resource identifier from its -components with a formatted resource.</p> -<p class="code"> -<a href="#http_uri_status_t">http_uri_status_t</a> httpAssembleURIf (<br /> -    <a href="#http_uri_coding_t">http_uri_coding_t</a> encoding,<br /> -    char *uri,<br /> -    int urilen,<br /> -    const char *scheme,<br /> -    const char *username,<br /> -    const char *host,<br /> -    int port,<br /> -    const char *resourcef,<br /> -    ...<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>encoding</dt> - <dd class="description">Encoding flags</dd> -<dt>uri</dt> - <dd class="description">URI buffer</dd> -<dt>urilen</dt> - <dd class="description">Size of URI buffer</dd> -<dt>scheme</dt> - <dd class="description">Scheme name</dd> -<dt>username</dt> - <dd class="description">Username</dd> -<dt>host</dt> - <dd class="description">Hostname or address</dd> -<dt>port</dt> - <dd class="description">Port number</dd> -<dt>resourcef</dt> - <dd class="description">Printf-style resource</dd> -<dt>...</dt> - <dd class="description">Additional arguments as needed</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">URI status</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function creates a formatted version of the resource string -argument "resourcef" and escapes reserved characters in the URI -depending on the value of the "encoding" argument. You should use -this function in place of traditional string functions whenever -you need to create a URI string. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpAssembleUUID">httpAssembleUUID</a></h3> - <p class="description">Assemble a name-based UUID URN conforming to RFC 4122.</p> -<p class="code"> -char *httpAssembleUUID (<br /> -    const char *server,<br /> -    int port,<br /> -    const char *name,<br /> -    int number,<br /> -    char *buffer,<br /> -    size_t bufsize<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>server</dt> - <dd class="description">Server name</dd> -<dt>port</dt> - <dd class="description">Port number</dd> -<dt>name</dt> - <dd class="description">Object name or NULL</dd> -<dt>number</dt> - <dd class="description">Object number or 0</dd> -<dt>buffer</dt> - <dd class="description">String buffer</dd> -<dt>bufsize</dt> - <dd class="description">Size of buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">UUID string</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function creates a unique 128-bit identifying number using the server -name, port number, random data, and optionally an object name and/or object -number. The result is formatted as a UUID URN as defined in RFC 4122.<br> -<br> -The buffer needs to be at least 46 bytes in size. - -</p> -<h3 class="function"><a id="httpBlocking">httpBlocking</a></h3> - <p class="description">Set blocking/non-blocking behavior on a connection.</p> -<p class="code"> -void httpBlocking (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    int b<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>b</dt> - <dd class="description">1 = blocking, 0 = non-blocking</dd> -</dl> -<h3 class="function"><a id="httpCheck">httpCheck</a></h3> - <p class="description">Check to see if there is a pending response from the server.</p> -<p class="code"> -int httpCheck (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 = no data, 1 = data available</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="httpClearCookie">httpClearCookie</a></h3> - <p class="description">Clear the cookie value(s).</p> -<p class="code"> -void httpClearCookie (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h3 class="function"><a id="httpClearFields">httpClearFields</a></h3> - <p class="description">Clear HTTP request fields.</p> -<p class="code"> -void httpClearFields (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h3 class="function"><a id="httpClose">httpClose</a></h3> - <p class="description">Close an HTTP connection.</p> -<p class="code"> -void httpClose (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpCompareCredentials">httpCompareCredentials</a></h3> - <p class="description">Compare two sets of X.509 credentials.</p> -<p class="code"> -int httpCompareCredentials (<br /> -    cups_array_t *cred1,<br /> -    cups_array_t *cred2<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>cred1</dt> - <dd class="description">First set of X.509 credentials</dd> -<dt>cred2</dt> - <dd class="description">Second set of X.509 credentials</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if they match, 0 if they do not</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpConnect">httpConnect</a></h3> - <p class="description">Connect to a HTTP server.</p> -<p class="code"> -<a href="#http_t">http_t</a> *httpConnect (<br /> -    const char *host,<br /> -    int port<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>host</dt> - <dd class="description">Host to connect to</dd> -<dt>port</dt> - <dd class="description">Port number</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New HTTP connection</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is deprecated - use <a href="#httpConnect2"><code>httpConnect2</code></a> instead. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpConnect2">httpConnect2</a></h3> - <p class="description">Connect to a HTTP server.</p> -<p class="code"> -<a href="#http_t">http_t</a> *httpConnect2 (<br /> -    const char *host,<br /> -    int port,<br /> -    <a href="#http_addrlist_t">http_addrlist_t</a> *addrlist,<br /> -    int family,<br /> -    <a href="#http_encryption_t">http_encryption_t</a> encryption,<br /> -    int blocking,<br /> -    int msec,<br /> -    int *cancel<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>host</dt> - <dd class="description">Host to connect to</dd> -<dt>port</dt> - <dd class="description">Port number</dd> -<dt>addrlist</dt> - <dd class="description">List of addresses or NULL to lookup</dd> -<dt>family</dt> - <dd class="description">Address family to use or <code>AF_UNSPEC</code> for any</dd> -<dt>encryption</dt> - <dd class="description">Type of encryption to use</dd> -<dt>blocking</dt> - <dd class="description">1 for blocking connection, 0 for non-blocking</dd> -<dt>msec</dt> - <dd class="description">Connection timeout in milliseconds, 0 means don't connect</dd> -<dt>cancel</dt> - <dd class="description">Pointer to "cancel" variable</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New HTTP connection</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpConnectEncrypt">httpConnectEncrypt</a></h3> - <p class="description">Connect to a HTTP server using encryption.</p> -<p class="code"> -<a href="#http_t">http_t</a> *httpConnectEncrypt (<br /> -    const char *host,<br /> -    int port,<br /> -    <a href="#http_encryption_t">http_encryption_t</a> encryption<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>host</dt> - <dd class="description">Host to connect to</dd> -<dt>port</dt> - <dd class="description">Port number</dd> -<dt>encryption</dt> - <dd class="description">Type of encryption to use</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New HTTP connection</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is now deprecated. Please use the <a href="#httpConnect2"><code>httpConnect2</code></a> function -instead. - -</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpDecode64">httpDecode64</a></h3> - <p class="description">Base64-decode a string.</p> -<p class="code"> -char *httpDecode64 (<br /> -    char *out,<br /> -    const char *in<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>out</dt> - <dd class="description">String to write to</dd> -<dt>in</dt> - <dd class="description">String to read from</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Decoded string</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is deprecated. Use the httpDecode64_2() function instead -which provides buffer length arguments. - -</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="httpDecode64_2">httpDecode64_2</a></h3> - <p class="description">Base64-decode a string.</p> -<p class="code"> -char *httpDecode64_2 (<br /> -    char *out,<br /> -    int *outlen,<br /> -    const char *in<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>out</dt> - <dd class="description">String to write to</dd> -<dt>outlen</dt> - <dd class="description">Size of output string</dd> -<dt>in</dt> - <dd class="description">String to read from</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Decoded string</p> -<h3 class="function"><a id="httpDelete">httpDelete</a></h3> - <p class="description">Send a DELETE request to the server.</p> -<p class="code"> -int httpDelete (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *uri<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>uri</dt> - <dd class="description">URI to delete</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of call (0 = success)</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpEncode64">httpEncode64</a></h3> - <p class="description">Base64-encode a string.</p> -<p class="code"> -char *httpEncode64 (<br /> -    char *out,<br /> -    const char *in<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>out</dt> - <dd class="description">String to write to</dd> -<dt>in</dt> - <dd class="description">String to read from</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Encoded string</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is deprecated. Use the httpEncode64_2() function instead -which provides buffer length arguments. - -</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="httpEncode64_2">httpEncode64_2</a></h3> - <p class="description">Base64-encode a string.</p> -<p class="code"> -char *httpEncode64_2 (<br /> -    char *out,<br /> -    int outlen,<br /> -    const char *in,<br /> -    int inlen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>out</dt> - <dd class="description">String to write to</dd> -<dt>outlen</dt> - <dd class="description">Size of output string</dd> -<dt>in</dt> - <dd class="description">String to read from</dd> -<dt>inlen</dt> - <dd class="description">Size of input string</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Encoded string</p> -<h3 class="function"><a id="httpEncryption">httpEncryption</a></h3> - <p class="description">Set the required encryption on the link.</p> -<p class="code"> -int httpEncryption (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#http_encryption_t">http_encryption_t</a> e<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>e</dt> - <dd class="description">New encryption preference</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">-1 on error, 0 on success</p> -<h3 class="function"><a id="httpError">httpError</a></h3> - <p class="description">Get the last error on a connection.</p> -<p class="code"> -int httpError (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Error code (errno) value</p> -<h3 class="function"><a id="httpFieldValue">httpFieldValue</a></h3> - <p class="description">Return the HTTP field enumeration value for a field -name.</p> -<p class="code"> -<a href="#http_field_t">http_field_t</a> httpFieldValue (<br /> -    const char *name<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">String name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Field index</p> -<h3 class="function"><a id="httpFlush">httpFlush</a></h3> - <p class="description">Flush data from a HTTP connection.</p> -<p class="code"> -void httpFlush (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpFlushWrite">httpFlushWrite</a></h3> - <p class="description">Flush data in write buffer.</p> -<p class="code"> -int httpFlushWrite (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Bytes written or -1 on error</p> -<h3 class="function"><a id="httpFreeCredentials">httpFreeCredentials</a></h3> - <p class="description">Free an array of credentials.</p> -<p class="code"> -void httpFreeCredentials (<br /> -    cups_array_t *credentials<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>credentials</dt> - <dd class="description">Array of credentials</dd> -</dl> -<h3 class="function"><a id="httpGet">httpGet</a></h3> - <p class="description">Send a GET request to the server.</p> -<p class="code"> -int httpGet (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *uri<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>uri</dt> - <dd class="description">URI to get</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of call (0 = success)</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetActivity">httpGetActivity</a></h3> - <p class="description">Get the most recent activity for a connection.</p> -<p class="code"> -time_t httpGetActivity (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Time of last read or write</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The return value is the UNIX time of the last read or write. - -</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetAddress">httpGetAddress</a></h3> - <p class="description">Get the address of the connected peer of a connection.</p> -<p class="code"> -<a href="#http_addr_t">http_addr_t</a> *httpGetAddress (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Connected address or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Returns <code>NULL</code> if the socket is currently unconnected. - -</p> -<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="httpGetAuthString">httpGetAuthString</a></h3> - <p class="description">Get the current authorization string.</p> -<p class="code"> -char *httpGetAuthString (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Authorization string</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The authorization string is set by cupsDoAuthentication() and -httpSetAuthString(). Use httpGetAuthString() to retrieve the -string to use with httpSetField() for the HTTP_FIELD_AUTHORIZATION -value. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetBlocking">httpGetBlocking</a></h3> - <p class="description">Get the blocking/non-block state of a connection.</p> -<p class="code"> -int httpGetBlocking (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if blocking, 0 if non-blocking</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpGetContentEncoding">httpGetContentEncoding</a></h3> - <p class="description">Get a common content encoding, if any, between -the client and server.</p> -<p class="code"> -const char *httpGetContentEncoding (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Content-Coding value or -<code>NULL</code> for the identity -coding.</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function uses the value of the Accepts-Encoding HTTP header and must be -called after receiving a response from the server or a request from the -client. The value returned can be use in subsequent requests (for clients) -or in the response (for servers) in order to compress the content stream. - -</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="httpGetCookie">httpGetCookie</a></h3> - <p class="description">Get any cookie data from the response.</p> -<p class="code"> -const char *httpGetCookie (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Cookie data or NULL</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpGetDateString">httpGetDateString</a></h3> - <p class="description">Get a formatted date/time string from a time value.</p> -<p class="code"> -const char *httpGetDateString (<br /> -    time_t t<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>t</dt> - <dd class="description">UNIX time</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Date/time string</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetDateString2">httpGetDateString2</a></h3> - <p class="description">Get a formatted date/time string from a time value.</p> -<p class="code"> -const char *httpGetDateString2 (<br /> -    time_t t,<br /> -    char *s,<br /> -    int slen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>t</dt> - <dd class="description">UNIX time</dd> -<dt>s</dt> - <dd class="description">String buffer</dd> -<dt>slen</dt> - <dd class="description">Size of string buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Date/time string</p> -<h3 class="function"><a id="httpGetDateTime">httpGetDateTime</a></h3> - <p class="description">Get a time value from a formatted date/time string.</p> -<p class="code"> -time_t httpGetDateTime (<br /> -    const char *s<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>s</dt> - <dd class="description">Date/time string</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">UNIX time</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetEncryption">httpGetEncryption</a></h3> - <p class="description">Get the current encryption mode of a connection.</p> -<p class="code"> -<a href="#http_encryption_t">http_encryption_t</a> httpGetEncryption (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Current encryption mode</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function returns the encryption mode for the connection. Use the -<a href="#httpIsEncrypted"><code>httpIsEncrypted</code></a> function to determine whether a TLS session has -been established. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpGetExpect">httpGetExpect</a></h3> - <p class="description">Get the value of the Expect header, if any.</p> -<p class="code"> -http_status_t httpGetExpect (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Expect: status, if any</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Returns <code>HTTP_STATUS_NONE</code> if there is no Expect header, otherwise -returns the expected HTTP status code, typically <code>HTTP_STATUS_CONTINUE</code>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetFd">httpGetFd</a></h3> - <p class="description">Get the file descriptor associated with a connection.</p> -<p class="code"> -int httpGetFd (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">File descriptor or -1 if none</p> -<h3 class="function"><a id="httpGetField">httpGetField</a></h3> - <p class="description">Get a field value from a request/response.</p> -<p class="code"> -const char *httpGetField (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#http_field_t">http_field_t</a> field<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>field</dt> - <dd class="description">Field to get</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Field value</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpGetHostByName">httpGetHostByName</a></h3> - <p class="description">Lookup a hostname or IPv4 address, and return -address records for the specified name.</p> -<p class="code"> -struct hostent *httpGetHostByName (<br /> -    const char *name<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Hostname or IP address</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Host entry</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetHostname">httpGetHostname</a></h3> - <p class="description">Get the FQDN for the connection or local system.</p> -<p class="code"> -const char *httpGetHostname (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    char *s,<br /> -    int slen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection or NULL</dd> -<dt>s</dt> - <dd class="description">String buffer for name</dd> -<dt>slen</dt> - <dd class="description">Size of buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">FQDN for connection or system</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">When "http" points to a connected socket, return the hostname or -address that was used in the call to httpConnect() or httpConnectEncrypt(), -or the address of the client for the connection from httpAcceptConnection(). -Otherwise, return the FQDN for the local system using both gethostname() -and gethostbyname() to get the local hostname with domain. - -</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetKeepAlive">httpGetKeepAlive</a></h3> - <p class="description">Get the current Keep-Alive state of the connection.</p> -<p class="code"> -<a href="#http_keepalive_t">http_keepalive_t</a> httpGetKeepAlive (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Keep-Alive state</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpGetLength">httpGetLength</a></h3> - <p class="description">Get the amount of data remaining from the -content-length or transfer-encoding fields.</p> -<p class="code"> -int httpGetLength (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Content length</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is deprecated and will not return lengths larger than -2^31 - 1; use httpGetLength2() instead. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetLength2">httpGetLength2</a></h3> - <p class="description">Get the amount of data remaining from the -content-length or transfer-encoding fields.</p> -<p class="code"> -off_t httpGetLength2 (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Content length</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function returns the complete content length, even for -content larger than 2^31 - 1. - -</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetPending">httpGetPending</a></h3> - <p class="description">Get the number of bytes that are buffered for writing.</p> -<p class="code"> -size_t httpGetPending (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes buffered</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetReady">httpGetReady</a></h3> - <p class="description">Get the number of bytes that can be read without blocking.</p> -<p class="code"> -size_t httpGetReady (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes available</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetRemaining">httpGetRemaining</a></h3> - <p class="description">Get the number of remaining bytes in the message -body or current chunk.</p> -<p class="code"> -size_t httpGetRemaining (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Remaining bytes</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <a href="#httpIsChunked"><code>httpIsChunked</code></a> function can be used to determine whether the -message body is chunked or fixed-length. - -</p> -<h3 class="function"><a id="httpGetState">httpGetState</a></h3> - <p class="description">Get the current state of the HTTP request.</p> -<p class="code"> -<a href="#http_state_t">http_state_t</a> httpGetState (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">HTTP state</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetStatus">httpGetStatus</a></h3> - <p class="description">Get the status of the last HTTP request.</p> -<p class="code"> -http_status_t httpGetStatus (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">HTTP status</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpGetSubField">httpGetSubField</a></h3> - <p class="description">Get a sub-field value.</p> -<p class="code"> -char *httpGetSubField (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#http_field_t">http_field_t</a> field,<br /> -    const char *name,<br /> -    char *value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>field</dt> - <dd class="description">Field index</dd> -<dt>name</dt> - <dd class="description">Name of sub-field</dd> -<dt>value</dt> - <dd class="description">Value string</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Value or NULL</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetSubField2">httpGetSubField2</a></h3> - <p class="description">Get a sub-field value.</p> -<p class="code"> -char *httpGetSubField2 (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#http_field_t">http_field_t</a> field,<br /> -    const char *name,<br /> -    char *value,<br /> -    int valuelen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>field</dt> - <dd class="description">Field index</dd> -<dt>name</dt> - <dd class="description">Name of sub-field</dd> -<dt>value</dt> - <dd class="description">Value string</dd> -<dt>valuelen</dt> - <dd class="description">Size of value buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Value or NULL</p> -<h3 class="function"><a id="httpGetVersion">httpGetVersion</a></h3> - <p class="description">Get the HTTP version at the other end.</p> -<p class="code"> -<a href="#http_version_t">http_version_t</a> httpGetVersion (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Version number</p> -<h3 class="function"><a id="httpGets">httpGets</a></h3> - <p class="description">Get a line of text from a HTTP connection.</p> -<p class="code"> -char *httpGets (<br /> -    char *line,<br /> -    int length,<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>line</dt> - <dd class="description">Line to read into</dd> -<dt>length</dt> - <dd class="description">Max length of buffer</dd> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Line or NULL</p> -<h3 class="function"><a id="httpHead">httpHead</a></h3> - <p class="description">Send a HEAD request to the server.</p> -<p class="code"> -int httpHead (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *uri<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>uri</dt> - <dd class="description">URI for head</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of call (0 = success)</p> -<h3 class="function"><a id="httpInitialize">httpInitialize</a></h3> - <p class="description">Initialize the HTTP interface library and set the -default HTTP proxy (if any).</p> -<p class="code"> -void httpInitialize (void);</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpIsChunked">httpIsChunked</a></h3> - <p class="description">Report whether a message body is chunked.</p> -<p class="code"> -int httpIsChunked (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if chunked, 0 if not</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function returns non-zero if the message body is composed of -variable-length chunks. - -</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpIsEncrypted">httpIsEncrypted</a></h3> - <p class="description">Report whether a connection is encrypted.</p> -<p class="code"> -int httpIsEncrypted (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if encrypted, 0 if not</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function returns non-zero if the connection is currently encrypted. - -</p> -<h3 class="function"><a id="httpMD5">httpMD5</a></h3> - <p class="description">Compute the MD5 sum of the username:group:password.</p> -<p class="code"> -char *httpMD5 (<br /> -    const char *username,<br /> -    const char *realm,<br /> -    const char *passwd,<br /> -    char md5[33]<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>username</dt> - <dd class="description">User name</dd> -<dt>realm</dt> - <dd class="description">Realm name</dd> -<dt>passwd</dt> - <dd class="description">Password string</dd> -<dt>md5[33]</dt> - <dd class="description">MD5 string</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">MD5 sum</p> -<h3 class="function"><a id="httpMD5Final">httpMD5Final</a></h3> - <p class="description">Combine the MD5 sum of the username, group, and password -with the server-supplied nonce value, method, and -request-uri.</p> -<p class="code"> -char *httpMD5Final (<br /> -    const char *nonce,<br /> -    const char *method,<br /> -    const char *resource,<br /> -    char md5[33]<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>nonce</dt> - <dd class="description">Server nonce value</dd> -<dt>method</dt> - <dd class="description">METHOD (GET, POST, etc.)</dd> -<dt>resource</dt> - <dd class="description">Resource path</dd> -<dt>md5[33]</dt> - <dd class="description">MD5 sum</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New sum</p> -<h3 class="function"><a id="httpMD5String">httpMD5String</a></h3> - <p class="description">Convert an MD5 sum to a character string.</p> -<p class="code"> -char *httpMD5String (<br /> -    const unsigned char *sum,<br /> -    char md5[33]<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>sum</dt> - <dd class="description">MD5 sum data</dd> -<dt>md5[33]</dt> - <dd class="description">MD5 sum in hex</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">MD5 sum in hex</p> -<h3 class="function"><a id="httpOptions">httpOptions</a></h3> - <p class="description">Send an OPTIONS request to the server.</p> -<p class="code"> -int httpOptions (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *uri<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>uri</dt> - <dd class="description">URI for options</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of call (0 = success)</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpPeek">httpPeek</a></h3> - <p class="description">Peek at data from a HTTP connection.</p> -<p class="code"> -ssize_t httpPeek (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    char *buffer,<br /> -    size_t length<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>buffer</dt> - <dd class="description">Buffer for data</dd> -<dt>length</dt> - <dd class="description">Maximum number of bytes</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes copied</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function copies available data from the given HTTP connection, reading -a buffer as needed. The data is still available for reading using -<a href="#httpRead"><code>httpRead</code></a> or <a href="#httpRead2"><code>httpRead2</code></a>.<br> -<br> -For non-blocking connections the usual timeouts apply. - -</p> -<h3 class="function"><a id="httpPost">httpPost</a></h3> - <p class="description">Send a POST request to the server.</p> -<p class="code"> -int httpPost (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *uri<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>uri</dt> - <dd class="description">URI for post</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of call (0 = success)</p> -<h3 class="function"><a id="httpPut">httpPut</a></h3> - <p class="description">Send a PUT request to the server.</p> -<p class="code"> -int httpPut (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *uri<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>uri</dt> - <dd class="description">URI to put</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of call (0 = success)</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpRead">httpRead</a></h3> - <p class="description">Read data from a HTTP connection.</p> -<p class="code"> -int httpRead (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    char *buffer,<br /> -    int length<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>buffer</dt> - <dd class="description">Buffer for data</dd> -<dt>length</dt> - <dd class="description">Maximum number of bytes</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes read</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is deprecated. Use the httpRead2() function which can -read more than 2GB of data. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpRead2">httpRead2</a></h3> - <p class="description">Read data from a HTTP connection.</p> -<p class="code"> -ssize_t httpRead2 (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    char *buffer,<br /> -    size_t length<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>buffer</dt> - <dd class="description">Buffer for data</dd> -<dt>length</dt> - <dd class="description">Maximum number of bytes</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes read</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpReadRequest">httpReadRequest</a></h3> - <p class="description">Read a HTTP request from a connection.</p> -<p class="code"> -<a href="#http_state_t">http_state_t</a> httpReadRequest (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    char *uri,<br /> -    size_t urilen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>uri</dt> - <dd class="description">URI buffer</dd> -<dt>urilen</dt> - <dd class="description">Size of URI buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New state of connection</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpReconnect">httpReconnect</a></h3> - <p class="description">Reconnect to a HTTP server.</p> -<p class="code"> -int httpReconnect (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, non-zero on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is deprecated. Please use the <a href="#httpReconnect2"><code>httpReconnect2</code></a> function -instead. - -</p> -<h3 class="function"><a id="httpReconnect2">httpReconnect2</a></h3> - <p class="description">Reconnect to a HTTP server with timeout and optional -cancel.</p> -<p class="code"> -int httpReconnect2 (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    int msec,<br /> -    int *cancel<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>msec</dt> - <dd class="description">Timeout in milliseconds</dd> -<dt>cancel</dt> - <dd class="description">Pointer to "cancel" variable</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, non-zero on failure</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpResolveHostname">httpResolveHostname</a></h3> - <p class="description">Resolve the hostname of the HTTP connection -address.</p> -<p class="code"> -const char *httpResolveHostname (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    char *buffer,<br /> -    size_t bufsize<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>buffer</dt> - <dd class="description">Hostname buffer</dd> -<dt>bufsize</dt> - <dd class="description">Size of buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Resolved hostname or <code>NULL</code></p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpSeparate">httpSeparate</a></h3> - <p class="description">Separate a Universal Resource Identifier into its -components.</p> -<p class="code"> -void httpSeparate (<br /> -    const char *uri,<br /> -    char *scheme,<br /> -    char *username,<br /> -    char *host,<br /> -    int *port,<br /> -    char *resource<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>uri</dt> - <dd class="description">Universal Resource Identifier</dd> -<dt>scheme</dt> - <dd class="description">Scheme [32] (http, https, etc.)</dd> -<dt>username</dt> - <dd class="description">Username [1024]</dd> -<dt>host</dt> - <dd class="description">Hostname [1024]</dd> -<dt>port</dt> - <dd class="description">Port number to use</dd> -<dt>resource</dt> - <dd class="description">Resource/filename [1024]</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is deprecated; use the httpSeparateURI() function instead. - -</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="httpSeparate2">httpSeparate2</a></h3> - <p class="description">Separate a Universal Resource Identifier into its -components.</p> -<p class="code"> -void httpSeparate2 (<br /> -    const char *uri,<br /> -    char *scheme,<br /> -    int schemelen,<br /> -    char *username,<br /> -    int usernamelen,<br /> -    char *host,<br /> -    int hostlen,<br /> -    int *port,<br /> -    char *resource,<br /> -    int resourcelen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>uri</dt> - <dd class="description">Universal Resource Identifier</dd> -<dt>scheme</dt> - <dd class="description">Scheme (http, https, etc.)</dd> -<dt>schemelen</dt> - <dd class="description">Size of scheme buffer</dd> -<dt>username</dt> - <dd class="description">Username</dd> -<dt>usernamelen</dt> - <dd class="description">Size of username buffer</dd> -<dt>host</dt> - <dd class="description">Hostname</dd> -<dt>hostlen</dt> - <dd class="description">Size of hostname buffer</dd> -<dt>port</dt> - <dd class="description">Port number to use</dd> -<dt>resource</dt> - <dd class="description">Resource/filename</dd> -<dt>resourcelen</dt> - <dd class="description">Size of resource buffer</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is deprecated; use the httpSeparateURI() function instead. - - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpSeparateURI">httpSeparateURI</a></h3> - <p class="description">Separate a Universal Resource Identifier into its -components.</p> -<p class="code"> -<a href="#http_uri_status_t">http_uri_status_t</a> httpSeparateURI (<br /> -    <a href="#http_uri_coding_t">http_uri_coding_t</a> decoding,<br /> -    const char *uri,<br /> -    char *scheme,<br /> -    int schemelen,<br /> -    char *username,<br /> -    int usernamelen,<br /> -    char *host,<br /> -    int hostlen,<br /> -    int *port,<br /> -    char *resource,<br /> -    int resourcelen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>decoding</dt> - <dd class="description">Decoding flags</dd> -<dt>uri</dt> - <dd class="description">Universal Resource Identifier</dd> -<dt>scheme</dt> - <dd class="description">Scheme (http, https, etc.)</dd> -<dt>schemelen</dt> - <dd class="description">Size of scheme buffer</dd> -<dt>username</dt> - <dd class="description">Username</dd> -<dt>usernamelen</dt> - <dd class="description">Size of username buffer</dd> -<dt>host</dt> - <dd class="description">Hostname</dd> -<dt>hostlen</dt> - <dd class="description">Size of hostname buffer</dd> -<dt>port</dt> - <dd class="description">Port number to use</dd> -<dt>resource</dt> - <dd class="description">Resource/filename</dd> -<dt>resourcelen</dt> - <dd class="description">Size of resource buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Result of separation</p> -<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="httpSetAuthString">httpSetAuthString</a></h3> - <p class="description">Set the current authorization string.</p> -<p class="code"> -void httpSetAuthString (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *scheme,<br /> -    const char *data<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>scheme</dt> - <dd class="description">Auth scheme (NULL to clear it)</dd> -<dt>data</dt> - <dd class="description">Auth data (NULL for none)</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function just stores a copy of the current authorization string in -the HTTP connection object. You must still call httpSetField() to set -HTTP_FIELD_AUTHORIZATION prior to issuing a HTTP request using httpGet(), -httpHead(), httpOptions(), httpPost, or httpPut(). - -</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="httpSetCookie">httpSetCookie</a></h3> - <p class="description">Set the cookie value(s).</p> -<p class="code"> -void httpSetCookie (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *cookie<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">Connection</dd> -<dt>cookie</dt> - <dd class="description">Cookie string</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="httpSetCredentials">httpSetCredentials</a></h3> - <p class="description">Set the credentials associated with an encrypted -connection.</p> -<p class="code"> -int httpSetCredentials (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    cups_array_t *credentials<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>credentials</dt> - <dd class="description">Array of credentials</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of call (0 = success)</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpSetDefaultField">httpSetDefaultField</a></h3> - <p class="description">Set the default value of an HTTP header.</p> -<p class="code"> -void httpSetDefaultField (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#http_field_t">http_field_t</a> field,<br /> -    const char *value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>field</dt> - <dd class="description">Field index</dd> -<dt>value</dt> - <dd class="description">Value</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Currently only <code>HTTP_FIELD_ACCEPT_ENCODING</code>, <code>HTTP_FIELD_SERVER</code>, -and <code>HTTP_FIELD_USER_AGENT</code> can be set. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpSetExpect">httpSetExpect</a></h3> - <p class="description">Set the Expect: header in a request.</p> -<p class="code"> -void httpSetExpect (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    http_status_t expect<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>expect</dt> - <dd class="description">HTTP status to expect -(<code>HTTP_STATUS_CONTINUE</code>)</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Currently only <code>HTTP_STATUS_CONTINUE</code> is supported for the "expect" -argument. - -</p> -<h3 class="function"><a id="httpSetField">httpSetField</a></h3> - <p class="description">Set the value of an HTTP header.</p> -<p class="code"> -void httpSetField (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#http_field_t">http_field_t</a> field,<br /> -    const char *value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>field</dt> - <dd class="description">Field index</dd> -<dt>value</dt> - <dd class="description">Value</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpSetKeepAlive">httpSetKeepAlive</a></h3> - <p class="description">Set the current Keep-Alive state of a connection.</p> -<p class="code"> -void httpSetKeepAlive (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#http_keepalive_t">http_keepalive_t</a> keep_alive<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>keep_alive</dt> - <dd class="description">New Keep-Alive value</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpSetLength">httpSetLength</a></h3> - <p class="description">Set the content-length and content-encoding.</p> -<p class="code"> -void httpSetLength (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    size_t length<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>length</dt> - <dd class="description">Length (0 for chunked)</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="httpSetTimeout">httpSetTimeout</a></h3> - <p class="description">Set read/write timeouts and an optional callback.</p> -<p class="code"> -void httpSetTimeout (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    double timeout,<br /> -    <a href="#http_timeout_cb_t">http_timeout_cb_t</a> cb,<br /> -    void *user_data<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>timeout</dt> - <dd class="description">Number of seconds for timeout, -must be greater than 0</dd> -<dt>cb</dt> - <dd class="description">Callback function or NULL</dd> -<dt>user_data</dt> - <dd class="description">User data pointer</dd> -</dl> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The optional timeout callback receives both the HTTP connection and a user -data pointer and must return 1 to continue or 0 to error (time) out. - -</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpShutdown">httpShutdown</a></h3> - <p class="description">Shutdown one side of an HTTP connection.</p> -<p class="code"> -void httpShutdown (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpStateString">httpStateString</a></h3> - <p class="description">Return the string describing a HTTP state value.</p> -<p class="code"> -const char *httpStateString (<br /> -    <a href="#http_state_t">http_state_t</a> state<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>state</dt> - <dd class="description">HTTP state value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">State string</p> -<h3 class="function"><a id="httpStatus">httpStatus</a></h3> - <p class="description">Return a short string describing a HTTP status code.</p> -<p class="code"> -const char *httpStatus (<br /> -    http_status_t status<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>status</dt> - <dd class="description">HTTP status code</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Localized status string</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The returned string is localized to the current POSIX locale and is based -on the status strings defined in RFC 2616.</p> -<h3 class="function"><a id="httpTrace">httpTrace</a></h3> - <p class="description">Send an TRACE request to the server.</p> -<p class="code"> -int httpTrace (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *uri<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>uri</dt> - <dd class="description">URI for trace</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status of call (0 = success)</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpURIStatusString">httpURIStatusString</a></h3> - <p class="description">Return a string describing a URI status code.</p> -<p class="code"> -const char *httpURIStatusString (<br /> -    <a href="#http_uri_status_t">http_uri_status_t</a> status<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>status</dt> - <dd class="description">URI status code</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Localized status string</p> -<h3 class="function"><a id="httpUpdate">httpUpdate</a></h3> - <p class="description">Update the current HTTP state for incoming data.</p> -<p class="code"> -http_status_t httpUpdate (<br /> -    <a href="#http_t">http_t</a> *http<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">HTTP status</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="httpWait">httpWait</a></h3> - <p class="description">Wait for data available on a connection.</p> -<p class="code"> -int httpWait (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    int msec<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>msec</dt> - <dd class="description">Milliseconds to wait</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if data is available, 0 otherwise</p> -<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpWrite">httpWrite</a></h3> - <p class="description">Write data to a HTTP connection.</p> -<p class="code"> -int httpWrite (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *buffer,<br /> -    int length<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>buffer</dt> - <dd class="description">Buffer for data</dd> -<dt>length</dt> - <dd class="description">Number of bytes to write</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes written</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function is deprecated. Use the httpWrite2() function which can -write more than 2GB of data. - -</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpWrite2">httpWrite2</a></h3> - <p class="description">Write data to a HTTP connection.</p> -<p class="code"> -ssize_t httpWrite2 (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    const char *buffer,<br /> -    size_t length<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>buffer</dt> - <dd class="description">Buffer for data</dd> -<dt>length</dt> - <dd class="description">Number of bytes to write</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes written</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpWriteResponse">httpWriteResponse</a></h3> - <p class="description">Write a HTTP response to a client connection.</p> -<p class="code"> -int httpWriteResponse (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    http_status_t status<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>status</dt> - <dd class="description">Status code</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">0 on success, -1 on error</p> -<h3 class="function"><a id="ippAddBoolean">ippAddBoolean</a></h3> - <p class="description">Add a boolean attribute to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBoolean (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    const char *name,<br /> -    char value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>value</dt> - <dd class="description">Value of attribute</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> -<h3 class="function"><a id="ippAddBooleans">ippAddBooleans</a></h3> - <p class="description">Add an array of boolean values.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBooleans (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    const char *name,<br /> -    int num_values,<br /> -    const char *values<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>num_values</dt> - <dd class="description">Number of values</dd> -<dt>values</dt> - <dd class="description">Values</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ippAddCollection">ippAddCollection</a></h3> - <p class="description">Add a collection value.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollection (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    const char *name,<br /> -    <a href="#ipp_t">ipp_t</a> *value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>value</dt> - <dd class="description">Value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). - -</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ippAddCollections">ippAddCollections</a></h3> - <p class="description">Add an array of collection values.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollections (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    const char *name,<br /> -    int num_values,<br /> -    const <a href="#ipp_t">ipp_t</a> **values<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>num_values</dt> - <dd class="description">Number of values</dd> -<dt>values</dt> - <dd class="description">Values</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). - -</p> -<h3 class="function"><a id="ippAddDate">ippAddDate</a></h3> - <p class="description">Add a date attribute to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddDate (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    const char *name,<br /> -    const <a href="#ipp_uchar_t">ipp_uchar_t</a> *value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>value</dt> - <dd class="description">Value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> -<h3 class="function"><a id="ippAddInteger">ippAddInteger</a></h3> - <p class="description">Add a integer attribute to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddInteger (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    ipp_tag_t value_tag,<br /> -    const char *name,<br /> -    int value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>value_tag</dt> - <dd class="description">Type of attribute</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>value</dt> - <dd class="description">Value of attribute</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> -<br> -Supported values include enum (<code>IPP_TAG_ENUM</code>) and integer -(<code>IPP_TAG_INTEGER</code>).</p> -<h3 class="function"><a id="ippAddIntegers">ippAddIntegers</a></h3> - <p class="description">Add an array of integer values.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddIntegers (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    ipp_tag_t value_tag,<br /> -    const char *name,<br /> -    int num_values,<br /> -    const int *values<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>value_tag</dt> - <dd class="description">Type of attribute</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>num_values</dt> - <dd class="description">Number of values</dd> -<dt>values</dt> - <dd class="description">Values</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> -<br> -Supported values include enum (<code>IPP_TAG_ENUM</code>) and integer -(<code>IPP_TAG_INTEGER</code>).</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippAddOctetString">ippAddOctetString</a></h3> - <p class="description">Add an octetString value to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddOctetString (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    const char *name,<br /> -    const void *data,<br /> -    int datalen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>data</dt> - <dd class="description">octetString data</dd> -<dt>datalen</dt> - <dd class="description">Length of data in bytes</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippAddOutOfBand">ippAddOutOfBand</a></h3> - <p class="description">Add an out-of-band value to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddOutOfBand (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    ipp_tag_t value_tag,<br /> -    const char *name<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>value_tag</dt> - <dd class="description">Type of attribute</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> -<br> -Supported out-of-band values include unsupported-value -(<code>IPP_TAG_UNSUPPORTED_VALUE</code>), default (<code>IPP_TAG_DEFAULT</code>), unknown -(<code>IPP_TAG_UNKNOWN</code>), no-value (<code>IPP_TAG_NOVALUE</code>), not-settable -(<code>IPP_TAG_NOTSETTABLE</code>), delete-attribute (<code>IPP_TAG_DELETEATTR</code>), and -admin-define (<code>IPP_TAG_ADMINDEFINE</code>). - -</p> -<h3 class="function"><a id="ippAddRange">ippAddRange</a></h3> - <p class="description">Add a range of values to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRange (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    const char *name,<br /> -    int lower,<br /> -    int upper<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>lower</dt> - <dd class="description">Lower value</dd> -<dt>upper</dt> - <dd class="description">Upper value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> -<br> -The <code>lower</code> parameter must be less than or equal to the <code>upper</code> parameter.</p> -<h3 class="function"><a id="ippAddRanges">ippAddRanges</a></h3> - <p class="description">Add ranges of values to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRanges (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    const char *name,<br /> -    int num_values,<br /> -    const int *lower,<br /> -    const int *upper<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>num_values</dt> - <dd class="description">Number of values</dd> -<dt>lower</dt> - <dd class="description">Lower values</dd> -<dt>upper</dt> - <dd class="description">Upper values</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> -<h3 class="function"><a id="ippAddResolution">ippAddResolution</a></h3> - <p class="description">Add a resolution value to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolution (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    const char *name,<br /> -    <a href="#ipp_res_t">ipp_res_t</a> units,<br /> -    int xres,<br /> -    int yres<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>units</dt> - <dd class="description">Units for resolution</dd> -<dt>xres</dt> - <dd class="description">X resolution</dd> -<dt>yres</dt> - <dd class="description">Y resolution</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> -<h3 class="function"><a id="ippAddResolutions">ippAddResolutions</a></h3> - <p class="description">Add resolution values to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolutions (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    const char *name,<br /> -    int num_values,<br /> -    <a href="#ipp_res_t">ipp_res_t</a> units,<br /> -    const int *xres,<br /> -    const int *yres<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>num_values</dt> - <dd class="description">Number of values</dd> -<dt>units</dt> - <dd class="description">Units for resolution</dd> -<dt>xres</dt> - <dd class="description">X resolutions</dd> -<dt>yres</dt> - <dd class="description">Y resolutions</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> -<h3 class="function"><a id="ippAddSeparator">ippAddSeparator</a></h3> - <p class="description">Add a group separator to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddSeparator (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.</p> -<h3 class="function"><a id="ippAddString">ippAddString</a></h3> - <p class="description">Add a language-encoded string to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddString (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    ipp_tag_t value_tag,<br /> -    const char *name,<br /> -    const char *language,<br /> -    const char *value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>value_tag</dt> - <dd class="description">Type of attribute</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>language</dt> - <dd class="description">Language code</dd> -<dt>value</dt> - <dd class="description">Value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> -<br> -Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword -(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType -(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage -(<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage -(<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme -(<code>IPP_TAG_URISCHEME</code>).<br> -<br> -The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage and -textWithLanguage string values and must be <code>NULL</code> for all other string values.</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippAddStringf">ippAddStringf</a></h3> - <p class="description">Add a formatted string to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStringf (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    ipp_tag_t value_tag,<br /> -    const char *name,<br /> -    const char *language,<br /> -    const char *format,<br /> -    ...<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>value_tag</dt> - <dd class="description">Type of attribute</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>language</dt> - <dd class="description">Language code (<code>NULL</code> for default)</dd> -<dt>format</dt> - <dd class="description">Printf-style format string</dd> -<dt>...</dt> - <dd class="description">Additional arguments as needed</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document -(<code>IPP_TAG_DOCUMENT</code>), event notification -(<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation (<code>IPP_TAG_OPERATION</code>), -printer (<code>IPP_TAG_PRINTER</code>), subscription (<code>IPP_TAG_SUBSCRIPTION</code>), -or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> -<br> -Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword -(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType -(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage -(<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage -(<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme -(<code>IPP_TAG_URISCHEME</code>).<br> -<br> -The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage -and textWithLanguage string values and must be <code>NULL</code> for all other -string values.<br> -<br> -The <code>format</code> parameter uses formatting characters compatible with the -printf family of standard functions. Additional arguments follow it as -needed. The formatted string is truncated as needed to the maximum length of -the corresponding value type. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippAddStringfv">ippAddStringfv</a></h3> - <p class="description">Add a formatted string to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStringfv (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    ipp_tag_t value_tag,<br /> -    const char *name,<br /> -    const char *language,<br /> -    const char *format,<br /> -    va_list ap<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>value_tag</dt> - <dd class="description">Type of attribute</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>language</dt> - <dd class="description">Language code (<code>NULL</code> for default)</dd> -<dt>format</dt> - <dd class="description">Printf-style format string</dd> -<dt>ap</dt> - <dd class="description">Additional arguments</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document -(<code>IPP_TAG_DOCUMENT</code>), event notification -(<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation (<code>IPP_TAG_OPERATION</code>), -printer (<code>IPP_TAG_PRINTER</code>), subscription (<code>IPP_TAG_SUBSCRIPTION</code>), -or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> -<br> -Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword -(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType -(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage -(<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage -(<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme -(<code>IPP_TAG_URISCHEME</code>).<br> -<br> -The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage -and textWithLanguage string values and must be <code>NULL</code> for all other -string values.<br> -<br> -The <code>format</code> parameter uses formatting characters compatible with the -printf family of standard functions. Additional arguments are passed in the -stdarg pointer <code>ap</code>. The formatted string is truncated as needed to the -maximum length of the corresponding value type. - -</p> -<h3 class="function"><a id="ippAddStrings">ippAddStrings</a></h3> - <p class="description">Add language-encoded strings to an IPP message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStrings (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_tag_t group,<br /> -    ipp_tag_t value_tag,<br /> -    const char *name,<br /> -    int num_values,<br /> -    const char *language,<br /> -    const char *const *values<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>group</dt> - <dd class="description">IPP group</dd> -<dt>value_tag</dt> - <dd class="description">Type of attribute</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>num_values</dt> - <dd class="description">Number of values</dd> -<dt>language</dt> - <dd class="description">Language code (<code>NULL</code> for default)</dd> -<dt>values</dt> - <dd class="description">Values</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> -<br> -Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword -(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType -(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage -(<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage -(<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme -(<code>IPP_TAG_URISCHEME</code>).<br> -<br> -The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage and -textWithLanguage string values and must be <code>NULL</code> for all other string values.</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippAttributeString">ippAttributeString</a></h3> - <p class="description">Convert the attribute's value to a string.</p> -<p class="code"> -size_t ippAttributeString (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br /> -    char *buffer,<br /> -    size_t bufsize<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">Attribute</dd> -<dt>buffer</dt> - <dd class="description">String buffer or NULL</dd> -<dt>bufsize</dt> - <dd class="description">Size of string buffer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of bytes less nul</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Returns the number of bytes that would be written, not including the -trailing nul. The buffer pointer can be NULL to get the required length, -just like (v)snprintf. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippContainsInteger">ippContainsInteger</a></h3> - <p class="description">Determine whether an attribute contains the -specified value or is within the list of ranges.</p> -<p class="code"> -int ippContainsInteger (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br /> -    int value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">Attribute</dd> -<dt>value</dt> - <dd class="description">Integer/enum value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on a match, 0 on no match</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Returns non-zero when the attribute contains either a matching integer or -enum value, or the value falls within one of the rangeOfInteger values for -the attribute. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippContainsString">ippContainsString</a></h3> - <p class="description">Determine whether an attribute contains the -specified string value.</p> -<p class="code"> -int ippContainsString (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br /> -    const char *value<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">Attribute</dd> -<dt>value</dt> - <dd class="description">String value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on a match, 0 on no match</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Returns non-zero when the attribute contains a matching charset, keyword, -language, mimeMediaType, name, text, URI, or URI scheme value. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippCopyAttribute">ippCopyAttribute</a></h3> - <p class="description">Copy an attribute.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippCopyAttribute (<br /> -    <a href="#ipp_t">ipp_t</a> *dst,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *srcattr,<br /> -    int quickcopy<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dst</dt> - <dd class="description">Destination IPP message</dd> -<dt>srcattr</dt> - <dd class="description">Attribute to copy</dd> -<dt>quickcopy</dt> - <dd class="description">1 for a referenced copy, 0 for normal</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The specified attribute, <code>attr</code>, is copied to the destination IPP message. -When <code>quickcopy</code> is non-zero, a "shallow" reference copy of the attribute is -created - this should only be done as long as the original source IPP message will -not be freed for the life of the destination. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippCopyAttributes">ippCopyAttributes</a></h3> - <p class="description">Copy attributes from one IPP message to another.</p> -<p class="code"> -int ippCopyAttributes (<br /> -    <a href="#ipp_t">ipp_t</a> *dst,<br /> -    <a href="#ipp_t">ipp_t</a> *src,<br /> -    int quickcopy,<br /> -    <a href="#ipp_copycb_t">ipp_copycb_t</a> cb,<br /> -    void *context<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dst</dt> - <dd class="description">Destination IPP message</dd> -<dt>src</dt> - <dd class="description">Source IPP message</dd> -<dt>quickcopy</dt> - <dd class="description">1 for a referenced copy, 0 for normal</dd> -<dt>cb</dt> - <dd class="description">Copy callback or <code>NULL</code> for none</dd> -<dt>context</dt> - <dd class="description">Context pointer</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Zero or more attributes are copied from the source IPP message, <code>src</code>, to the -destination IPP message, <code>dst</code>. When <code>quickcopy</code> is non-zero, a "shallow" -reference copy of the attribute is created - this should only be done as long as the -original source IPP message will not be freed for the life of the destination.<br> -<br> -The <code>cb</code> and <code>context</code> parameters provide a generic way to "filter" the -attributes that are copied - the function must return 1 to copy the attribute or -0 to skip it. The function may also choose to do a partial copy of the source attribute -itself. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippCreateRequestedArray">ippCreateRequestedArray</a></h3> - <p class="description">Create a CUPS array of attribute names from the -given requested-attributes attribute.</p> -<p class="code"> -cups_array_t *ippCreateRequestedArray (<br /> -    <a href="#ipp_t">ipp_t</a> *request<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>request</dt> - <dd class="description">IPP request</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">CUPS array or <code>NULL</code> if all</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function creates a (sorted) CUPS array of attribute names matching the -list of "requested-attribute" values supplied in an IPP request. All IANA- -registered values are supported in addition to the CUPS IPP extension -attributes.<br> -<br> -The <code>request</code> parameter specifies the request message that was read from -the client. - -<code>NULL</code> is returned if all attributes should be returned. Otherwise, the -result is a sorted array of attribute names, where <code>cupsArrayFind(array, -"attribute-name")</code> will return a non-NULL pointer. The array must be freed -using the <code>cupsArrayDelete</code> function. - -</p> -<h3 class="function"><a id="ippDateToTime">ippDateToTime</a></h3> - <p class="description">Convert from RFC 1903 Date/Time format to UNIX time -in seconds.</p> -<p class="code"> -time_t ippDateToTime (<br /> -    const <a href="#ipp_uchar_t">ipp_uchar_t</a> *date<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>date</dt> - <dd class="description">RFC 1903 date info</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">UNIX time value</p> -<h3 class="function"><a id="ippDelete">ippDelete</a></h3> - <p class="description">Delete an IPP message.</p> -<p class="code"> -void ippDelete (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ippDeleteAttribute">ippDeleteAttribute</a></h3> - <p class="description">Delete a single attribute in an IPP message.</p> -<p class="code"> -void ippDeleteAttribute (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">Attribute to delete</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippDeleteValues">ippDeleteValues</a></h3> - <p class="description">Delete values in an attribute.</p> -<p class="code"> -int ippDeleteValues (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    int element,<br /> -    int count<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">Attribute</dd> -<dt>element</dt> - <dd class="description">Index of first value to delete (0-based)</dd> -<dt>count</dt> - <dd class="description">Number of values to delete</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>element</code> parameter specifies the first value to delete, starting at -0. It must be less than the number of values returned by <a href="#ippGetCount"><code>ippGetCount</code></a>.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -Deleting all values in an attribute deletes the attribute. - -</p> -<h3 class="function"><a id="ippEnumString">ippEnumString</a></h3> - <p class="description">Return a string corresponding to the enum value.</p> -<p class="code"> -const char *ippEnumString (<br /> -    const char *attrname,<br /> -    int enumvalue<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attrname</dt> - <dd class="description">Attribute name</dd> -<dt>enumvalue</dt> - <dd class="description">Enum value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Enum string</p> -<h3 class="function"><a id="ippEnumValue">ippEnumValue</a></h3> - <p class="description">Return the value associated with a given enum string.</p> -<p class="code"> -int ippEnumValue (<br /> -    const char *attrname,<br /> -    const char *enumstring<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attrname</dt> - <dd class="description">Attribute name</dd> -<dt>enumstring</dt> - <dd class="description">Enum string</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Enum value or -1 if unknown</p> -<h3 class="function"><a id="ippErrorString">ippErrorString</a></h3> - <p class="description">Return a name for the given status code.</p> -<p class="code"> -const char *ippErrorString (<br /> -    ipp_status_t error<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>error</dt> - <dd class="description">Error status</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Text string</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippErrorValue">ippErrorValue</a></h3> - <p class="description">Return a status code for the given name.</p> -<p class="code"> -ipp_status_t ippErrorValue (<br /> -    const char *name<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">IPP status code</p> -<h3 class="function"><a id="ippFindAttribute">ippFindAttribute</a></h3> - <p class="description">Find a named attribute in a request.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindAttribute (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    const char *name,<br /> -    ipp_tag_t type<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>type</dt> - <dd class="description">Type of attribute</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Matching attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Starting with CUPS 2.0, the attribute name can contain a hierarchical list -of attribute and member names separated by slashes, for example -"media-col/media-size".</p> -<h3 class="function"><a id="ippFindNextAttribute">ippFindNextAttribute</a></h3> - <p class="description">Find the next named attribute in a request.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindNextAttribute (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    const char *name,<br /> -    ipp_tag_t type<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>name</dt> - <dd class="description">Name of attribute</dd> -<dt>type</dt> - <dd class="description">Type of attribute</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Matching attribute</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">Starting with CUPS 2.0, the attribute name can contain a hierarchical list -of attribute and member names separated by slashes, for example -"media-col/media-size".</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippFirstAttribute">ippFirstAttribute</a></h3> - <p class="description">Return the first attribute in the message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFirstAttribute (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">First attribute or <code>NULL</code> if none</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetBoolean">ippGetBoolean</a></h3> - <p class="description">Get a boolean value for an attribute.</p> -<p class="code"> -int ippGetBoolean (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br /> -    int element<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Boolean value or 0 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetCollection">ippGetCollection</a></h3> - <p class="description">Get a collection value for an attribute.</p> -<p class="code"> -<a href="#ipp_t">ipp_t</a> *ippGetCollection (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br /> -    int element<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Collection value or <code>NULL</code> on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetCount">ippGetCount</a></h3> - <p class="description">Get the number of values in an attribute.</p> -<p class="code"> -int ippGetCount (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Number of values or 0 on error</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetDate">ippGetDate</a></h3> - <p class="description">Get a date value for an attribute.</p> -<p class="code"> -const <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippGetDate (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br /> -    int element<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Date value or <code>NULL</code></p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetGroupTag">ippGetGroupTag</a></h3> - <p class="description">Get the group associated with an attribute.</p> -<p class="code"> -ipp_tag_t ippGetGroupTag (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Group tag or <code>IPP_TAG_ZERO</code> on error</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetInteger">ippGetInteger</a></h3> - <p class="description">Get the integer/enum value for an attribute.</p> -<p class="code"> -int ippGetInteger (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br /> -    int element<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Value or 0 on error</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetName">ippGetName</a></h3> - <p class="description">Get the attribute name.</p> -<p class="code"> -const char *ippGetName (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Attribute name or <code>NULL</code> for separators</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippGetOctetString">ippGetOctetString</a></h3> - <p class="description">Get an octetString value from an IPP attribute.</p> -<p class="code"> -void *ippGetOctetString (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br /> -    int element,<br /> -    int *datalen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>datalen</dt> - <dd class="description">Length of octetString data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Pointer to octetString data</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetOperation">ippGetOperation</a></h3> - <p class="description">Get the operation ID in an IPP message.</p> -<p class="code"> -ipp_op_t ippGetOperation (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP request message</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Operation ID or 0 on error</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetRange">ippGetRange</a></h3> - <p class="description">Get a rangeOfInteger value from an attribute.</p> -<p class="code"> -int ippGetRange (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br /> -    int element,<br /> -    int *uppervalue<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>uppervalue</dt> - <dd class="description">Upper value of range</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Lower value of range or 0</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetRequestId">ippGetRequestId</a></h3> - <p class="description">Get the request ID from an IPP message.</p> -<p class="code"> -int ippGetRequestId (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Request ID or 0 on error</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetResolution">ippGetResolution</a></h3> - <p class="description">Get a resolution value for an attribute.</p> -<p class="code"> -int ippGetResolution (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br /> -    int element,<br /> -    int *yres,<br /> -    <a href="#ipp_res_t">ipp_res_t</a> *units<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>yres</dt> - <dd class="description">Vertical/feed resolution</dd> -<dt>units</dt> - <dd class="description">Units for resolution</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Horizontal/cross feed resolution or 0</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetState">ippGetState</a></h3> - <p class="description">Get the IPP message state.</p> -<p class="code"> -<a href="#ipp_state_t">ipp_state_t</a> ippGetState (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">IPP message state value</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetStatusCode">ippGetStatusCode</a></h3> - <p class="description">Get the status code from an IPP response or event message.</p> -<p class="code"> -ipp_status_t ippGetStatusCode (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP response or event message</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Status code in IPP message</p> -<h3 class="function"><a id="ippGetString">ippGetString</a></h3> - <p class="description">Return the value...</p> -<p class="code"> -const char *ippGetString (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br /> -    int element,<br /> -    const char **language<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>language</dt> - <dd class="description">Language code (<code>NULL</code> for don't care)</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Get the string and optionally the language code for an attribute.</p> - <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetValueTag">ippGetValueTag</a></h3> - <p class="description">Get the value tag for an attribute.</p> -<p class="code"> -ipp_tag_t ippGetValueTag (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Value tag or <code>IPP_TAG_ZERO</code> on error</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetVersion">ippGetVersion</a></h3> - <p class="description">Get the major and minor version number from an IPP message.</p> -<p class="code"> -int ippGetVersion (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    int *minor<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>minor</dt> - <dd class="description">Minor version number or <code>NULL</code></dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Major version number or 0 on error</p> -<h3 class="function"><a id="ippLength">ippLength</a></h3> - <p class="description">Compute the length of an IPP message.</p> -<p class="code"> -size_t ippLength (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Size of IPP message</p> -<h3 class="function"><a id="ippNew">ippNew</a></h3> - <p class="description">Allocate a new IPP message.</p> -<p class="code"> -<a href="#ipp_t">ipp_t</a> *ippNew (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">New IPP message</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippNewRequest">ippNewRequest</a></h3> - <p class="description">Allocate a new IPP request message.</p> -<p class="code"> -<a href="#ipp_t">ipp_t</a> *ippNewRequest (<br /> -    ipp_op_t op<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>op</dt> - <dd class="description">Operation code</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">IPP request message</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The new request message is initialized with the attributes-charset and -attributes-natural-language attributes added. The -attributes-natural-language value is derived from the current locale. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippNewResponse">ippNewResponse</a></h3> - <p class="description">Allocate a new IPP response message.</p> -<p class="code"> -<a href="#ipp_t">ipp_t</a> *ippNewResponse (<br /> -    <a href="#ipp_t">ipp_t</a> *request<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>request</dt> - <dd class="description">IPP request message</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">IPP response message</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The new response message is initialized with the same version-number, -request-id, attributes-charset, and attributes-natural-language as the -provided request message. If the attributes-charset or -attributes-natural-language attributes are missing from the request, -"utf-8" and a value derived from the current locale are substituted, -respectively. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippNextAttribute">ippNextAttribute</a></h3> - <p class="description">Return the next attribute in the message.</p> -<p class="code"> -<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippNextAttribute (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Next attribute or <code>NULL</code> if none</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippOpString">ippOpString</a></h3> - <p class="description">Return a name for the given operation id.</p> -<p class="code"> -const char *ippOpString (<br /> -    ipp_op_t op<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>op</dt> - <dd class="description">Operation ID</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Name</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippOpValue">ippOpValue</a></h3> - <p class="description">Return an operation id for the given name.</p> -<p class="code"> -ipp_op_t ippOpValue (<br /> -    const char *name<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Textual name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Operation ID</p> -<h3 class="function"><a id="ippPort">ippPort</a></h3> - <p class="description">Return the default IPP port number.</p> -<p class="code"> -int ippPort (void);</p> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Port number</p> -<h3 class="function"><a id="ippRead">ippRead</a></h3> - <p class="description">Read data for an IPP message from a HTTP connection.</p> -<p class="code"> -<a href="#ipp_state_t">ipp_state_t</a> ippRead (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>ipp</dt> - <dd class="description">IPP data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Current state</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ippReadFile">ippReadFile</a></h3> - <p class="description">Read data for an IPP message from a file.</p> -<p class="code"> -<a href="#ipp_state_t">ipp_state_t</a> ippReadFile (<br /> -    int fd,<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fd</dt> - <dd class="description">HTTP data</dd> -<dt>ipp</dt> - <dd class="description">IPP data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Current state</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippReadIO">ippReadIO</a></h3> - <p class="description">Read data for an IPP message.</p> -<p class="code"> -<a href="#ipp_state_t">ipp_state_t</a> ippReadIO (<br /> -    void *src,<br /> -    <a href="#ipp_iocb_t">ipp_iocb_t</a> cb,<br /> -    int blocking,<br /> -    <a href="#ipp_t">ipp_t</a> *parent,<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>src</dt> - <dd class="description">Data source</dd> -<dt>cb</dt> - <dd class="description">Read callback function</dd> -<dt>blocking</dt> - <dd class="description">Use blocking IO?</dd> -<dt>parent</dt> - <dd class="description">Parent request, if any</dd> -<dt>ipp</dt> - <dd class="description">IPP data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Current state</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetBoolean">ippSetBoolean</a></h3> - <p class="description">Set a boolean value in an attribute.</p> -<p class="code"> -int ippSetBoolean (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    int element,<br /> -    int boolvalue<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>boolvalue</dt> - <dd class="description">Boolean value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -The <code>element</code> parameter specifies which value to set from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetCollection">ippSetCollection</a></h3> - <p class="description">Set a collection value in an attribute.</p> -<p class="code"> -int ippSetCollection (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    int element,<br /> -    <a href="#ipp_t">ipp_t</a> *colvalue<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>colvalue</dt> - <dd class="description">Collection value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -The <code>element</code> parameter specifies which value to set from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetDate">ippSetDate</a></h3> - <p class="description">Set a date value in an attribute.</p> -<p class="code"> -int ippSetDate (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    int element,<br /> -    const <a href="#ipp_uchar_t">ipp_uchar_t</a> *datevalue<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>datevalue</dt> - <dd class="description">Date value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -The <code>element</code> parameter specifies which value to set from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetGroupTag">ippSetGroupTag</a></h3> - <p class="description">Set the group tag of an attribute.</p> -<p class="code"> -int ippSetGroupTag (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    ipp_tag_t group_tag<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">Attribute</dd> -<dt>group_tag</dt> - <dd class="description">Group tag</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -The <code>group</code> parameter specifies the IPP attribute group tag: none -(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), -event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation -(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription -(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetInteger">ippSetInteger</a></h3> - <p class="description">Set an integer or enum value in an attribute.</p> -<p class="code"> -int ippSetInteger (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    int element,<br /> -    int intvalue<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>intvalue</dt> - <dd class="description">Integer/enum value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -The <code>element</code> parameter specifies which value to set from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetName">ippSetName</a></h3> - <p class="description">Set the name of an attribute.</p> -<p class="code"> -int ippSetName (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    const char *name<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>name</dt> - <dd class="description">Attribute name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippSetOctetString">ippSetOctetString</a></h3> - <p class="description">Set an octetString value in an IPP attribute.</p> -<p class="code"> -int ippSetOctetString (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    int element,<br /> -    const void *data,<br /> -    int datalen<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>data</dt> - <dd class="description">Pointer to octetString data</dd> -<dt>datalen</dt> - <dd class="description">Length of octetString data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -The <code>element</code> parameter specifies which value to set from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetOperation">ippSetOperation</a></h3> - <p class="description">Set the operation ID in an IPP request message.</p> -<p class="code"> -int ippSetOperation (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_op_t op<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP request message</dd> -<dt>op</dt> - <dd class="description">Operation ID</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions. - -</p> -<h3 class="function"><a id="ippSetPort">ippSetPort</a></h3> - <p class="description">Set the default port number.</p> -<p class="code"> -void ippSetPort (<br /> -    int p<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>p</dt> - <dd class="description">Port number to use</dd> -</dl> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetRange">ippSetRange</a></h3> - <p class="description">Set a rangeOfInteger value in an attribute.</p> -<p class="code"> -int ippSetRange (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    int element,<br /> -    int lowervalue,<br /> -    int uppervalue<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>lowervalue</dt> - <dd class="description">Lower bound for range</dd> -<dt>uppervalue</dt> - <dd class="description">Upper bound for range</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -The <code>element</code> parameter specifies which value to set from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetRequestId">ippSetRequestId</a></h3> - <p class="description">Set the request ID in an IPP message.</p> -<p class="code"> -int ippSetRequestId (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    int request_id<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>request_id</dt> - <dd class="description">Request ID</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>request_id</code> parameter must be greater than 0. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetResolution">ippSetResolution</a></h3> - <p class="description">Set a resolution value in an attribute.</p> -<p class="code"> -int ippSetResolution (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    int element,<br /> -    <a href="#ipp_res_t">ipp_res_t</a> unitsvalue,<br /> -    int xresvalue,<br /> -    int yresvalue<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>unitsvalue</dt> - <dd class="description">Resolution units</dd> -<dt>xresvalue</dt> - <dd class="description">Horizontal/cross feed resolution</dd> -<dt>yresvalue</dt> - <dd class="description">Vertical/feed resolution</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -The <code>element</code> parameter specifies which value to set from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetState">ippSetState</a></h3> - <p class="description">Set the current state of the IPP message.</p> -<p class="code"> -int ippSetState (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_state_t">ipp_state_t</a> state<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>state</dt> - <dd class="description">IPP state value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetStatusCode">ippSetStatusCode</a></h3> - <p class="description">Set the status code in an IPP response or event message.</p> -<p class="code"> -int ippSetStatusCode (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    ipp_status_t status<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP response or event message</dd> -<dt>status</dt> - <dd class="description">Status code</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetString">ippSetString</a></h3> - <p class="description">Set a string value in an attribute.</p> -<p class="code"> -int ippSetString (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    int element,<br /> -    const char *strvalue<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>strvalue</dt> - <dd class="description">String value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -The <code>element</code> parameter specifies which value to set from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippSetStringf">ippSetStringf</a></h3> - <p class="description">Set a formatted string value of an attribute.</p> -<p class="code"> -int ippSetStringf (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    int element,<br /> -    const char *format,<br /> -    ...<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>format</dt> - <dd class="description">Printf-style format string</dd> -<dt>...</dt> - <dd class="description">Additional arguments as needed</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -The <code>element</code> parameter specifies which value to set from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.<br> -<br> -The <code>format</code> parameter uses formatting characters compatible with the -printf family of standard functions. Additional arguments follow it as -needed. The formatted string is truncated as needed to the maximum length of -the corresponding value type. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippSetStringfv">ippSetStringfv</a></h3> - <p class="description">Set a formatted string value of an attribute.</p> -<p class="code"> -int ippSetStringfv (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    int element,<br /> -    const char *format,<br /> -    va_list ap<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>element</dt> - <dd class="description">Value number (0-based)</dd> -<dt>format</dt> - <dd class="description">Printf-style format string</dd> -<dt>ap</dt> - <dd class="description">Pointer to additional arguments</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -The <code>element</code> parameter specifies which value to set from 0 to -<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.<br> -<br> -The <code>format</code> parameter uses formatting characters compatible with the -printf family of standard functions. Additional arguments follow it as -needed. The formatted string is truncated as needed to the maximum length of -the corresponding value type. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetValueTag">ippSetValueTag</a></h3> - <p class="description">Set the value tag of an attribute.</p> -<p class="code"> -int ippSetValueTag (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br /> -    ipp_tag_t value_tag<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>attr</dt> - <dd class="description">IPP attribute</dd> -<dt>value_tag</dt> - <dd class="description">Value tag</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The <code>attr</code> parameter may be modified as a result of setting the value.<br> -<br> -Integer (<code>IPP_TAG_INTEGER</code>) values can be promoted to rangeOfInteger -(<code>IPP_TAG_RANGE</code>) values, the various string tags can be promoted to name -(<code>IPP_TAG_NAME</code>) or nameWithLanguage (<code>IPP_TAG_NAMELANG</code>) values, text -(<code>IPP_TAG_TEXT</code>) values can be promoted to textWithLanguage -(<code>IPP_TAG_TEXTLANG</code>) values, and all values can be demoted to the various -out-of-band value tags such as no-value (<code>IPP_TAG_NOVALUE</code>). All other changes -will be rejected.<br> -<br> -Promoting a string attribute to nameWithLanguage or textWithLanguage adds the language -code in the "attributes-natural-language" attribute or, if not present, the language -code for the current locale. - -</p> -<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetVersion">ippSetVersion</a></h3> - <p class="description">Set the version number in an IPP message.</p> -<p class="code"> -int ippSetVersion (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp,<br /> -    int major,<br /> -    int minor<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -<dt>major</dt> - <dd class="description">Major version number (major.minor)</dd> -<dt>minor</dt> - <dd class="description">Minor version number (major.minor)</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 on success, 0 on failure</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using -the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> -<br> -The valid version numbers are currently 1.0, 1.1, 2.0, 2.1, and 2.2. - -</p> -<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="ippStateString">ippStateString</a></h3> - <p class="description">Return the name corresponding to a state value.</p> -<p class="code"> -const char *ippStateString (<br /> -    <a href="#ipp_state_t">ipp_state_t</a> state<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>state</dt> - <dd class="description">State value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">State name</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="ippTagString">ippTagString</a></h3> - <p class="description">Return the tag name corresponding to a tag value.</p> -<p class="code"> -const char *ippTagString (<br /> -    ipp_tag_t tag<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>tag</dt> - <dd class="description">Tag value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Tag name</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The returned names are defined in RFC 2911 and 3382. - -</p> -<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="ippTagValue">ippTagValue</a></h3> - <p class="description">Return the tag value corresponding to a tag name.</p> -<p class="code"> -ipp_tag_t ippTagValue (<br /> -    const char *name<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>name</dt> - <dd class="description">Tag name</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Tag value</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">The tag names are defined in RFC 2911 and 3382. - -</p> -<h3 class="function"><a id="ippTimeToDate">ippTimeToDate</a></h3> - <p class="description">Convert from UNIX time to RFC 1903 format.</p> -<p class="code"> -const <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippTimeToDate (<br /> -    time_t t<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>t</dt> - <dd class="description">UNIX time value</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">RFC-1903 date/time data</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippValidateAttribute">ippValidateAttribute</a></h3> - <p class="description">Validate the contents of an attribute.</p> -<p class="code"> -int ippValidateAttribute (<br /> -    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>attr</dt> - <dd class="description">Attribute</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if valid, 0 otherwise</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function validates the contents of an attribute based on the name and -value tag. 1 is returned if the attribute is valid, 0 otherwise. On -failure, cupsLastErrorString() is set to a human-readable message. - -</p> -<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippValidateAttributes">ippValidateAttributes</a></h3> - <p class="description">Validate all attributes in an IPP message.</p> -<p class="code"> -int ippValidateAttributes (<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>ipp</dt> - <dd class="description">IPP message</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">1 if valid, 0 otherwise</p> -<h4 class="discussion">Discussion</h4> - <p class="discussion">This function validates the contents of the IPP message, including each -attribute. Like <a href="#ippValidateAttribute"><code>ippValidateAttribute</code></a>, cupsLastErrorString() is set -to a human-readable message on failure. - -</p> -<h3 class="function"><a id="ippWrite">ippWrite</a></h3> - <p class="description">Write data for an IPP message to a HTTP connection.</p> -<p class="code"> -<a href="#ipp_state_t">ipp_state_t</a> ippWrite (<br /> -    <a href="#http_t">http_t</a> *http,<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>http</dt> - <dd class="description">HTTP connection</dd> -<dt>ipp</dt> - <dd class="description">IPP data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Current state</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ippWriteFile">ippWriteFile</a></h3> - <p class="description">Write data for an IPP message to a file.</p> -<p class="code"> -<a href="#ipp_state_t">ipp_state_t</a> ippWriteFile (<br /> -    int fd,<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>fd</dt> - <dd class="description">HTTP data</dd> -<dt>ipp</dt> - <dd class="description">IPP data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Current state</p> -<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippWriteIO">ippWriteIO</a></h3> - <p class="description">Write data for an IPP message.</p> -<p class="code"> -<a href="#ipp_state_t">ipp_state_t</a> ippWriteIO (<br /> -    void *dst,<br /> -    <a href="#ipp_iocb_t">ipp_iocb_t</a> cb,<br /> -    int blocking,<br /> -    <a href="#ipp_t">ipp_t</a> *parent,<br /> -    <a href="#ipp_t">ipp_t</a> *ipp<br /> -);</p> -<h4 class="parameters">Parameters</h4> -<dl> -<dt>dst</dt> - <dd class="description">Destination</dd> -<dt>cb</dt> - <dd class="description">Write callback function</dd> -<dt>blocking</dt> - <dd class="description">Use blocking IO?</dd> -<dt>parent</dt> - <dd class="description">Parent IPP message</dd> -<dt>ipp</dt> - <dd class="description">IPP data</dd> -</dl> -<h4 class="returnvalue">Return Value</h4> - <p class="description">Current state</p> - <h2 class="title"><a id="TYPES">Data Types</a></h2> - <h3 class="typedef"><a id="gss_auth_identity_desc">gss_auth_identity_desc</a></h3> - <p class="description">Local functions...</p> - <p class="code"> -typedef struct <a href="#gss_auth_identity">gss_auth_identity</a> gss_auth_identity_desc; -</p> - <h3 class="typedef"><a id="http_addr_t"><span class="info"> CUPS 1.2/macOS 10.5 </span>http_addr_t</a></h3> - <p class="description">Socket address union, which -makes using IPv6 and other -address types easier and -more portable. </p> - <p class="code"> -typedef union _http_addr_u / http_addr_t; -</p> - <h3 class="typedef"><a id="http_addrlist_t"><span class="info"> CUPS 1.2/macOS 10.5 </span>http_addrlist_t</a></h3> - <p class="description">Socket address list, which is -used to enumerate all of the -addresses that are associated -with a hostname. </p> - <p class="code"> -typedef struct <a href="#http_addrlist_s">http_addrlist_s</a> / http_addrlist_t; -</p> - <h3 class="typedef"><a id="http_auth_t">http_auth_t</a></h3> - <p class="description">HTTP authentication types</p> - <p class="code"> -typedef enum <a href="#http_auth_e">http_auth_e</a> http_auth_t; -</p> - <h3 class="typedef"><a id="http_credential_t"><span class="info"> CUPS 1.5/macOS 10.7 </span>http_credential_t</a></h3> - <p class="description">HTTP credential data </p> - <p class="code"> -typedef struct <a href="#http_credential_s">http_credential_s</a> http_credential_t; -</p> - <h3 class="typedef"><a id="http_encoding_t">http_encoding_t</a></h3> - <p class="description">HTTP transfer encoding values</p> - <p class="code"> -typedef enum <a href="#http_encoding_e">http_encoding_e</a> http_encoding_t; -</p> - <h3 class="typedef"><a id="http_encryption_t">http_encryption_t</a></h3> - <p class="description">HTTP encryption values</p> - <p class="code"> -typedef enum <a href="#http_encryption_e">http_encryption_e</a> http_encryption_t; -</p> - <h3 class="typedef"><a id="http_field_t">http_field_t</a></h3> - <p class="description">HTTP field names</p> - <p class="code"> -typedef enum <a href="#http_field_e">http_field_e</a> http_field_t; -</p> - <h3 class="typedef"><a id="http_keepalive_t">http_keepalive_t</a></h3> - <p class="description">HTTP keep-alive values</p> - <p class="code"> -typedef enum <a href="#http_keepalive_e">http_keepalive_e</a> http_keepalive_t; -</p> - <h3 class="typedef"><a id="http_state_t">http_state_t</a></h3> - <p class="description">HTTP state values; states -are server-oriented...</p> - <p class="code"> -typedef enum <a href="#http_state_e">http_state_e</a> http_state_t; -</p> - <h3 class="typedef"><a id="http_t">http_t</a></h3> - <p class="description">HTTP connection type</p> - <p class="code"> -typedef struct _http_s http_t; -</p> - <h3 class="typedef"><a id="http_timeout_cb_t"><span class="info"> CUPS 1.5/macOS 10.7 </span>http_timeout_cb_t</a></h3> - <p class="description">HTTP timeout callback </p> - <p class="code"> -typedef int (*http_timeout_cb_t)(<a href="#http_t">http_t</a> *http, void *user_data); -</p> - <h3 class="typedef"><a id="http_trust_t"><span class="info"> CUPS 2.0/OS 10.10 </span>http_trust_t</a></h3> - <p class="description">Level of trust for credentials </p> - <p class="code"> -typedef enum <a href="#http_trust_e">http_trust_e</a> http_trust_t; -</p> - <h3 class="typedef"><a id="http_uri_coding_t">http_uri_coding_t</a></h3> - <p class="description">URI en/decode flags</p> - <p class="code"> -typedef enum <a href="#http_uri_coding_e">http_uri_coding_e</a> http_uri_coding_t; -</p> - <h3 class="typedef"><a id="http_uri_status_t"><span class="info"> CUPS 1.2 </span>http_uri_status_t</a></h3> - <p class="description">URI separation status </p> - <p class="code"> -typedef enum <a href="#http_uri_status_e">http_uri_status_e</a> http_uri_status_t; -</p> - <h3 class="typedef"><a id="http_version_t">http_version_t</a></h3> - <p class="description">HTTP version numbers</p> - <p class="code"> -typedef enum <a href="#http_version_e">http_version_e</a> http_version_t; -</p> - <h3 class="typedef"><a id="ipp_attribute_t">ipp_attribute_t</a></h3> - <p class="description">IPP attribute</p> - <p class="code"> -typedef struct _ipp_attribute_s ipp_attribute_t; -</p> - <h3 class="typedef"><a id="ipp_copycb_t">ipp_copycb_t</a></h3> - <p class="description">The following structures are PRIVATE starting with CUPS 1.6/macOS 10.8. -Please use the new accessor functions available in CUPS 1.6 and later, as -these definitions will be moved to a private header file in a future release.</p> - <p class="code"> -typedef int (*ipp_copycb_t)(void *context, <a href="#ipp_t">ipp_t</a> *dst, <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr); -</p> - <h3 class="typedef"><a id="ipp_dstate_t">ipp_dstate_t</a></h3> - <p class="description">Document states</p> - <p class="code"> -typedef enum <a href="#ipp_dstate_e">ipp_dstate_e</a> ipp_dstate_t; -</p> - <h3 class="typedef"><a id="ipp_finish_t">ipp_finish_t</a></h3> - <p class="description">Job collation types</p> - <p class="code"> -typedef enum <a href="#ipp_finishings_e">ipp_finishings_e</a> ipp_finish_t; -</p> - <h3 class="typedef"><a id="ipp_iocb_t"><span class="info"> CUPS 1.2/macOS 10.5 </span>ipp_iocb_t</a></h3> - <p class="description">IPP IO Callback Function </p> - <p class="code"> -typedef ssize_t (*ipp_iocb_t)(void *context, <a href="#ipp_uchar_t">ipp_uchar_t</a> *buffer, size_t bytes); -</p> - <h3 class="typedef"><a id="ipp_jcollate_t">ipp_jcollate_t</a></h3> - <p class="description">Job collation types</p> - <p class="code"> -typedef enum <a href="#ipp_jcollate_e">ipp_jcollate_e</a> ipp_jcollate_t; -</p> - <h3 class="typedef"><a id="ipp_orient_t">ipp_orient_t</a></h3> - <p class="description">Orientation values</p> - <p class="code"> -typedef enum <a href="#ipp_orient_e">ipp_orient_e</a> ipp_orient_t; -</p> - <h3 class="typedef"><a id="ipp_pstate_t">ipp_pstate_t</a></h3> - <p class="description">Printer states</p> - <p class="code"> -typedef enum <a href="#ipp_pstate_e">ipp_pstate_e</a> ipp_pstate_t; -</p> - <h3 class="typedef"><a id="ipp_quality_t">ipp_quality_t</a></h3> - <p class="description">Qualities</p> - <p class="code"> -typedef enum <a href="#ipp_quality_e">ipp_quality_e</a> ipp_quality_t; -</p> - <h3 class="typedef"><a id="ipp_res_t">ipp_res_t</a></h3> - <p class="description">Resolution units</p> - <p class="code"> -typedef enum <a href="#ipp_res_e">ipp_res_e</a> ipp_res_t; -</p> - <h3 class="typedef"><a id="ipp_state_t">ipp_state_t</a></h3> - <p class="description">IPP states</p> - <p class="code"> -typedef enum <a href="#ipp_state_e">ipp_state_e</a> ipp_state_t; -</p> - <h3 class="typedef"><a id="ipp_t">ipp_t</a></h3> - <p class="description">IPP request/response data</p> - <p class="code"> -typedef struct _ipp_s ipp_t; -</p> - <h3 class="typedef"><a id="ipp_uchar_t">ipp_uchar_t</a></h3> - <p class="description">Unsigned 8-bit integer/character</p> - <p class="code"> -typedef unsigned char ipp_uchar_t; -</p> - <h2 class="title"><a id="STRUCTURES">Structures</a></h2> -<h3 class="struct"><a id="gss_auth_identity">gss_auth_identity</a></h3> - <p class="description">Local functions...</p> -<p class="code">struct gss_auth_identity {<br /> -    gss_buffer_t *credentialsRef;<br /> -    uint32_t flags;<br /> -    char *password;<br /> -    char *realm;<br /> -    uint32_t type;<br /> -    char *username;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>credentialsRef </dt> -<dt>flags </dt> -<dt>password </dt> -<dt>realm </dt> -<dt>type </dt> -<dt>username </dt> -</dl> -<h3 class="struct"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="http_addrlist_s">http_addrlist_s</a></h3> - <p class="description">Socket address list, which is -used to enumerate all of the -addresses that are associated -with a hostname. </p> -<p class="code">struct http_addrlist_s {<br /> -    <a href="#http_addr_t">http_addr_t</a> addr;<br /> -    struct <a href="#http_addrlist_s">http_addrlist_s</a> *next;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>addr </dt> - <dd class="description">Address</dd> -<dt>next </dt> - <dd class="description">Pointer to next address in list</dd> -</dl> -<h3 class="struct"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="http_credential_s">http_credential_s</a></h3> - <p class="description">HTTP credential data </p> -<p class="code">struct http_credential_s {<br /> -    void *data;<br /> -    size_t datalen;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>data </dt> - <dd class="description">Pointer to credential data</dd> -<dt>datalen </dt> - <dd class="description">Credential length</dd> -</dl> -<h3 class="struct"><a id="pollfd">pollfd</a></h3> - <p class="description">User data (unused)</p> -<p class="code">struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {<br /> -    void) context;<br /> -    void) timeout;<br /> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>context </dt> -<dt>timeout </dt> -</dl> - <h2 class="title"><a id="ENUMERATIONS">Constants</a></h2> - <h3 class="enumeration"><a id="http_auth_e">http_auth_e</a></h3> - <p class="description">HTTP authentication types</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>HTTP_AUTH_BASIC </dt> - <dd class="description">Basic authentication in use</dd> - <dt>HTTP_AUTH_MD5 </dt> - <dd class="description">Digest authentication in use</dd> - <dt>HTTP_AUTH_MD5_INT </dt> - <dd class="description">Digest authentication in use for body</dd> - <dt>HTTP_AUTH_MD5_SESS </dt> - <dd class="description">MD5-session authentication in use</dd> - <dt>HTTP_AUTH_MD5_SESS_INT </dt> - <dd class="description">MD5-session authentication in use for body</dd> - <dt>HTTP_AUTH_NEGOTIATE <span class="info"> CUPS 1.3/macOS 10.5 </span></dt> - <dd class="description">GSSAPI authentication in use </dd> - <dt>HTTP_AUTH_NONE </dt> - <dd class="description">No authentication in use</dd> -</dl> - <h3 class="enumeration"><a id="http_encoding_e">http_encoding_e</a></h3> - <p class="description">HTTP transfer encoding values</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>HTTP_ENCODING_CHUNKED </dt> - <dd class="description">Data is chunked</dd> - <dt>HTTP_ENCODING_FIELDS </dt> - <dd class="description">Sending HTTP fields</dd> - <dt>HTTP_ENCODING_LENGTH </dt> - <dd class="description">Data is sent with Content-Length</dd> -</dl> - <h3 class="enumeration"><a id="http_encryption_e">http_encryption_e</a></h3> - <p class="description">HTTP encryption values</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>HTTP_ENCRYPTION_ALWAYS </dt> - <dd class="description">Always encrypt (SSL)</dd> - <dt>HTTP_ENCRYPTION_IF_REQUESTED </dt> - <dd class="description">Encrypt if requested (TLS upgrade)</dd> - <dt>HTTP_ENCRYPTION_NEVER </dt> - <dd class="description">Never encrypt</dd> - <dt>HTTP_ENCRYPTION_REQUIRED </dt> - <dd class="description">Encryption is required (TLS upgrade)</dd> -</dl> - <h3 class="enumeration"><a id="http_field_e">http_field_e</a></h3> - <p class="description">HTTP field names</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>HTTP_FIELD_ACCEPT_ENCODING <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> - <dd class="description">Accepting-Encoding field </dd> - <dt>HTTP_FIELD_ACCEPT_LANGUAGE </dt> - <dd class="description">Accept-Language field</dd> - <dt>HTTP_FIELD_ACCEPT_RANGES </dt> - <dd class="description">Accept-Ranges field</dd> - <dt>HTTP_FIELD_ALLOW <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> - <dd class="description">Allow field </dd> - <dt>HTTP_FIELD_AUTHORIZATION </dt> - <dd class="description">Authorization field</dd> - <dt>HTTP_FIELD_CONNECTION </dt> - <dd class="description">Connection field</dd> - <dt>HTTP_FIELD_CONTENT_ENCODING </dt> - <dd class="description">Content-Encoding field</dd> - <dt>HTTP_FIELD_CONTENT_LANGUAGE </dt> - <dd class="description">Content-Language field</dd> - <dt>HTTP_FIELD_CONTENT_LENGTH </dt> - <dd class="description">Content-Length field</dd> - <dt>HTTP_FIELD_CONTENT_LOCATION </dt> - <dd class="description">Content-Location field</dd> - <dt>HTTP_FIELD_CONTENT_MD5 </dt> - <dd class="description">Content-MD5 field</dd> - <dt>HTTP_FIELD_CONTENT_RANGE </dt> - <dd class="description">Content-Range field</dd> - <dt>HTTP_FIELD_CONTENT_TYPE </dt> - <dd class="description">Content-Type field</dd> - <dt>HTTP_FIELD_CONTENT_VERSION </dt> - <dd class="description">Content-Version field</dd> - <dt>HTTP_FIELD_DATE </dt> - <dd class="description">Date field</dd> - <dt>HTTP_FIELD_HOST </dt> - <dd class="description">Host field</dd> - <dt>HTTP_FIELD_IF_MODIFIED_SINCE </dt> - <dd class="description">If-Modified-Since field</dd> - <dt>HTTP_FIELD_IF_UNMODIFIED_SINCE </dt> - <dd class="description">If-Unmodified-Since field</dd> - <dt>HTTP_FIELD_KEEP_ALIVE </dt> - <dd class="description">Keep-Alive field</dd> - <dt>HTTP_FIELD_LAST_MODIFIED </dt> - <dd class="description">Last-Modified field</dd> - <dt>HTTP_FIELD_LINK </dt> - <dd class="description">Link field</dd> - <dt>HTTP_FIELD_LOCATION </dt> - <dd class="description">Location field</dd> - <dt>HTTP_FIELD_MAX </dt> - <dd class="description">Maximum field index</dd> - <dt>HTTP_FIELD_RANGE </dt> - <dd class="description">Range field</dd> - <dt>HTTP_FIELD_REFERER </dt> - <dd class="description">Referer field</dd> - <dt>HTTP_FIELD_RETRY_AFTER </dt> - <dd class="description">Retry-After field</dd> - <dt>HTTP_FIELD_SERVER <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> - <dd class="description">Server field </dd> - <dt>HTTP_FIELD_TRANSFER_ENCODING </dt> - <dd class="description">Transfer-Encoding field</dd> - <dt>HTTP_FIELD_UNKNOWN </dt> - <dd class="description">Unknown field</dd> - <dt>HTTP_FIELD_UPGRADE </dt> - <dd class="description">Upgrade field</dd> - <dt>HTTP_FIELD_USER_AGENT </dt> - <dd class="description">User-Agent field</dd> - <dt>HTTP_FIELD_WWW_AUTHENTICATE </dt> - <dd class="description">WWW-Authenticate field</dd> -</dl> - <h3 class="enumeration"><a id="http_keepalive_e">http_keepalive_e</a></h3> - <p class="description">HTTP keep-alive values</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>HTTP_KEEPALIVE_OFF </dt> - <dd class="description">No keep alive support</dd> - <dt>HTTP_KEEPALIVE_ON </dt> - <dd class="description">Use keep alive</dd> -</dl> - <h3 class="enumeration"><a id="http_state_e">http_state_e</a></h3> - <p class="description">HTTP state values; states -are server-oriented...</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>HTTP_STATE_CONNECT </dt> - <dd class="description">CONNECT command, waiting for blank line</dd> - <dt>HTTP_STATE_DELETE </dt> - <dd class="description">DELETE command, waiting for blank line</dd> - <dt>HTTP_STATE_ERROR </dt> - <dd class="description">Error on socket</dd> - <dt>HTTP_STATE_GET </dt> - <dd class="description">GET command, waiting for blank line</dd> - <dt>HTTP_STATE_GET_SEND </dt> - <dd class="description">GET command, sending data</dd> - <dt>HTTP_STATE_HEAD </dt> - <dd class="description">HEAD command, waiting for blank line</dd> - <dt>HTTP_STATE_OPTIONS </dt> - <dd class="description">OPTIONS command, waiting for blank line</dd> - <dt>HTTP_STATE_POST </dt> - <dd class="description">POST command, waiting for blank line</dd> - <dt>HTTP_STATE_POST_RECV </dt> - <dd class="description">POST command, receiving data</dd> - <dt>HTTP_STATE_POST_SEND </dt> - <dd class="description">POST command, sending data</dd> - <dt>HTTP_STATE_PUT </dt> - <dd class="description">PUT command, waiting for blank line</dd> - <dt>HTTP_STATE_PUT_RECV </dt> - <dd class="description">PUT command, receiving data</dd> - <dt>HTTP_STATE_STATUS </dt> - <dd class="description">Command complete, sending status</dd> - <dt>HTTP_STATE_TRACE </dt> - <dd class="description">TRACE command, waiting for blank line</dd> - <dt>HTTP_STATE_UNKNOWN_METHOD <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> - <dd class="description">Unknown request method, waiting for blank line </dd> - <dt>HTTP_STATE_UNKNOWN_VERSION <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> - <dd class="description">Unknown request method, waiting for blank line </dd> - <dt>HTTP_STATE_WAITING </dt> - <dd class="description">Waiting for command</dd> -</dl> - <h3 class="enumeration"><a id="http_status_e">http_status_e</a></h3> - <p class="description">HTTP status codes</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>HTTP_STATUS_ACCEPTED </dt> - <dd class="description">DELETE command was successful</dd> - <dt>HTTP_STATUS_BAD_GATEWAY </dt> - <dd class="description">Bad gateway</dd> - <dt>HTTP_STATUS_BAD_REQUEST </dt> - <dd class="description">Bad request</dd> - <dt>HTTP_STATUS_CONFLICT </dt> - <dd class="description">Request is self-conflicting</dd> - <dt>HTTP_STATUS_CONTINUE </dt> - <dd class="description">Everything OK, keep going...</dd> - <dt>HTTP_STATUS_CREATED </dt> - <dd class="description">PUT command was successful</dd> - <dt>HTTP_STATUS_CUPS_AUTHORIZATION_CANCELED <span class="info"> CUPS 1.4 </span></dt> - <dd class="description">User canceled authorization </dd> - <dt>HTTP_STATUS_CUPS_PKI_ERROR <span class="info"> CUPS 1.5/macOS 10.7 </span></dt> - <dd class="description">Error negotiating a secure connection </dd> - <dt>HTTP_STATUS_ERROR </dt> - <dd class="description">An error response from httpXxxx()</dd> - <dt>HTTP_STATUS_EXPECTATION_FAILED </dt> - <dd class="description">The expectation given in an Expect header field was not met</dd> - <dt>HTTP_STATUS_FORBIDDEN </dt> - <dd class="description">Forbidden to access this URI</dd> - <dt>HTTP_STATUS_GATEWAY_TIMEOUT </dt> - <dd class="description">Gateway connection timed out</dd> - <dt>HTTP_STATUS_GONE </dt> - <dd class="description">Server has gone away</dd> - <dt>HTTP_STATUS_LENGTH_REQUIRED </dt> - <dd class="description">A content length or encoding is required</dd> - <dt>HTTP_STATUS_METHOD_NOT_ALLOWED </dt> - <dd class="description">Method is not allowed</dd> - <dt>HTTP_STATUS_MOVED_PERMANENTLY </dt> - <dd class="description">Document has moved permanently</dd> - <dt>HTTP_STATUS_MOVED_TEMPORARILY </dt> - <dd class="description">Document has moved temporarily</dd> - <dt>HTTP_STATUS_MULTIPLE_CHOICES </dt> - <dd class="description">Multiple files match request</dd> - <dt>HTTP_STATUS_NONE <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> - <dd class="description">No Expect value </dd> - <dt>HTTP_STATUS_NOT_ACCEPTABLE </dt> - <dd class="description">Not Acceptable</dd> - <dt>HTTP_STATUS_NOT_AUTHORITATIVE </dt> - <dd class="description">Information isn't authoritative</dd> - <dt>HTTP_STATUS_NOT_FOUND </dt> - <dd class="description">URI was not found</dd> - <dt>HTTP_STATUS_NOT_IMPLEMENTED </dt> - <dd class="description">Feature not implemented</dd> - <dt>HTTP_STATUS_NOT_MODIFIED </dt> - <dd class="description">File not modified</dd> - <dt>HTTP_STATUS_NOT_SUPPORTED </dt> - <dd class="description">HTTP version not supported</dd> - <dt>HTTP_STATUS_NO_CONTENT </dt> - <dd class="description">Successful command, no new data</dd> - <dt>HTTP_STATUS_OK </dt> - <dd class="description">OPTIONS/GET/HEAD/POST/TRACE command was successful</dd> - <dt>HTTP_STATUS_PARTIAL_CONTENT </dt> - <dd class="description">Only a partial file was received/sent</dd> - <dt>HTTP_STATUS_PAYMENT_REQUIRED </dt> - <dd class="description">Payment required</dd> - <dt>HTTP_STATUS_PRECONDITION </dt> - <dd class="description">Precondition failed</dd> - <dt>HTTP_STATUS_PROXY_AUTHENTICATION </dt> - <dd class="description">Proxy Authentication is Required</dd> - <dt>HTTP_STATUS_REQUESTED_RANGE </dt> - <dd class="description">The requested range is not satisfiable</dd> - <dt>HTTP_STATUS_REQUEST_TIMEOUT </dt> - <dd class="description">Request timed out</dd> - <dt>HTTP_STATUS_REQUEST_TOO_LARGE </dt> - <dd class="description">Request entity too large</dd> - <dt>HTTP_STATUS_RESET_CONTENT </dt> - <dd class="description">Content was reset/recreated</dd> - <dt>HTTP_STATUS_SEE_OTHER </dt> - <dd class="description">See this other link...</dd> - <dt>HTTP_STATUS_SERVER_ERROR </dt> - <dd class="description">Internal server error</dd> - <dt>HTTP_STATUS_SERVICE_UNAVAILABLE </dt> - <dd class="description">Service is unavailable</dd> - <dt>HTTP_STATUS_SWITCHING_PROTOCOLS </dt> - <dd class="description">HTTP upgrade to TLS/SSL</dd> - <dt>HTTP_STATUS_UNAUTHORIZED </dt> - <dd class="description">Unauthorized to access host</dd> - <dt>HTTP_STATUS_UNSUPPORTED_MEDIATYPE </dt> - <dd class="description">The requested media type is unsupported</dd> - <dt>HTTP_STATUS_UPGRADE_REQUIRED </dt> - <dd class="description">Upgrade to SSL/TLS required</dd> - <dt>HTTP_STATUS_URI_TOO_LONG </dt> - <dd class="description">URI too long</dd> - <dt>HTTP_STATUS_USE_PROXY </dt> - <dd class="description">Must use a proxy to access this URI</dd> -</dl> - <h3 class="enumeration"><a id="http_trust_e"><span class="info"> CUPS 2.0/OS 10.10 </span>http_trust_e</a></h3> - <p class="description">Level of trust for credentials </p> - <h4 class="constants">Constants</h4> - <dl> - <dt>HTTP_TRUST_CHANGED </dt> - <dd class="description">Credentials have changed</dd> - <dt>HTTP_TRUST_EXPIRED </dt> - <dd class="description">Credentials are expired</dd> - <dt>HTTP_TRUST_INVALID </dt> - <dd class="description">Credentials are invalid</dd> - <dt>HTTP_TRUST_OK </dt> - <dd class="description">Credentials are OK/trusted</dd> - <dt>HTTP_TRUST_RENEWED </dt> - <dd class="description">Credentials have been renewed</dd> - <dt>HTTP_TRUST_UNKNOWN </dt> - <dd class="description">Credentials are unknown/new</dd> -</dl> - <h3 class="enumeration"><a id="http_uri_coding_e">http_uri_coding_e</a></h3> - <p class="description">URI en/decode flags</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>HTTP_URI_CODING_ALL </dt> - <dd class="description">En/decode everything</dd> - <dt>HTTP_URI_CODING_HOSTNAME </dt> - <dd class="description">En/decode the hostname portion</dd> - <dt>HTTP_URI_CODING_MOST </dt> - <dd class="description">En/decode all but the query</dd> - <dt>HTTP_URI_CODING_NONE </dt> - <dd class="description">Don't en/decode anything</dd> - <dt>HTTP_URI_CODING_QUERY </dt> - <dd class="description">En/decode the query portion</dd> - <dt>HTTP_URI_CODING_RESOURCE </dt> - <dd class="description">En/decode the resource portion</dd> - <dt>HTTP_URI_CODING_RFC6874 </dt> - <dd class="description">Use RFC 6874 address format</dd> - <dt>HTTP_URI_CODING_USERNAME </dt> - <dd class="description">En/decode the username portion</dd> -</dl> - <h3 class="enumeration"><a id="http_uri_status_e"><span class="info"> CUPS 1.2 </span>http_uri_status_e</a></h3> - <p class="description">URI separation status </p> - <h4 class="constants">Constants</h4> - <dl> - <dt>HTTP_URI_STATUS_BAD_ARGUMENTS </dt> - <dd class="description">Bad arguments to function (error)</dd> - <dt>HTTP_URI_STATUS_BAD_HOSTNAME </dt> - <dd class="description">Bad hostname in URI (error)</dd> - <dt>HTTP_URI_STATUS_BAD_PORT </dt> - <dd class="description">Bad port number in URI (error)</dd> - <dt>HTTP_URI_STATUS_BAD_RESOURCE </dt> - <dd class="description">Bad resource in URI (error)</dd> - <dt>HTTP_URI_STATUS_BAD_SCHEME </dt> - <dd class="description">Bad scheme in URI (error)</dd> - <dt>HTTP_URI_STATUS_BAD_URI </dt> - <dd class="description">Bad/empty URI (error)</dd> - <dt>HTTP_URI_STATUS_BAD_USERNAME </dt> - <dd class="description">Bad username in URI (error)</dd> - <dt>HTTP_URI_STATUS_MISSING_RESOURCE </dt> - <dd class="description">Missing resource in URI (warning)</dd> - <dt>HTTP_URI_STATUS_MISSING_SCHEME </dt> - <dd class="description">Missing scheme in URI (warning)</dd> - <dt>HTTP_URI_STATUS_OK </dt> - <dd class="description">URI decoded OK</dd> - <dt>HTTP_URI_STATUS_OVERFLOW </dt> - <dd class="description">URI buffer for httpAssembleURI is too small</dd> - <dt>HTTP_URI_STATUS_UNKNOWN_SCHEME </dt> - <dd class="description">Unknown scheme in URI (warning)</dd> -</dl> - <h3 class="enumeration"><a id="http_version_e">http_version_e</a></h3> - <p class="description">HTTP version numbers</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>HTTP_VERSION_0_9 </dt> - <dd class="description">HTTP/0.9</dd> - <dt>HTTP_VERSION_1_0 </dt> - <dd class="description">HTTP/1.0</dd> - <dt>HTTP_VERSION_1_1 </dt> - <dd class="description">HTTP/1.1</dd> -</dl> - <h3 class="enumeration"><a id="ipp_dstate_e">ipp_dstate_e</a></h3> - <p class="description">Document states</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_DOCUMENT_ABORTED </dt> - <dd class="description">Document is aborted</dd> - <dt>IPP_DOCUMENT_CANCELED </dt> - <dd class="description">Document is canceled</dd> - <dt>IPP_DOCUMENT_COMPLETED </dt> - <dd class="description">Document is completed</dd> - <dt>IPP_DOCUMENT_PENDING </dt> - <dd class="description">Document is pending</dd> - <dt>IPP_DOCUMENT_PROCESSING </dt> - <dd class="description">Document is processing</dd> -</dl> - <h3 class="enumeration"><a id="ipp_finishings_e">ipp_finishings_e</a></h3> - <p class="description">Finishings</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_FINISHINGS_BALE </dt> - <dd class="description">Bale (any type)</dd> - <dt>IPP_FINISHINGS_BIND </dt> - <dd class="description">Bind</dd> - <dt>IPP_FINISHINGS_BIND_BOTTOM </dt> - <dd class="description">Bind on bottom</dd> - <dt>IPP_FINISHINGS_BIND_LEFT </dt> - <dd class="description">Bind on left</dd> - <dt>IPP_FINISHINGS_BIND_RIGHT </dt> - <dd class="description">Bind on right</dd> - <dt>IPP_FINISHINGS_BIND_TOP </dt> - <dd class="description">Bind on top</dd> - <dt>IPP_FINISHINGS_BOOKLET_MAKER </dt> - <dd class="description">Fold to make booklet</dd> - <dt>IPP_FINISHINGS_COAT </dt> - <dd class="description">Apply protective liquid or powder coating</dd> - <dt>IPP_FINISHINGS_COVER </dt> - <dd class="description">Add cover</dd> - <dt>IPP_FINISHINGS_CUPS_FOLD_ACCORDIAN </dt> - <dd class="description">Accordian-fold the paper vertically into four sections</dd> - <dt>IPP_FINISHINGS_CUPS_FOLD_DOUBLE_GATE </dt> - <dd class="description">Fold the top and bottom quarters of the paper towards the midline, then fold in half vertically</dd> - <dt>IPP_FINISHINGS_CUPS_FOLD_GATE </dt> - <dd class="description">Fold the top and bottom quarters of the paper towards the midline</dd> - <dt>IPP_FINISHINGS_CUPS_FOLD_HALF </dt> - <dd class="description">Fold the paper in half vertically</dd> - <dt>IPP_FINISHINGS_CUPS_FOLD_HALF_Z </dt> - <dd class="description">Fold the paper in half horizontally, then Z-fold the paper vertically</dd> - <dt>IPP_FINISHINGS_CUPS_FOLD_LEFT_GATE </dt> - <dd class="description">Fold the top quarter of the paper towards the midline</dd> - <dt>IPP_FINISHINGS_CUPS_FOLD_LETTER </dt> - <dd class="description">Fold the paper into three sections vertically; sometimes also known as a C fold</dd> - <dt>IPP_FINISHINGS_CUPS_FOLD_PARALLEL </dt> - <dd class="description">Fold the paper in half vertically two times, yielding four sections</dd> - <dt>IPP_FINISHINGS_CUPS_FOLD_POSTER </dt> - <dd class="description">Fold the paper in half horizontally and vertically; sometimes also called a cross fold</dd> - <dt>IPP_FINISHINGS_CUPS_FOLD_RIGHT_GATE </dt> - <dd class="description">Fold the bottom quarter of the paper towards the midline</dd> - <dt>IPP_FINISHINGS_CUPS_FOLD_Z </dt> - <dd class="description">Fold the paper vertically into three sections, forming a Z</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_BOTTOM_LEFT </dt> - <dd class="description">Punch 1 hole bottom left</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_BOTTOM_RIGHT </dt> - <dd class="description">Punch 1 hole bottom right</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_BOTTOM </dt> - <dd class="description">Punch 2 holes bottom edge</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_LEFT </dt> - <dd class="description">Punch 2 holes left side</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_RIGHT </dt> - <dd class="description">Punch 2 holes right side</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_TOP </dt> - <dd class="description">Punch 2 holes top edge</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_BOTTOM </dt> - <dd class="description">Punch 4 holes bottom edge</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_LEFT </dt> - <dd class="description">Punch 4 holes left side</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_RIGHT </dt> - <dd class="description">Punch 4 holes right side</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_TOP </dt> - <dd class="description">Punch 4 holes top edge</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_TOP_LEFT </dt> - <dd class="description">Punch 1 hole top left</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_TOP_RIGHT </dt> - <dd class="description">Punch 1 hole top right</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_BOTTOM </dt> - <dd class="description">Punch 3 holes bottom edge</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_LEFT </dt> - <dd class="description">Punch 3 holes left side</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_RIGHT </dt> - <dd class="description">Punch 3 holes right side</dd> - <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_TOP </dt> - <dd class="description">Punch 3 holes top edge</dd> - <dt>IPP_FINISHINGS_EDGE_STITCH </dt> - <dd class="description">Stitch along any side</dd> - <dt>IPP_FINISHINGS_EDGE_STITCH_BOTTOM </dt> - <dd class="description">Stitch along bottom edge</dd> - <dt>IPP_FINISHINGS_EDGE_STITCH_LEFT </dt> - <dd class="description">Stitch along left side</dd> - <dt>IPP_FINISHINGS_EDGE_STITCH_RIGHT </dt> - <dd class="description">Stitch along right side</dd> - <dt>IPP_FINISHINGS_EDGE_STITCH_TOP </dt> - <dd class="description">Stitch along top edge</dd> - <dt>IPP_FINISHINGS_FOLD </dt> - <dd class="description">Fold (any type)</dd> - <dt>IPP_FINISHINGS_FOLD_ACCORDIAN </dt> - <dd class="description">Accordian-fold the paper vertically into four sections</dd> - <dt>IPP_FINISHINGS_FOLD_DOUBLE_GATE </dt> - <dd class="description">Fold the top and bottom quarters of the paper towards the midline, then fold in half vertically</dd> - <dt>IPP_FINISHINGS_FOLD_ENGINEERING_Z </dt> - <dd class="description">Fold the paper vertically into two small sections and one larger, forming an elongated Z</dd> - <dt>IPP_FINISHINGS_FOLD_GATE </dt> - <dd class="description">Fold the top and bottom quarters of the paper towards the midline</dd> - <dt>IPP_FINISHINGS_FOLD_HALF </dt> - <dd class="description">Fold the paper in half vertically</dd> - <dt>IPP_FINISHINGS_FOLD_HALF_Z </dt> - <dd class="description">Fold the paper in half horizontally, then Z-fold the paper vertically</dd> - <dt>IPP_FINISHINGS_FOLD_LEFT_GATE </dt> - <dd class="description">Fold the top quarter of the paper towards the midline</dd> - <dt>IPP_FINISHINGS_FOLD_LETTER </dt> - <dd class="description">Fold the paper into three sections vertically; sometimes also known as a C fold</dd> - <dt>IPP_FINISHINGS_FOLD_PARALLEL </dt> - <dd class="description">Fold the paper in half vertically two times, yielding four sections</dd> - <dt>IPP_FINISHINGS_FOLD_POSTER </dt> - <dd class="description">Fold the paper in half horizontally and vertically; sometimes also called a cross fold</dd> - <dt>IPP_FINISHINGS_FOLD_RIGHT_GATE </dt> - <dd class="description">Fold the bottom quarter of the paper towards the midline</dd> - <dt>IPP_FINISHINGS_FOLD_Z </dt> - <dd class="description">Fold the paper vertically into three sections, forming a Z</dd> - <dt>IPP_FINISHINGS_JOG_OFFSET </dt> - <dd class="description">Offset for binding (any type)</dd> - <dt>IPP_FINISHINGS_LAMINATE </dt> - <dd class="description">Apply protective (solid) material</dd> - <dt>IPP_FINISHINGS_NONE </dt> - <dd class="description">No finishing</dd> - <dt>IPP_FINISHINGS_PUNCH </dt> - <dd class="description">Punch (any location/count)</dd> - <dt>IPP_FINISHINGS_PUNCH_BOTTOM_LEFT </dt> - <dd class="description">Punch 1 hole bottom left</dd> - <dt>IPP_FINISHINGS_PUNCH_BOTTOM_RIGHT </dt> - <dd class="description">Punch 1 hole bottom right</dd> - <dt>IPP_FINISHINGS_PUNCH_DUAL_BOTTOM </dt> - <dd class="description">Punch 2 holes bottom edge</dd> - <dt>IPP_FINISHINGS_PUNCH_DUAL_LEFT </dt> - <dd class="description">Punch 2 holes left side</dd> - <dt>IPP_FINISHINGS_PUNCH_DUAL_RIGHT </dt> - <dd class="description">Punch 2 holes right side</dd> - <dt>IPP_FINISHINGS_PUNCH_DUAL_TOP </dt> - <dd class="description">Punch 2 holes top edge</dd> - <dt>IPP_FINISHINGS_PUNCH_MULTIPLE_BOTTOM </dt> - <dd class="description">Pucnh multiple holes bottom edge</dd> - <dt>IPP_FINISHINGS_PUNCH_MULTIPLE_LEFT </dt> - <dd class="description">Pucnh multiple holes left side</dd> - <dt>IPP_FINISHINGS_PUNCH_MULTIPLE_RIGHT </dt> - <dd class="description">Pucnh multiple holes right side</dd> - <dt>IPP_FINISHINGS_PUNCH_MULTIPLE_TOP </dt> - <dd class="description">Pucnh multiple holes top edge</dd> - <dt>IPP_FINISHINGS_PUNCH_QUAD_BOTTOM </dt> - <dd class="description">Punch 4 holes bottom edge</dd> - <dt>IPP_FINISHINGS_PUNCH_QUAD_LEFT </dt> - <dd class="description">Punch 4 holes left side</dd> - <dt>IPP_FINISHINGS_PUNCH_QUAD_RIGHT </dt> - <dd class="description">Punch 4 holes right side</dd> - <dt>IPP_FINISHINGS_PUNCH_QUAD_TOP </dt> - <dd class="description">Punch 4 holes top edge</dd> - <dt>IPP_FINISHINGS_PUNCH_TOP_LEFT </dt> - <dd class="description">Punch 1 hole top left</dd> - <dt>IPP_FINISHINGS_PUNCH_TOP_RIGHT </dt> - <dd class="description">Punch 1 hole top right</dd> - <dt>IPP_FINISHINGS_PUNCH_TRIPLE_BOTTOM </dt> - <dd class="description">Punch 3 holes bottom edge</dd> - <dt>IPP_FINISHINGS_PUNCH_TRIPLE_LEFT </dt> - <dd class="description">Punch 3 holes left side</dd> - <dt>IPP_FINISHINGS_PUNCH_TRIPLE_RIGHT </dt> - <dd class="description">Punch 3 holes right side</dd> - <dt>IPP_FINISHINGS_PUNCH_TRIPLE_TOP </dt> - <dd class="description">Punch 3 holes top edge</dd> - <dt>IPP_FINISHINGS_SADDLE_STITCH </dt> - <dd class="description">Staple interior</dd> - <dt>IPP_FINISHINGS_STAPLE </dt> - <dd class="description">Staple (any location)</dd> - <dt>IPP_FINISHINGS_STAPLE_BOTTOM_LEFT </dt> - <dd class="description">Staple bottom left corner</dd> - <dt>IPP_FINISHINGS_STAPLE_BOTTOM_RIGHT </dt> - <dd class="description">Staple bottom right corner</dd> - <dt>IPP_FINISHINGS_STAPLE_DUAL_BOTTOM </dt> - <dd class="description">Two staples on bottom</dd> - <dt>IPP_FINISHINGS_STAPLE_DUAL_LEFT </dt> - <dd class="description">Two staples on left</dd> - <dt>IPP_FINISHINGS_STAPLE_DUAL_RIGHT </dt> - <dd class="description">Two staples on right</dd> - <dt>IPP_FINISHINGS_STAPLE_DUAL_TOP </dt> - <dd class="description">Two staples on top</dd> - <dt>IPP_FINISHINGS_STAPLE_TOP_LEFT </dt> - <dd class="description">Staple top left corner</dd> - <dt>IPP_FINISHINGS_STAPLE_TOP_RIGHT </dt> - <dd class="description">Staple top right corner</dd> - <dt>IPP_FINISHINGS_STAPLE_TRIPLE_BOTTOM </dt> - <dd class="description">Three staples on bottom</dd> - <dt>IPP_FINISHINGS_STAPLE_TRIPLE_LEFT </dt> - <dd class="description">Three staples on left</dd> - <dt>IPP_FINISHINGS_STAPLE_TRIPLE_RIGHT </dt> - <dd class="description">Three staples on right</dd> - <dt>IPP_FINISHINGS_STAPLE_TRIPLE_TOP </dt> - <dd class="description">Three staples on top</dd> - <dt>IPP_FINISHINGS_TRIM </dt> - <dd class="description">Trim (any type)</dd> - <dt>IPP_FINISHINGS_TRIM_AFTER_COPIES </dt> - <dd class="description">Trim output after each copy</dd> - <dt>IPP_FINISHINGS_TRIM_AFTER_DOCUMENTS </dt> - <dd class="description">Trim output after each document</dd> - <dt>IPP_FINISHINGS_TRIM_AFTER_JOB </dt> - <dd class="description">Trim output after job</dd> - <dt>IPP_FINISHINGS_TRIM_AFTER_PAGES </dt> - <dd class="description">Trim output after each page</dd> -</dl> - <h3 class="enumeration"><a id="ipp_jcollate_e">ipp_jcollate_e</a></h3> - <p class="description">Job collation types</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_JCOLLATE_COLLATED_DOCUMENTS </dt> - <dt>IPP_JCOLLATE_UNCOLLATED_DOCUMENTS </dt> - <dt>IPP_JCOLLATE_UNCOLLATED_SHEETS </dt> -</dl> - <h3 class="enumeration"><a id="ipp_jstate_e">ipp_jstate_e</a></h3> - <p class="description">Job states</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_JSTATE_ABORTED </dt> - <dd class="description">Job has aborted due to error</dd> - <dt>IPP_JSTATE_CANCELED </dt> - <dd class="description">Job has been canceled</dd> - <dt>IPP_JSTATE_COMPLETED </dt> - <dd class="description">Job has completed successfully</dd> - <dt>IPP_JSTATE_HELD </dt> - <dd class="description">Job is held for printing</dd> - <dt>IPP_JSTATE_PENDING </dt> - <dd class="description">Job is waiting to be printed</dd> - <dt>IPP_JSTATE_PROCESSING </dt> - <dd class="description">Job is currently printing</dd> - <dt>IPP_JSTATE_STOPPED </dt> - <dd class="description">Job has been stopped</dd> -</dl> - <h3 class="enumeration"><a id="ipp_op_e">ipp_op_e</a></h3> - <p class="description">IPP operations</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_OP_ACKNOWLEDGE_DOCUMENT </dt> - <dd class="description">Acknowledge-Document</dd> - <dt>IPP_OP_ACKNOWLEDGE_IDENTIFY_PRINTER </dt> - <dd class="description">Acknowledge-Identify-Printer</dd> - <dt>IPP_OP_ACKNOWLEDGE_JOB </dt> - <dd class="description">Acknowledge-Job</dd> - <dt>IPP_OP_ACTIVATE_PRINTER </dt> - <dd class="description">Start a printer</dd> - <dt>IPP_OP_ADD_DOCUMENT_IMAGES </dt> - <dd class="description">Add-Document-Images</dd> - <dt>IPP_OP_CANCEL_CURRENT_JOB </dt> - <dd class="description">Cancel the current job</dd> - <dt>IPP_OP_CANCEL_DOCUMENT </dt> - <dd class="description">Cancel-Document</dd> - <dt>IPP_OP_CANCEL_JOB </dt> - <dd class="description">Cancel a job</dd> - <dt>IPP_OP_CANCEL_JOBS </dt> - <dd class="description">Cancel-Jobs</dd> - <dt>IPP_OP_CANCEL_MY_JOBS </dt> - <dd class="description">Cancel-My-Jobs</dd> - <dt>IPP_OP_CANCEL_SUBSCRIPTION <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Cancel a subscription </dd> - <dt>IPP_OP_CLOSE_JOB </dt> - <dd class="description">Close-Job</dd> - <dt>IPP_OP_CREATE_JOB </dt> - <dd class="description">Create an empty print job</dd> - <dt>IPP_OP_CREATE_JOB_SUBSCRIPTIONS <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Create one of more job subscriptions </dd> - <dt>IPP_OP_CREATE_PRINTER_SUBSCRIPTIONS <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Create one or more printer subscriptions </dd> - <dt>IPP_OP_CUPS_ACCEPT_JOBS </dt> - <dd class="description">Accept new jobs on a printer</dd> - <dt>IPP_OP_CUPS_ADD_MODIFY_CLASS </dt> - <dd class="description">Add or modify a class</dd> - <dt>IPP_OP_CUPS_ADD_MODIFY_PRINTER </dt> - <dd class="description">Add or modify a printer</dd> - <dt>IPP_OP_CUPS_AUTHENTICATE_JOB <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Authenticate a job </dd> - <dt>IPP_OP_CUPS_CREATE_LOCAL_PRINTER <span class="info"> CUPS 2.2 </span></dt> - <dd class="description">Create a local (temporary) printer <dt>IPP_OP_CUPS_DELETE_CLASS </dt> - <dd class="description">Delete a class</dd> - <dt>IPP_OP_CUPS_DELETE_PRINTER </dt> - <dd class="description">Delete a printer</dd> - <dt>IPP_OP_CUPS_GET_CLASSES <span class="info"> DEPRECATED </span></dt> - <dd class="description">Get a list of classes </dd> - <dt>IPP_OP_CUPS_GET_DEFAULT </dt> - <dd class="description">Get the default printer</dd> - <dt>IPP_OP_CUPS_GET_DEVICES <span class="info"> DEPRECATED </span></dt> - <dd class="description">Get a list of supported devices </dd> - <dt>IPP_OP_CUPS_GET_DOCUMENT <span class="info"> CUPS 1.4/macOS 10.6 </span></dt> - <dd class="description">Get a document file </dd> - <dt>IPP_OP_CUPS_GET_PPD <span class="info"> DEPRECATED </span></dt> - <dd class="description">Get a PPD file </dd> - <dt>IPP_OP_CUPS_GET_PPDS <span class="info"> DEPRECATED </span></dt> - <dd class="description">Get a list of supported drivers </dd> - <dt>IPP_OP_CUPS_GET_PRINTERS </dt> - <dd class="description">Get a list of printers and/or classes</dd> - <dt>IPP_OP_CUPS_INVALID </dt> - <dd class="description">Invalid operation name for <a href="#ippOpValue"><code>ippOpValue</code></a></dd> - <dt>IPP_OP_CUPS_MOVE_JOB </dt> - <dd class="description">Move a job to a different printer</dd> - <dt>IPP_OP_CUPS_REJECT_JOBS </dt> - <dd class="description">Reject new jobs on a printer</dd> - <dt>IPP_OP_CUPS_SET_DEFAULT </dt> - <dd class="description">Set the default printer</dd> - <dt>IPP_OP_DEACTIVATE_PRINTER </dt> - <dd class="description">Stop a printer</dd> - <dt>IPP_OP_DELETE_DOCUMENT </dt> - <dd class="description">Delete-Document</dd> - <dt>IPP_OP_DEREGISTER_OUTPUT_DEVICE </dt> - <dd class="description">Deregister-Output-Device</dd> - <dt>IPP_OP_DISABLE_PRINTER </dt> - <dd class="description">Stop a printer</dd> - <dt>IPP_OP_ENABLE_PRINTER </dt> - <dd class="description">Start a printer</dd> - <dt>IPP_OP_FETCH_DOCUMENT </dt> - <dd class="description">Fetch-Document</dd> - <dt>IPP_OP_FETCH_JOB </dt> - <dd class="description">Fetch-Job</dd> - <dt>IPP_OP_GET_DOCUMENTS </dt> - <dd class="description">Get-Documents</dd> - <dt>IPP_OP_GET_DOCUMENT_ATTRIBUTES </dt> - <dd class="description">Get-Document-Attributes</dd> - <dt>IPP_OP_GET_JOBS </dt> - <dd class="description">Get a list of jobs</dd> - <dt>IPP_OP_GET_JOB_ATTRIBUTES </dt> - <dd class="description">Get job attributes</dd> - <dt>IPP_OP_GET_NEXT_DOCUMENT_DATA </dt> - <dd class="description">Get-Next-Document-Data</dd> - <dt>IPP_OP_GET_NOTIFICATIONS <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Get notification events </dd> - <dt>IPP_OP_GET_OUTPUT_DEVICE_ATTRIBUTES </dt> - <dd class="description">Get-Output-Device-Attributes</dd> - <dt>IPP_OP_GET_PRINTER_ATTRIBUTES </dt> - <dd class="description">Get printer attributes</dd> - <dt>IPP_OP_GET_PRINTER_SUPPORTED_VALUES </dt> - <dd class="description">Get supported attribute values</dd> - <dt>IPP_OP_GET_SUBSCRIPTIONS <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Get list of subscriptions </dd> - <dt>IPP_OP_GET_SUBSCRIPTION_ATTRIBUTES <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Get subscription attributes </dd> - <dt>IPP_OP_HOLD_JOB </dt> - <dd class="description">Hold a job for printing</dd> - <dt>IPP_OP_HOLD_NEW_JOBS </dt> - <dd class="description">Hold new jobs</dd> - <dt>IPP_OP_IDENTIFY_PRINTER </dt> - <dd class="description">Identify-Printer</dd> - <dt>IPP_OP_PAUSE_PRINTER </dt> - <dd class="description">Stop a printer</dd> - <dt>IPP_OP_PAUSE_PRINTER_AFTER_CURRENT_JOB </dt> - <dd class="description">Stop printer after the current job</dd> - <dt>IPP_OP_PRINT_JOB </dt> - <dd class="description">Print a single file</dd> - <dt>IPP_OP_PRINT_URI </dt> - <dd class="description">Print a single URL</dd> - <dt>IPP_OP_PROMOTE_JOB </dt> - <dd class="description">Promote a job to print sooner</dd> - <dt>IPP_OP_PURGE_JOBS </dt> - <dd class="description">Cancel all jobs</dd> - <dt>IPP_OP_RELEASE_HELD_NEW_JOBS </dt> - <dd class="description">Release new jobs</dd> - <dt>IPP_OP_RELEASE_JOB </dt> - <dd class="description">Release a job for printing</dd> - <dt>IPP_OP_RENEW_SUBSCRIPTION <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> - <dd class="description">Renew a printer subscription </dd> - <dt>IPP_OP_REPROCESS_JOB </dt> - <dd class="description">Reprint a job</dd> - <dt>IPP_OP_RESTART_JOB </dt> - <dd class="description">Reprint a job</dd> - <dt>IPP_OP_RESTART_PRINTER </dt> - <dd class="description">Restart a printer</dd> - <dt>IPP_OP_RESUBMIT_JOB </dt> - <dd class="description">Resubmit-Job</dd> - <dt>IPP_OP_RESUME_JOB </dt> - <dd class="description">Resume the current job</dd> - <dt>IPP_OP_RESUME_PRINTER </dt> - <dd class="description">Start a printer</dd> - <dt>IPP_OP_SCHEDULE_JOB_AFTER </dt> - <dd class="description">Schedule a job to print after another</dd> - <dt>IPP_OP_SEND_DOCUMENT </dt> - <dd class="description">Add a file to a job</dd> - <dt>IPP_OP_SEND_URI </dt> - <dd class="description">Add a URL to a job</dd> - <dt>IPP_OP_SET_DOCUMENT_ATTRIBUTES </dt> - <dd class="description">Set-Document-Attributes</dd> - <dt>IPP_OP_SET_JOB_ATTRIBUTES </dt> - <dd class="description">Set job attributes</dd> - <dt>IPP_OP_SET_PRINTER_ATTRIBUTES </dt> - <dd class="description">Set printer attributes</dd> - <dt>IPP_OP_SHUTDOWN_PRINTER </dt> - <dd class="description">Turn a printer off</dd> - <dt>IPP_OP_STARTUP_PRINTER </dt> - <dd class="description">Turn a printer on</dd> - <dt>IPP_OP_SUSPEND_CURRENT_JOB </dt> - <dd class="description">Suspend the current job</dd> - <dt>IPP_OP_UPDATE_ACTIVE_JOBS </dt> - <dd class="description">Update-Active-Jobs</dd> - <dt>IPP_OP_UPDATE_DOCUMENT_STATUS </dt> - <dd class="description">Update-Document-Status</dd> - <dt>IPP_OP_UPDATE_JOB_STATUS </dt> - <dd class="description">Update-Job-Status</dd> - <dt>IPP_OP_UPDATE_OUTPUT_DEVICE_ATTRIBUTES </dt> - <dd class="description">Update-Output-Device-Attributes</dd> - <dt>IPP_OP_VALIDATE_DOCUMENT </dt> - <dd class="description">Validate-Document</dd> - <dt>IPP_OP_VALIDATE_JOB </dt> - <dd class="description">Validate job options</dd> -</dl> - <h3 class="enumeration"><a id="ipp_orient_e">ipp_orient_e</a></h3> - <p class="description">Orientation values</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_ORIENT_LANDSCAPE </dt> - <dd class="description">90 degrees counter-clockwise</dd> - <dt>IPP_ORIENT_NONE </dt> - <dd class="description">No rotation</dd> - <dt>IPP_ORIENT_PORTRAIT </dt> - <dd class="description">No rotation</dd> - <dt>IPP_ORIENT_REVERSE_LANDSCAPE </dt> - <dd class="description">90 degrees clockwise</dd> - <dt>IPP_ORIENT_REVERSE_PORTRAIT </dt> - <dd class="description">180 degrees</dd> -</dl> - <h3 class="enumeration"><a id="ipp_pstate_e">ipp_pstate_e</a></h3> - <p class="description">Printer states</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_PSTATE_IDLE </dt> - <dd class="description">Printer is idle</dd> - <dt>IPP_PSTATE_PROCESSING </dt> - <dd class="description">Printer is working</dd> - <dt>IPP_PSTATE_STOPPED </dt> - <dd class="description">Printer is stopped</dd> -</dl> - <h3 class="enumeration"><a id="ipp_quality_e">ipp_quality_e</a></h3> - <p class="description">Qualities</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_QUALITY_DRAFT </dt> - <dd class="description">Draft quality</dd> - <dt>IPP_QUALITY_HIGH </dt> - <dd class="description">High quality</dd> - <dt>IPP_QUALITY_NORMAL </dt> - <dd class="description">Normal quality</dd> -</dl> - <h3 class="enumeration"><a id="ipp_res_e">ipp_res_e</a></h3> - <p class="description">Resolution units</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_RES_PER_CM </dt> - <dd class="description">Pixels per centimeter</dd> - <dt>IPP_RES_PER_INCH </dt> - <dd class="description">Pixels per inch</dd> -</dl> - <h3 class="enumeration"><a id="ipp_state_e">ipp_state_e</a></h3> - <p class="description">IPP states</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_STATE_ATTRIBUTE </dt> - <dd class="description">One or more attributes need to be sent/received</dd> - <dt>IPP_STATE_DATA </dt> - <dd class="description">IPP request data needs to be sent/received</dd> - <dt>IPP_STATE_ERROR </dt> - <dd class="description">An error occurred</dd> - <dt>IPP_STATE_HEADER </dt> - <dd class="description">The request header needs to be sent/received</dd> - <dt>IPP_STATE_IDLE </dt> - <dd class="description">Nothing is happening/request completed</dd> -</dl> - <h3 class="enumeration"><a id="ipp_status_e">ipp_status_e</a></h3> - <p class="description">IPP status codes</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_STATUS_CUPS_INVALID </dt> - <dd class="description">Invalid status name for <a href="#ippErrorValue"><code>ippErrorValue</code></a></dd> - <dt>IPP_STATUS_CUPS_SEE_OTHER </dt> - <dd class="description">cups-see-other</dd> - <dt>IPP_STATUS_ERROR_ACCOUNT_AUTHORIZATION_FAILED </dt> - <dd class="description">client-error-account-authorization-failed</dd> - <dt>IPP_STATUS_ERROR_ACCOUNT_CLOSED </dt> - <dd class="description">client-error-account-closed</dd> - <dt>IPP_STATUS_ERROR_ACCOUNT_INFO_NEEDED </dt> - <dd class="description">client-error-account-info-needed</dd> - <dt>IPP_STATUS_ERROR_ACCOUNT_LIMIT_REACHED </dt> - <dd class="description">client-error-account-limit-reached</dd> - <dt>IPP_STATUS_ERROR_ATTRIBUTES_NOT_SETTABLE </dt> - <dd class="description">client-error-attributes-not-settable</dd> - <dt>IPP_STATUS_ERROR_ATTRIBUTES_OR_VALUES </dt> - <dd class="description">client-error-attributes-or-values-not-supported</dd> - <dt>IPP_STATUS_ERROR_BAD_REQUEST </dt> - <dd class="description">client-error-bad-request</dd> - <dt>IPP_STATUS_ERROR_BUSY </dt> - <dd class="description">server-error-busy</dd> - <dt>IPP_STATUS_ERROR_CHARSET </dt> - <dd class="description">client-error-charset-not-supported</dd> - <dt>IPP_STATUS_ERROR_COMPRESSION_ERROR </dt> - <dd class="description">client-error-compression-error</dd> - <dt>IPP_STATUS_ERROR_COMPRESSION_NOT_SUPPORTED </dt> - <dd class="description">client-error-compression-not-supported</dd> - <dt>IPP_STATUS_ERROR_CONFLICTING </dt> - <dd class="description">client-error-conflicting-attributes</dd> - <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_AUTHORIZATION_FAILED <span class="info"> DEPRECATED </span></dt> - <dd class="description">cups-error-account-authorization-failed </dd> - <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_CLOSED </dt> - <dd class="description">cups-error-account-closed @deprecate@</dd> - <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_INFO_NEEDED <span class="info"> DEPRECATED </span></dt> - <dd class="description">cups-error-account-info-needed </dd> - <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_LIMIT_REACHED <span class="info"> DEPRECATED </span></dt> - <dd class="description">cups-error-account-limit-reached </dd> - <dt>IPP_STATUS_ERROR_CUPS_AUTHENTICATION_CANCELED <span class="info"> CUPS 1.5/macOS 10.7 </span></dt> - <dd class="description">cups-authentication-canceled - Authentication canceled by user </dd> - <dt>IPP_STATUS_ERROR_CUPS_PKI <span class="info"> CUPS 1.5/macOS 10.7 </span></dt> - <dd class="description">cups-pki-error - Error negotiating a secure connection </dd> - <dt>IPP_STATUS_ERROR_CUPS_UPGRADE_REQUIRED </dt> - <dd class="description">cups-upgrade-required - TLS upgrade required</dd> - <dt>IPP_STATUS_ERROR_DEVICE </dt> - <dd class="description">server-error-device-error</dd> - <dt>IPP_STATUS_ERROR_DOCUMENT_ACCESS </dt> - <dd class="description">client-error-document-access-error</dd> - <dt>IPP_STATUS_ERROR_DOCUMENT_FORMAT_ERROR </dt> - <dd class="description">client-error-document-format-error</dd> - <dt>IPP_STATUS_ERROR_DOCUMENT_FORMAT_NOT_SUPPORTED </dt> - <dd class="description">client-error-document-format-not-supported</dd> - <dt>IPP_STATUS_ERROR_DOCUMENT_PASSWORD </dt> - <dd class="description">client-error-document-password-error</dd> - <dt>IPP_STATUS_ERROR_DOCUMENT_PERMISSION </dt> - <dd class="description">client-error-document-permission-error</dd> - <dt>IPP_STATUS_ERROR_DOCUMENT_SECURITY </dt> - <dd class="description">client-error-document-security-error</dd> - <dt>IPP_STATUS_ERROR_DOCUMENT_UNPRINTABLE </dt> - <dd class="description">client-error-document-unprintable-error</dd> - <dt>IPP_STATUS_ERROR_FORBIDDEN </dt> - <dd class="description">client-error-forbidden</dd> - <dt>IPP_STATUS_ERROR_GONE </dt> - <dd class="description">client-error-gone</dd> - <dt>IPP_STATUS_ERROR_IGNORED_ALL_SUBSCRIPTIONS </dt> - <dd class="description">client-error-ignored-all-subscriptions</dd> - <dt>IPP_STATUS_ERROR_INTERNAL </dt> - <dd class="description">server-error-internal-error</dd> - <dt>IPP_STATUS_ERROR_JOB_CANCELED </dt> - <dd class="description">server-error-job-canceled</dd> - <dt>IPP_STATUS_ERROR_MULTIPLE_JOBS_NOT_SUPPORTED </dt> - <dd class="description">server-error-multiple-document-jobs-not-supported</dd> - <dt>IPP_STATUS_ERROR_NOT_ACCEPTING_JOBS </dt> - <dd class="description">server-error-not-accepting-jobs</dd> - <dt>IPP_STATUS_ERROR_NOT_AUTHENTICATED </dt> - <dd class="description">client-error-not-authenticated</dd> - <dt>IPP_STATUS_ERROR_NOT_AUTHORIZED </dt> - <dd class="description">client-error-not-authorized</dd> - <dt>IPP_STATUS_ERROR_NOT_FETCHABLE </dt> - <dd class="description">client-error-not-fetchable</dd> - <dt>IPP_STATUS_ERROR_NOT_FOUND </dt> - <dd class="description">client-error-not-found</dd> - <dt>IPP_STATUS_ERROR_NOT_POSSIBLE </dt> - <dd class="description">client-error-not-possible</dd> - <dt>IPP_STATUS_ERROR_OPERATION_NOT_SUPPORTED </dt> - <dd class="description">server-error-operation-not-supported</dd> - <dt>IPP_STATUS_ERROR_PRINTER_IS_DEACTIVATED </dt> - <dd class="description">server-error-printer-is-deactivated</dd> - <dt>IPP_STATUS_ERROR_REQUEST_ENTITY </dt> - <dd class="description">client-error-request-entity-too-large</dd> - <dt>IPP_STATUS_ERROR_REQUEST_VALUE </dt> - <dd class="description">client-error-request-value-too-long</dd> - <dt>IPP_STATUS_ERROR_SERVICE_UNAVAILABLE </dt> - <dd class="description">server-error-service-unavailable</dd> - <dt>IPP_STATUS_ERROR_TEMPORARY </dt> - <dd class="description">server-error-temporary-error</dd> - <dt>IPP_STATUS_ERROR_TIMEOUT </dt> - <dd class="description">client-error-timeout</dd> - <dt>IPP_STATUS_ERROR_TOO_MANY_DOCUMENTS </dt> - <dd class="description">server-error-too-many-documents</dd> - <dt>IPP_STATUS_ERROR_TOO_MANY_JOBS </dt> - <dd class="description">server-error-too-many-jobs</dd> - <dt>IPP_STATUS_ERROR_TOO_MANY_SUBSCRIPTIONS </dt> - <dd class="description">client-error-too-many-subscriptions</dd> - <dt>IPP_STATUS_ERROR_URI_SCHEME </dt> - <dd class="description">client-error-uri-scheme-not-supported</dd> - <dt>IPP_STATUS_ERROR_VERSION_NOT_SUPPORTED </dt> - <dd class="description">server-error-version-not-supported</dd> - <dt>IPP_STATUS_OK </dt> - <dd class="description">successful-ok</dd> - <dt>IPP_STATUS_OK_CONFLICTING </dt> - <dd class="description">successful-ok-conflicting-attributes</dd> - <dt>IPP_STATUS_OK_EVENTS_COMPLETE </dt> - <dd class="description">successful-ok-events-complete</dd> - <dt>IPP_STATUS_OK_IGNORED_OR_SUBSTITUTED </dt> - <dd class="description">successful-ok-ignored-or-substituted-attributes</dd> - <dt>IPP_STATUS_OK_IGNORED_SUBSCRIPTIONS </dt> - <dd class="description">successful-ok-ignored-subscriptions</dd> - <dt>IPP_STATUS_OK_TOO_MANY_EVENTS </dt> - <dd class="description">successful-ok-too-many-events</dd> -</dl> - <h3 class="enumeration"><a id="ipp_tag_e">ipp_tag_e</a></h3> - <p class="description">Format tags for attributes</p> - <h4 class="constants">Constants</h4> - <dl> - <dt>IPP_TAG_ADMINDEFINE </dt> - <dd class="description">Admin-defined value</dd> - <dt>IPP_TAG_BEGIN_COLLECTION </dt> - <dd class="description">Beginning of collection value</dd> - <dt>IPP_TAG_BOOLEAN </dt> - <dd class="description">Boolean value</dd> - <dt>IPP_TAG_CHARSET </dt> - <dd class="description">Character set value</dd> - <dt>IPP_TAG_CUPS_INVALID </dt> - <dd class="description">Invalid tag name for <a href="#ippTagValue"><code>ippTagValue</code></a></dd> - <dt>IPP_TAG_DATE </dt> - <dd class="description">Date/time value</dd> - <dt>IPP_TAG_DEFAULT </dt> - <dd class="description">Default value</dd> - <dt>IPP_TAG_DELETEATTR </dt> - <dd class="description">Delete-attribute value</dd> - <dt>IPP_TAG_DOCUMENT </dt> - <dd class="description">Document group</dd> - <dt>IPP_TAG_END </dt> - <dd class="description">End-of-attributes</dd> - <dt>IPP_TAG_END_COLLECTION </dt> - <dd class="description">End of collection value</dd> - <dt>IPP_TAG_ENUM </dt> - <dd class="description">Enumeration value</dd> - <dt>IPP_TAG_EVENT_NOTIFICATION </dt> - <dd class="description">Event group</dd> - <dt>IPP_TAG_EXTENSION </dt> - <dd class="description">Extension point for 32-bit tags</dd> - <dt>IPP_TAG_INTEGER </dt> - <dd class="description">Integer value</dd> - <dt>IPP_TAG_JOB </dt> - <dd class="description">Job group</dd> - <dt>IPP_TAG_KEYWORD </dt> - <dd class="description">Keyword value</dd> - <dt>IPP_TAG_LANGUAGE </dt> - <dd class="description">Language value</dd> - <dt>IPP_TAG_MEMBERNAME </dt> - <dd class="description">Collection member name value</dd> - <dt>IPP_TAG_MIMETYPE </dt> - <dd class="description">MIME media type value</dd> - <dt>IPP_TAG_NAME </dt> - <dd class="description">Name value</dd> - <dt>IPP_TAG_NAMELANG </dt> - <dd class="description">Name-with-language value</dd> - <dt>IPP_TAG_NOTSETTABLE </dt> - <dd class="description">Not-settable value</dd> - <dt>IPP_TAG_NOVALUE </dt> - <dd class="description">No-value value</dd> - <dt>IPP_TAG_OPERATION </dt> - <dd class="description">Operation group</dd> - <dt>IPP_TAG_PRINTER </dt> - <dd class="description">Printer group</dd> - <dt>IPP_TAG_RANGE </dt> - <dd class="description">Range value</dd> - <dt>IPP_TAG_RESOLUTION </dt> - <dd class="description">Resolution value</dd> - <dt>IPP_TAG_STRING </dt> - <dd class="description">Octet string value</dd> - <dt>IPP_TAG_SUBSCRIPTION </dt> - <dd class="description">Subscription group</dd> - <dt>IPP_TAG_TEXT </dt> - <dd class="description">Text value</dd> - <dt>IPP_TAG_TEXTLANG </dt> - <dd class="description">Text-with-language value</dd> - <dt>IPP_TAG_UNKNOWN </dt> - <dd class="description">Unknown value</dd> - <dt>IPP_TAG_UNSUPPORTED_GROUP </dt> - <dd class="description">Unsupported attributes group</dd> - <dt>IPP_TAG_UNSUPPORTED_VALUE </dt> - <dd class="description">Unsupported value</dd> - <dt>IPP_TAG_URI </dt> - <dd class="description">URI value</dd> - <dt>IPP_TAG_URISCHEME </dt> - <dd class="description">URI scheme value</dd> - <dt>IPP_TAG_ZERO </dt> - <dd class="description">Zero tag - used for separators</dd> -</dl> - </div> - </body> -</html> diff --git a/doc/help/api-overview.html b/doc/help/api-overview.html deleted file mode 100644 index 89a27413d..000000000 --- a/doc/help/api-overview.html +++ /dev/null @@ -1,516 +0,0 @@ -<!doctype html> -<html> -<!-- SECTION: Programming --> - <head> - <title>Introduction to CUPS Programming</title> - <meta name="keywords" content="Programming"> - <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> - <meta name="creator" content="Mini-XML v2.11"> - <meta name="author" content="Unknown"> - <meta name="copyright" content="Unknown"> - <style type="text/css"><!-- -BODY { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -H1, H2, H3, H4, H5, H6, P, TD, TH { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -KBD { - font-family: monaco, courier, monospace; - font-weight: bold; -} - -PRE { - font-family: monaco, courier, monospace; -} - -PRE.command { - border: dotted thin #7f7f7f; - margin-left: 36pt; - padding: 10px; -} - -P.compact { - margin: 0; -} - -P.example { - font-style: italic; - margin-left: 36pt; -} - -DL.man DD { - margin-left: 5em; -} - -DL.man DT { - margin-left: 0; -} - -PRE.man { - margin: 0; -} - -PRE.example { - background: #eeeeee; - border: dotted thin #999999; - margin-left: 36pt; - padding: 10pt; -} - -PRE.command EM, PRE.example EM { - font-family: lucida grande, geneva, helvetica, arial, sans-serif; -} - -P.command { - font-family: monaco, courier, monospace; - margin-left: 36pt; -} - -P.formula { - font-style: italic; - margin-left: 36pt; -} - -BLOCKQUOTE { - background: #eeeeee; - border: solid thin #999999; - padding: 10pt; -} - -A IMG { - border: none; -} - -A:link:hover IMG { - background: #f0f0f0; - border-radius: 10px; - -moz-border-radius: 10px; -} - -A:link, A:visited { - font-weight: inherit; - text-decoration: none; -} - -A:link:hover, A:visited:hover, A:active { - text-decoration: underline; -} - -SUB, SUP { - font-size: 50%; -} - -TR.data, TD.data, TR.data TD { - margin-top: 10pt; - padding: 5pt; - border-bottom: solid 1pt #999999; -} - -TR.data TH { - border-bottom: solid 1pt #999999; - padding-top: 10pt; - padding-left: 5pt; - text-align: left; -} - -DIV.table TABLE { - border: solid thin #999999; - border-collapse: collapse; - border-spacing: 0; - margin-left: auto; - margin-right: auto; -} - -DIV.table CAPTION { - caption-side: top; - font-size: 120%; - font-style: italic; - font-weight: bold; - margin-left: auto; - margin-right: auto; -} - -DIV.table TABLE TD { - border: solid thin #cccccc; - padding-top: 5pt; -} - -DIV.table TABLE TH { - background: #cccccc; - border: none; - border-bottom: solid thin #999999; -} - -DIV.figure TABLE { - margin-left: auto; - margin-right: auto; -} - -DIV.figure CAPTION { - caption-side: bottom; - font-size: 120%; - font-style: italic; - font-weight: bold; - margin-left: auto; - margin-right: auto; -} - -TH.label { - text-align: right; - vertical-align: top; -} - -TH.sublabel { - text-align: right; - font-weight: normal; -} - -HR { - border: solid thin; -} - -SPAN.info { - background: black; - border: thin solid black; - color: white; - font-size: 80%; - font-style: italic; - font-weight: bold; - white-space: nowrap; -} - -H2 SPAN.info, H3 SPAN.info, H4 SPAN.info { - float: right; - font-size: 100%; -} - -H1.title { -} - -H2.title, H3.title { - border-bottom: solid 2pt #000000; -} - -DIV.indent, TABLE.indent { - margin-top: 2em; - margin-left: auto; - margin-right: auto; - width: 90%; -} - -TABLE.indent { - border-collapse: collapse; -} - -TABLE.indent TD, TABLE.indent TH { - padding: 0; -} - -TABLE.list { - border-collapse: collapse; - margin-left: auto; - margin-right: auto; - width: 90%; -} - -TABLE.list TH { - background: white; - border-bottom: solid thin #cccccc; - color: #444444; - padding-top: 10pt; - padding-left: 5pt; - text-align: left; - vertical-align: bottom; - white-space: nowrap; -} - -TABLE.list TH A { - color: #4444cc; -} - -TABLE.list TD { - border-bottom: solid thin #eeeeee; - padding-top: 5pt; - padding-left: 5pt; -} - -TABLE.list TR:nth-child(even) { - background: #f8f8f8; -} - -TABLE.list TR:nth-child(odd) { - background: #f4f4f4; -} - -DT { - margin-left: 36pt; - margin-top: 12pt; -} - -DD { - margin-left: 54pt; -} - -DL.category DT { - font-weight: bold; -} - -P.summary { - margin-left: 36pt; - font-family: monaco, courier, monospace; -} - -DIV.summary TABLE { - border: solid thin #999999; - border-collapse: collapse; - border-spacing: 0; - margin: 10px; -} - -DIV.summary TABLE TD, DIV.summary TABLE TH { - border: solid thin #999999; - padding: 5px; - text-align: left; - vertical-align: top; -} - -DIV.summary TABLE THEAD TH { - background: #eeeeee; -} - -/* API documentation styles... */ -div.body h1 { - margin: 0; -} -div.body h2 { - margin-top: 1.5em; -} -div.body h3, div.body h4, div.body h5 { - margin-bottom: 0.5em; - margin-top: 1.5em; -} -.class, .enumeration, .function, .struct, .typedef, .union { - border-bottom: solid thin #999999; - margin-bottom: 0; - margin-top: 2em; -} -.description { - margin-top: 0.5em; -} -code, p.code, pre, ul.code li { - font-family: monaco, courier, monospace; - font-size: 90%; -} -ul.code, ul.contents, ul.subcontents { - list-style-type: none; - margin: 0; - padding-left: 0; -} -ul.code li { - margin: 0; -} -ul.contents > li { - margin-top: 1em; -} -ul.contents li ul.code, ul.contents li ul.subcontents { - padding-left: 2em; -} -div.body dl { - margin-left: 0; - margin-top: 0; -} -div.body dt { - font-style: italic; - margin-left: 0; - margin-top: 0; -} -div.body dd { - margin-bottom: 0.5em; -} - -/* This is just for the HTML files generated with the framedhelp target */ -div.contents { - background: #e8e8e8; - border: solid thin black; - padding: 10px; -} -div.contents h1 { - font-size: 110%; -} -div.contents h2 { - font-size: 100%; -} -div.contents ul.contents { - font-size: 80%; -} -div.contents ul.subcontents li { - margin-left: 1em; - text-indent: -1em; -} ---></style> - </head> - <body> -<!-- - Introduction to CUPS programming header for CUPS. - - Copyright 2008-2016 by Apple Inc. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h1 class='title'>Introduction to CUPS Programming</h1> - -<div class='summary'><table summary='General Information'> -<thead> -<tr> - <th>Headers</th> - <th>cups/cups.h<br> - cups/adminutil.h<br> - cups/array.h<br> - cups/dir.h<br> - cups/file.h<br> - cups/http.h<br> - cups/ipp.h<br> - cups/language.h<br> - cups/ppd.h<br> - cups/pwg.h<br> - cups/raster.h</th> -</tr> -</thead> -<tbody> -<tr> - <th>Libraries</th> - <td>-lcups</td> -</tr> -<tr> - <th>See Also</th> - <td>Programming: <a href='raster-driver.html' target='_top'>Developing Raster Printer Drivers</a><br> - Programming: <a href='postscript-driver.html' target='_top'>Developing PostScript Printer Drivers</a><br> - Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br> - Programming: <a href='ppd-compiler.html' target='_top'>Introduction to the PPD Compiler</a><br> - Programming: <a href='api-admin.html' target='_top'>Administrative APIs</a><br> - Programming: <a href='api-array.html' target='_top'>Array API</a><br> - Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br> - Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br> - Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br> - Programming: <a href='api-ppd.html' target='_top'>PPD API (DEPRECATED)</a><br> - Programming: <a href='api-raster.html' target='_top'>Raster API</a><br> - References: <a href='ref-ppdcfile.html' target='_top'>PPD Compiler Driver Information File Reference</a><br> - Specifications: <a href='spec-ppd.html' target='_top'>CUPS PPD Extensions</a></td> -</tr> -</tbody> -</table></div> - <div class="contents"> - <h2 class="title">Contents</h2> - <ul class="contents"> - <li><a href="#OVERVIEW">Overview</a></li> - <li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents"> - <li><a href="#XCODE">Compiling with Xcode</a></li> - <li><a href="#COMMANDLINE">Compiling with GCC</a></li> - </ul></li> - <li><a href="#WHERETOGO">Where to Go Next</a></li> - </ul> - </div> - <div class="body"> -<!-- - Introduction to CUPS programming content for CUPS. - - Copyright 2008-2011 by Apple Inc. - - These coded instructions, statements, and computer programs are the - property of Apple Inc. and are protected by Federal copyright - law. Distribution and use rights are outlined in the file "LICENSE.txt" - which should have been included with this file. If this file is - file is missing or damaged, see the license at "http://www.cups.org/". ---> - -<h2 class="title"><a name="OVERVIEW">Overview</a></h2> - -<p>CUPS provides two libraries that interface with the different parts of the -printing system. The "cups" library provides all of the common application and -filter functions while the "cupsimage" library provides all of the imaging -functions used in raster printer drivers. The "cups" library functions are -accessed by including the <var><cups/cups.h></var> header, while -"cupsimage" functions are found in the <var><cups/raster.h></var> -header.</p> - -<h2 class="title"><a name="COMPILING">Compiling Programs</a></h2> - -<p>The CUPS libraries can be used from any C, C++, or Objective C program. -The method of compiling against the libraries varies depending on the -operating system and installation of CUPS. The following sections show how -to compile a simple program (shown below) in two common environments.</p> - -<p>The following simple program lists the available printers on the system:</p> - -<pre class="example"> -#include <stdio.h> -#include <cups/cups.h> - -int main(void) -{ - int i; - cups_dest_t *dests, *dest; - int num_dests = cupsGetDests(&dests); - - for (i = num_dests, dest = dests; i > 0; i --, dest ++) - { - if (dest->instance) - printf("%s/%s\n", dest->name, dest->instance); - else - puts(dest->name); - } - - return (0); -} -</pre> - -<h3><a name="XCODE">Compiling with Xcode</a></h3> - -<p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu, -then select the <var>Standard Tool</var> project type under <var>Command Line -Utility</var>. Click <var>Next</var> and choose a project directory. Click -<var>Next</var> to create the project.</p> - -<p>In the project window, double-click on the <var>Targets</var> group and -control-click on the simple target to show the context menu. Choose -<var>Existing Framework...</var> from the <var>Add</var> submenu. When the file -chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll -down the file list and select the <var>libcups.dylib</var> file. Click the -<var>Add</var> button in the file chooser and attributes sheets.</p> - -<p>In the project window, double-click on the <var>main.c</var> source file. -Replace the template source code with the listing above and save it. Click the -<var>Build and Go</var> button to build the sample program and run it.</p> - -<h3><a name="COMMANDLINE">Compiling with GCC</a></h3> - -<p>From the command-line, create a file called <var>sample.c</var> using your -favorite editor and then run the following command to compile it with GCC and -run it:</p> - -<pre class="command"> -gcc -o simple `cups-config --cflags` simple.c `cups-config --libs` -./simple -</pre> - -<p>The <code>cups-config</code> command provides the compiler flags -("cups-config --cflags") and libraries ("cups-config --libs") needed for the -local system.</p> - -<h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2> - -<p>If you are developing a print filter, driver, or backend, see the -<a href="api-filter.html" target="_top">Filter and Backend Programming</a> -guide. Raster printer driver developers should also read the -<a href="api-raster.html" target="_top">Raster API</a> reference.</p> - </div> - </body> -</html> diff --git a/doc/help/api-ppd.html b/doc/help/api-ppd.html index b56df5f93..25709415d 100644 --- a/doc/help/api-ppd.html +++ b/doc/help/api-ppd.html @@ -8,6 +8,7 @@ <meta name="creator" content="Mini-XML v2.11"> <meta name="author" content="Unknown"> <meta name="copyright" content="Unknown"> + <meta name="version" content="0.0"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -709,11 +710,11 @@ for (attr = <a href="#ppdFindAttr">ppdFindAttr</a>(ppd, "Product", NULL); <h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsGetConflicts">cupsGetConflicts</a></h3> <p class="description">Get a list of conflicting options in a marked PPD.</p> <p class="code"> -int cupsGetConflicts (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *option,<br /> -    const char *choice,<br /> -    cups_option_t **options<br /> +int cupsGetConflicts (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *option,<br> +    const char *choice,<br> +    cups_option_t **options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -742,8 +743,8 @@ the conflicting options. The returned option array must be freed using <h3 class="function"><a id="cupsGetPPD">cupsGetPPD</a></h3> <p class="description">Get the PPD file for a printer on the default server.</p> <p class="code"> -const char *cupsGetPPD (<br /> -    const char *name<br /> +const char *cupsGetPPD (<br> +    const char *name<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -762,9 +763,9 @@ file that is created and must <code>unlink</code> the returned filename.</p> <h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsGetPPD2">cupsGetPPD2</a></h3> <p class="description">Get the PPD file for a printer from the specified server.</p> <p class="code"> -const char *cupsGetPPD2 (<br /> -    http_t *http,<br /> -    const char *name<br /> +const char *cupsGetPPD2 (<br> +    http_t *http,<br> +    const char *name<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -788,12 +789,12 @@ file that is created and must <code>unlink</code> the returned filename. <p class="description">Get the PPD file for a printer on the specified server if it has changed.</p> <p class="code"> -http_status_t cupsGetPPD3 (<br /> -    http_t *http,<br /> -    const char *name,<br /> -    time_t *modtime,<br /> -    char *buffer,<br /> -    size_t bufsize<br /> +http_status_t cupsGetPPD3 (<br> +    http_t *http,<br> +    const char *name,<br> +    time_t *modtime,<br> +    char *buffer,<br> +    size_t bufsize<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -831,9 +832,9 @@ in the class. <h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsGetServerPPD">cupsGetServerPPD</a></h3> <p class="description">Get an available PPD file from the server.</p> <p class="code"> -char *cupsGetServerPPD (<br /> -    http_t *http,<br /> -    const char *name<br /> +char *cupsGetServerPPD (<br> +    http_t *http,<br> +    const char *name<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -858,10 +859,10 @@ or <a href="#cupsGetServerPPD"><code>cupsGetServerPPD</code></a>. <h3 class="function"><a id="cupsMarkOptions">cupsMarkOptions</a></h3> <p class="description">Mark command-line options in a PPD file.</p> <p class="code"> -int cupsMarkOptions (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    int num_options,<br /> -    cups_option_t *options<br /> +int cupsMarkOptions (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    int num_options,<br> +    cups_option_t *options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -882,12 +883,12 @@ corresponding PPD options and choices.</p> <h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsResolveConflicts">cupsResolveConflicts</a></h3> <p class="description">Resolve conflicts in a marked PPD.</p> <p class="code"> -int cupsResolveConflicts (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *option,<br /> -    const char *choice,<br /> -    int *num_options,<br /> -    cups_option_t **options<br /> +int cupsResolveConflicts (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *option,<br> +    const char *choice,<br> +    int *num_options,<br> +    cups_option_t **options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -941,10 +942,10 @@ until a non-conflicting option choice is found. <p class="description">Collect all marked options that reside in the specified section.</p> <p class="code"> -int ppdCollect (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    <a href="#ppd_section_t">ppd_section_t</a> section,<br /> -    <a href="#ppd_choice_t">ppd_choice_t</a> ***choices<br /> +int ppdCollect (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    <a href="#ppd_section_t">ppd_section_t</a> section,<br> +    <a href="#ppd_choice_t">ppd_choice_t</a> ***choices<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -964,11 +965,11 @@ finished with it.</p> <p class="description">Collect all marked options that reside in the specified section and minimum order.</p> <p class="code"> -int ppdCollect2 (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    <a href="#ppd_section_t">ppd_section_t</a> section,<br /> -    float min_order,<br /> -    <a href="#ppd_choice_t">ppd_choice_t</a> ***choices<br /> +int ppdCollect2 (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    <a href="#ppd_section_t">ppd_section_t</a> section,<br> +    float min_order,<br> +    <a href="#ppd_choice_t">ppd_choice_t</a> ***choices<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -992,8 +993,8 @@ finished with it. <p class="description">Check to see if there are any conflicts among the marked option choices.</p> <p class="code"> -int ppdConflicts (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd<br /> +int ppdConflicts (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1007,10 +1008,10 @@ int ppdConflicts (<br /> <h3 class="function"><a id="ppdEmit">ppdEmit</a></h3> <p class="description">Emit code for marked options to a file.</p> <p class="code"> -int ppdEmit (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    FILE *fp,<br /> -    <a href="#ppd_section_t">ppd_section_t</a> section<br /> +int ppdEmit (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    FILE *fp,<br> +    <a href="#ppd_section_t">ppd_section_t</a> section<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1026,12 +1027,12 @@ int ppdEmit (<br /> <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppdEmitAfterOrder">ppdEmitAfterOrder</a></h3> <p class="description">Emit a subset of the code for marked options to a file.</p> <p class="code"> -int ppdEmitAfterOrder (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    FILE *fp,<br /> -    <a href="#ppd_section_t">ppd_section_t</a> section,<br /> -    int limit,<br /> -    float min_order<br /> +int ppdEmitAfterOrder (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    FILE *fp,<br> +    <a href="#ppd_section_t">ppd_section_t</a> section,<br> +    int limit,<br> +    float min_order<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1058,10 +1059,10 @@ When "limit" is zero, this function is identical to ppdEmit(). <h3 class="function"><a id="ppdEmitFd">ppdEmitFd</a></h3> <p class="description">Emit code for marked options to a file.</p> <p class="code"> -int ppdEmitFd (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    int fd,<br /> -    <a href="#ppd_section_t">ppd_section_t</a> section<br /> +int ppdEmitFd (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    int fd,<br> +    <a href="#ppd_section_t">ppd_section_t</a> section<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1077,12 +1078,12 @@ int ppdEmitFd (<br /> <h3 class="function"><a id="ppdEmitJCL">ppdEmitJCL</a></h3> <p class="description">Emit code for JCL options to a file.</p> <p class="code"> -int ppdEmitJCL (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    FILE *fp,<br /> -    int job_id,<br /> -    const char *user,<br /> -    const char *title<br /> +int ppdEmitJCL (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    FILE *fp,<br> +    int job_id,<br> +    const char *user,<br> +    const char *title<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1102,9 +1103,9 @@ int ppdEmitJCL (<br /> <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppdEmitJCLEnd">ppdEmitJCLEnd</a></h3> <p class="description">Emit JCLEnd code to a file.</p> <p class="code"> -int ppdEmitJCLEnd (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    FILE *fp<br /> +int ppdEmitJCLEnd (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    FILE *fp<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1118,10 +1119,10 @@ int ppdEmitJCLEnd (<br /> <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppdEmitString">ppdEmitString</a></h3> <p class="description">Get a string containing the code for marked options.</p> <p class="code"> -char *ppdEmitString (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    <a href="#ppd_section_t">ppd_section_t</a> section,<br /> -    float min_order<br /> +char *ppdEmitString (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    <a href="#ppd_section_t">ppd_section_t</a> section,<br> +    float min_order<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1147,10 +1148,10 @@ The return string is allocated on the heap and should be freed using <h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ppdFindAttr">ppdFindAttr</a></h3> <p class="description">Find the first matching attribute.</p> <p class="code"> -<a href="#ppd_attr_t">ppd_attr_t</a> *ppdFindAttr (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *name,<br /> -    const char *spec<br /> +<a href="#ppd_attr_t">ppd_attr_t</a> *ppdFindAttr (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *name,<br> +    const char *spec<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1166,9 +1167,9 @@ The return string is allocated on the heap and should be freed using <h3 class="function"><a id="ppdFindChoice">ppdFindChoice</a></h3> <p class="description">Return a pointer to an option choice.</p> <p class="code"> -<a href="#ppd_choice_t">ppd_choice_t</a> *ppdFindChoice (<br /> -    <a href="#ppd_option_t">ppd_option_t</a> *o,<br /> -    const char *choice<br /> +<a href="#ppd_choice_t">ppd_choice_t</a> *ppdFindChoice (<br> +    <a href="#ppd_option_t">ppd_option_t</a> *o,<br> +    const char *choice<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1182,9 +1183,9 @@ The return string is allocated on the heap and should be freed using <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppdFindCustomOption">ppdFindCustomOption</a></h3> <p class="description">Find a custom option.</p> <p class="code"> -<a href="#ppd_coption_t">ppd_coption_t</a> *ppdFindCustomOption (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *keyword<br /> +<a href="#ppd_coption_t">ppd_coption_t</a> *ppdFindCustomOption (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *keyword<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1198,9 +1199,9 @@ The return string is allocated on the heap and should be freed using <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppdFindCustomParam">ppdFindCustomParam</a></h3> <p class="description">Find a parameter for a custom option.</p> <p class="code"> -<a href="#ppd_cparam_t">ppd_cparam_t</a> *ppdFindCustomParam (<br /> -    <a href="#ppd_coption_t">ppd_coption_t</a> *opt,<br /> -    const char *name<br /> +<a href="#ppd_cparam_t">ppd_cparam_t</a> *ppdFindCustomParam (<br> +    <a href="#ppd_coption_t">ppd_coption_t</a> *opt,<br> +    const char *name<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1214,9 +1215,9 @@ The return string is allocated on the heap and should be freed using <h3 class="function"><a id="ppdFindMarkedChoice">ppdFindMarkedChoice</a></h3> <p class="description">Return the marked choice for the specified option.</p> <p class="code"> -<a href="#ppd_choice_t">ppd_choice_t</a> *ppdFindMarkedChoice (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *option<br /> +<a href="#ppd_choice_t">ppd_choice_t</a> *ppdFindMarkedChoice (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *option<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1230,10 +1231,10 @@ The return string is allocated on the heap and should be freed using <h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ppdFindNextAttr">ppdFindNextAttr</a></h3> <p class="description">Find the next matching attribute.</p> <p class="code"> -<a href="#ppd_attr_t">ppd_attr_t</a> *ppdFindNextAttr (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *name,<br /> -    const char *spec<br /> +<a href="#ppd_attr_t">ppd_attr_t</a> *ppdFindNextAttr (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *name,<br> +    const char *spec<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1249,9 +1250,9 @@ The return string is allocated on the heap and should be freed using <h3 class="function"><a id="ppdFindOption">ppdFindOption</a></h3> <p class="description">Return a pointer to the specified option.</p> <p class="code"> -<a href="#ppd_option_t">ppd_option_t</a> *ppdFindOption (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *option<br /> +<a href="#ppd_option_t">ppd_option_t</a> *ppdFindOption (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *option<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1265,8 +1266,8 @@ The return string is allocated on the heap and should be freed using <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppdFirstCustomParam">ppdFirstCustomParam</a></h3> <p class="description">Return the first parameter for a custom option.</p> <p class="code"> -<a href="#ppd_cparam_t">ppd_cparam_t</a> *ppdFirstCustomParam (<br /> -    <a href="#ppd_coption_t">ppd_coption_t</a> *opt<br /> +<a href="#ppd_cparam_t">ppd_cparam_t</a> *ppdFirstCustomParam (<br> +    <a href="#ppd_coption_t">ppd_coption_t</a> *opt<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1278,8 +1279,8 @@ The return string is allocated on the heap and should be freed using <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppdFirstOption">ppdFirstOption</a></h3> <p class="description">Return the first option in the PPD file.</p> <p class="code"> -<a href="#ppd_option_t">ppd_option_t</a> *ppdFirstOption (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd<br /> +<a href="#ppd_option_t">ppd_option_t</a> *ppdFirstOption (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1296,10 +1297,10 @@ The return string is allocated on the heap and should be freed using <p class="description">Test whether an option choice conflicts with an installable option.</p> <p class="code"> -int ppdInstallableConflict (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *option,<br /> -    const char *choice<br /> +int ppdInstallableConflict (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *option,<br> +    const char *choice<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1320,10 +1321,10 @@ on constraints against options in the "InstallableOptions" group. <h3 class="function"><a id="ppdIsMarked">ppdIsMarked</a></h3> <p class="description">Check to see if an option is marked.</p> <p class="code"> -int ppdIsMarked (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *option,<br /> -    const char *choice<br /> +int ppdIsMarked (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *option,<br> +    const char *choice<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1339,8 +1340,8 @@ int ppdIsMarked (<br /> <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppdLocalize">ppdLocalize</a></h3> <p class="description">Localize the PPD file to the current locale.</p> <p class="code"> -int ppdLocalize (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd<br /> +int ppdLocalize (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1358,10 +1359,10 @@ localized string uses the UTF-8 character encoding. <h3 class="function"><a id="ppdLocalizeAttr">ppdLocalizeAttr</a></h3> <p class="description">Localize an attribute.</p> <p class="code"> -<a href="#ppd_attr_t">ppd_attr_t</a> *ppdLocalizeAttr (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *keyword,<br /> -    const char *spec<br /> +<a href="#ppd_attr_t">ppd_attr_t</a> *ppdLocalizeAttr (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *keyword,<br> +    const char *spec<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1382,12 +1383,12 @@ attribute exists for the current locale, the unlocalized version is returned.</p <p class="description">Get the localized version of a cupsIPPReason attribute.</p> <p class="code"> -const char *ppdLocalizeIPPReason (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *reason,<br /> -    const char *scheme,<br /> -    char *buffer,<br /> -    size_t bufsize<br /> +const char *ppdLocalizeIPPReason (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *reason,<br> +    const char *scheme,<br> +    char *buffer,<br> +    size_t bufsize<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1417,9 +1418,9 @@ If no value of the requested scheme can be found, NULL is returned. <p class="description">Get the localized version of a marker-names attribute value.</p> <p class="code"> -const char *ppdLocalizeMarkerName (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *name<br /> +const char *ppdLocalizeMarkerName (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *name<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1439,8 +1440,8 @@ name can be found, <code>NULL</code> is returned. <h3 class="function"><a id="ppdMarkDefaults">ppdMarkDefaults</a></h3> <p class="description">Mark all default options in the PPD file.</p> <p class="code"> -void ppdMarkDefaults (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd<br /> +void ppdMarkDefaults (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1451,10 +1452,10 @@ void ppdMarkDefaults (<br /> <p class="description">Mark an option in a PPD file and return the number of conflicts.</p> <p class="code"> -int ppdMarkOption (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *option,<br /> -    const char *choice<br /> +int ppdMarkOption (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *option,<br> +    const char *choice<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1470,8 +1471,8 @@ int ppdMarkOption (<br /> <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppdNextCustomParam">ppdNextCustomParam</a></h3> <p class="description">Return the next parameter for a custom option.</p> <p class="code"> -<a href="#ppd_cparam_t">ppd_cparam_t</a> *ppdNextCustomParam (<br /> -    <a href="#ppd_coption_t">ppd_coption_t</a> *opt<br /> +<a href="#ppd_cparam_t">ppd_cparam_t</a> *ppdNextCustomParam (<br> +    <a href="#ppd_coption_t">ppd_coption_t</a> *opt<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1483,8 +1484,8 @@ int ppdMarkOption (<br /> <h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppdNextOption">ppdNextOption</a></h3> <p class="description">Return the next option in the PPD file.</p> <p class="code"> -<a href="#ppd_option_t">ppd_option_t</a> *ppdNextOption (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd<br /> +<a href="#ppd_option_t">ppd_option_t</a> *ppdNextOption (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1500,9 +1501,9 @@ int ppdMarkOption (<br /> <h3 class="function"><a id="ppdPageLength">ppdPageLength</a></h3> <p class="description">Get the page length for the given size.</p> <p class="code"> -float ppdPageLength (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *name<br /> +float ppdPageLength (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *name<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1516,9 +1517,9 @@ float ppdPageLength (<br /> <h3 class="function"><a id="ppdPageSize">ppdPageSize</a></h3> <p class="description">Get the page size record for the named size.</p> <p class="code"> -<a href="#ppd_size_t">ppd_size_t</a> *ppdPageSize (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *name<br /> +<a href="#ppd_size_t">ppd_size_t</a> *ppdPageSize (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *name<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1532,10 +1533,10 @@ float ppdPageLength (<br /> <h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="ppdPageSizeLimits">ppdPageSizeLimits</a></h3> <p class="description">Return the custom page size limits.</p> <p class="code"> -int ppdPageSizeLimits (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    <a href="#ppd_size_t">ppd_size_t</a> *minimum,<br /> -    <a href="#ppd_size_t">ppd_size_t</a> *maximum<br /> +int ppdPageSizeLimits (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    <a href="#ppd_size_t">ppd_size_t</a> *minimum,<br> +    <a href="#ppd_size_t">ppd_size_t</a> *maximum<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1559,9 +1560,9 @@ If the specified PPD file does not support custom page sizes, both <h3 class="function"><a id="ppdPageWidth">ppdPageWidth</a></h3> <p class="description">Get the page width for the given size.</p> <p class="code"> -float ppdPageWidth (<br /> -    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br /> -    const char *name<br /> +float ppdPageWidth (<br> +    <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> +    const char *name<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1671,11 +1672,11 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <h2 class="title"><a id="STRUCTURES">Structures</a></h2> <h3 class="struct"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ppd_attr_s">ppd_attr_s</a></h3> <p class="description">PPD Attribute Structure </p> -<p class="code">struct ppd_attr_s {<br /> -    char name[PPD_MAX_NAME];<br /> -    char spec[PPD_MAX_NAME];<br /> -    char text[PPD_MAX_TEXT];<br /> -    char *value;<br /> +<p class="code">struct ppd_attr_s {<br> +    char name[PPD_MAX_NAME];<br> +    char spec[PPD_MAX_NAME];<br> +    char text[PPD_MAX_TEXT];<br> +    char *value;<br> };</p> <h4 class="members">Members</h4> <dl> @@ -1690,12 +1691,12 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </dl> <h3 class="struct"><a id="ppd_choice_s">ppd_choice_s</a></h3> <p class="description">Option choices</p> -<p class="code">struct ppd_choice_s {<br /> -    char choice[PPD_MAX_NAME];<br /> -    char *code;<br /> -    char marked;<br /> -    <a href="#ppd_option_t">ppd_option_t</a> *option;<br /> -    char text[PPD_MAX_TEXT];<br /> +<p class="code">struct ppd_choice_s {<br> +    char choice[PPD_MAX_NAME];<br> +    char *code;<br> +    char marked;<br> +    <a href="#ppd_option_t">ppd_option_t</a> *option;<br> +    char text[PPD_MAX_TEXT];<br> };</p> <h4 class="members">Members</h4> <dl> @@ -1712,11 +1713,11 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </dl> <h3 class="struct"><a id="ppd_const_s">ppd_const_s</a></h3> <p class="description">Constraints</p> -<p class="code">struct ppd_const_s {<br /> -    char choice1[PPD_MAX_NAME];<br /> -    char choice2[PPD_MAX_NAME];<br /> -    char option1[PPD_MAX_NAME];<br /> -    char option2[PPD_MAX_NAME];<br /> +<p class="code">struct ppd_const_s {<br> +    char choice1[PPD_MAX_NAME];<br> +    char choice2[PPD_MAX_NAME];<br> +    char option1[PPD_MAX_NAME];<br> +    char option2[PPD_MAX_NAME];<br> };</p> <h4 class="members">Members</h4> <dl> @@ -1731,11 +1732,11 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </dl> <h3 class="struct"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppd_coption_s">ppd_coption_s</a></h3> <p class="description">Custom Option </p> -<p class="code">struct ppd_coption_s {<br /> -    char keyword[PPD_MAX_NAME];<br /> -    int marked;<br /> -    <a href="#ppd_option_t">ppd_option_t</a> *option;<br /> -    cups_array_t *params;<br /> +<p class="code">struct ppd_coption_s {<br> +    char keyword[PPD_MAX_NAME];<br> +    int marked;<br> +    <a href="#ppd_option_t">ppd_option_t</a> *option;<br> +    cups_array_t *params;<br> };</p> <h4 class="members">Members</h4> <dl> @@ -1750,13 +1751,13 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </dl> <h3 class="struct"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppd_cparam_s">ppd_cparam_s</a></h3> <p class="description">Custom Parameter </p> -<p class="code">struct ppd_cparam_s {<br /> -    <a href="#ppd_cpvalue_t">ppd_cpvalue_t</a> current;<br /> -    <a href="#ppd_cplimit_t">ppd_cplimit_t</a> minimum, maximum;<br /> -    char name[PPD_MAX_NAME];<br /> -    int order;<br /> -    char text[PPD_MAX_TEXT];<br /> -    <a href="#ppd_cptype_t">ppd_cptype_t</a> type;<br /> +<p class="code">struct ppd_cparam_s {<br> +    <a href="#ppd_cpvalue_t">ppd_cpvalue_t</a> current;<br> +    <a href="#ppd_cplimit_t">ppd_cplimit_t</a> minimum, maximum;<br> +    char name[PPD_MAX_NAME];<br> +    int order;<br> +    char text[PPD_MAX_TEXT];<br> +    <a href="#ppd_cptype_t">ppd_cptype_t</a> type;<br> };</p> <h4 class="members">Members</h4> <dl> @@ -1775,10 +1776,10 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </dl> <h3 class="struct"><a id="ppd_emul_s">ppd_emul_s</a></h3> <p class="description">Emulators</p> -<p class="code">struct ppd_emul_s {<br /> -    char name[PPD_MAX_NAME];<br /> -    char *start;<br /> -    char *stop;<br /> +<p class="code">struct ppd_emul_s {<br> +    char name[PPD_MAX_NAME];<br> +    char *start;<br> +    char *stop;<br> };</p> <h4 class="members">Members</h4> <dl> @@ -1791,49 +1792,49 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </dl> <h3 class="struct"><a id="ppd_file_s">ppd_file_s</a></h3> <p class="description">PPD File</p> -<p class="code">struct ppd_file_s {<br /> -    int accurate_screens;<br /> -    int color_device;<br /> -    <a href="#ppd_cs_t">ppd_cs_t</a> colorspace;<br /> -    <a href="#ppd_const_t">ppd_const_t</a> *consts;<br /> -    int contone_only;<br /> -    float custom_margins[4];<br /> -    float custom_max[2];<br /> -    float custom_min[2];<br /> -    <a href="#ppd_emul_t">ppd_emul_t</a> *emulations;<br /> -    char **filters;<br /> -    int flip_duplex;<br /> -    char **fonts;<br /> -    <a href="#ppd_group_t">ppd_group_t</a> *groups;<br /> -    char *jcl_begin;<br /> -    char *jcl_end;<br /> -    char *jcl_ps;<br /> -    int landscape;<br /> -    char *lang_encoding;<br /> -    char *lang_version;<br /> -    int language_level;<br /> -    int manual_copies;<br /> -    char *manufacturer;<br /> -    int model_number;<br /> -    char *modelname;<br /> -    char *nickname;<br /> -    int num_consts;<br /> -    int num_emulations;<br /> -    int num_filters;<br /> -    int num_fonts;<br /> -    int num_groups;<br /> -    int num_profiles;<br /> -    int num_sizes;<br /> -    char *patches;<br /> -    char *pcfilename;<br /> -    char *product;<br /> -    <a href="#ppd_profile_t">ppd_profile_t</a> *profiles;<br /> -    char *protocols;<br /> -    char *shortnickname;<br /> -    <a href="#ppd_size_t">ppd_size_t</a> *sizes;<br /> -    int throughput;<br /> -    char *ttrasterizer;<br /> -    int variable_sizes;<br /> +<p class="code">struct ppd_file_s {<br> +    int accurate_screens;<br> +    int color_device;<br> +    <a href="#ppd_cs_t">ppd_cs_t</a> colorspace;<br> +    <a href="#ppd_const_t">ppd_const_t</a> *consts;<br> +    int contone_only;<br> +    float custom_margins[4];<br> +    float custom_max[2];<br> +    float custom_min[2];<br> +    <a href="#ppd_emul_t">ppd_emul_t</a> *emulations;<br> +    char **filters;<br> +    int flip_duplex;<br> +    char **fonts;<br> +    <a href="#ppd_group_t">ppd_group_t</a> *groups;<br> +    char *jcl_begin;<br> +    char *jcl_end;<br> +    char *jcl_ps;<br> +    int landscape;<br> +    char *lang_encoding;<br> +    char *lang_version;<br> +    int language_level;<br> +    int manual_copies;<br> +    char *manufacturer;<br> +    int model_number;<br> +    char *modelname;<br> +    char *nickname;<br> +    int num_consts;<br> +    int num_emulations;<br> +    int num_filters;<br> +    int num_fonts;<br> +    int num_groups;<br> +    int num_profiles;<br> +    int num_sizes;<br> +    char *patches;<br> +    char *pcfilename;<br> +    char *product;<br> +    <a href="#ppd_profile_t">ppd_profile_t</a> *profiles;<br> +    char *protocols;<br> +    char *shortnickname;<br> +    <a href="#ppd_size_t">ppd_size_t</a> *sizes;<br> +    int throughput;<br> +    char *ttrasterizer;<br> +    int variable_sizes;<br> };</p> <h4 class="members">Members</h4> <dl> @@ -1924,13 +1925,13 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </dl> <h3 class="struct"><a id="ppd_group_s">ppd_group_s</a></h3> <p class="description">Groups</p> -<p class="code">struct ppd_group_s {<br /> -    char text[PPD_MAX_TEXT - PPD_MAX_NAME];<br /> -    char name[PPD_MAX_NAME];<br /> -    int num_options;<br /> -    int num_subgroups;<br /> -    <a href="#ppd_option_t">ppd_option_t</a> *options;<br /> -    struct <a href="#ppd_group_s">ppd_group_s</a> *subgroups;<br /> +<p class="code">struct ppd_group_s {<br> +    char text[PPD_MAX_TEXT - PPD_MAX_NAME];<br> +    char name[PPD_MAX_NAME];<br> +    int num_options;<br> +    int num_subgroups;<br> +    <a href="#ppd_option_t">ppd_option_t</a> *options;<br> +    struct <a href="#ppd_group_s">ppd_group_s</a> *subgroups;<br> };</p> <h4 class="members">Members</h4> <dl> @@ -1949,16 +1950,16 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </dl> <h3 class="struct"><a id="ppd_option_s">ppd_option_s</a></h3> <p class="description">Options</p> -<p class="code">struct ppd_option_s {<br /> -    <a href="#ppd_choice_t">ppd_choice_t</a> *choices;<br /> -    char conflicted;<br /> -    char defchoice[PPD_MAX_NAME];<br /> -    char keyword[PPD_MAX_NAME];<br /> -    int num_choices;<br /> -    float order;<br /> -    <a href="#ppd_section_t">ppd_section_t</a> section;<br /> -    char text[PPD_MAX_TEXT];<br /> -    <a href="#ppd_ui_t">ppd_ui_t</a> ui;<br /> +<p class="code">struct ppd_option_s {<br> +    <a href="#ppd_choice_t">ppd_choice_t</a> *choices;<br> +    char conflicted;<br> +    char defchoice[PPD_MAX_NAME];<br> +    char keyword[PPD_MAX_NAME];<br> +    int num_choices;<br> +    float order;<br> +    <a href="#ppd_section_t">ppd_section_t</a> section;<br> +    char text[PPD_MAX_TEXT];<br> +    <a href="#ppd_ui_t">ppd_ui_t</a> ui;<br> };</p> <h4 class="members">Members</h4> <dl> @@ -1983,12 +1984,12 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </dl> <h3 class="struct"><a id="ppd_profile_s">ppd_profile_s</a></h3> <p class="description">sRGB Color Profiles</p> -<p class="code">struct ppd_profile_s {<br /> -    float density;<br /> -    float gamma;<br /> -    float matrix[3][3];<br /> -    char media_type[PPD_MAX_NAME];<br /> -    char resolution[PPD_MAX_NAME];<br /> +<p class="code">struct ppd_profile_s {<br> +    float density;<br> +    float gamma;<br> +    float matrix[3][3];<br> +    char media_type[PPD_MAX_NAME];<br> +    char resolution[PPD_MAX_NAME];<br> };</p> <h4 class="members">Members</h4> <dl> @@ -2005,15 +2006,15 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </dl> <h3 class="struct"><a id="ppd_size_s">ppd_size_s</a></h3> <p class="description">Page Sizes</p> -<p class="code">struct ppd_size_s {<br /> -    float bottom;<br /> -    float left;<br /> -    float length;<br /> -    int marked;<br /> -    char name[PPD_MAX_NAME];<br /> -    float right;<br /> -    float top;<br /> -    float width;<br /> +<p class="code">struct ppd_size_s {<br> +    float bottom;<br> +    float left;<br> +    float length;<br> +    int marked;<br> +    char name[PPD_MAX_NAME];<br> +    float right;<br> +    float top;<br> +    float width;<br> };</p> <h4 class="members">Members</h4> <dl> @@ -2037,15 +2038,15 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <h2 class="title"><a id="UNIONS">Unions</a></h2> <h3 class="union"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppd_cplimit_u">ppd_cplimit_u</a></h3> <p class="description">Custom Parameter Limit </p> -<p class="code">union ppd_cplimit_u {<br /> -    float custom_curve;<br /> -    int custom_int;<br /> -    float custom_invcurve;<br /> -    int custom_passcode;<br /> -    int custom_password;<br /> -    float custom_points;<br /> -    float custom_real;<br /> -    int custom_string;<br /> +<p class="code">union ppd_cplimit_u {<br> +    float custom_curve;<br> +    int custom_int;<br> +    float custom_invcurve;<br> +    int custom_passcode;<br> +    int custom_password;<br> +    float custom_points;<br> +    float custom_real;<br> +    int custom_string;<br> };</p> <h4 class="members">Members</h4> <dl> @@ -2068,15 +2069,15 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </dl> <h3 class="union"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ppd_cpvalue_u">ppd_cpvalue_u</a></h3> <p class="description">Custom Parameter Value </p> -<p class="code">union ppd_cpvalue_u {<br /> -    float custom_curve;<br /> -    int custom_int;<br /> -    float custom_invcurve;<br /> -    char *custom_passcode;<br /> -    char *custom_password;<br /> -    float custom_points;<br /> -    float custom_real;<br /> -    char *custom_string;<br /> +<p class="code">union ppd_cpvalue_u {<br> +    float custom_curve;<br> +    int custom_int;<br> +    float custom_invcurve;<br> +    char *custom_passcode;<br> +    char *custom_password;<br> +    float custom_points;<br> +    float custom_real;<br> +    char *custom_string;<br> };</p> <h4 class="members">Members</h4> <dl> diff --git a/doc/help/cupspm.epub b/doc/help/cupspm.epub Binary files differnew file mode 100644 index 000000000..7a38910fd --- /dev/null +++ b/doc/help/cupspm.epub diff --git a/doc/help/cupspm.html b/doc/help/cupspm.html new file mode 100644 index 000000000..196e7eee0 --- /dev/null +++ b/doc/help/cupspm.html @@ -0,0 +1,10312 @@ +<!doctype html> +<html> +<!-- SECTION: Programming --> + <head> + <title>CUPS Programming Manual</title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.11"> + <meta name="author" content="Michael R Sweet"> + <meta name="copyright" content="Copyright (c) 2007-2017 by Apple Inc. All Rights Reserved."> + <meta name="version" content="2.2.4"> + <style type="text/css"><!-- +body, p, h1, h2, h3, h4 { + font-family: sans-serif; +} +div.body h1 { + font-size: 250%; + font-weight: bold; + margin: 0; +} +div.body h2 { + font-size: 250%; + margin-top: 1.5em; +} +div.body h3 { + font-size: 150%; + margin-bottom: 0.5em; + margin-top: 1.5em; +} +div.body h4 { + font-size: 110%; + margin-bottom: 0.5em; + margin-top: 1.5em; +} +div.body h5 { + font-size: 100%; + margin-bottom: 0.5em; + margin-top: 1.5em; +} +div.contents { + background: #e8e8e8; + border: solid thin black; + padding: 10px; +} +div.contents h1 { + font-size: 110%; +} +div.contents h2 { + font-size: 100%; +} +div.contents ul.contents { + font-size: 80%; +} +.class { + border-bottom: solid 2px gray; +} +.constants { +} +.description { + margin-top: 0.5em; +} +.discussion { +} +.enumeration { + border-bottom: solid 2px gray; +} +.function { + border-bottom: solid 2px gray; + margin-bottom: 0; +} +.members { +} +.method { +} +.parameters { +} +.returnvalue { +} +.struct { + border-bottom: solid 2px gray; +} +.typedef { + border-bottom: solid 2px gray; +} +.union { + border-bottom: solid 2px gray; +} +.variable { +} +blockquote { + border: solid thin gray; + box-shadow: 3px 3px 5px rgba(0,0,0,0.5); + padding: 0px 10px; + page-break-inside: avoid; +} +p code, li code, p.code, pre, ul.code li { + background: rgba(127,127,127,0.1); + border: thin dotted gray; + font-family: monospace; + font-size: 90%; + hyphens: manual; + -webkit-hyphens: manual; + page-break-inside: avoid; +} +p.code, pre, ul.code li { + padding: 10px; +} +p code, li code { + padding: 2px 5px; +} +a:link, a:visited { + text-decoration: none; +} +span.info { + background: black; + border: solid thin black; + color: white; + font-size: 80%; + font-style: italic; + font-weight: bold; + white-space: nowrap; +} +h3 span.info, h4 span.info { + float: right; + font-size: 100%; +} +ul.code, ul.contents, ul.subcontents { + list-style-type: none; + margin: 0; + padding-left: 0; +} +ul.code li { + margin: 0; +} +ul.contents > li { + margin-top: 1em; +} +ul.contents li ul.code, ul.contents li ul.subcontents { + padding-left: 2em; +} +div.body dl { + margin-top: 0; +} +div.body dt { + font-style: italic; + margin-top: 0; +} +div.body dd { + margin-bottom: 0.5em; +} +h1.title { +} +h2.title { + border-bottom: solid 2px black; +} +h3.title { + border-bottom: solid 2px black; +} +--></style> + </head> + <body> + <h1 class="title">CUPS Programming Manual</h1> + <p>Michael R Sweet</p> + <p>Copyright (c) 2007-2017 by Apple Inc. All Rights Reserved.</p> + <div class="contents"> + <h2 class="title">Contents</h2> + <ul class="contents"> + <li><a href="#Introduction">Introduction</a><ul class="subcontents"> + <li><a href="#Guidelines">Guidelines</a></li> + <li><a href="#TermsUsedinThisDocument">Terms Used in This Document</a></li> + <li><a href="#CompilingProgramsThatUsetheCUPSAPI">Compiling Programs That Use the CUPS API</a></li> + </ul></li> + <li><a href="#WorkingwithDestinations">Working with Destinations</a><ul class="subcontents"> + <li><a href="#FindingAvailableDestinations">Finding Available Destinations</a></li> + <li><a href="#BasicDestinationInformation">Basic Destination Information</a></li> + <li><a href="#DetailedDestinationInformation">Detailed Destination Information</a></li> + <li><a href="#SubmittingaPrintJob">Submitting a Print Job</a></li> + </ul></li> + <li><a href="#FUNCTIONS">Functions</a><ul class="subcontents"> + <li><a href="#cupsAddDest">cupsAddDest</a></li> + <li><a href="#cupsAddOption">cupsAddOption</a></li> + <li><a href="#cupsArrayAdd">cupsArrayAdd</a></li> + <li><a href="#cupsArrayClear">cupsArrayClear</a></li> + <li><a href="#cupsArrayCount">cupsArrayCount</a></li> + <li><a href="#cupsArrayCurrent">cupsArrayCurrent</a></li> + <li><a href="#cupsArrayDelete">cupsArrayDelete</a></li> + <li><a href="#cupsArrayDup">cupsArrayDup</a></li> + <li><a href="#cupsArrayFind">cupsArrayFind</a></li> + <li><a href="#cupsArrayFirst">cupsArrayFirst</a></li> + <li><a href="#cupsArrayGetIndex">cupsArrayGetIndex</a></li> + <li><a href="#cupsArrayGetInsert">cupsArrayGetInsert</a></li> + <li><a href="#cupsArrayIndex">cupsArrayIndex</a></li> + <li><a href="#cupsArrayInsert">cupsArrayInsert</a></li> + <li><a href="#cupsArrayLast">cupsArrayLast</a></li> + <li><a href="#cupsArrayNew">cupsArrayNew</a></li> + <li><a href="#cupsArrayNew2">cupsArrayNew2</a></li> + <li><a href="#cupsArrayNew3">cupsArrayNew3</a></li> + <li><a href="#cupsArrayNext">cupsArrayNext</a></li> + <li><a href="#cupsArrayPrev">cupsArrayPrev</a></li> + <li><a href="#cupsArrayRemove">cupsArrayRemove</a></li> + <li><a href="#cupsArrayRestore">cupsArrayRestore</a></li> + <li><a href="#cupsArraySave">cupsArraySave</a></li> + <li><a href="#cupsArrayUserData">cupsArrayUserData</a></li> + <li><a href="#cupsCancelDestJob">cupsCancelDestJob</a></li> + <li><a href="#cupsCancelJob">cupsCancelJob</a></li> + <li><a href="#cupsCancelJob2">cupsCancelJob2</a></li> + <li><a href="#cupsCheckDestSupported">cupsCheckDestSupported</a></li> + <li><a href="#cupsCloseDestJob">cupsCloseDestJob</a></li> + <li><a href="#cupsConnectDest">cupsConnectDest</a></li> + <li><a href="#cupsConnectDestBlock">cupsConnectDestBlock</a></li> + <li><a href="#cupsCopyDest">cupsCopyDest</a></li> + <li><a href="#cupsCopyDestConflicts">cupsCopyDestConflicts</a></li> + <li><a href="#cupsCopyDestInfo">cupsCopyDestInfo</a></li> + <li><a href="#cupsCreateDestJob">cupsCreateDestJob</a></li> + <li><a href="#cupsCreateJob">cupsCreateJob</a></li> + <li><a href="#cupsDirClose">cupsDirClose</a></li> + <li><a href="#cupsDirOpen">cupsDirOpen</a></li> + <li><a href="#cupsDirRead">cupsDirRead</a></li> + <li><a href="#cupsDirRewind">cupsDirRewind</a></li> + <li><a href="#cupsDoAuthentication">cupsDoAuthentication</a></li> + <li><a href="#cupsEncodeOptions">cupsEncodeOptions</a></li> + <li><a href="#cupsEncodeOptions2">cupsEncodeOptions2</a></li> + <li><a href="#cupsEncryption">cupsEncryption</a></li> + <li><a href="#cupsEnumDests">cupsEnumDests</a></li> + <li><a href="#cupsEnumDestsBlock">cupsEnumDestsBlock</a></li> + <li><a href="#cupsFileClose">cupsFileClose</a></li> + <li><a href="#cupsFileCompression">cupsFileCompression</a></li> + <li><a href="#cupsFileEOF">cupsFileEOF</a></li> + <li><a href="#cupsFileFind">cupsFileFind</a></li> + <li><a href="#cupsFileFlush">cupsFileFlush</a></li> + <li><a href="#cupsFileGetChar">cupsFileGetChar</a></li> + <li><a href="#cupsFileGetConf">cupsFileGetConf</a></li> + <li><a href="#cupsFileGetLine">cupsFileGetLine</a></li> + <li><a href="#cupsFileGets">cupsFileGets</a></li> + <li><a href="#cupsFileLock">cupsFileLock</a></li> + <li><a href="#cupsFileNumber">cupsFileNumber</a></li> + <li><a href="#cupsFileOpen">cupsFileOpen</a></li> + <li><a href="#cupsFileOpenFd">cupsFileOpenFd</a></li> + <li><a href="#cupsFilePeekChar">cupsFilePeekChar</a></li> + <li><a href="#cupsFilePrintf">cupsFilePrintf</a></li> + <li><a href="#cupsFilePutChar">cupsFilePutChar</a></li> + <li><a href="#cupsFilePutConf">cupsFilePutConf</a></li> + <li><a href="#cupsFilePuts">cupsFilePuts</a></li> + <li><a href="#cupsFileRead">cupsFileRead</a></li> + <li><a href="#cupsFileRewind">cupsFileRewind</a></li> + <li><a href="#cupsFileSeek">cupsFileSeek</a></li> + <li><a href="#cupsFileStderr">cupsFileStderr</a></li> + <li><a href="#cupsFileStdin">cupsFileStdin</a></li> + <li><a href="#cupsFileStdout">cupsFileStdout</a></li> + <li><a href="#cupsFileTell">cupsFileTell</a></li> + <li><a href="#cupsFileUnlock">cupsFileUnlock</a></li> + <li><a href="#cupsFileWrite">cupsFileWrite</a></li> + <li><a href="#cupsFindDestDefault">cupsFindDestDefault</a></li> + <li><a href="#cupsFindDestReady">cupsFindDestReady</a></li> + <li><a href="#cupsFindDestSupported">cupsFindDestSupported</a></li> + <li><a href="#cupsFinishDestDocument">cupsFinishDestDocument</a></li> + <li><a href="#cupsFinishDocument">cupsFinishDocument</a></li> + <li><a href="#cupsFreeDestInfo">cupsFreeDestInfo</a></li> + <li><a href="#cupsFreeDests">cupsFreeDests</a></li> + <li><a href="#cupsFreeJobs">cupsFreeJobs</a></li> + <li><a href="#cupsFreeOptions">cupsFreeOptions</a></li> + <li><a href="#cupsGetClasses">cupsGetClasses</a></li> + <li><a href="#cupsGetDefault">cupsGetDefault</a></li> + <li><a href="#cupsGetDefault2">cupsGetDefault2</a></li> + <li><a href="#cupsGetDest">cupsGetDest</a></li> + <li><a href="#cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></li> + <li><a href="#cupsGetDestMediaByName">cupsGetDestMediaByName</a></li> + <li><a href="#cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></li> + <li><a href="#cupsGetDestMediaCount">cupsGetDestMediaCount</a></li> + <li><a href="#cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></li> + <li><a href="#cupsGetDestWithURI">cupsGetDestWithURI</a></li> + <li><a href="#cupsGetDests">cupsGetDests</a></li> + <li><a href="#cupsGetDests2">cupsGetDests2</a></li> + <li><a href="#cupsGetJobs">cupsGetJobs</a></li> + <li><a href="#cupsGetJobs2">cupsGetJobs2</a></li> + <li><a href="#cupsGetNamedDest">cupsGetNamedDest</a></li> + <li><a href="#cupsGetOption">cupsGetOption</a></li> + <li><a href="#cupsGetPassword">cupsGetPassword</a></li> + <li><a href="#cupsGetPassword2">cupsGetPassword2</a></li> + <li><a href="#cupsGetPrinters">cupsGetPrinters</a></li> + <li><a href="#cupsLangDefault">cupsLangDefault</a></li> + <li><a href="#cupsLangEncoding">cupsLangEncoding</a></li> + <li><a href="#cupsLangFlush">cupsLangFlush</a></li> + <li><a href="#cupsLangFree">cupsLangFree</a></li> + <li><a href="#cupsLangGet">cupsLangGet</a></li> + <li><a href="#cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></li> + <li><a href="#cupsLocalizeDestOption">cupsLocalizeDestOption</a></li> + <li><a href="#cupsLocalizeDestValue">cupsLocalizeDestValue</a></li> + <li><a href="#cupsMakeServerCredentials">cupsMakeServerCredentials</a></li> + <li><a href="#cupsNotifySubject">cupsNotifySubject</a></li> + <li><a href="#cupsNotifyText">cupsNotifyText</a></li> + <li><a href="#cupsParseOptions">cupsParseOptions</a></li> + <li><a href="#cupsPrintFile">cupsPrintFile</a></li> + <li><a href="#cupsPrintFile2">cupsPrintFile2</a></li> + <li><a href="#cupsPrintFiles">cupsPrintFiles</a></li> + <li><a href="#cupsPrintFiles2">cupsPrintFiles2</a></li> + <li><a href="#cupsRemoveDest">cupsRemoveDest</a></li> + <li><a href="#cupsRemoveOption">cupsRemoveOption</a></li> + <li><a href="#cupsServer">cupsServer</a></li> + <li><a href="#cupsSetClientCertCB">cupsSetClientCertCB</a></li> + <li><a href="#cupsSetCredentials">cupsSetCredentials</a></li> + <li><a href="#cupsSetDefaultDest">cupsSetDefaultDest</a></li> + <li><a href="#cupsSetDests">cupsSetDests</a></li> + <li><a href="#cupsSetDests2">cupsSetDests2</a></li> + <li><a href="#cupsSetEncryption">cupsSetEncryption</a></li> + <li><a href="#cupsSetPasswordCB">cupsSetPasswordCB</a></li> + <li><a href="#cupsSetPasswordCB2">cupsSetPasswordCB2</a></li> + <li><a href="#cupsSetServer">cupsSetServer</a></li> + <li><a href="#cupsSetServerCertCB">cupsSetServerCertCB</a></li> + <li><a href="#cupsSetServerCredentials">cupsSetServerCredentials</a></li> + <li><a href="#cupsSetUser">cupsSetUser</a></li> + <li><a href="#cupsSetUserAgent">cupsSetUserAgent</a></li> + <li><a href="#cupsStartDestDocument">cupsStartDestDocument</a></li> + <li><a href="#cupsStartDocument">cupsStartDocument</a></li> + <li><a href="#cupsTempFd">cupsTempFd</a></li> + <li><a href="#cupsTempFile">cupsTempFile</a></li> + <li><a href="#cupsTempFile2">cupsTempFile2</a></li> + <li><a href="#cupsUser">cupsUser</a></li> + <li><a href="#cupsUserAgent">cupsUserAgent</a></li> + <li><a href="#httpAcceptConnection">httpAcceptConnection</a></li> + <li><a href="#httpAddCredential">httpAddCredential</a></li> + <li><a href="#httpAddrAny">httpAddrAny</a></li> + <li><a href="#httpAddrClose">httpAddrClose</a></li> + <li><a href="#httpAddrConnect">httpAddrConnect</a></li> + <li><a href="#httpAddrConnect2">httpAddrConnect2</a></li> + <li><a href="#httpAddrCopyList">httpAddrCopyList</a></li> + <li><a href="#httpAddrEqual">httpAddrEqual</a></li> + <li><a href="#httpAddrFamily">httpAddrFamily</a></li> + <li><a href="#httpAddrFreeList">httpAddrFreeList</a></li> + <li><a href="#httpAddrGetList">httpAddrGetList</a></li> + <li><a href="#httpAddrLength">httpAddrLength</a></li> + <li><a href="#httpAddrListen">httpAddrListen</a></li> + <li><a href="#httpAddrLocalhost">httpAddrLocalhost</a></li> + <li><a href="#httpAddrLookup">httpAddrLookup</a></li> + <li><a href="#httpAddrPort">httpAddrPort</a></li> + <li><a href="#httpAddrString">httpAddrString</a></li> + <li><a href="#httpAssembleURI">httpAssembleURI</a></li> + <li><a href="#httpAssembleURIf">httpAssembleURIf</a></li> + <li><a href="#httpAssembleUUID">httpAssembleUUID</a></li> + <li><a href="#httpBlocking">httpBlocking</a></li> + <li><a href="#httpCheck">httpCheck</a></li> + <li><a href="#httpClearCookie">httpClearCookie</a></li> + <li><a href="#httpClearFields">httpClearFields</a></li> + <li><a href="#httpClose">httpClose</a></li> + <li><a href="#httpCompareCredentials">httpCompareCredentials</a></li> + <li><a href="#httpConnect">httpConnect</a></li> + <li><a href="#httpConnect2">httpConnect2</a></li> + <li><a href="#httpConnectEncrypt">httpConnectEncrypt</a></li> + <li><a href="#httpCopyCredentials">httpCopyCredentials</a></li> + <li><a href="#httpCredentialsAreValidForName">httpCredentialsAreValidForName</a></li> + <li><a href="#httpCredentialsGetExpiration">httpCredentialsGetExpiration</a></li> + <li><a href="#httpCredentialsGetTrust">httpCredentialsGetTrust</a></li> + <li><a href="#httpCredentialsString">httpCredentialsString</a></li> + <li><a href="#httpDecode64">httpDecode64</a></li> + <li><a href="#httpDecode64_2">httpDecode64_2</a></li> + <li><a href="#httpDelete">httpDelete</a></li> + <li><a href="#httpEncode64">httpEncode64</a></li> + <li><a href="#httpEncode64_2">httpEncode64_2</a></li> + <li><a href="#httpEncryption">httpEncryption</a></li> + <li><a href="#httpError">httpError</a></li> + <li><a href="#httpFieldValue">httpFieldValue</a></li> + <li><a href="#httpFlush">httpFlush</a></li> + <li><a href="#httpFlushWrite">httpFlushWrite</a></li> + <li><a href="#httpFreeCredentials">httpFreeCredentials</a></li> + <li><a href="#httpGet">httpGet</a></li> + <li><a href="#httpGetActivity">httpGetActivity</a></li> + <li><a href="#httpGetAddress">httpGetAddress</a></li> + <li><a href="#httpGetAuthString">httpGetAuthString</a></li> + <li><a href="#httpGetBlocking">httpGetBlocking</a></li> + <li><a href="#httpGetContentEncoding">httpGetContentEncoding</a></li> + <li><a href="#httpGetCookie">httpGetCookie</a></li> + <li><a href="#httpGetDateString">httpGetDateString</a></li> + <li><a href="#httpGetDateString2">httpGetDateString2</a></li> + <li><a href="#httpGetDateTime">httpGetDateTime</a></li> + <li><a href="#httpGetEncryption">httpGetEncryption</a></li> + <li><a href="#httpGetExpect">httpGetExpect</a></li> + <li><a href="#httpGetFd">httpGetFd</a></li> + <li><a href="#httpGetField">httpGetField</a></li> + <li><a href="#httpGetHostByName">httpGetHostByName</a></li> + <li><a href="#httpGetHostname">httpGetHostname</a></li> + <li><a href="#httpGetKeepAlive">httpGetKeepAlive</a></li> + <li><a href="#httpGetLength">httpGetLength</a></li> + <li><a href="#httpGetLength2">httpGetLength2</a></li> + <li><a href="#httpGetPending">httpGetPending</a></li> + <li><a href="#httpGetReady">httpGetReady</a></li> + <li><a href="#httpGetRemaining">httpGetRemaining</a></li> + <li><a href="#httpGetState">httpGetState</a></li> + <li><a href="#httpGetStatus">httpGetStatus</a></li> + <li><a href="#httpGetSubField">httpGetSubField</a></li> + <li><a href="#httpGetSubField2">httpGetSubField2</a></li> + <li><a href="#httpGetVersion">httpGetVersion</a></li> + <li><a href="#httpGets">httpGets</a></li> + <li><a href="#httpHead">httpHead</a></li> + <li><a href="#httpInitialize">httpInitialize</a></li> + <li><a href="#httpIsChunked">httpIsChunked</a></li> + <li><a href="#httpIsEncrypted">httpIsEncrypted</a></li> + <li><a href="#httpLoadCredentials">httpLoadCredentials</a></li> + <li><a href="#httpOptions">httpOptions</a></li> + <li><a href="#httpPeek">httpPeek</a></li> + <li><a href="#httpPost">httpPost</a></li> + <li><a href="#httpPut">httpPut</a></li> + <li><a href="#httpRead">httpRead</a></li> + <li><a href="#httpRead2">httpRead2</a></li> + <li><a href="#httpReadRequest">httpReadRequest</a></li> + <li><a href="#httpReconnect">httpReconnect</a></li> + <li><a href="#httpReconnect2">httpReconnect2</a></li> + <li><a href="#httpResolveHostname">httpResolveHostname</a></li> + <li><a href="#httpSaveCredentials">httpSaveCredentials</a></li> + <li><a href="#httpSeparate">httpSeparate</a></li> + <li><a href="#httpSeparate2">httpSeparate2</a></li> + <li><a href="#httpSeparateURI">httpSeparateURI</a></li> + <li><a href="#httpSetAuthString">httpSetAuthString</a></li> + <li><a href="#httpSetCookie">httpSetCookie</a></li> + <li><a href="#httpSetCredentials">httpSetCredentials</a></li> + <li><a href="#httpSetDefaultField">httpSetDefaultField</a></li> + <li><a href="#httpSetExpect">httpSetExpect</a></li> + <li><a href="#httpSetField">httpSetField</a></li> + <li><a href="#httpSetKeepAlive">httpSetKeepAlive</a></li> + <li><a href="#httpSetLength">httpSetLength</a></li> + <li><a href="#httpSetTimeout">httpSetTimeout</a></li> + <li><a href="#httpShutdown">httpShutdown</a></li> + <li><a href="#httpStateString">httpStateString</a></li> + <li><a href="#httpStatus">httpStatus</a></li> + <li><a href="#httpTrace">httpTrace</a></li> + <li><a href="#httpURIStatusString">httpURIStatusString</a></li> + <li><a href="#httpUpdate">httpUpdate</a></li> + <li><a href="#httpWait">httpWait</a></li> + <li><a href="#httpWrite">httpWrite</a></li> + <li><a href="#httpWrite2">httpWrite2</a></li> + <li><a href="#httpWriteResponse">httpWriteResponse</a></li> + <li><a href="#ippAddBoolean">ippAddBoolean</a></li> + <li><a href="#ippAddBooleans">ippAddBooleans</a></li> + <li><a href="#ippAddCollection">ippAddCollection</a></li> + <li><a href="#ippAddCollections">ippAddCollections</a></li> + <li><a href="#ippAddDate">ippAddDate</a></li> + <li><a href="#ippAddInteger">ippAddInteger</a></li> + <li><a href="#ippAddIntegers">ippAddIntegers</a></li> + <li><a href="#ippAddOctetString">ippAddOctetString</a></li> + <li><a href="#ippAddOutOfBand">ippAddOutOfBand</a></li> + <li><a href="#ippAddRange">ippAddRange</a></li> + <li><a href="#ippAddRanges">ippAddRanges</a></li> + <li><a href="#ippAddResolution">ippAddResolution</a></li> + <li><a href="#ippAddResolutions">ippAddResolutions</a></li> + <li><a href="#ippAddSeparator">ippAddSeparator</a></li> + <li><a href="#ippAddString">ippAddString</a></li> + <li><a href="#ippAddStringf">ippAddStringf</a></li> + <li><a href="#ippAddStringfv">ippAddStringfv</a></li> + <li><a href="#ippAddStrings">ippAddStrings</a></li> + <li><a href="#ippAttributeString">ippAttributeString</a></li> + <li><a href="#ippContainsInteger">ippContainsInteger</a></li> + <li><a href="#ippContainsString">ippContainsString</a></li> + <li><a href="#ippCopyAttribute">ippCopyAttribute</a></li> + <li><a href="#ippCopyAttributes">ippCopyAttributes</a></li> + <li><a href="#ippCreateRequestedArray">ippCreateRequestedArray</a></li> + <li><a href="#ippDateToTime">ippDateToTime</a></li> + <li><a href="#ippDelete">ippDelete</a></li> + <li><a href="#ippDeleteAttribute">ippDeleteAttribute</a></li> + <li><a href="#ippDeleteValues">ippDeleteValues</a></li> + <li><a href="#ippEnumString">ippEnumString</a></li> + <li><a href="#ippEnumValue">ippEnumValue</a></li> + <li><a href="#ippErrorString">ippErrorString</a></li> + <li><a href="#ippErrorValue">ippErrorValue</a></li> + <li><a href="#ippFindAttribute">ippFindAttribute</a></li> + <li><a href="#ippFindNextAttribute">ippFindNextAttribute</a></li> + <li><a href="#ippFirstAttribute">ippFirstAttribute</a></li> + <li><a href="#ippGetBoolean">ippGetBoolean</a></li> + <li><a href="#ippGetCollection">ippGetCollection</a></li> + <li><a href="#ippGetCount">ippGetCount</a></li> + <li><a href="#ippGetDate">ippGetDate</a></li> + <li><a href="#ippGetGroupTag">ippGetGroupTag</a></li> + <li><a href="#ippGetInteger">ippGetInteger</a></li> + <li><a href="#ippGetName">ippGetName</a></li> + <li><a href="#ippGetOctetString">ippGetOctetString</a></li> + <li><a href="#ippGetOperation">ippGetOperation</a></li> + <li><a href="#ippGetRange">ippGetRange</a></li> + <li><a href="#ippGetRequestId">ippGetRequestId</a></li> + <li><a href="#ippGetResolution">ippGetResolution</a></li> + <li><a href="#ippGetState">ippGetState</a></li> + <li><a href="#ippGetStatusCode">ippGetStatusCode</a></li> + <li><a href="#ippGetString">ippGetString</a></li> + <li><a href="#ippGetValueTag">ippGetValueTag</a></li> + <li><a href="#ippGetVersion">ippGetVersion</a></li> + <li><a href="#ippLength">ippLength</a></li> + <li><a href="#ippNew">ippNew</a></li> + <li><a href="#ippNewRequest">ippNewRequest</a></li> + <li><a href="#ippNewResponse">ippNewResponse</a></li> + <li><a href="#ippNextAttribute">ippNextAttribute</a></li> + <li><a href="#ippOpString">ippOpString</a></li> + <li><a href="#ippOpValue">ippOpValue</a></li> + <li><a href="#ippPort">ippPort</a></li> + <li><a href="#ippRead">ippRead</a></li> + <li><a href="#ippReadFile">ippReadFile</a></li> + <li><a href="#ippReadIO">ippReadIO</a></li> + <li><a href="#ippSetBoolean">ippSetBoolean</a></li> + <li><a href="#ippSetCollection">ippSetCollection</a></li> + <li><a href="#ippSetDate">ippSetDate</a></li> + <li><a href="#ippSetGroupTag">ippSetGroupTag</a></li> + <li><a href="#ippSetInteger">ippSetInteger</a></li> + <li><a href="#ippSetName">ippSetName</a></li> + <li><a href="#ippSetOctetString">ippSetOctetString</a></li> + <li><a href="#ippSetOperation">ippSetOperation</a></li> + <li><a href="#ippSetPort">ippSetPort</a></li> + <li><a href="#ippSetRange">ippSetRange</a></li> + <li><a href="#ippSetRequestId">ippSetRequestId</a></li> + <li><a href="#ippSetResolution">ippSetResolution</a></li> + <li><a href="#ippSetState">ippSetState</a></li> + <li><a href="#ippSetStatusCode">ippSetStatusCode</a></li> + <li><a href="#ippSetString">ippSetString</a></li> + <li><a href="#ippSetStringf">ippSetStringf</a></li> + <li><a href="#ippSetStringfv">ippSetStringfv</a></li> + <li><a href="#ippSetValueTag">ippSetValueTag</a></li> + <li><a href="#ippSetVersion">ippSetVersion</a></li> + <li><a href="#ippStateString">ippStateString</a></li> + <li><a href="#ippTagString">ippTagString</a></li> + <li><a href="#ippTagValue">ippTagValue</a></li> + <li><a href="#ippTimeToDate">ippTimeToDate</a></li> + <li><a href="#ippValidateAttribute">ippValidateAttribute</a></li> + <li><a href="#ippValidateAttributes">ippValidateAttributes</a></li> + <li><a href="#ippWrite">ippWrite</a></li> + <li><a href="#ippWriteFile">ippWriteFile</a></li> + <li><a href="#ippWriteIO">ippWriteIO</a></li> + <li><a href="#pwgFormatSizeName">pwgFormatSizeName</a></li> + <li><a href="#pwgInitSize">pwgInitSize</a></li> + <li><a href="#pwgMediaForLegacy">pwgMediaForLegacy</a></li> + <li><a href="#pwgMediaForPPD">pwgMediaForPPD</a></li> + <li><a href="#pwgMediaForPWG">pwgMediaForPWG</a></li> + <li><a href="#pwgMediaForSize">pwgMediaForSize</a></li> + </ul></li> + <li><a href="#TYPES">Data Types</a><ul class="subcontents"> + <li><a href="#cups_acopy_func_t">cups_acopy_func_t</a></li> + <li><a href="#cups_afree_func_t">cups_afree_func_t</a></li> + <li><a href="#cups_ahash_func_t">cups_ahash_func_t</a></li> + <li><a href="#cups_array_func_t">cups_array_func_t</a></li> + <li><a href="#cups_array_t">cups_array_t</a></li> + <li><a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a></li> + <li><a href="#cups_dentry_t">cups_dentry_t</a></li> + <li><a href="#cups_dest_block_t">cups_dest_block_t</a></li> + <li><a href="#cups_dest_cb_t">cups_dest_cb_t</a></li> + <li><a href="#cups_dest_t">cups_dest_t</a></li> + <li><a href="#cups_dinfo_t">cups_dinfo_t</a></li> + <li><a href="#cups_dir_t">cups_dir_t</a></li> + <li><a href="#cups_encoding_t">cups_encoding_t</a></li> + <li><a href="#cups_file_t">cups_file_t</a></li> + <li><a href="#cups_job_t">cups_job_t</a></li> + <li><a href="#cups_lang_t">cups_lang_t</a></li> + <li><a href="#cups_option_t">cups_option_t</a></li> + <li><a href="#cups_password_cb2_t">cups_password_cb2_t</a></li> + <li><a href="#cups_password_cb_t">cups_password_cb_t</a></li> + <li><a href="#cups_ptype_t">cups_ptype_t</a></li> + <li><a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a></li> + <li><a href="#cups_size_t">cups_size_t</a></li> + <li><a href="#gss_auth_identity_desc">gss_auth_identity_desc</a></li> + <li><a href="#http_addr_t">http_addr_t</a></li> + <li><a href="#http_addrlist_t">http_addrlist_t</a></li> + <li><a href="#http_auth_t">http_auth_t</a></li> + <li><a href="#http_credential_t">http_credential_t</a></li> + <li><a href="#http_encoding_t">http_encoding_t</a></li> + <li><a href="#http_encryption_t">http_encryption_t</a></li> + <li><a href="#http_field_t">http_field_t</a></li> + <li><a href="#http_keepalive_t">http_keepalive_t</a></li> + <li><a href="#http_state_t">http_state_t</a></li> + <li><a href="#http_t">http_t</a></li> + <li><a href="#http_timeout_cb_t">http_timeout_cb_t</a></li> + <li><a href="#http_trust_t">http_trust_t</a></li> + <li><a href="#http_uri_coding_t">http_uri_coding_t</a></li> + <li><a href="#http_uri_status_t">http_uri_status_t</a></li> + <li><a href="#http_version_t">http_version_t</a></li> + <li><a href="#ipp_attribute_t">ipp_attribute_t</a></li> + <li><a href="#ipp_copycb_t">ipp_copycb_t</a></li> + <li><a href="#ipp_dstate_t">ipp_dstate_t</a></li> + <li><a href="#ipp_finish_t">ipp_finish_t</a></li> + <li><a href="#ipp_iocb_t">ipp_iocb_t</a></li> + <li><a href="#ipp_jcollate_t">ipp_jcollate_t</a></li> + <li><a href="#ipp_orient_t">ipp_orient_t</a></li> + <li><a href="#ipp_pstate_t">ipp_pstate_t</a></li> + <li><a href="#ipp_quality_t">ipp_quality_t</a></li> + <li><a href="#ipp_res_t">ipp_res_t</a></li> + <li><a href="#ipp_state_t">ipp_state_t</a></li> + <li><a href="#ipp_t">ipp_t</a></li> + <li><a href="#ipp_uchar_t">ipp_uchar_t</a></li> + <li><a href="#pwg_map_t">pwg_map_t</a></li> + <li><a href="#pwg_media_t">pwg_media_t</a></li> + <li><a href="#pwg_size_t">pwg_size_t</a></li> + </ul></li> + <li><a href="#STRUCTURES">Structures</a><ul class="subcontents"> + <li><a href="#cups_dentry_s">cups_dentry_s</a></li> + <li><a href="#cups_dest_s">cups_dest_s</a></li> + <li><a href="#cups_job_s">cups_job_s</a></li> + <li><a href="#cups_lang_s">cups_lang_s</a></li> + <li><a href="#cups_option_s">cups_option_s</a></li> + <li><a href="#cups_size_s">cups_size_s</a></li> + <li><a href="#gss_auth_identity">gss_auth_identity</a></li> + <li><a href="#http_addrlist_s">http_addrlist_s</a></li> + <li><a href="#http_credential_s">http_credential_s</a></li> + <li><a href="#pollfd">pollfd</a></li> + <li><a href="#pwg_map_s">pwg_map_s</a></li> + <li><a href="#pwg_media_s">pwg_media_s</a></li> + <li><a href="#pwg_size_s">pwg_size_s</a></li> + </ul></li> + <li><a href="#VARIABLES">Variables</a><ul class="subcontents"> + <li><a href="#CF_RETURNS_RETAINED">CF_RETURNS_RETAINED</a></li> + <li><a href="#environ">environ</a></li> + </ul></li> + <li><a href="#ENUMERATIONS">Enumerations</a><ul class="subcontents"> + <li><a href="#cups_encoding_e">cups_encoding_e</a></li> + <li><a href="#cups_ptype_e">cups_ptype_e</a></li> + <li><a href="#http_auth_e">http_auth_e</a></li> + <li><a href="#http_encoding_e">http_encoding_e</a></li> + <li><a href="#http_encryption_e">http_encryption_e</a></li> + <li><a href="#http_field_e">http_field_e</a></li> + <li><a href="#http_keepalive_e">http_keepalive_e</a></li> + <li><a href="#http_state_e">http_state_e</a></li> + <li><a href="#http_status_e">http_status_e</a></li> + <li><a href="#http_trust_e">http_trust_e</a></li> + <li><a href="#http_uri_coding_e">http_uri_coding_e</a></li> + <li><a href="#http_uri_status_e">http_uri_status_e</a></li> + <li><a href="#http_version_e">http_version_e</a></li> + <li><a href="#ipp_dstate_e">ipp_dstate_e</a></li> + <li><a href="#ipp_finishings_e">ipp_finishings_e</a></li> + <li><a href="#ipp_jcollate_e">ipp_jcollate_e</a></li> + <li><a href="#ipp_jstate_e">ipp_jstate_e</a></li> + <li><a href="#ipp_op_e">ipp_op_e</a></li> + <li><a href="#ipp_orient_e">ipp_orient_e</a></li> + <li><a href="#ipp_pstate_e">ipp_pstate_e</a></li> + <li><a href="#ipp_quality_e">ipp_quality_e</a></li> + <li><a href="#ipp_res_e">ipp_res_e</a></li> + <li><a href="#ipp_state_e">ipp_state_e</a></li> + <li><a href="#ipp_status_e">ipp_status_e</a></li> + <li><a href="#ipp_tag_e">ipp_tag_e</a></li> + </ul></li> + </ul> + </div> + <div class="body"> + <blockquote> + <p>Note: This document is under active development and is incomplete, with a goal completing it prior to releasing CUPS 2.2.4. Please <a href="https://github.com/apple/cups/issues">file issues on Github</a> to provide any feedback.</p> +</blockquote> + <h2><a id="Introduction">Introduction</a></h2> + <p>CUPS provides the "cups" library to talk to the different parts of CUPS and with Internet Printing Protocol (IPP) printers. The "cups" library functions are accessed by including the <code><cups/cups.h></code> header.</p> + <p>CUPS is based on the Internet Printing Protocol ("IPP"), which allows clients (applications) to communicate with a server (the scheduler, printers, etc.) to get a list of destinations, send print jobs, and so forth. You identify which server you want to communicate with using a pointer to the opaque structure <code>http_t</code>. The <code>CUPS_HTTP_DEFAULT</code> constant can be used when you want to talk to the CUPS scheduler.</p> + <h3><a id="Guidelines">Guidelines</a></h3> + <p>When writing software that uses the "cups" library:</p> + <ul> + <li>Do not use undocumented or deprecated APIs,</li> + <li>Do not rely on pre-configured printers,</li> + <li>Do not assume that printers support specific features or formats, and</li> + <li>Do not rely on implementation details (PPDs, etc.)</li> +</ul> + <p>CUPS is designed to insulate users and developers from the implementation details of printers and file formats. The goal is to allow an application to supply a print file in a standard format with the user intent ("print four copies, two-sided on A4 media, and staple each copy") and have the printing system manage the printer communication and format conversion needed.</p> + <p>Similarly, printer and job management applications can use standard query operations to obtain the status information in a common, generic form and use standard management operations to control the state of those printers and jobs.</p> + <h3><a id="TermsUsedinThisDocument">Terms Used in This Document</a></h3> + <p>A <em>Destination</em> is a printer or print queue that accepts print jobs. A <em>Print</em> Job* is one or more documents that are processed by a destination using options supplied when creating the job. A <em>Document</em> is a file (JPEG image, PDF file, etc.) suitable for printing. An <em>Option</em> controls some aspect of printing, such as the media used. <em>Media</em> is the sheets or roll that is printed on. An <em>Attribute</em> is an option encoded for an Internet Printing Protocol (IPP) request.</p> + <h3><a id="CompilingProgramsThatUsetheCUPSAPI">Compiling Programs That Use the CUPS API</a></h3> + <p>The CUPS libraries can be used from any C, C++, or Objective C program. The method of compiling against the libraries varies depending on the operating system and installation of CUPS. The following sections show how to compile a simple program (shown below) in two common environments.</p> + <p>The following simple program lists the available destinations:</p> + <pre><code>#include <stdio.h> +#include <cups/cups.h> + +int print_dest(void *user_data, unsigned flags, cups_dest_t *dest) +{ + if (dest->instance) + printf("%s/%s\n", dest->name, dest->instance); + else + puts(dest->name); + + return (1); +} + +int main(void) +{ + cupsEnumDests(CUPS_DEST_FLAGS_NONE, 1000, NULL, 0, 0, print_dest, NULL); + + return (0); +} +</code></pre> + <h4><a id="CompilingwithXcode">Compiling with Xcode</a></h4> + <p>In Xcode, choose <em>New</em> Project...* from the <em>File</em> menu (or press SHIFT+CMD+N), then select the <em>Command</em> Line Tool* under the macOS Application project type. Click <em>Next</em> and enter a name for the project, for example "firstcups". Click <em>Next</em> and choose a project directory. The click <em>Next</em> to create the project.</p> + <p>In the project window, click on the <em>Build</em> Phases* group and expand the <em>Link</em> Binary with Libraries* section. Click <em>+</em>, type "libcups" to show the library, and then double-click on <code>libcups.tbd</code>.</p> + <p>Finally, click on the <code>main.c</code> file in the sidebar and copy the example program to the file. Build and run (CMD+R) to see the list of destinations.</p> + <h4><a id="CompilingwithGCC">Compiling with GCC</a></h4> + <p>From the command-line, create a file called <code>sample.c</code> using your favorite editor, copy the example to this file, and save. Then run the following command to compile it with GCC and run it:</p> + <pre><code>gcc -o simple `cups-config --cflags` simple.c `cups-config --libs` +./simple +</code></pre> + <p>The <code>cups-config</code> command provides the compiler flags (`cups-config --cflags`) and libraries (`cups-config --libs`) needed for the local system.</p> + <h2><a id="WorkingwithDestinations">Working with Destinations</a></h2> + <p>Destinations, which in CUPS represent individual printers or classes (collections) of printers, are represented by the <code>cups_dest_t</code> structure which includes the name (`name`), instance (`instance`, saved options/settings), whether the destination is the default for the user (`is_default`), and the options and attributes associated with that destination (`num_options` and <code>options</code>).</p> + <p>Historically destinations have been manually maintained by the administrator of a system or network, but CUPS also supports dynamic discovery of destinations on the current network.</p> + <h3><a id="FindingAvailableDestinations">Finding Available Destinations</a></h3> + <p>The <code>cupsEnumDests</code> function finds all of the available destinations:</p> + <pre><code> int + cupsEnumDests(unsigned flags, int msec, int *cancel, + cups_ptype_t type, cups_ptype_t mask, + cups_dest_cb_t cb, void *user_data) +</code></pre> + <p>The <code>flags</code> argument specifies enumeration options, which at present must be <code>CUPS_DEST_FLAGS_NONE</code>.</p> + <p>The <code>msec</code> argument specifies the maximum amount of time that should be used for enumeration in milliseconds - interactive applications should keep this value to 5000 or less when run on the main thread.</p> + <p>The <code>cancel</code> argument points to an integer variable that, when set to a non-zero value, will cause enumeration to stop as soon as possible. It can be <code>NULL</code> if not needed.</p> + <p>The <code>type</code> and <code>mask</code> arguments are bitfields that allow the caller to filter the destinations based on categories and/or capabilities. The destination's "printer-type" value is masked by the <code>mask</code> value and compared to the <code>type</code> value when filtering. For example, to only enumerate destinations that are hosted on the local system, pass <code>CUPS_PRINTER_LOCAL</code> for the <code>type</code> argument and <code>CUPS_PRINTER_REMOTE</code> for the <code>mask</code> argument. The following constants can be used for filtering:</p> + <ul> + <li><code>CUPS_PRINTER_CLASS</code>: A collection of destinations.</li> + <li><code>CUPS_PRINTER_FAX</code>: A facsimile device.</li> + <li><code>CUPS_PRINTER_LOCAL</code>: A local printer or class. This constant has the value 0 (no bits set) and is only used for the <code>type</code> argument and is paired with the <code>CUPS_PRINTER_REMOTE</code> constant passed in the <code>mask</code> argument.</li> + <li><code>CUPS_PRINTER_REMOTE</code>: A remote printer or class.</li> + <li><code>CUPS_PRINTER_BW</code>: Can do B&W printing.</li> + <li><code>CUPS_PRINTER_COLOR</code>: Can do color printing.</li> + <li><code>CUPS_PRINTER_DUPLEX</code>: Can do two-sided printing.</li> + <li><code>CUPS_PRINTER_STAPLE</code>: Can staple output.</li> + <li><code>CUPS_PRINTER_COLLATE</code>: Can quickly collate copies.</li> + <li><code>CUPS_PRINTER_PUNCH</code>: Can punch output.</li> + <li><code>CUPS_PRINTER_COVER</code>: Can cover output.</li> + <li><code>CUPS_PRINTER_BIND</code>: Can bind output.</li> + <li><code>CUPS_PRINTER_SORT</code>: Can sort output (mailboxes, etc.)</li> + <li><code>CUPS_PRINTER_SMALL</code>: Can print on Letter/Legal/A4-size media.</li> + <li><code>CUPS_PRINTER_MEDIUM</code>: Can print on Tabloid/B/C/A3/A2-size media.</li> + <li><code>CUPS_PRINTER_LARGE</code>: Can print on D/E/A1/A0-size media.</li> + <li><code>CUPS_PRINTER_VARIABLE</code>: Can print on rolls and custom-size media.</li> +</ul> + <p>The <code>cb</code> argument specifies a function to call for every destination that is found:</p> + <pre><code>typedef int (*cups_dest_cb_t)(void *user_data, + unsigned flags, + cups_dest_t *dest); +</code></pre> + <p>The callback function receives a copy of the <code>user_data</code> argument along with a bitfield (`flags`) and the destination that was found. The <code>flags</code> argument can have any of the following constant (bit) values set:</p> + <ul> + <li><code>CUPS_DEST_FLAGS_MORE</code>: There are more destinations coming.</li> + <li><code>CUPS_DEST_FLAGS_REMOVED</code>: The destination has gone away and should be removed from the list of destinations a user can select.</li> + <li><code>CUPS_DEST_FLAGS_ERROR</code>: An error occurred. The reason for the error can be found by calling the <code>cupsLastError</code> and/or <code>cupsLastErrorString</code> functions.</li> +</ul> + <p>The callback function returns 0 to stop enumeration or 1 to continue.</p> + <p>The following example shows how to use <code>cupsEnumDests</code> to get a filtered array of destinations:</p> + <pre><code>typedef struct +{ + int num_dests; + cups_dest_t *dests; +} my_user_data_t; + +int +my_dest_cb(my_user_data_t *user_data, unsigned flags, + cups_dest_t *dest) +{ + if (flags & CUPS_DEST_FLAGS_REMOVED) + { + /* + * Remove destination from array... + */ + + user_data->num_dests = + cupsRemoveDest(dest->name, dest->instance, + user_data->num_dests, + &(user_data->dests)); + } + else + { + /* + * Add destination to array... + */ + + user_data->num_dests = + cupsCopyDest(dest, user_data->num_dests, + &(user_data->dests)); + } + + return (1); +} + +int +my_get_dests(cups_ptype_t type, cups_ptype_t mask, + cups_dest_t **dests) +{ + my_user_data_t user_data = { 0, NULL }; + + if (!cupsEnumDests(CUPS_DEST_FLAGS_NONE, 1000, NULL, type, + mask, (cups_dest_cb_t)my_dest_cb, + &user_data)) + { + /* + * An error occurred, free all of the destinations and + * return... + */ + + cupsFreeDests(user_data.num_dests, user_dasta.dests); + + *dests = NULL; + + return (0); + } + + /* + * Return the destination array... + */ + + *dests = user_data.dests; + + return (user_data.num_dests); +} +</code></pre> + <h3><a id="BasicDestinationInformation">Basic Destination Information</a></h3> + <p>The <code>num_options</code> and <code>options</code> members of the <code>cups_dest_t</code> structure provide basic attributes about the destination in addition to the user default options and values for that destination. The following names are predefined for various destination attributes:</p> + <ul> + <li>"auth-info-required": The type of authentication required for printing to this destination: "none", "username,password", "domain,username,password", or "negotiate" (Kerberos).</li> + <li>"printer-info": The human-readable description of the destination such as "My Laser Printer".</li> + <li>"printer-is-accepting-jobs": "true" if the destination is accepting new jobs, "false" otherwise.</li> + <li>"printer-is-shared": "true" if the destination is being shared with other computers, "false" otherwise.</li> + <li>"printer-location": The human-readable location of the destination such as "Lab 4".</li> + <li>"printer-make-and-model": The human-readable make and model of the destination such as "ExampleCorp LaserPrinter 4000 Series".</li> + <li>"printer-state": "3" if the destination is idle, "4" if the destination is printing a job, and "5" if the destination is stopped.</li> + <li>"printer-state-change-time": The UNIX time when the destination entered the current state.</li> + <li>"printer-state-reasons": Additional comma-delimited state keywords for the destination such as "media-tray-empty-error" and "toner-low-warning".</li> + <li>"printer-type": The <code>cups_ptype_t</code> value associated with the destination.</li> +</ul> + <p>Use the <code>cupsGetOption</code> function to retrieve the value. For example, the following code gets the make and model of a destination:</p> + <pre><code>const char *model = cupsGetOption("printer-make-and-model", + dest->num_options, + dest->options); +</code></pre> + <h3><a id="DetailedDestinationInformation">Detailed Destination Information</a></h3> + <p>Once a destination has been chosen, the <code>cupsCopyDestInfo</code> function can be used to gather detailed information about the destination:</p> + <pre><code>cups_dinfo_t * +cupsCopyDestInfo(http_t *http, cups_dest_t *dest); +</code></pre> + <p>The <code>http</code> argument specifies a connection to the CUPS scheduler and is typically the constant <code>CUPS_HTTP_DEFAULT</code>. The <code>dest</code> argument specifies the destination to query.</p> + <p>The <code>cups_dinfo_t</code> structure that is returned contains a snapshot of the supported options and their supported, ready, and default values. It also can report constraints between different options and values, and recommend changes to resolve those constraints.</p> + <h4><a id="GettingSupportedOptionsandValues">Getting Supported Options and Values</a></h4> + <p>The <code>cupsCheckDestSupported</code> function can be used to test whether a particular option or option and value is supported:</p> + <pre><code>int +cupsCheckDestSupported(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, + const char *option, + const char *value); +</code></pre> + <p>The <code>option</code> argument specifies the name of the option to check. The following constants can be used to check the various standard options:</p> + <ul> + <li><code>CUPS_COPIES</code>: Controls the number of copies that are produced.</li> + <li><code>CUPS_FINISHINGS</code>: A comma-delimited list of integer constants that control the finishing processes that are applied to the job, including stapling, punching, and folding.</li> + <li><code>CUPS_MEDIA</code>: Controls the media size that is used, typically one of the following: <code>CUPS_MEDIA_3X5</code>, <code>CUPS_MEDIA_4X6</code>, <code>CUPS_MEDIA_5X7</code>, <code>CUPS_MEDIA_8X10</code>, <code>CUPS_MEDIA_A3</code>, <code>CUPS_MEDIA_A4</code>, <code>CUPS_MEDIA_A5</code>, <code>CUPS_MEDIA_A6</code>, <code>CUPS_MEDIA_ENV10</code>, <code>CUPS_MEDIA_ENVDL</code>, <code>CUPS_MEDIA_LEGAL</code>, <code>CUPS_MEDIA_LETTER</code>, <code>CUPS_MEDIA_PHOTO_L</code>, <code>CUPS_MEDIA_SUPERBA3</code>, or <code>CUPS_MEDIA_TABLOID</code>.</li> + <li><code>CUPS_MEDIA_SOURCE</code>: Controls where the media is pulled from, typically either <code>CUPS_MEDIA_SOURCE_AUTO</code> or <code>CUPS_MEDIA_SOURCE_MANUAL</code>.</li> + <li><code>CUPS_MEDIA_TYPE</code>: Controls the type of media that is used, typically one of the following: <code>CUPS_MEDIA_TYPE_AUTO</code>, <code>CUPS_MEDIA_TYPE_ENVELOPE</code>, <code>CUPS_MEDIA_TYPE_LABELS</code>, <code>CUPS_MEDIA_TYPE_LETTERHEAD</code>, <code>CUPS_MEDIA_TYPE_PHOTO</code>, <code>CUPS_MEDIA_TYPE_PHOTO_GLOSSY</code>, <code>CUPS_MEDIA_TYPE_PHOTO_MATTE</code>, <code>CUPS_MEDIA_TYPE_PLAIN</code>, or <code>CUPS_MEDIA_TYPE_TRANSPARENCY</code>.</li> + <li><code>CUPS_NUMBER_UP</code>: Controls the number of document pages that are placed on each media side.</li> + <li><code>CUPS_ORIENTATION</code>: Controls the orientation of document pages placed on the media: <code>CUPS_ORIENTATION_PORTRAIT</code> or <code>CUPS_ORIENTATION_LANDSCAPE</code>.</li> + <li><code>CUPS_PRINT_COLOR_MODE</code>: Controls whether the output is in color (`CUPS_PRINT_COLOR_MODE_COLOR`), grayscale (`CUPS_PRINT_COLOR_MODE_MONOCHROME`), or either (`CUPS_PRINT_COLOR_MODE_AUTO`).</li> + <li><code>CUPS_PRINT_QUALITY</code>: Controls the generate quality of the output: <code>CUPS_PRINT_QUALITY_DRAFT</code>, <code>CUPS_PRINT_QUALITY_NORMAL</code>, or <code>CUPS_PRINT_QUALITY_HIGH</code>.</li> + <li><code>CUPS_SIDES</code>: Controls whether prints are placed on one or both sides of the media: <code>CUPS_SIDES_ONE_SIDED</code>, <code>CUPS_SIDES_TWO_SIDED_PORTRAIT</code>, or <code>CUPS_SIDES_TWO_SIDED_LANDSCAPE</code>.</li> +</ul> + <p>If the <code>value</code> argument is <code>NULL</code>, the <code>cupsCheckDestSupported</code> function returns whether the option is supported by the destination. Otherwise, the function returns whether the specified value of the option is supported.</p> + <p>The <code>cupsFindDestSupported</code> function returns the IPP attribute containing the supported values for a given option:</p> + <pre><code> ipp_attribute_t * + cupsFindDestSupported(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, + const char *option); +</code></pre> + <p>For example, the following code prints the supported finishing processes for a destination, if any, to the standard output:</p> + <pre><code>cups_dinfo_t *info = cupsCopyDestInfo(CUPS_HTTP_DEFAULT, + dest); + +if (cupsCheckDestSupported(CUPS_HTTP_DEFAULT, dest, info, + CUPS_FINISHINGS, NULL)) +{ + ipp_attribute_t *finishings = + cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info, + CUPS_FINISHINGS); + int i, count = ippGetCount(finishings); + + puts("finishings supported:"); + for (i = 0; i < count; i ++) + printf(" %d\n", ippGetInteger(finishings, i)); +} +else + puts("finishings not supported."); +</code></pre> + <p>The "job-creation-attributes" option can be queried to get a list of supported options. For example, the following code prints the list of supported options to the standard output:</p> + <pre><code>ipp_attribute_t *attrs = + cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info, + "job-creation-attributes"); +int i, count = ippGetCount(attrs); + +for (i = 0; i < count; i ++) + puts(ippGetString(attrs, i, NULL)); +</code></pre> + <h4><a id="GettingDefaultValues">Getting Default Values</a></h4> + <p>There are two sets of default values - user defaults that are available via the <code>num_options</code> and <code>options</code> members of the <code>cups_dest_t</code> structure, and destination defaults that available via the <code>cups_dinfo_t</code> structure and the <code>cupsFindDestDefault</code> function which returns the IPP attribute containing the default value(s) for a given option:</p> + <pre><code>ipp_attribute_t * +cupsFindDestDefault(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, + const char *option); +</code></pre> + <p>The user defaults from <code>cupsGetOption</code> should always take preference over the destination defaults. For example, the following code prints the default finishings value(s) to the standard output:</p> + <pre><code>const char *def_value = + cupsGetOption(CUPS_FINISHINGS, dest->num_options, + dest->options); +ipp_attribute_t *def_attr = + cupsFindDestDefault(CUPS_HTTP_DEFAULT, dest, info, + CUPS_FINISHINGS); + +if (def_value != NULL) +{ + printf("Default finishings: %s\n", def_value); +} +else +{ + int i, count = ippGetCount(def_attr); + + printf("Default finishings: %d", + ippGetInteger(def_attr, 0)); + for (i = 1; i < count; i ++) + printf(",%d", ippGetInteger(def_attr, i)); + putchar('\n'); +} +</code></pre> + <h4><a id="GettingReadyLoadedValues">Getting Ready (Loaded) Values</a></h4> + <p>The finishings and media options also support queries for the ready, or loaded, values. For example, a printer may have punch and staple finishers installed but be out of staples - the supported values will list both punch and staple finishing processes but the ready values will only list the punch processes. Similarly, a printer may support hundreds of different sizes of media but only have a single size loaded at any given time - the ready values are limited to the media that is actually in the printer.</p> + <p>The <code>cupsFindDestReady</code> function finds the IPP attribute containing the ready values for a given option:</p> + <pre><code>ipp_attribute_t * +cupsFindDestReady(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, const char *option); +</code></pre> + <p>For example, the following code lists the ready finishing processes:</p> + <pre><code>ipp_attribute_t *ready_finishings = + cupsFindDestReady(CUPS_HTTP_DEFAULT, dest, info, + CUPS_FINISHINGS); + +if (ready_finishings != NULL) +{ + int i, count = ippGetCount(ready_finishings); + + puts("finishings ready:"); + for (i = 0; i < count; i ++) + printf(" %d\n", ippGetInteger(ready_finishings, i)); +} +else + puts("no finishings are ready."); +</code></pre> + <h4><a id="MediaSizeOptions">Media Size Options</a></h4> + <p>CUPS provides functions for querying the dimensions and margins for each of the supported media size options. The <code>cups_size_t</code> structure is used to describe a media size:</p> + <pre><code>typedef struct cups_size_s +{ + char media[128]; + int width, length; + int bottom, left, right, top; +} cups_size_t; +</code></pre> + <p>The <code>width</code> and <code>length</code> members specify the dimensions of the media in hundredths of millimeters (1/2540th of an inch). The <code>bottom</code>, <code>left</code>, <code>right</code>, and <code>top</code> members specify the margins of the printable area, also in hundredths of millimeters.</p> + <p>The <code>cupsGetDestMediaByName</code> and <code>cupsGetDestMediaBySize</code> functions lookup the media size information using a standard media size name or dimensions in hundredths of millimeters:</p> + <pre><code>int +cupsGetDestMediaByName(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, + const char *media, + unsigned flags, cups_size_t *size); + +int +cupsGetDestMediaBySize(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, + int width, int length, + unsigned flags, cups_size_t *size); +</code></pre> + <p>The <code>media</code>, <code>width</code>, and <code>length</code> arguments specify the size to lookup. The <code>flags</code> argument specifies a bitfield controlling various lookup options:</p> + <ul> + <li><code>CUPS_MEDIA_FLAGS_DEFAULT</code>: Find the closest size supported by the printer.</li> + <li><code>CUPS_MEDIA_FLAGS_BORDERLESS</code>: Find a borderless size.</li> + <li><code>CUPS_MEDIA_FLAGS_DUPLEX</code>: Find a size compatible with two-sided printing.</li> + <li><code>CUPS_MEDIA_FLAGS_EXACT</code>: Find an exact match for the size.</li> + <li><code>CUPS_MEDIA_FLAGS_READY</code>: If the printer supports media sensing or configuration of the media in each tray/source, find the size amongst the "ready" media.</li> +</ul> + <p>If a matching size is found for the destination, the size information is stored in the structure pointed to by the <code>size</code> argument and 1 is returned. Otherwise 0 is returned.</p> + <p>For example, the following code prints the margins for two-sided printing on US Letter media:</p> + <pre><code>cups_size_t size; + +if (cupsGetDestMediaByName(CUPS_HTTP_DEFAULT, dest, info, + CUPS_MEDIA_LETTER, + CUPS_MEDIA_FLAGS_DUPLEX, &size)) +{ + puts("Margins for duplex US Letter:"); + printf(" Bottom: %.2fin\n", size.bottom / 2540.0); + printf(" Left: %.2fin\n", size.left / 2540.0); + printf(" Right: %.2fin\n", size.right / 2540.0); + printf(" Top: %.2fin\n", size.top / 2540.0); +} +else + puts("Margins for duplex US Letter are not available."); +</code></pre> + <p>You can also enumerate all of the sizes that match a given <code>flags</code> value using the <code>cupsGetDestMediaByIndex</code> and <code>cupsGetDestMediaCount</code> functions:</p> + <pre><code>int +cupsGetDestMediaByIndex(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, int n, + unsigned flags, cups_size_t *size); + +int +cupsGetDestMediaCount(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, unsigned flags); +</code></pre> + <p>For example, the following code prints the list of ready media and corresponding margins:</p> + <pre><code>cups_size_t size; +int i; +int count = cupsGetDestMediaCount(CUPS_HTTP_DEFAULT, + dest, info, + CUPS_MEDIA_FLAGS_READY); + +for (i = 0; i < count; i ++) +{ + if (cupsGetDestMediaByIndex(CUPS_HTTP_DEFAULT, dest, info, + i, CUPS_MEDIA_FLAGS_READY, + &size)) + { + printf("%s:\n", size.name); + printf(" Width: %.2fin\n", size.width / 2540.0); + printf(" Length: %.2fin\n", size.length / 2540.0); + printf(" Bottom: %.2fin\n", size.bottom / 2540.0); + printf(" Left: %.2fin\n", size.left / 2540.0); + printf(" Right: %.2fin\n", size.right / 2540.0); + printf(" Top: %.2fin\n", size.top / 2540.0); + } +} +</code></pre> + <p>Finally, the <code>cupsGetDestMediaDefault</code> function returns the default media size:</p> + <pre><code>int +cupsGetDestMediaDefault(http_t *http, cups_dest_t *dest, + cups_dinfo_t *dinfo, unsigned flags, + cups_size_t *size); +</code></pre> + <h4><a id="LocalizingOptionsandValues">Localizing Options and Values</a></h4> + <p>CUPS provides three functions to get localized versions of options and values: <code>cupsLocalizeDestMedia</code>, <code>cupsLocalizeDestOption</code>, and <code>cupsLocalizeDestValue</code>:</p> + <pre><code>const char * +cupsLocalizeDestMedia(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, unsigned flags, + cups_size_t *size); + +const char * +cupsLocalizeDestOption(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, + const char *option); + +const char * +cupsLocalizeDestValue(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, + const char *option, const char *value); +</code></pre> + <h3><a id="SubmittingaPrintJob">Submitting a Print Job</a></h3> + <p>Once you are ready to submit a print job, you create a job using the <code>cupsCreateDestJob</code> function:</p> + <pre><code>ipp_status_t +cupsCreateDestJob(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, int *job_id, + const char *title, int num_options, + cups_option_t *options); +</code></pre> + <p>The <code>title</code> argument specifies a name for the print job such as "My Document". The <code>num_options</code> and <code>options</code> arguments specify the options for the print job which are allocated using the <code>cupsAddOption</code> function.</p> + <p>When successful, the job's numeric identifier is stored in the integer pointed to by the <code>job_id</code> argument and <code>IPP_STATUS_OK</code> is returned. Otherwise, an IPP error status is returned.</p> + <p>For example, the following code creates a new job that will print 42 copies of a two-sided US Letter document:</p> + <pre><code>int job_id = 0; +int num_options = 0; +cups_option_t *options = NULL; + +num_options = cupsAddOption(CUPS_COPIES, "42", + num_options, &options); +num_options = cupsAddOption(CUPS_MEDIA, CUPS_MEDIA_LETTER, + num_options, &options); +num_options = cupsAddOption(CUPS_SIDES, + CUPS_SIDES_TWO_SIDED_PORTRAIT, + num_options, &options); + +if (cupsCreateDestJob(CUPS_HTTP_DEFAULT, dest, info, + &job_id, "My Document", num_options, + options) == IPP_STATUS_OK) + printf("Created job: %d\n", job_id); +else + printf("Unable to create job: %s\n", + cupsLastErrorString()); +</code></pre> + <p>Once the job is created, you submit documents for the job using the <code>cupsStartDestDocument</code>, <code>cupsWriteRequestData</code>, and <code>cupsFinishDestDocument</code> functions:</p> + <pre><code>http_status_t +cupsStartDestDocument(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info, int job_id, + const char *docname, + const char *format, + int num_options, + cups_option_t *options, + int last_document); + +http_status_t +cupsWriteRequestData(http_t *http, const char *buffer, + size_t length); + +ipp_status_t +cupsFinishDestDocument(http_t *http, cups_dest_t *dest, + cups_dinfo_t *info); +</code></pre> + <p>The <code>docname</code> argument specifies the name of the document, typically the original filename. The <code>format</code> argument specifies the MIME media type of the document, including the following constants:</p> + <ul> + <li><code>CUPS_FORMAT_JPEG</code>: "image/jpeg"</li> + <li><code>CUPS_FORMAT_PDF</code>: "application/pdf"</li> + <li><code>CUPS_FORMAT_POSTSCRIPT</code>: "application/postscript"</li> + <li><code>CUPS_FORMAT_TEXT</code>: "text/plain"</li> +</ul> + <p>The <code>num_options</code> and <code>options</code> arguments specify per-document print options, which at present must be 0 and <code>NULL</code>. The <code>last_document</code> argument specifies whether this is the last document in the job.</p> + <p>For example, the following code submits a PDF file to the job that was just created:</p> + <pre><code>FILE *fp = fopen("filename.pdf", "rb"); +size_t bytes; +char buffer[65536]; + +if (cupsStartDestDocument(CUPS_HTTP_DEFAULT, dest, info, + job_id, "filename.pdf", 0, NULL, + 1) == HTTP_STATUS_CONTINUE) +{ + while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) + if (cupsWriteRequestData(CUPS_HTTP_DEFAULT, buffer, + bytes) != HTTP_STATUS_CONTINUE) + break; + + if (cupsFinishDestDocument(CUPS_HTTP_DEFAULT, dest, + info) == IPP_STATUS_OK) + puts("Document send succeeded."); + else + printf("Document send failed: %s\n", + cupsLastErrorString()); +} + +fclose(fp); +</code></pre> + <h2 class="title"><a id="FUNCTIONS">Functions</a></h2> +<h3 class="function"><a id="cupsAddDest">cupsAddDest</a></h3> + <p class="description">Add a destination to the list of destinations.</p> +<p class="code"> +int cupsAddDest (<br> +    const char *name,<br> +    const char *instance,<br> +    int num_dests,<br> +    <a href="#cups_dest_t">cups_dest_t</a> **dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Destination name</dd> +<dt>instance</dt> + <dd class="description">Instance name or <code>NULL</code> for none/primary</dd> +<dt>num_dests</dt> + <dd class="description">Number of destinations</dd> +<dt>dests</dt> + <dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New number of destinations</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function cannot be used to add a new class or printer queue, +it only adds a new container of saved options for the named +destination or instance.<br> +<br> +If the named destination already exists, the destination list is +returned unchanged. Adding a new instance of a destination creates +a copy of that destination's options.<br> +<br> +Use the <a href="#cupsSaveDests"><code>cupsSaveDests</code></a> function to save the updated list of +destinations to the user's lpoptions file.</p> +<h3 class="function"><a id="cupsAddOption">cupsAddOption</a></h3> + <p class="description">Add an option to an option array.</p> +<p class="code"> +int cupsAddOption (<br> +    const char *name,<br> +    const char *value,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> **options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Name of option</dd> +<dt>value</dt> + <dd class="description">Value of option</dd> +<dt>num_options</dt> + <dd class="description">Number of options</dd> +<dt>options</dt> + <dd class="description">Pointer to options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of options</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">New option arrays can be initialized simply by passing 0 for the +"num_options" parameter.</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayAdd">cupsArrayAdd</a></h3> + <p class="description">Add an element to the array.</p> +<p class="code"> +int cupsArrayAdd (<br> +    <a href="#cups_array_t">cups_array_t</a> *a,<br> +    void *e<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +<dt>e</dt> + <dd class="description">Element</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">When adding an element to a sorted array, non-unique elements are +appended at the end of the run of identical elements. For unsorted arrays, +the element is appended to the end of the array. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayClear">cupsArrayClear</a></h3> + <p class="description">Clear the array.</p> +<p class="code"> +void cupsArrayClear (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is equivalent to removing all elements in the array. +The caller is responsible for freeing the memory used by the +elements themselves. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayCount">cupsArrayCount</a></h3> + <p class="description">Get the number of elements in the array.</p> +<p class="code"> +int cupsArrayCount (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of elements</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayCurrent">cupsArrayCurrent</a></h3> + <p class="description">Return the current element in the array.</p> +<p class="code"> +void *cupsArrayCurrent (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Element</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>, +<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayDelete">cupsArrayDelete</a></h3> + <p class="description">Free all memory used by the array.</p> +<p class="code"> +void cupsArrayDelete (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The caller is responsible for freeing the memory used by the +elements themselves. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayDup">cupsArrayDup</a></h3> + <p class="description">Duplicate the array.</p> +<p class="code"> +<a href="#cups_array_t">cups_array_t</a> *cupsArrayDup (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Duplicate array</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayFind">cupsArrayFind</a></h3> + <p class="description">Find an element in the array.</p> +<p class="code"> +void *cupsArrayFind (<br> +    <a href="#cups_array_t">cups_array_t</a> *a,<br> +    void *e<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +<dt>e</dt> + <dd class="description">Element</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Element found or <code>NULL</code></p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayFirst">cupsArrayFirst</a></h3> + <p class="description">Get the first element in the array.</p> +<p class="code"> +void *cupsArrayFirst (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">First element or <code>NULL</code> if the array is empty</p> +<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsArrayGetIndex">cupsArrayGetIndex</a></h3> + <p class="description">Get the index of the current element.</p> +<p class="code"> +int cupsArrayGetIndex (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Index of the current element, starting at 0</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>, +<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsArrayGetInsert">cupsArrayGetInsert</a></h3> + <p class="description">Get the index of the last inserted element.</p> +<p class="code"> +int cupsArrayGetInsert (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Index of the last inserted element, starting at 0</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayIndex">cupsArrayIndex</a></h3> + <p class="description">Get the N-th element in the array.</p> +<p class="code"> +void *cupsArrayIndex (<br> +    <a href="#cups_array_t">cups_array_t</a> *a,<br> +    int n<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +<dt>n</dt> + <dd class="description">Index into array, starting at 0</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">N-th element or <code>NULL</code></p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayInsert">cupsArrayInsert</a></h3> + <p class="description">Insert an element in the array.</p> +<p class="code"> +int cupsArrayInsert (<br> +    <a href="#cups_array_t">cups_array_t</a> *a,<br> +    void *e<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +<dt>e</dt> + <dd class="description">Element</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on failure, 1 on success</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">When inserting an element in a sorted array, non-unique elements are +inserted at the beginning of the run of identical elements. For unsorted +arrays, the element is inserted at the beginning of the array. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayLast">cupsArrayLast</a></h3> + <p class="description">Get the last element in the array.</p> +<p class="code"> +void *cupsArrayLast (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Last element or <code>NULL</code> if the array is empty</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayNew">cupsArrayNew</a></h3> + <p class="description">Create a new array.</p> +<p class="code"> +<a href="#cups_array_t">cups_array_t</a> *cupsArrayNew (<br> +    <a href="#cups_array_func_t">cups_array_func_t</a> f,<br> +    void *d<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>f</dt> + <dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd> +<dt>d</dt> + <dd class="description">User data pointer or <code>NULL</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Array</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The comparison function ("f") is used to create a sorted array. The function +receives pointers to two elements and the user data pointer ("d") - the user +data pointer argument can safely be omitted when not required so functions +like <code>strcmp</code> can be used for sorted string arrays. + +</p> +<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsArrayNew2">cupsArrayNew2</a></h3> + <p class="description">Create a new array with hash.</p> +<p class="code"> +<a href="#cups_array_t">cups_array_t</a> *cupsArrayNew2 (<br> +    <a href="#cups_array_func_t">cups_array_func_t</a> f,<br> +    void *d,<br> +    <a href="#cups_ahash_func_t">cups_ahash_func_t</a> h,<br> +    int hsize<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>f</dt> + <dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd> +<dt>d</dt> + <dd class="description">User data or <code>NULL</code></dd> +<dt>h</dt> + <dd class="description">Hash function or <code>NULL</code> for unhashed lookups</dd> +<dt>hsize</dt> + <dd class="description">Hash size (>= 0)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Array</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The comparison function ("f") is used to create a sorted array. The function +receives pointers to two elements and the user data pointer ("d") - the user +data pointer argument can safely be omitted when not required so functions +like <code>strcmp</code> can be used for sorted string arrays.<br> +<br> +The hash function ("h") is used to implement cached lookups with the +specified hash size ("hsize"). + +</p> +<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="cupsArrayNew3">cupsArrayNew3</a></h3> + <p class="description">Create a new array with hash and/or free function.</p> +<p class="code"> +<a href="#cups_array_t">cups_array_t</a> *cupsArrayNew3 (<br> +    <a href="#cups_array_func_t">cups_array_func_t</a> f,<br> +    void *d,<br> +    <a href="#cups_ahash_func_t">cups_ahash_func_t</a> h,<br> +    int hsize,<br> +    <a href="#cups_acopy_func_t">cups_acopy_func_t</a> cf,<br> +    <a href="#cups_afree_func_t">cups_afree_func_t</a> ff<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>f</dt> + <dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd> +<dt>d</dt> + <dd class="description">User data or <code>NULL</code></dd> +<dt>h</dt> + <dd class="description">Hash function or <code>NULL</code> for unhashed lookups</dd> +<dt>hsize</dt> + <dd class="description">Hash size (>= 0)</dd> +<dt>cf</dt> + <dd class="description">Copy function</dd> +<dt>ff</dt> + <dd class="description">Free function</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Array</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The comparison function ("f") is used to create a sorted array. The function +receives pointers to two elements and the user data pointer ("d") - the user +data pointer argument can safely be omitted when not required so functions +like <code>strcmp</code> can be used for sorted string arrays.<br> +<br> +The hash function ("h") is used to implement cached lookups with the +specified hash size ("hsize").<br> +<br> +The copy function ("cf") is used to automatically copy/retain elements when +added or the array is copied.<br> +<br> +The free function ("cf") is used to automatically free/release elements when +removed or the array is deleted. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayNext">cupsArrayNext</a></h3> + <p class="description">Get the next element in the array.</p> +<p class="code"> +void *cupsArrayNext (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Next element or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) + 1)".<br> +<br> +The next element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>, +<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a> +to set the current element. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayPrev">cupsArrayPrev</a></h3> + <p class="description">Get the previous element in the array.</p> +<p class="code"> +void *cupsArrayPrev (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Previous element or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) - 1)".<br> +<br> +The previous element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>, +<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a> +to set the current element. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayRemove">cupsArrayRemove</a></h3> + <p class="description">Remove an element from the array.</p> +<p class="code"> +int cupsArrayRemove (<br> +    <a href="#cups_array_t">cups_array_t</a> *a,<br> +    void *e<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +<dt>e</dt> + <dd class="description">Element</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">If more than one element matches "e", only the first matching element is +removed.<br> +<br> +The caller is responsible for freeing the memory used by the +removed element. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayRestore">cupsArrayRestore</a></h3> + <p class="description">Reset the current element to the last <a href="#cupsArraySave"><code>cupsArraySave</code></a>.</p> +<p class="code"> +void *cupsArrayRestore (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New current element</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArraySave">cupsArraySave</a></h3> + <p class="description">Mark the current element for a later <a href="#cupsArrayRestore"><code>cupsArrayRestore</code></a>.</p> +<p class="code"> +int cupsArraySave (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>, +<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a> +to set the current element.<br> +<br> +The save/restore stack is guaranteed to be at least 32 elements deep. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsArrayUserData">cupsArrayUserData</a></h3> + <p class="description">Return the user data for an array.</p> +<p class="code"> +void *cupsArrayUserData (<br> +    <a href="#cups_array_t">cups_array_t</a> *a<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>a</dt> + <dd class="description">Array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">User data</p> +<h3 class="function"><a id="cupsCancelDestJob">cupsCancelDestJob</a></h3> + <p class="description">Include necessary headers...</p> +<p class="code"> +ipp_status_t cupsCancelDestJob (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    int job_id<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>job_id</dt> + <dd class="description">Job ID</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Cancel a job on a destination.</p> + <p class="discussion">The "job_id" is the number returned by cupsCreateDestJob.<br> +<br> +Returns <code>IPP_STATUS_OK</code> on success and +<code>IPP_STATUS_ERRPR_NOT_AUTHORIZED</code> or +<code>IPP_STATUS_ERROR_FORBIDDEN</code> on failure. + +</p> +<h3 class="function"><a id="cupsCancelJob">cupsCancelJob</a></h3> + <p class="description">Cancel a print job on the default server.</p> +<p class="code"> +int cupsCancelJob (<br> +    const char *name,<br> +    int job_id<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Name of printer or class</dd> +<dt>job_id</dt> + <dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code> +to cancel the current job on the named destination.<br> +<br> +Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get +the cause of any failure.</p> +<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsCancelJob2">cupsCancelJob2</a></h3> + <p class="description">Cancel or purge a print job.</p> +<p class="code"> +ipp_status_t cupsCancelJob2 (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *name,<br> +    int job_id,<br> +    int purge<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> + <dd class="description">Name of printer or class</dd> +<dt>job_id</dt> + <dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd> +<dt>purge</dt> + <dd class="description">1 to purge, 0 to cancel</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">IPP status</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Canceled jobs remain in the job history while purged jobs are removed +from the job history.<br> +<br> +Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code> +to cancel the current job on the named destination.<br> +<br> +Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get +the cause of any failure. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsCheckDestSupported">cupsCheckDestSupported</a></h3> + <p class="description">Check that the option and value are supported +by the destination.</p> +<p class="code"> +int cupsCheckDestSupported (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    const char *option,<br> +    const char *value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>option</dt> + <dd class="description">Option</dd> +<dt>value</dt> + <dd class="description">Value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if supported, 0 otherwise</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Returns 1 if supported, 0 otherwise. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsCloseDestJob">cupsCloseDestJob</a></h3> + <p class="description">Close a job and start printing.</p> +<p class="code"> +ipp_status_t cupsCloseDestJob (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br> +    int job_id<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>info</dt> + <dd class="description">Destination information</dd> +<dt>job_id</dt> + <dd class="description">Job ID</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">IPP status code</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Use when the last call to cupsStartDocument passed 0 for "last_document". +"job_id" is the job ID returned by cupsCreateDestJob. Returns <code>IPP_STATUS_OK</code> +on success. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsConnectDest">cupsConnectDest</a></h3> + <p class="description">Connect to the server for a destination.</p> +<p class="code"> +<a href="#http_t">http_t</a> *cupsConnectDest (<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    unsigned flags,<br> +    int msec,<br> +    int *cancel,<br> +    char *resource,<br> +    size_t resourcesize,<br> +    <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br> +    void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>flags</dt> + <dd class="description">Connection flags</dd> +<dt>msec</dt> + <dd class="description">Timeout in milliseconds</dd> +<dt>cancel</dt> + <dd class="description">Pointer to "cancel" variable</dd> +<dt>resource</dt> + <dd class="description">Resource buffer</dd> +<dt>resourcesize</dt> + <dd class="description">Size of resource buffer</dd> +<dt>cb</dt> + <dd class="description">Callback function</dd> +<dt>user_data</dt> + <dd class="description">User data pointer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Connection to server or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Connect to the destination, returning a new http_t connection object and +optionally the resource path to use for the destination. These calls will +block until a connection is made, the timeout expires, the integer pointed +to by "cancel" is non-zero, or the callback function (or block) returns 0, +The caller is responsible for calling httpClose() on the returned object. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsConnectDestBlock">cupsConnectDestBlock</a></h3> + <p class="description">Connect to the server for a destination.</p> +<p class="code"> +<a href="#http_t">http_t</a> *cupsConnectDestBlock (<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    unsigned flags,<br> +    int msec,<br> +    int *cancel,<br> +    char *resource,<br> +    size_t resourcesize,<br> +    <a href="#cups_dest_block_t">cups_dest_block_t</a> block<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>flags</dt> + <dd class="description">Connection flags</dd> +<dt>msec</dt> + <dd class="description">Timeout in milliseconds</dd> +<dt>cancel</dt> + <dd class="description">Pointer to "cancel" variable</dd> +<dt>resource</dt> + <dd class="description">Resource buffer</dd> +<dt>resourcesize</dt> + <dd class="description">Size of resource buffer</dd> +<dt>block</dt> + <dd class="description">Callback block</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Connection to server or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Connect to the destination, returning a new http_t connection object and +optionally the resource path to use for the destination. These calls will +block until a connection is made, the timeout expires, the integer pointed +to by "cancel" is non-zero, or the callback function (or block) returns 0, +The caller is responsible for calling httpClose() on the returned object. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsCopyDest">cupsCopyDest</a></h3> + <p class="description">Copy a destination.</p> +<p class="code"> +int cupsCopyDest (<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    int num_dests,<br> +    <a href="#cups_dest_t">cups_dest_t</a> **dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dest</dt> + <dd class="description">Destination to copy</dd> +<dt>num_dests</dt> + <dd class="description">Number of destinations</dd> +<dt>dests</dt> + <dd class="description">Destination array</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New number of destinations</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Make a copy of the destination to an array of destinations (or just a single +copy) - for use with the cupsEnumDests* functions. The caller is responsible +for calling cupsFreeDests() on the returned object(s). + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsCopyDestConflicts">cupsCopyDestConflicts</a></h3> + <p class="description">Get conflicts and resolutions for a new +option/value pair.</p> +<p class="code"> +int cupsCopyDestConflicts (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options,<br> +    const char *new_option,<br> +    const char *new_value,<br> +    int *num_conflicts,<br> +    <a href="#cups_option_t">cups_option_t</a> **conflicts,<br> +    int *num_resolved,<br> +    <a href="#cups_option_t">cups_option_t</a> **resolved<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>num_options</dt> + <dd class="description">Number of current options</dd> +<dt>options</dt> + <dd class="description">Current options</dd> +<dt>new_option</dt> + <dd class="description">New option</dd> +<dt>new_value</dt> + <dd class="description">New value</dd> +<dt>num_conflicts</dt> + <dd class="description">Number of conflicting options</dd> +<dt>conflicts</dt> + <dd class="description">Conflicting options</dd> +<dt>num_resolved</dt> + <dd class="description">Number of options to resolve</dd> +<dt>resolved</dt> + <dd class="description">Resolved options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if there is a conflict, 0 if none, -1 on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">"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.<br> +<br> +Returns 1 if there is a conflict, 0 if there are no conflicts, and -1 if +there was an unrecoverable error such as a resolver loop.<br> +<br> +If "num_conflicts" and "conflicts" are not <code>NULL</code>, they are set to +contain the list of conflicting option/value pairs. Similarly, if +"num_resolved" and "resolved" are not <code>NULL</code> they will be set to the +list of changes needed to resolve the conflict.<br> +<br> +If cupsCopyDestConflicts returns 1 but "num_resolved" and "resolved" are set +to 0 and <code>NULL</code>, respectively, then the conflict cannot be resolved. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsCopyDestInfo">cupsCopyDestInfo</a></h3> + <p class="description">Get the supported values/capabilities for the +destination.</p> +<p class="code"> +<a href="#cups_dinfo_t">cups_dinfo_t</a> *cupsCopyDestInfo (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Destination information</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The caller is responsible for calling <a href="#cupsFreeDestInfo"><code>cupsFreeDestInfo</code></a> on the return +value. <code>NULL</code> is returned on error. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsCreateDestJob">cupsCreateDestJob</a></h3> + <p class="description">Create a job on a destination.</p> +<p class="code"> +ipp_status_t cupsCreateDestJob (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br> +    int *job_id,<br> +    const char *title,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>info</dt> + <dd class="description">Destination information</dd> +<dt>job_id</dt> + <dd class="description">Job ID or 0 on error</dd> +<dt>title</dt> + <dd class="description">Job name</dd> +<dt>num_options</dt> + <dd class="description">Number of job options</dd> +<dt>options</dt> + <dd class="description">Job options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">IPP status code</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success, saving the job ID +in the variable pointed to by "job_id". + +</p> +<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsCreateJob">cupsCreateJob</a></h3> + <p class="description">Create an empty job for streaming.</p> +<p class="code"> +int cupsCreateJob (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *name,<br> +    const char *title,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> + <dd class="description">Destination name</dd> +<dt>title</dt> + <dd class="description">Title of job</dd> +<dt>num_options</dt> + <dd class="description">Number of options</dd> +<dt>options</dt> + <dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Job ID or 0 on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Use this function when you want to stream print data using the +<a href="#cupsStartDocument"><code>cupsStartDocument</code></a>, <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a>, and +<a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> functions. If you have one or more files to +print, use the <a href="#cupsPrintFile2"><code>cupsPrintFile2</code></a> or <a href="#cupsPrintFiles2"><code>cupsPrintFiles2</code></a> function +instead. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsDirClose">cupsDirClose</a></h3> + <p class="description">Close a directory.</p> +<p class="code"> +void cupsDirClose (<br> +    <a href="#cups_dir_t">cups_dir_t</a> *dp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dp</dt> + <dd class="description">Directory pointer</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsDirOpen">cupsDirOpen</a></h3> + <p class="description">Open a directory.</p> +<p class="code"> +<a href="#cups_dir_t">cups_dir_t</a> *cupsDirOpen (<br> +    const char *directory<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>directory</dt> + <dd class="description">Directory name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Directory pointer or <code>NULL</code> if the directory could not be opened.</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsDirRead">cupsDirRead</a></h3> + <p class="description">Read the next directory entry.</p> +<p class="code"> +<a href="#cups_dentry_t">cups_dentry_t</a> *cupsDirRead (<br> +    <a href="#cups_dir_t">cups_dir_t</a> *dp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dp</dt> + <dd class="description">Directory pointer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Directory entry or <code>NULL</code> when there are no more</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsDirRewind">cupsDirRewind</a></h3> + <p class="description">Rewind to the start of the directory.</p> +<p class="code"> +void cupsDirRewind (<br> +    <a href="#cups_dir_t">cups_dir_t</a> *dp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dp</dt> + <dd class="description">Directory pointer</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 1.1.20/macOS 10.4 </span><a id="cupsDoAuthentication">cupsDoAuthentication</a></h3> + <p class="description">Authenticate a request.</p> +<p class="code"> +int cupsDoAuthentication (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *method,<br> +    const char *resource<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>method</dt> + <dd class="description">Request method ("GET", "POST", "PUT")</dd> +<dt>resource</dt> + <dd class="description">Resource path</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, -1 on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function should be called in response to a <code>HTTP_STATUS_UNAUTHORIZED</code> +status, prior to resubmitting your request. + +</p> +<h3 class="function"><a id="cupsEncodeOptions">cupsEncodeOptions</a></h3> + <p class="description">Encode printer options into IPP attributes.</p> +<p class="code"> +void cupsEncodeOptions (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">Request to add to</dd> +<dt>num_options</dt> + <dd class="description">Number of options</dd> +<dt>options</dt> + <dd class="description">Options</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function adds operation, job, and then subscription attributes, +in that order. Use the cupsEncodeOptions2() function to add attributes +for a single group.</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsEncodeOptions2">cupsEncodeOptions2</a></h3> + <p class="description">Encode printer options into IPP attributes for a group.</p> +<p class="code"> +void cupsEncodeOptions2 (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options,<br> +    ipp_tag_t group_tag<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">Request to add to</dd> +<dt>num_options</dt> + <dd class="description">Number of options</dd> +<dt>options</dt> + <dd class="description">Options</dd> +<dt>group_tag</dt> + <dd class="description">Group to encode</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function only adds attributes for a single group. Call this +function multiple times for each group, or use cupsEncodeOptions() +to add the standard groups. + +</p> +<h3 class="function"><a id="cupsEncryption">cupsEncryption</a></h3> + <p class="description">Get the current encryption settings.</p> +<p class="code"> +<a href="#http_encryption_t">http_encryption_t</a> cupsEncryption (void);</p> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Encryption settings</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION +environment variable, then the ~/.cups/client.conf file, and finally the +/etc/cups/client.conf file. If not set, the default is +<code>HTTP_ENCRYPTION_IF_REQUESTED</code>.<br> +<br> +Note: The current encryption setting is tracked separately for each thread +in a program. Multi-threaded programs that override the setting via the +<a href="#cupsSetEncryption"><code>cupsSetEncryption</code></a> function need to do so in each thread for the same +setting to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsEnumDests">cupsEnumDests</a></h3> + <p class="description">Enumerate available destinations with a callback function.</p> +<p class="code"> +int cupsEnumDests (<br> +    unsigned flags,<br> +    int msec,<br> +    int *cancel,<br> +    <a href="#cups_ptype_t">cups_ptype_t</a> type,<br> +    <a href="#cups_ptype_t">cups_ptype_t</a> mask,<br> +    <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br> +    void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>flags</dt> + <dd class="description">Enumeration flags</dd> +<dt>msec</dt> + <dd class="description">Timeout in milliseconds, -1 for indefinite</dd> +<dt>cancel</dt> + <dd class="description">Pointer to "cancel" variable</dd> +<dt>type</dt> + <dd class="description">Printer type bits</dd> +<dt>mask</dt> + <dd class="description">Mask for printer type bits</dd> +<dt>cb</dt> + <dd class="description">Callback function</dd> +<dt>user_data</dt> + <dd class="description">User data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Destinations are enumerated from one or more sources. The callback function +receives the <code>user_data</code> pointer, destination name, instance, number of +options, and options which can be used as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a> +function. The function must return 1 to continue enumeration or 0 to stop.<br> +<br> +Enumeration happens on the current thread and does not return until all +destinations have been enumerated or the callback function returns 0. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsEnumDestsBlock">cupsEnumDestsBlock</a></h3> + <p class="description">Enumerate available destinations with a block.</p> +<p class="code"> +int cupsEnumDestsBlock (<br> +    unsigned flags,<br> +    int timeout,<br> +    int *cancel,<br> +    <a href="#cups_ptype_t">cups_ptype_t</a> type,<br> +    <a href="#cups_ptype_t">cups_ptype_t</a> mask,<br> +    <a href="#cups_dest_block_t">cups_dest_block_t</a> block<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>flags</dt> + <dd class="description">Enumeration flags</dd> +<dt>timeout</dt> + <dd class="description">Timeout in milliseconds, 0 for indefinite</dd> +<dt>cancel</dt> + <dd class="description">Pointer to "cancel" variable</dd> +<dt>type</dt> + <dd class="description">Printer type bits</dd> +<dt>mask</dt> + <dd class="description">Mask for printer type bits</dd> +<dt>block</dt> + <dd class="description">Block</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Destinations are enumerated from one or more sources. The block receives the +destination name, instance, number of options, and options which can be used +as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a> function. The block must return 1 to +continue enumeration or 0 to stop.<br> +<br> +Enumeration happens on the current thread and does not return until all +destinations have been enumerated or the block returns 0. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileClose">cupsFileClose</a></h3> + <p class="description">Close a CUPS file.</p> +<p class="code"> +int cupsFileClose (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileCompression">cupsFileCompression</a></h3> + <p class="description">Return whether a file is compressed.</p> +<p class="code"> +int cupsFileCompression (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description"><code>CUPS_FILE_NONE</code> or <code>CUPS_FILE_GZIP</code></p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileEOF">cupsFileEOF</a></h3> + <p class="description">Return the end-of-file status.</p> +<p class="code"> +int cupsFileEOF (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on end of file, 0 otherwise</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileFind">cupsFileFind</a></h3> + <p class="description">Find a file using the specified path.</p> +<p class="code"> +const char *cupsFileFind (<br> +    const char *filename,<br> +    const char *path,<br> +    int executable,<br> +    char *buffer,<br> +    int bufsize<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>filename</dt> + <dd class="description">File to find</dd> +<dt>path</dt> + <dd class="description">Colon/semicolon-separated path</dd> +<dt>executable</dt> + <dd class="description">1 = executable files, 0 = any file/dir</dd> +<dt>buffer</dt> + <dd class="description">Filename buffer</dd> +<dt>bufsize</dt> + <dd class="description">Size of filename buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Full path to file or <code>NULL</code> if not found</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function allows the paths in the path string to be separated by +colons (UNIX standard) or semicolons (Windows standard) and stores the +result in the buffer supplied. If the file cannot be found in any of +the supplied paths, <code>NULL</code> is returned. A <code>NULL</code> path only +matches the current directory. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileFlush">cupsFileFlush</a></h3> + <p class="description">Flush pending output.</p> +<p class="code"> +int cupsFileFlush (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileGetChar">cupsFileGetChar</a></h3> + <p class="description">Get a single character from a file.</p> +<p class="code"> +int cupsFileGetChar (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Character or -1 on end of file</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileGetConf">cupsFileGetConf</a></h3> + <p class="description">Get a line from a configuration file.</p> +<p class="code"> +char *cupsFileGetConf (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp,<br> +    char *buf,<br> +    size_t buflen,<br> +    char **value,<br> +    int *linenum<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +<dt>buf</dt> + <dd class="description">String buffer</dd> +<dt>buflen</dt> + <dd class="description">Size of string buffer</dd> +<dt>value</dt> + <dd class="description">Pointer to value</dd> +<dt>linenum</dt> + <dd class="description">Current line number</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Line read or <code>NULL</code> on end of file or error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileGetLine">cupsFileGetLine</a></h3> + <p class="description">Get a CR and/or LF-terminated line that may +contain binary data.</p> +<p class="code"> +size_t cupsFileGetLine (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp,<br> +    char *buf,<br> +    size_t buflen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">File to read from</dd> +<dt>buf</dt> + <dd class="description">Buffer</dd> +<dt>buflen</dt> + <dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes on line or 0 on end of file</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function differs from <a href="#cupsFileGets"><code>cupsFileGets</code></a> in that the trailing CR +and LF are preserved, as is any binary data on the line. The buffer is +nul-terminated, however you should use the returned length to determine +the number of bytes on the line. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileGets">cupsFileGets</a></h3> + <p class="description">Get a CR and/or LF-terminated line.</p> +<p class="code"> +char *cupsFileGets (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp,<br> +    char *buf,<br> +    size_t buflen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +<dt>buf</dt> + <dd class="description">String buffer</dd> +<dt>buflen</dt> + <dd class="description">Size of string buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Line read or <code>NULL</code> on end of file or error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileLock">cupsFileLock</a></h3> + <p class="description">Temporarily lock access to a file.</p> +<p class="code"> +int cupsFileLock (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp,<br> +    int block<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +<dt>block</dt> + <dd class="description">1 to wait for the lock, 0 to fail right away</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileNumber">cupsFileNumber</a></h3> + <p class="description">Return the file descriptor associated with a CUPS file.</p> +<p class="code"> +int cupsFileNumber (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">File descriptor</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileOpen">cupsFileOpen</a></h3> + <p class="description">Open a CUPS file.</p> +<p class="code"> +<a href="#cups_file_t">cups_file_t</a> *cupsFileOpen (<br> +    const char *filename,<br> +    const char *mode<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>filename</dt> + <dd class="description">Name of file</dd> +<dt>mode</dt> + <dd class="description">Open mode</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">CUPS file or <code>NULL</code> if the file or socket cannot be opened</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The "mode" parameter can be "r" to read, "w" to write, overwriting any +existing file, "a" to append to an existing file or create a new file, +or "s" to open a socket connection.<br> +<br> +When opening for writing ("w"), an optional number from 1 to 9 can be +supplied which enables Flate compression of the file. Compression is +not supported for the "a" (append) mode.<br> +<br> +When opening a socket connection, the filename is a string of the form +"address:port" or "hostname:port". The socket will make an IPv4 or IPv6 +connection as needed, generally preferring IPv6 connections when there is +a choice. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileOpenFd">cupsFileOpenFd</a></h3> + <p class="description">Open a CUPS file using a file descriptor.</p> +<p class="code"> +<a href="#cups_file_t">cups_file_t</a> *cupsFileOpenFd (<br> +    int fd,<br> +    const char *mode<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fd</dt> + <dd class="description">File descriptor</dd> +<dt>mode</dt> + <dd class="description">Open mode</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">CUPS file or <code>NULL</code> if the file could not be opened</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The "mode" parameter can be "r" to read, "w" to write, "a" to append, +or "s" to treat the file descriptor as a bidirectional socket connection.<br> +<br> +When opening for writing ("w"), an optional number from 1 to 9 can be +supplied which enables Flate compression of the file. Compression is +not supported for the "a" (append) mode. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFilePeekChar">cupsFilePeekChar</a></h3> + <p class="description">Peek at the next character from a file.</p> +<p class="code"> +int cupsFilePeekChar (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Character or -1 on end of file</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFilePrintf">cupsFilePrintf</a></h3> + <p class="description">Write a formatted string.</p> +<p class="code"> +int cupsFilePrintf (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp,<br> +    const char *format,<br> +    ...<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +<dt>format</dt> + <dd class="description">Printf-style format string</dd> +<dt>...</dt> + <dd class="description">Additional args as necessary</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes written or -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFilePutChar">cupsFilePutChar</a></h3> + <p class="description">Write a character.</p> +<p class="code"> +int cupsFilePutChar (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp,<br> +    int c<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +<dt>c</dt> + <dd class="description">Character to write</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsFilePutConf">cupsFilePutConf</a></h3> + <p class="description">Write a configuration line.</p> +<p class="code"> +ssize_t cupsFilePutConf (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp,<br> +    const char *directive,<br> +    const char *value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +<dt>directive</dt> + <dd class="description">Directive</dd> +<dt>value</dt> + <dd class="description">Value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes written or -1 on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function handles any comment escaping of the value. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFilePuts">cupsFilePuts</a></h3> + <p class="description">Write a string.</p> +<p class="code"> +int cupsFilePuts (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp,<br> +    const char *s<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +<dt>s</dt> + <dd class="description">String to write</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes written or -1 on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Like the <code>fputs</code> function, no newline is appended to the string. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileRead">cupsFileRead</a></h3> + <p class="description">Read from a file.</p> +<p class="code"> +ssize_t cupsFileRead (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp,<br> +    char *buf,<br> +    size_t bytes<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +<dt>buf</dt> + <dd class="description">Buffer</dd> +<dt>bytes</dt> + <dd class="description">Number of bytes to read</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes read or -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileRewind">cupsFileRewind</a></h3> + <p class="description">Set the current file position to the beginning of the +file.</p> +<p class="code"> +off_t cupsFileRewind (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New file position or -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileSeek">cupsFileSeek</a></h3> + <p class="description">Seek in a file.</p> +<p class="code"> +off_t cupsFileSeek (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp,<br> +    off_t pos<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +<dt>pos</dt> + <dd class="description">Position in file</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New file position or -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileStderr">cupsFileStderr</a></h3> + <p class="description">Return a CUPS file associated with stderr.</p> +<p class="code"> +<a href="#cups_file_t">cups_file_t</a> *cupsFileStderr (void);</p> +<h4 class="returnvalue">Return Value</h4> + <p class="description">CUPS file</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileStdin">cupsFileStdin</a></h3> + <p class="description">Return a CUPS file associated with stdin.</p> +<p class="code"> +<a href="#cups_file_t">cups_file_t</a> *cupsFileStdin (void);</p> +<h4 class="returnvalue">Return Value</h4> + <p class="description">CUPS file</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileStdout">cupsFileStdout</a></h3> + <p class="description">Return a CUPS file associated with stdout.</p> +<p class="code"> +<a href="#cups_file_t">cups_file_t</a> *cupsFileStdout (void);</p> +<h4 class="returnvalue">Return Value</h4> + <p class="description">CUPS file</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileTell">cupsFileTell</a></h3> + <p class="description">Return the current file position.</p> +<p class="code"> +off_t cupsFileTell (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">File position</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileUnlock">cupsFileUnlock</a></h3> + <p class="description">Unlock access to a file.</p> +<p class="code"> +int cupsFileUnlock (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsFileWrite">cupsFileWrite</a></h3> + <p class="description">Write to a file.</p> +<p class="code"> +ssize_t cupsFileWrite (<br> +    <a href="#cups_file_t">cups_file_t</a> *fp,<br> +    const char *buf,<br> +    size_t bytes<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fp</dt> + <dd class="description">CUPS file</dd> +<dt>buf</dt> + <dd class="description">Buffer</dd> +<dt>bytes</dt> + <dd class="description">Number of bytes to write</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes written or -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsFindDestDefault">cupsFindDestDefault</a></h3> + <p class="description">Find the default value(s) for the given option.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *cupsFindDestDefault (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    const char *option<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>option</dt> + <dd class="description">Option/attribute name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Default attribute or <code>NULL</code> for none</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>, +<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>, +<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>, +<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code> +functions to inspect the default value(s) as needed. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsFindDestReady">cupsFindDestReady</a></h3> + <p class="description">Find the default value(s) for the given option.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *cupsFindDestReady (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    const char *option<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>option</dt> + <dd class="description">Option/attribute name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Default attribute or <code>NULL</code> for none</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>, +<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>, +<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>, +<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code> +functions to inspect the default value(s) as needed. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsFindDestSupported">cupsFindDestSupported</a></h3> + <p class="description">Find the default value(s) for the given option.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *cupsFindDestSupported (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    const char *option<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>option</dt> + <dd class="description">Option/attribute name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Default attribute or <code>NULL</code> for none</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>, +<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>, +<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>, +<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code> +functions to inspect the default value(s) as needed. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsFinishDestDocument">cupsFinishDestDocument</a></h3> + <p class="description">Finish the current document.</p> +<p class="code"> +ipp_status_t cupsFinishDestDocument (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *info<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>info</dt> + <dd class="description">Destination information</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of document submission</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success. + +</p> +<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsFinishDocument">cupsFinishDocument</a></h3> + <p class="description">Finish sending a document.</p> +<p class="code"> +ipp_status_t cupsFinishDocument (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> + <dd class="description">Destination name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of document submission</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The document must have been started using <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>. + +</p> +<h3 class="function"><a id="cupsFreeDestInfo">cupsFreeDestInfo</a></h3> + <p class="description">Free destination information obtained using +<a href="#cupsCopyDestInfo"><code>cupsCopyDestInfo</code></a>.</p> +<p class="code"> +void cupsFreeDestInfo (<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +</dl> +<h3 class="function"><a id="cupsFreeDests">cupsFreeDests</a></h3> + <p class="description">Free the memory used by the list of destinations.</p> +<p class="code"> +void cupsFreeDests (<br> +    int num_dests,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>num_dests</dt> + <dd class="description">Number of destinations</dd> +<dt>dests</dt> + <dd class="description">Destinations</dd> +</dl> +<h3 class="function"><a id="cupsFreeJobs">cupsFreeJobs</a></h3> + <p class="description">Free memory used by job data.</p> +<p class="code"> +void cupsFreeJobs (<br> +    int num_jobs,<br> +    <a href="#cups_job_t">cups_job_t</a> *jobs<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>num_jobs</dt> + <dd class="description">Number of jobs</dd> +<dt>jobs</dt> + <dd class="description">Jobs</dd> +</dl> +<h3 class="function"><a id="cupsFreeOptions">cupsFreeOptions</a></h3> + <p class="description">Free all memory used by options.</p> +<p class="code"> +void cupsFreeOptions (<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>num_options</dt> + <dd class="description">Number of options</dd> +<dt>options</dt> + <dd class="description">Pointer to options</dd> +</dl> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="cupsGetClasses">cupsGetClasses</a></h3> + <p class="description">Get a list of printer classes from the default server.</p> +<p class="code"> +int cupsGetClasses (<br> +    char ***classes<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>classes</dt> + <dd class="description">Classes</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of classes</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is deprecated and no longer returns a list of printer +classes - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead. + +</p> +<h3 class="function"><a id="cupsGetDefault">cupsGetDefault</a></h3> + <p class="description">Get the default printer or class for the default server.</p> +<p class="code"> +const char *cupsGetDefault (void);</p> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Default printer or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function returns the default printer or class as defined by +the LPDEST or PRINTER environment variables. If these environment +variables are not set, the server default destination is returned. +Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> +functions to get the user-defined default printer, as this function does +not support the lpoptions-defined default printer.</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsGetDefault2">cupsGetDefault2</a></h3> + <p class="description">Get the default printer or class for the specified server.</p> +<p class="code"> +const char *cupsGetDefault2 (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Default printer or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function returns the default printer or class as defined by +the LPDEST or PRINTER environment variables. If these environment +variables are not set, the server default destination is returned. +Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> +functions to get the user-defined default printer, as this function does +not support the lpoptions-defined default printer. + +</p> +<h3 class="function"><a id="cupsGetDest">cupsGetDest</a></h3> + <p class="description">Get the named destination from the list.</p> +<p class="code"> +<a href="#cups_dest_t">cups_dest_t</a> *cupsGetDest (<br> +    const char *name,<br> +    const char *instance,<br> +    int num_dests,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Destination name or <code>NULL</code> for the default destination</dd> +<dt>instance</dt> + <dd class="description">Instance name or <code>NULL</code></dd> +<dt>num_dests</dt> + <dd class="description">Number of destinations</dd> +<dt>dests</dt> + <dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Destination pointer or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> or <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> functions to get a +list of supported destinations for the current user.</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></h3> + <p class="description">Get a media name, dimension, and margins for a +specific size.</p> +<p class="code"> +int cupsGetDestMediaByIndex (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    int n,<br> +    unsigned flags,<br> +    <a href="#cups_size_t">cups_size_t</a> *size<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>n</dt> + <dd class="description">Media size number (0-based)</dd> +<dt>flags</dt> + <dd class="description">Media flags</dd> +<dt>size</dt> + <dd class="description">Media size information</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>flags</code> parameter determines which set of media are indexed. For +example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will get the Nth +borderless size supported by the printer. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsGetDestMediaByName">cupsGetDestMediaByName</a></h3> + <p class="description">Get media names, dimensions, and margins.</p> +<p class="code"> +int cupsGetDestMediaByName (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    const char *media,<br> +    unsigned flags,<br> +    <a href="#cups_size_t">cups_size_t</a> *size<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>media</dt> + <dd class="description">Media name</dd> +<dt>flags</dt> + <dd class="description">Media matching flags</dd> +<dt>size</dt> + <dd class="description">Media size information</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on match, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The "media" string is a PWG media name. "Flags" provides some matching +guidance (multiple flags can be combined):<br> +<br> +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, and +CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the +size amongst the "ready" media.<br> +<br> +The matching result (if any) is returned in the "cups_size_t" structure.<br> +<br> +Returns 1 when there is a match and 0 if there is not a match. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></h3> + <p class="description">Get media names, dimensions, and margins.</p> +<p class="code"> +int cupsGetDestMediaBySize (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    int width,<br> +    int length,<br> +    unsigned flags,<br> +    <a href="#cups_size_t">cups_size_t</a> *size<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>width</dt> + <dd class="description">Media width in hundredths of +of millimeters</dd> +<dt>length</dt> + <dd class="description">Media length in hundredths of +of millimeters</dd> +<dt>flags</dt> + <dd class="description">Media matching flags</dd> +<dt>size</dt> + <dd class="description">Media size information</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on match, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">"Width" and "length" are the dimensions in hundredths of millimeters. +"Flags" provides some matching guidance (multiple flags can be combined):<br> +<br> +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, and +CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the +size amongst the "ready" media.<br> +<br> +The matching result (if any) is returned in the "cups_size_t" structure.<br> +<br> +Returns 1 when there is a match and 0 if there is not a match. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsGetDestMediaCount">cupsGetDestMediaCount</a></h3> + <p class="description">Get the number of sizes supported by a +destination.</p> +<p class="code"> +int cupsGetDestMediaCount (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    unsigned flags<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>flags</dt> + <dd class="description">Media flags</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of sizes</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>flags</code> parameter determines the set of media sizes that are +counted. For example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return +the number of borderless sizes. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></h3> + <p class="description">Get the default size for a destination.</p> +<p class="code"> +int cupsGetDestMediaDefault (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    unsigned flags,<br> +    <a href="#cups_size_t">cups_size_t</a> *size<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>flags</dt> + <dd class="description">Media flags</dd> +<dt>size</dt> + <dd class="description">Media size information</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>flags</code> parameter determines which default size is returned. For +example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return the default +borderless size, typically US Letter or A4, but sometimes 4x6 photo media. + +</p> +<h3 class="function"><span class="info"> CUPS 2.0/macOS 10.10 </span><a id="cupsGetDestWithURI">cupsGetDestWithURI</a></h3> + <p class="description">Get a destination associated with a URI.</p> +<p class="code"> +<a href="#cups_dest_t">cups_dest_t</a> *cupsGetDestWithURI (<br> +    const char *name,<br> +    const char *uri<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Desired printer name or <code>NULL</code></dd> +<dt>uri</dt> + <dd class="description">URI for the printer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Destination or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">"name" is the desired name for the printer. If <code>NULL</code>, a name will be +created using the URI.<br> +<br> +"uri" is the "ipp" or "ipps" URI for the printer. + +</p> +<h3 class="function"><a id="cupsGetDests">cupsGetDests</a></h3> + <p class="description">Get the list of destinations from the default server.</p> +<p class="code"> +int cupsGetDests (<br> +    <a href="#cups_dest_t">cups_dest_t</a> **dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dests</dt> + <dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of destinations</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the +printer-info, printer-is-accepting-jobs, printer-is-shared, +printer-make-and-model, printer-state, printer-state-change-time, +printer-state-reasons, and printer-type attributes as options. CUPS 1.4 +adds the marker-change-time, marker-colors, marker-high-levels, +marker-levels, marker-low-levels, marker-message, marker-names, +marker-types, and printer-commands attributes as well.<br> +<br> +Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and +the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsGetDests2">cupsGetDests2</a></h3> + <p class="description">Get the list of destinations from the specified server.</p> +<p class="code"> +int cupsGetDests2 (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> **dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>dests</dt> + <dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of destinations</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the +printer-info, printer-is-accepting-jobs, printer-is-shared, +printer-make-and-model, printer-state, printer-state-change-time, +printer-state-reasons, and printer-type attributes as options. CUPS 1.4 +adds the marker-change-time, marker-colors, marker-high-levels, +marker-levels, marker-low-levels, marker-message, marker-names, +marker-types, and printer-commands attributes as well.<br> +<br> +Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and +the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination. + +</p> +<h3 class="function"><a id="cupsGetJobs">cupsGetJobs</a></h3> + <p class="description">Get the jobs from the default server.</p> +<p class="code"> +int cupsGetJobs (<br> +    <a href="#cups_job_t">cups_job_t</a> **jobs,<br> +    const char *name,<br> +    int myjobs,<br> +    int whichjobs<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>jobs</dt> + <dd class="description">Job data</dd> +<dt>name</dt> + <dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd> +<dt>myjobs</dt> + <dd class="description">0 = all users, 1 = mine</dd> +<dt>whichjobs</dt> + <dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of jobs</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless +of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are +pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns +jobs that are stopped, canceled, aborted, or completed.</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsGetJobs2">cupsGetJobs2</a></h3> + <p class="description">Get the jobs from the specified server.</p> +<p class="code"> +int cupsGetJobs2 (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_job_t">cups_job_t</a> **jobs,<br> +    const char *name,<br> +    int myjobs,<br> +    int whichjobs<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>jobs</dt> + <dd class="description">Job data</dd> +<dt>name</dt> + <dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd> +<dt>myjobs</dt> + <dd class="description">0 = all users, 1 = mine</dd> +<dt>whichjobs</dt> + <dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of jobs</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless +of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are +pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns +jobs that are stopped, canceled, aborted, or completed. + +</p> +<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsGetNamedDest">cupsGetNamedDest</a></h3> + <p class="description">Get options for the named destination.</p> +<p class="code"> +<a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *name,<br> +    const char *instance<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> + <dd class="description">Destination name or <code>NULL</code> for the default destination</dd> +<dt>instance</dt> + <dd class="description">Instance name or <code>NULL</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Destination or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is optimized for retrieving a single destination and should +be used instead of <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> when you either +know the name of the destination or want to print to the default destination. +If <code>NULL</code> is returned, the destination does not exist or there is no +default destination.<br> +<br> +If "http" is <code>CUPS_HTTP_DEFAULT</code>, the connection to the default print +server will be used.<br> +<br> +If "name" is <code>NULL</code>, the default printer for the current user will be +returned.<br> +<br> +The returned destination must be freed using <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> with a +"num_dests" value of 1. + +</p> +<h3 class="function"><a id="cupsGetOption">cupsGetOption</a></h3> + <p class="description">Get an option value.</p> +<p class="code"> +const char *cupsGetOption (<br> +    const char *name,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Name of option</dd> +<dt>num_options</dt> + <dd class="description">Number of options</dd> +<dt>options</dt> + <dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Option value or <code>NULL</code></p> +<h3 class="function"><a id="cupsGetPassword">cupsGetPassword</a></h3> + <p class="description">Get a password from the user.</p> +<p class="code"> +const char *cupsGetPassword (<br> +    const char *prompt<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>prompt</dt> + <dd class="description">Prompt string</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Password</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the +user does not provide a password.<br> +<br> +Note: The current password callback function is tracked separately for each +thread in a program. Multi-threaded programs that override the setting via +the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to +do so in each thread for the same function to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsGetPassword2">cupsGetPassword2</a></h3> + <p class="description">Get a password from the user using the advanced +password callback.</p> +<p class="code"> +const char *cupsGetPassword2 (<br> +    const char *prompt,<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *method,<br> +    const char *resource<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>prompt</dt> + <dd class="description">Prompt string</dd> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>method</dt> + <dd class="description">Request method ("GET", "POST", "PUT")</dd> +<dt>resource</dt> + <dd class="description">Resource path</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Password</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the +user does not provide a password.<br> +<br> +Note: The current password callback function is tracked separately for each +thread in a program. Multi-threaded programs that override the setting via +the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to +do so in each thread for the same function to be used. + +</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="cupsGetPrinters">cupsGetPrinters</a></h3> + <p class="description">Get a list of printers from the default server.</p> +<p class="code"> +int cupsGetPrinters (<br> +    char ***printers<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>printers</dt> + <dd class="description">Printers</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of printers</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is deprecated and no longer returns a list of printers - use +<a href="#cupsGetDests"><code>cupsGetDests</code></a> instead. + +</p> +<h3 class="function"><a id="cupsLangDefault">cupsLangDefault</a></h3> + <p class="description">Return the default language.</p> +<p class="code"> +<a href="#cups_lang_t">cups_lang_t</a> *cupsLangDefault (void);</p> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Language data</p> +<h3 class="function"><a id="cupsLangEncoding">cupsLangEncoding</a></h3> + <p class="description">Return the character encoding (us-ascii, etc.) +for the given language.</p> +<p class="code"> +const char *cupsLangEncoding (<br> +    <a href="#cups_lang_t">cups_lang_t</a> *lang<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>lang</dt> + <dd class="description">Language data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Character encoding</p> +<h3 class="function"><a id="cupsLangFlush">cupsLangFlush</a></h3> + <p class="description">Flush all language data out of the cache.</p> +<p class="code"> +void cupsLangFlush (void);</p> +<h3 class="function"><a id="cupsLangFree">cupsLangFree</a></h3> + <p class="description">Free language data.</p> +<p class="code"> +void cupsLangFree (<br> +    <a href="#cups_lang_t">cups_lang_t</a> *lang<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>lang</dt> + <dd class="description">Language to free</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This does not actually free anything; use <a href="#cupsLangFlush"><code>cupsLangFlush</code></a> for that.</p> +<h3 class="function"><a id="cupsLangGet">cupsLangGet</a></h3> + <p class="description">Get a language.</p> +<p class="code"> +<a href="#cups_lang_t">cups_lang_t</a> *cupsLangGet (<br> +    const char *language<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>language</dt> + <dd class="description">Language or locale</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Language data</p> +<h3 class="function"><span class="info"> CUPS 2.0/macOS 10.10 </span><a id="cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></h3> + <p class="description">Get the localized string for a destination media +size.</p> +<p class="code"> +const char *cupsLocalizeDestMedia (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    unsigned flags,<br> +    <a href="#cups_size_t">cups_size_t</a> *size<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>flags</dt> + <dd class="description">Media flags</dd> +<dt>size</dt> + <dd class="description">Media size</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Localized string</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The returned string is stored in the destination information and will become +invalid if the destination information is deleted. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsLocalizeDestOption">cupsLocalizeDestOption</a></h3> + <p class="description">Get the localized string for a destination +option.</p> +<p class="code"> +const char *cupsLocalizeDestOption (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    const char *option<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>option</dt> + <dd class="description">Option to localize</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Localized string</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The returned string is stored in the destination information and will become +invalid if the destination information is deleted. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsLocalizeDestValue">cupsLocalizeDestValue</a></h3> + <p class="description">Get the localized string for a destination +option+value pair.</p> +<p class="code"> +const char *cupsLocalizeDestValue (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> +    const char *option,<br> +    const char *value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>dinfo</dt> + <dd class="description">Destination information</dd> +<dt>option</dt> + <dd class="description">Option to localize</dd> +<dt>value</dt> + <dd class="description">Value to localize</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Localized string</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The returned string is stored in the destination information and will become +invalid if the destination information is deleted. + +</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="cupsMakeServerCredentials">cupsMakeServerCredentials</a></h3> + <p class="description">Make a self-signed certificate and private key pair.</p> +<p class="code"> +int cupsMakeServerCredentials (<br> +    const char *path,<br> +    const char *common_name,<br> +    int num_alt_names,<br> +    const char **alt_names,<br> +    time_t expiration_date<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>path</dt> + <dd class="description">Keychain path or <code>NULL</code> for default</dd> +<dt>common_name</dt> + <dd class="description">Common name</dd> +<dt>num_alt_names</dt> + <dd class="description">Number of subject alternate names</dd> +<dt>alt_names</dt> + <dd class="description">Subject Alternate Names</dd> +<dt>expiration_date</dt> + <dd class="description">Expiration date</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsNotifySubject">cupsNotifySubject</a></h3> + <p class="description">Return the subject for the given notification message.</p> +<p class="code"> +char *cupsNotifySubject (<br> +    <a href="#cups_lang_t">cups_lang_t</a> *lang,<br> +    <a href="#ipp_t">ipp_t</a> *event<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>lang</dt> + <dd class="description">Language data</dd> +<dt>event</dt> + <dd class="description">Event data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Subject string or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The returned string must be freed by the caller using <code>free</code>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsNotifyText">cupsNotifyText</a></h3> + <p class="description">Return the text for the given notification message.</p> +<p class="code"> +char *cupsNotifyText (<br> +    <a href="#cups_lang_t">cups_lang_t</a> *lang,<br> +    <a href="#ipp_t">ipp_t</a> *event<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>lang</dt> + <dd class="description">Language data</dd> +<dt>event</dt> + <dd class="description">Event data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Message text or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The returned string must be freed by the caller using <code>free</code>. + +</p> +<h3 class="function"><a id="cupsParseOptions">cupsParseOptions</a></h3> + <p class="description">Parse options from a command-line argument.</p> +<p class="code"> +int cupsParseOptions (<br> +    const char *arg,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> **options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>arg</dt> + <dd class="description">Argument to parse</dd> +<dt>num_options</dt> + <dd class="description">Number of options</dd> +<dt>options</dt> + <dd class="description">Options found</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of options found</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function converts space-delimited name/value pairs according +to the PAPI text option ABNF specification. Collection values +("name={a=... b=... c=...}") are stored with the curley brackets +intact - use <code>cupsParseOptions</code> on the value to extract the +collection attributes.</p> +<h3 class="function"><a id="cupsPrintFile">cupsPrintFile</a></h3> + <p class="description">Print a file to a printer or class on the default server.</p> +<p class="code"> +int cupsPrintFile (<br> +    const char *name,<br> +    const char *filename,<br> +    const char *title,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Destination name</dd> +<dt>filename</dt> + <dd class="description">File to print</dd> +<dt>title</dt> + <dd class="description">Title of job</dd> +<dt>num_options</dt> + <dd class="description">Number of options</dd> +<dt>options</dt> + <dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Job ID or 0 on error</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsPrintFile2">cupsPrintFile2</a></h3> + <p class="description">Print a file to a printer or class on the specified +server.</p> +<p class="code"> +int cupsPrintFile2 (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *name,<br> +    const char *filename,<br> +    const char *title,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server</dd> +<dt>name</dt> + <dd class="description">Destination name</dd> +<dt>filename</dt> + <dd class="description">File to print</dd> +<dt>title</dt> + <dd class="description">Title of job</dd> +<dt>num_options</dt> + <dd class="description">Number of options</dd> +<dt>options</dt> + <dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Job ID or 0 on error</p> +<h3 class="function"><a id="cupsPrintFiles">cupsPrintFiles</a></h3> + <p class="description">Print one or more files to a printer or class on the +default server.</p> +<p class="code"> +int cupsPrintFiles (<br> +    const char *name,<br> +    int num_files,<br> +    const char **files,<br> +    const char *title,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Destination name</dd> +<dt>num_files</dt> + <dd class="description">Number of files</dd> +<dt>files</dt> + <dd class="description">File(s) to print</dd> +<dt>title</dt> + <dd class="description">Title of job</dd> +<dt>num_options</dt> + <dd class="description">Number of options</dd> +<dt>options</dt> + <dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Job ID or 0 on error</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsPrintFiles2">cupsPrintFiles2</a></h3> + <p class="description">Print one or more files to a printer or class on the +specified server.</p> +<p class="code"> +int cupsPrintFiles2 (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *name,<br> +    int num_files,<br> +    const char **files,<br> +    const char *title,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> + <dd class="description">Destination name</dd> +<dt>num_files</dt> + <dd class="description">Number of files</dd> +<dt>files</dt> + <dd class="description">File(s) to print</dd> +<dt>title</dt> + <dd class="description">Title of job</dd> +<dt>num_options</dt> + <dd class="description">Number of options</dd> +<dt>options</dt> + <dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Job ID or 0 on error</p> +<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsRemoveDest">cupsRemoveDest</a></h3> + <p class="description">Remove a destination from the destination list.</p> +<p class="code"> +int cupsRemoveDest (<br> +    const char *name,<br> +    const char *instance,<br> +    int num_dests,<br> +    <a href="#cups_dest_t">cups_dest_t</a> **dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Destination name</dd> +<dt>instance</dt> + <dd class="description">Instance name or <code>NULL</code></dd> +<dt>num_dests</dt> + <dd class="description">Number of destinations</dd> +<dt>dests</dt> + <dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New number of destinations</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Removing a destination/instance does not delete the class or printer +queue, merely the lpoptions for that destination/instance. Use the +<a href="#cupsSetDests"><code>cupsSetDests</code></a> or <a href="#cupsSetDests2"><code>cupsSetDests2</code></a> functions to save the new +options for the user. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsRemoveOption">cupsRemoveOption</a></h3> + <p class="description">Remove an option from an option array.</p> +<p class="code"> +int cupsRemoveOption (<br> +    const char *name,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> **options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Option name</dd> +<dt>num_options</dt> + <dd class="description">Current number of options</dd> +<dt>options</dt> + <dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New number of options</p> +<h3 class="function"><a id="cupsServer">cupsServer</a></h3> + <p class="description">Return the hostname/address of the current server.</p> +<p class="code"> +const char *cupsServer (void);</p> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Server name</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The default server comes from the CUPS_SERVER environment variable, then the +~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not +set, the default is the local system - either "localhost" or a domain socket +path.<br> +<br> +The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6 +address, or a domain socket pathname.<br> +<br> +Note: The current server is tracked separately for each thread in a program. +Multi-threaded programs that override the server via the +<a href="#cupsSetServer"><code>cupsSetServer</code></a> function need to do so in each thread for the same +server to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="cupsSetClientCertCB">cupsSetClientCertCB</a></h3> + <p class="description">Set the client certificate callback.</p> +<p class="code"> +void cupsSetClientCertCB (<br> +    <a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a> cb,<br> +    void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>cb</dt> + <dd class="description">Callback function</dd> +<dt>user_data</dt> + <dd class="description">User data pointer</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Pass <code>NULL</code> to restore the default callback.<br> +<br> +Note: The current certificate callback is tracked separately for each thread +in a program. Multi-threaded programs that override the callback need to do +so in each thread for the same callback to be used. + +</p> +<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="cupsSetCredentials">cupsSetCredentials</a></h3> + <p class="description">Set the default credentials to be used for SSL/TLS +connections.</p> +<p class="code"> +int cupsSetCredentials (<br> +    <a href="#cups_array_t">cups_array_t</a> *credentials<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>credentials</dt> + <dd class="description">Array of credentials</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of call (0 = success)</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Note: The default credentials are tracked separately for each thread in a +program. Multi-threaded programs that override the setting need to do so in +each thread for the same setting to be used. + +</p> +<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="cupsSetDefaultDest">cupsSetDefaultDest</a></h3> + <p class="description">Set the default destination.</p> +<p class="code"> +void cupsSetDefaultDest (<br> +    const char *name,<br> +    const char *instance,<br> +    int num_dests,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Destination name</dd> +<dt>instance</dt> + <dd class="description">Instance name or <code>NULL</code></dd> +<dt>num_dests</dt> + <dd class="description">Number of destinations</dd> +<dt>dests</dt> + <dd class="description">Destinations</dd> +</dl> +<h3 class="function"><a id="cupsSetDests">cupsSetDests</a></h3> + <p class="description">Save the list of destinations for the default server.</p> +<p class="code"> +void cupsSetDests (<br> +    int num_dests,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>num_dests</dt> + <dd class="description">Number of destinations</dd> +<dt>dests</dt> + <dd class="description">Destinations</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run +as root and ~/.cups/lpoptions when run as a normal user.</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="cupsSetDests2">cupsSetDests2</a></h3> + <p class="description">Save the list of destinations for the specified server.</p> +<p class="code"> +int cupsSetDests2 (<br> +    <a href="#http_t">http_t</a> *http,<br> +    int num_dests,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>num_dests</dt> + <dd class="description">Number of destinations</dd> +<dt>dests</dt> + <dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, -1 on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run +as root and ~/.cups/lpoptions when run as a normal user. + +</p> +<h3 class="function"><a id="cupsSetEncryption">cupsSetEncryption</a></h3> + <p class="description">Set the encryption preference.</p> +<p class="code"> +void cupsSetEncryption (<br> +    <a href="#http_encryption_t">http_encryption_t</a> e<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>e</dt> + <dd class="description">New encryption preference</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION +environment variable, then the ~/.cups/client.conf file, and finally the +/etc/cups/client.conf file. If not set, the default is +<code>HTTP_ENCRYPTION_IF_REQUESTED</code>.<br> +<br> +Note: The current encryption setting is tracked separately for each thread +in a program. Multi-threaded programs that override the setting need to do +so in each thread for the same setting to be used.</p> +<h3 class="function"><a id="cupsSetPasswordCB">cupsSetPasswordCB</a></h3> + <p class="description">Set the password callback for CUPS.</p> +<p class="code"> +void cupsSetPasswordCB (<br> +    <a href="#cups_password_cb_t">cups_password_cb_t</a> cb<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>cb</dt> + <dd class="description">Callback function</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which +reads the password from the console. Programs should call either this +function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered +by a program per thread.<br> +<br> +Note: The current password callback is tracked separately for each thread +in a program. Multi-threaded programs that override the callback need to do +so in each thread for the same callback to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3> + <p class="description">Set the advanced password callback for CUPS.</p> +<p class="code"> +void cupsSetPasswordCB2 (<br> +    <a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb,<br> +    void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>cb</dt> + <dd class="description">Callback function</dd> +<dt>user_data</dt> + <dd class="description">User data pointer</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which +reads the password from the console. Programs should call either this +function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered +by a program per thread.<br> +<br> +Note: The current password callback is tracked separately for each thread +in a program. Multi-threaded programs that override the callback need to do +so in each thread for the same callback to be used. + +</p> +<h3 class="function"><a id="cupsSetServer">cupsSetServer</a></h3> + <p class="description">Set the default server name and port.</p> +<p class="code"> +void cupsSetServer (<br> +    const char *server<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>server</dt> + <dd class="description">Server name</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The "server" string can be a fully-qualified hostname, a numeric +IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP +addresses can be optionally followed by a colon and port number to override +the default port 631, e.g. "hostname:8631". Pass <code>NULL</code> to restore the +default server name and port.<br> +<br> +Note: The current server is tracked separately for each thread in a program. +Multi-threaded programs that override the server need to do so in each +thread for the same server to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="cupsSetServerCertCB">cupsSetServerCertCB</a></h3> + <p class="description">Set the server certificate callback.</p> +<p class="code"> +void cupsSetServerCertCB (<br> +    <a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a> cb,<br> +    void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>cb</dt> + <dd class="description">Callback function</dd> +<dt>user_data</dt> + <dd class="description">User data pointer</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Pass <code>NULL</code> to restore the default callback.<br> +<br> +Note: The current credentials callback is tracked separately for each thread +in a program. Multi-threaded programs that override the callback need to do +so in each thread for the same callback to be used. + +</p> +<h3 class="function"><span class="info"> CUPS 2.0/macOS 10.10 </span><a id="cupsSetServerCredentials">cupsSetServerCredentials</a></h3> + <p class="description">Set the default server credentials.</p> +<p class="code"> +int cupsSetServerCredentials (<br> +    const char *path,<br> +    const char *common_name,<br> +    int auto_create<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>path</dt> + <dd class="description">Keychain path or <code>NULL</code> for default</dd> +<dt>common_name</dt> + <dd class="description">Default common name for server</dd> +<dt>auto_create</dt> + <dd class="description">1 = automatically create self-signed certificates</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Note: The server credentials are used by all threads in the running process. +This function is threadsafe. + +</p> +<h3 class="function"><a id="cupsSetUser">cupsSetUser</a></h3> + <p class="description">Set the default user name.</p> +<p class="code"> +void cupsSetUser (<br> +    const char *user<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>user</dt> + <dd class="description">User name</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Pass <code>NULL</code> to restore the default user name.<br> +<br> +Note: The current user name is tracked separately for each thread in a +program. Multi-threaded programs that override the user name need to do so +in each thread for the same user name to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsSetUserAgent">cupsSetUserAgent</a></h3> + <p class="description">Set the default HTTP User-Agent string.</p> +<p class="code"> +void cupsSetUserAgent (<br> +    const char *user_agent<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>user_agent</dt> + <dd class="description">User-Agent string or <code>NULL</code></dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Setting the string to NULL forces the default value containing the CUPS +version, IPP version, and operating system version and architecture. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cupsStartDestDocument">cupsStartDestDocument</a></h3> + <p class="description">Start a new document.</p> +<p class="code"> +http_status_t cupsStartDestDocument (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> +    <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br> +    int job_id,<br> +    const char *docname,<br> +    const char *format,<br> +    int num_options,<br> +    <a href="#cups_option_t">cups_option_t</a> *options,<br> +    int last_document<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to destination</dd> +<dt>dest</dt> + <dd class="description">Destination</dd> +<dt>info</dt> + <dd class="description">Destination information</dd> +<dt>job_id</dt> + <dd class="description">Job ID</dd> +<dt>docname</dt> + <dd class="description">Document name</dd> +<dt>format</dt> + <dd class="description">Document format</dd> +<dt>num_options</dt> + <dd class="description">Number of document options</dd> +<dt>options</dt> + <dd class="description">Document options</dd> +<dt>last_document</dt> + <dd class="description">1 if this is the last document</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of document creation</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">"job_id" is the job ID returned by cupsCreateDestJob. "docname" is the name +of the document/file being printed, "format" is the MIME media type for the +document (see CUPS_FORMAT_xxx constants), and "num_options" and "options" +are the options do be applied to the document. "last_document" should be 1 +if this is the last document to be submitted in the job. Returns +<code>HTTP_CONTINUE</code> on success. + +</p> +<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="cupsStartDocument">cupsStartDocument</a></h3> + <p class="description">Add a document to a job created with cupsCreateJob().</p> +<p class="code"> +http_status_t cupsStartDocument (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *name,<br> +    int job_id,<br> +    const char *docname,<br> +    const char *format,<br> +    int last_document<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> + <dd class="description">Destination name</dd> +<dt>job_id</dt> + <dd class="description">Job ID from <a href="#cupsCreateJob"><code>cupsCreateJob</code></a></dd> +<dt>docname</dt> + <dd class="description">Name of document</dd> +<dt>format</dt> + <dd class="description">MIME type or <code>CUPS_FORMAT_foo</code></dd> +<dt>last_document</dt> + <dd class="description">1 for last document in job, 0 otherwise</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">HTTP status of request</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write data for the document and +<a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> to finish the document and get the submission status.<br> +<br> +The MIME type constants <code>CUPS_FORMAT_AUTO</code>, <code>CUPS_FORMAT_PDF</code>, +<code>CUPS_FORMAT_POSTSCRIPT</code>, <code>CUPS_FORMAT_RAW</code>, and +<code>CUPS_FORMAT_TEXT</code> are provided for the "format" argument, although +any supported MIME type string can be supplied. + +</p> +<h3 class="function"><a id="cupsTempFd">cupsTempFd</a></h3> + <p class="description">Creates a temporary file.</p> +<p class="code"> +int cupsTempFd (<br> +    char *filename,<br> +    int len<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>filename</dt> + <dd class="description">Pointer to buffer</dd> +<dt>len</dt> + <dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New file descriptor or -1 on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The temporary filename is returned in the filename buffer. +The temporary file is opened for reading and writing.</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="cupsTempFile">cupsTempFile</a></h3> + <p class="description">Generates a temporary filename.</p> +<p class="code"> +char *cupsTempFile (<br> +    char *filename,<br> +    int len<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>filename</dt> + <dd class="description">Pointer to buffer</dd> +<dt>len</dt> + <dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Filename or <code>NULL</code> on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The temporary filename is returned in the filename buffer. +This function is deprecated and will no longer generate a temporary +filename - use <a href="#cupsTempFd"><code>cupsTempFd</code></a> or <a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="cupsTempFile2">cupsTempFile2</a></h3> + <p class="description">Creates a temporary CUPS file.</p> +<p class="code"> +<a href="#cups_file_t">cups_file_t</a> *cupsTempFile2 (<br> +    char *filename,<br> +    int len<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>filename</dt> + <dd class="description">Pointer to buffer</dd> +<dt>len</dt> + <dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">CUPS file or <code>NULL</code> on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The temporary filename is returned in the filename buffer. +The temporary file is opened for writing. + +</p> +<h3 class="function"><a id="cupsUser">cupsUser</a></h3> + <p class="description">Return the current user's name.</p> +<p class="code"> +const char *cupsUser (void);</p> +<h4 class="returnvalue">Return Value</h4> + <p class="description">User name</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Note: The current user name is tracked separately for each thread in a +program. Multi-threaded programs that override the user name with the +<a href="#cupsSetUser"><code>cupsSetUser</code></a> function need to do so in each thread for the same user +name to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="cupsUserAgent">cupsUserAgent</a></h3> + <p class="description">Return the default HTTP User-Agent string.</p> +<p class="code"> +const char *cupsUserAgent (void);</p> +<h4 class="returnvalue">Return Value</h4> + <p class="description">User-Agent string</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpAcceptConnection">httpAcceptConnection</a></h3> + <p class="description">Accept a new HTTP client connection from the +specified listening socket.</p> +<p class="code"> +<a href="#http_t">http_t</a> *httpAcceptConnection (<br> +    int fd,<br> +    int blocking<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fd</dt> + <dd class="description">Listen socket file descriptor</dd> +<dt>blocking</dt> + <dd class="description">1 if the connection should be +blocking, 0 otherwise</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">HTTP connection or <code>NULL</code></p> +<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="httpAddCredential">httpAddCredential</a></h3> + <p class="description">Allocates and adds a single credential to an array.</p> +<p class="code"> +int httpAddCredential (<br> +    <a href="#cups_array_t">cups_array_t</a> *credentials,<br> +    const void *data,<br> +    size_t datalen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>credentials</dt> + <dd class="description">Credentials array</dd> +<dt>data</dt> + <dd class="description">PEM-encoded X.509 data</dd> +<dt>datalen</dt> + <dd class="description">Length of data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, -1 on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Use <code>cupsArrayNew(NULL, NULL)</code> to create a credentials array. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrAny">httpAddrAny</a></h3> + <p class="description">Check for the "any" address.</p> +<p class="code"> +int httpAddrAny (<br> +    const <a href="#http_addr_t">http_addr_t</a> *addr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addr</dt> + <dd class="description">Address to check</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if "any", 0 otherwise</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpAddrClose">httpAddrClose</a></h3> + <p class="description">Close a socket created by <a href="#httpAddrConnect"><code>httpAddrConnect</code></a> or +<a href="#httpAddrListen"><code>httpAddrListen</code></a>.</p> +<p class="code"> +int httpAddrClose (<br> +    <a href="#http_addr_t">http_addr_t</a> *addr,<br> +    int fd<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addr</dt> + <dd class="description">Listen address or <code>NULL</code></dd> +<dt>fd</dt> + <dd class="description">Socket file descriptor</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, -1 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Pass <code>NULL</code> for sockets created with <a href="#httpAddrConnect"><code>httpAddrConnect</code></a> and the +listen address for sockets created with <a href="#httpAddrListen"><code>httpAddrListen</code></a>. This will +ensure that domain sockets are removed when closed. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrConnect">httpAddrConnect</a></h3> + <p class="description">Connect to any of the addresses in the list.</p> +<p class="code"> +<a href="#http_addrlist_t">http_addrlist_t</a> *httpAddrConnect (<br> +    <a href="#http_addrlist_t">http_addrlist_t</a> *addrlist,<br> +    int *sock<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addrlist</dt> + <dd class="description">List of potential addresses</dd> +<dt>sock</dt> + <dd class="description">Socket</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Connected address or NULL on failure</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpAddrConnect2">httpAddrConnect2</a></h3> + <p class="description">Connect to any of the addresses in the list with a +timeout and optional cancel.</p> +<p class="code"> +<a href="#http_addrlist_t">http_addrlist_t</a> *httpAddrConnect2 (<br> +    <a href="#http_addrlist_t">http_addrlist_t</a> *addrlist,<br> +    int *sock,<br> +    int msec,<br> +    int *cancel<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addrlist</dt> + <dd class="description">List of potential addresses</dd> +<dt>sock</dt> + <dd class="description">Socket</dd> +<dt>msec</dt> + <dd class="description">Timeout in milliseconds</dd> +<dt>cancel</dt> + <dd class="description">Pointer to "cancel" variable</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Connected address or NULL on failure</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpAddrCopyList">httpAddrCopyList</a></h3> + <p class="description">Copy an address list.</p> +<p class="code"> +<a href="#http_addrlist_t">http_addrlist_t</a> *httpAddrCopyList (<br> +    <a href="#http_addrlist_t">http_addrlist_t</a> *src<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>src</dt> + <dd class="description">Source address list</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New address list or <code>NULL</code> on error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrEqual">httpAddrEqual</a></h3> + <p class="description">Compare two addresses.</p> +<p class="code"> +int httpAddrEqual (<br> +    const <a href="#http_addr_t">http_addr_t</a> *addr1,<br> +    const <a href="#http_addr_t">http_addr_t</a> *addr2<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addr1</dt> + <dd class="description">First address</dd> +<dt>addr2</dt> + <dd class="description">Second address</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if equal, 0 if not</p> +<h3 class="function"><a id="httpAddrFamily">httpAddrFamily</a></h3> + <p class="description">Get the address family of an address.</p> +<p class="code"> +int httpAddrFamily (<br> +    <a href="#http_addr_t">http_addr_t</a> *addr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addr</dt> + <dd class="description">Address</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Address family</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrFreeList">httpAddrFreeList</a></h3> + <p class="description">Free an address list.</p> +<p class="code"> +void httpAddrFreeList (<br> +    <a href="#http_addrlist_t">http_addrlist_t</a> *addrlist<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addrlist</dt> + <dd class="description">Address list to free</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrGetList">httpAddrGetList</a></h3> + <p class="description">Get a list of addresses for a hostname.</p> +<p class="code"> +<a href="#http_addrlist_t">http_addrlist_t</a> *httpAddrGetList (<br> +    const char *hostname,<br> +    int family,<br> +    const char *service<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>hostname</dt> + <dd class="description">Hostname, IP address, or NULL for passive listen address</dd> +<dt>family</dt> + <dd class="description">Address family or AF_UNSPEC</dd> +<dt>service</dt> + <dd class="description">Service name or port number</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">List of addresses or NULL</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrLength">httpAddrLength</a></h3> + <p class="description">Return the length of the address in bytes.</p> +<p class="code"> +int httpAddrLength (<br> +    const <a href="#http_addr_t">http_addr_t</a> *addr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addr</dt> + <dd class="description">Address</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Length in bytes</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpAddrListen">httpAddrListen</a></h3> + <p class="description">Create a listening socket bound to the specified +address and port.</p> +<p class="code"> +int httpAddrListen (<br> +    <a href="#http_addr_t">http_addr_t</a> *addr,<br> +    int port<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addr</dt> + <dd class="description">Address to bind to</dd> +<dt>port</dt> + <dd class="description">Port number to bind to</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Socket or -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrLocalhost">httpAddrLocalhost</a></h3> + <p class="description">Check for the local loopback address.</p> +<p class="code"> +int httpAddrLocalhost (<br> +    const <a href="#http_addr_t">http_addr_t</a> *addr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addr</dt> + <dd class="description">Address to check</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if local host, 0 otherwise</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrLookup">httpAddrLookup</a></h3> + <p class="description">Lookup the hostname associated with the address.</p> +<p class="code"> +char *httpAddrLookup (<br> +    const <a href="#http_addr_t">http_addr_t</a> *addr,<br> +    char *name,<br> +    int namelen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addr</dt> + <dd class="description">Address to lookup</dd> +<dt>name</dt> + <dd class="description">Host name buffer</dd> +<dt>namelen</dt> + <dd class="description">Size of name buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Host name</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpAddrPort">httpAddrPort</a></h3> + <p class="description">Get the port number associated with an address.</p> +<p class="code"> +int httpAddrPort (<br> +    <a href="#http_addr_t">http_addr_t</a> *addr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addr</dt> + <dd class="description">Address</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Port number</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAddrString">httpAddrString</a></h3> + <p class="description">Convert an address to a numeric string.</p> +<p class="code"> +char *httpAddrString (<br> +    const <a href="#http_addr_t">http_addr_t</a> *addr,<br> +    char *s,<br> +    int slen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>addr</dt> + <dd class="description">Address to convert</dd> +<dt>s</dt> + <dd class="description">String buffer</dd> +<dt>slen</dt> + <dd class="description">Length of string</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Numeric address string</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAssembleURI">httpAssembleURI</a></h3> + <p class="description">Assemble a uniform resource identifier from its +components.</p> +<p class="code"> +<a href="#http_uri_status_t">http_uri_status_t</a> httpAssembleURI (<br> +    <a href="#http_uri_coding_t">http_uri_coding_t</a> encoding,<br> +    char *uri,<br> +    int urilen,<br> +    const char *scheme,<br> +    const char *username,<br> +    const char *host,<br> +    int port,<br> +    const char *resource<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>encoding</dt> + <dd class="description">Encoding flags</dd> +<dt>uri</dt> + <dd class="description">URI buffer</dd> +<dt>urilen</dt> + <dd class="description">Size of URI buffer</dd> +<dt>scheme</dt> + <dd class="description">Scheme name</dd> +<dt>username</dt> + <dd class="description">Username</dd> +<dt>host</dt> + <dd class="description">Hostname or address</dd> +<dt>port</dt> + <dd class="description">Port number</dd> +<dt>resource</dt> + <dd class="description">Resource</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">URI status</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function escapes reserved characters in the URI depending on the +value of the "encoding" argument. You should use this function in +place of traditional string functions whenever you need to create a +URI string. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpAssembleURIf">httpAssembleURIf</a></h3> + <p class="description">Assemble a uniform resource identifier from its +components with a formatted resource.</p> +<p class="code"> +<a href="#http_uri_status_t">http_uri_status_t</a> httpAssembleURIf (<br> +    <a href="#http_uri_coding_t">http_uri_coding_t</a> encoding,<br> +    char *uri,<br> +    int urilen,<br> +    const char *scheme,<br> +    const char *username,<br> +    const char *host,<br> +    int port,<br> +    const char *resourcef,<br> +    ...<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>encoding</dt> + <dd class="description">Encoding flags</dd> +<dt>uri</dt> + <dd class="description">URI buffer</dd> +<dt>urilen</dt> + <dd class="description">Size of URI buffer</dd> +<dt>scheme</dt> + <dd class="description">Scheme name</dd> +<dt>username</dt> + <dd class="description">Username</dd> +<dt>host</dt> + <dd class="description">Hostname or address</dd> +<dt>port</dt> + <dd class="description">Port number</dd> +<dt>resourcef</dt> + <dd class="description">Printf-style resource</dd> +<dt>...</dt> + <dd class="description">Additional arguments as needed</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">URI status</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function creates a formatted version of the resource string +argument "resourcef" and escapes reserved characters in the URI +depending on the value of the "encoding" argument. You should use +this function in place of traditional string functions whenever +you need to create a URI string. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpAssembleUUID">httpAssembleUUID</a></h3> + <p class="description">Assemble a name-based UUID URN conforming to RFC 4122.</p> +<p class="code"> +char *httpAssembleUUID (<br> +    const char *server,<br> +    int port,<br> +    const char *name,<br> +    int number,<br> +    char *buffer,<br> +    size_t bufsize<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>server</dt> + <dd class="description">Server name</dd> +<dt>port</dt> + <dd class="description">Port number</dd> +<dt>name</dt> + <dd class="description">Object name or NULL</dd> +<dt>number</dt> + <dd class="description">Object number or 0</dd> +<dt>buffer</dt> + <dd class="description">String buffer</dd> +<dt>bufsize</dt> + <dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">UUID string</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function creates a unique 128-bit identifying number using the server +name, port number, random data, and optionally an object name and/or object +number. The result is formatted as a UUID URN as defined in RFC 4122.<br> +<br> +The buffer needs to be at least 46 bytes in size. + +</p> +<h3 class="function"><a id="httpBlocking">httpBlocking</a></h3> + <p class="description">Set blocking/non-blocking behavior on a connection.</p> +<p class="code"> +void httpBlocking (<br> +    <a href="#http_t">http_t</a> *http,<br> +    int b<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>b</dt> + <dd class="description">1 = blocking, 0 = non-blocking</dd> +</dl> +<h3 class="function"><a id="httpCheck">httpCheck</a></h3> + <p class="description">Check to see if there is a pending response from the server.</p> +<p class="code"> +int httpCheck (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 = no data, 1 = data available</p> +<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="httpClearCookie">httpClearCookie</a></h3> + <p class="description">Clear the cookie value(s).</p> +<p class="code"> +void httpClearCookie (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h3 class="function"><a id="httpClearFields">httpClearFields</a></h3> + <p class="description">Clear HTTP request fields.</p> +<p class="code"> +void httpClearFields (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h3 class="function"><a id="httpClose">httpClose</a></h3> + <p class="description">Close an HTTP connection.</p> +<p class="code"> +void httpClose (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpCompareCredentials">httpCompareCredentials</a></h3> + <p class="description">Compare two sets of X.509 credentials.</p> +<p class="code"> +int httpCompareCredentials (<br> +    <a href="#cups_array_t">cups_array_t</a> *cred1,<br> +    <a href="#cups_array_t">cups_array_t</a> *cred2<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>cred1</dt> + <dd class="description">First set of X.509 credentials</dd> +<dt>cred2</dt> + <dd class="description">Second set of X.509 credentials</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if they match, 0 if they do not</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpConnect">httpConnect</a></h3> + <p class="description">Connect to a HTTP server.</p> +<p class="code"> +<a href="#http_t">http_t</a> *httpConnect (<br> +    const char *host,<br> +    int port<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>host</dt> + <dd class="description">Host to connect to</dd> +<dt>port</dt> + <dd class="description">Port number</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New HTTP connection</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is deprecated - use <a href="#httpConnect2"><code>httpConnect2</code></a> instead. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpConnect2">httpConnect2</a></h3> + <p class="description">Connect to a HTTP server.</p> +<p class="code"> +<a href="#http_t">http_t</a> *httpConnect2 (<br> +    const char *host,<br> +    int port,<br> +    <a href="#http_addrlist_t">http_addrlist_t</a> *addrlist,<br> +    int family,<br> +    <a href="#http_encryption_t">http_encryption_t</a> encryption,<br> +    int blocking,<br> +    int msec,<br> +    int *cancel<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>host</dt> + <dd class="description">Host to connect to</dd> +<dt>port</dt> + <dd class="description">Port number</dd> +<dt>addrlist</dt> + <dd class="description">List of addresses or NULL to lookup</dd> +<dt>family</dt> + <dd class="description">Address family to use or <code>AF_UNSPEC</code> for any</dd> +<dt>encryption</dt> + <dd class="description">Type of encryption to use</dd> +<dt>blocking</dt> + <dd class="description">1 for blocking connection, 0 for non-blocking</dd> +<dt>msec</dt> + <dd class="description">Connection timeout in milliseconds, 0 means don't connect</dd> +<dt>cancel</dt> + <dd class="description">Pointer to "cancel" variable</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New HTTP connection</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpConnectEncrypt">httpConnectEncrypt</a></h3> + <p class="description">Connect to a HTTP server using encryption.</p> +<p class="code"> +<a href="#http_t">http_t</a> *httpConnectEncrypt (<br> +    const char *host,<br> +    int port,<br> +    <a href="#http_encryption_t">http_encryption_t</a> encryption<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>host</dt> + <dd class="description">Host to connect to</dd> +<dt>port</dt> + <dd class="description">Port number</dd> +<dt>encryption</dt> + <dd class="description">Type of encryption to use</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New HTTP connection</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is now deprecated. Please use the <a href="#httpConnect2"><code>httpConnect2</code></a> function +instead. + +</p> +<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="httpCopyCredentials">httpCopyCredentials</a></h3> + <p class="description">Copy the credentials associated with the peer in +an encrypted connection.</p> +<p class="code"> +int httpCopyCredentials (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_array_t">cups_array_t</a> **credentials<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection to server</dd> +<dt>credentials</dt> + <dd class="description">Array of credentials</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of call (0 = success)</p> +<h3 class="function"><span class="info"> CUPS 2.0/macOS 10.10 </span><a id="httpCredentialsAreValidForName">httpCredentialsAreValidForName</a></h3> + <p class="description">Return whether the credentials are valid for the given name.</p> +<p class="code"> +int httpCredentialsAreValidForName (<br> +    <a href="#cups_array_t">cups_array_t</a> *credentials,<br> +    const char *common_name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>credentials</dt> + <dd class="description">Credentials</dd> +<dt>common_name</dt> + <dd class="description">Name to check</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if valid, 0 otherwise</p> +<h3 class="function"><span class="info"> CUPS 2.0/macOS 10.10 </span><a id="httpCredentialsGetExpiration">httpCredentialsGetExpiration</a></h3> + <p class="description">Return the expiration date of the credentials.</p> +<p class="code"> +time_t httpCredentialsGetExpiration (<br> +    <a href="#cups_array_t">cups_array_t</a> *credentials<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>credentials</dt> + <dd class="description">Credentials</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Expiration date of credentials</p> +<h3 class="function"><span class="info"> CUPS 2.0/macOS 10.10 </span><a id="httpCredentialsGetTrust">httpCredentialsGetTrust</a></h3> + <p class="description">Return the trust of credentials.</p> +<p class="code"> +<a href="#http_trust_t">http_trust_t</a> httpCredentialsGetTrust (<br> +    <a href="#cups_array_t">cups_array_t</a> *credentials,<br> +    const char *common_name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>credentials</dt> + <dd class="description">Credentials</dd> +<dt>common_name</dt> + <dd class="description">Common name for trust lookup</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Level of trust</p> +<h3 class="function"><span class="info"> CUPS 2.0/macOS 10.10 </span><a id="httpCredentialsString">httpCredentialsString</a></h3> + <p class="description">Return a string representing the credentials.</p> +<p class="code"> +size_t httpCredentialsString (<br> +    <a href="#cups_array_t">cups_array_t</a> *credentials,<br> +    char *buffer,<br> +    size_t bufsize<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>credentials</dt> + <dd class="description">Credentials</dd> +<dt>buffer</dt> + <dd class="description">Buffer or <code>NULL</code></dd> +<dt>bufsize</dt> + <dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Total size of credentials string</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpDecode64">httpDecode64</a></h3> + <p class="description">Base64-decode a string.</p> +<p class="code"> +char *httpDecode64 (<br> +    char *out,<br> +    const char *in<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>out</dt> + <dd class="description">String to write to</dd> +<dt>in</dt> + <dd class="description">String to read from</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Decoded string</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is deprecated. Use the httpDecode64_2() function instead +which provides buffer length arguments. + +</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="httpDecode64_2">httpDecode64_2</a></h3> + <p class="description">Base64-decode a string.</p> +<p class="code"> +char *httpDecode64_2 (<br> +    char *out,<br> +    int *outlen,<br> +    const char *in<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>out</dt> + <dd class="description">String to write to</dd> +<dt>outlen</dt> + <dd class="description">Size of output string</dd> +<dt>in</dt> + <dd class="description">String to read from</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Decoded string</p> +<h3 class="function"><a id="httpDelete">httpDelete</a></h3> + <p class="description">Send a DELETE request to the server.</p> +<p class="code"> +int httpDelete (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *uri<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>uri</dt> + <dd class="description">URI to delete</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of call (0 = success)</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpEncode64">httpEncode64</a></h3> + <p class="description">Base64-encode a string.</p> +<p class="code"> +char *httpEncode64 (<br> +    char *out,<br> +    const char *in<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>out</dt> + <dd class="description">String to write to</dd> +<dt>in</dt> + <dd class="description">String to read from</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Encoded string</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is deprecated. Use the httpEncode64_2() function instead +which provides buffer length arguments. + +</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="httpEncode64_2">httpEncode64_2</a></h3> + <p class="description">Base64-encode a string.</p> +<p class="code"> +char *httpEncode64_2 (<br> +    char *out,<br> +    int outlen,<br> +    const char *in,<br> +    int inlen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>out</dt> + <dd class="description">String to write to</dd> +<dt>outlen</dt> + <dd class="description">Size of output string</dd> +<dt>in</dt> + <dd class="description">String to read from</dd> +<dt>inlen</dt> + <dd class="description">Size of input string</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Encoded string</p> +<h3 class="function"><a id="httpEncryption">httpEncryption</a></h3> + <p class="description">Set the required encryption on the link.</p> +<p class="code"> +int httpEncryption (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#http_encryption_t">http_encryption_t</a> e<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>e</dt> + <dd class="description">New encryption preference</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">-1 on error, 0 on success</p> +<h3 class="function"><a id="httpError">httpError</a></h3> + <p class="description">Get the last error on a connection.</p> +<p class="code"> +int httpError (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Error code (errno) value</p> +<h3 class="function"><a id="httpFieldValue">httpFieldValue</a></h3> + <p class="description">Return the HTTP field enumeration value for a field +name.</p> +<p class="code"> +<a href="#http_field_t">http_field_t</a> httpFieldValue (<br> +    const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">String name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Field index</p> +<h3 class="function"><a id="httpFlush">httpFlush</a></h3> + <p class="description">Flush data from a HTTP connection.</p> +<p class="code"> +void httpFlush (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpFlushWrite">httpFlushWrite</a></h3> + <p class="description">Flush data in write buffer.</p> +<p class="code"> +int httpFlushWrite (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Bytes written or -1 on error</p> +<h3 class="function"><a id="httpFreeCredentials">httpFreeCredentials</a></h3> + <p class="description">Free an array of credentials.</p> +<p class="code"> +void httpFreeCredentials (<br> +    <a href="#cups_array_t">cups_array_t</a> *credentials<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>credentials</dt> + <dd class="description">Array of credentials</dd> +</dl> +<h3 class="function"><a id="httpGet">httpGet</a></h3> + <p class="description">Send a GET request to the server.</p> +<p class="code"> +int httpGet (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *uri<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>uri</dt> + <dd class="description">URI to get</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of call (0 = success)</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetActivity">httpGetActivity</a></h3> + <p class="description">Get the most recent activity for a connection.</p> +<p class="code"> +time_t httpGetActivity (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Time of last read or write</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The return value is the UNIX time of the last read or write. + +</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetAddress">httpGetAddress</a></h3> + <p class="description">Get the address of the connected peer of a connection.</p> +<p class="code"> +<a href="#http_addr_t">http_addr_t</a> *httpGetAddress (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Connected address or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Returns <code>NULL</code> if the socket is currently unconnected. + +</p> +<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="httpGetAuthString">httpGetAuthString</a></h3> + <p class="description">Get the current authorization string.</p> +<p class="code"> +char *httpGetAuthString (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Authorization string</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The authorization string is set by cupsDoAuthentication() and +httpSetAuthString(). Use httpGetAuthString() to retrieve the +string to use with httpSetField() for the HTTP_FIELD_AUTHORIZATION +value. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetBlocking">httpGetBlocking</a></h3> + <p class="description">Get the blocking/non-block state of a connection.</p> +<p class="code"> +int httpGetBlocking (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if blocking, 0 if non-blocking</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpGetContentEncoding">httpGetContentEncoding</a></h3> + <p class="description">Get a common content encoding, if any, between +the client and server.</p> +<p class="code"> +const char *httpGetContentEncoding (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Content-Coding value or +<code>NULL</code> for the identity +coding.</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function uses the value of the Accepts-Encoding HTTP header and must be +called after receiving a response from the server or a request from the +client. The value returned can be use in subsequent requests (for clients) +or in the response (for servers) in order to compress the content stream. + +</p> +<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="httpGetCookie">httpGetCookie</a></h3> + <p class="description">Get any cookie data from the response.</p> +<p class="code"> +const char *httpGetCookie (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Cookie data or NULL</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpGetDateString">httpGetDateString</a></h3> + <p class="description">Get a formatted date/time string from a time value.</p> +<p class="code"> +const char *httpGetDateString (<br> +    time_t t<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>t</dt> + <dd class="description">UNIX time</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Date/time string</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetDateString2">httpGetDateString2</a></h3> + <p class="description">Get a formatted date/time string from a time value.</p> +<p class="code"> +const char *httpGetDateString2 (<br> +    time_t t,<br> +    char *s,<br> +    int slen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>t</dt> + <dd class="description">UNIX time</dd> +<dt>s</dt> + <dd class="description">String buffer</dd> +<dt>slen</dt> + <dd class="description">Size of string buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Date/time string</p> +<h3 class="function"><a id="httpGetDateTime">httpGetDateTime</a></h3> + <p class="description">Get a time value from a formatted date/time string.</p> +<p class="code"> +time_t httpGetDateTime (<br> +    const char *s<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>s</dt> + <dd class="description">Date/time string</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">UNIX time</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetEncryption">httpGetEncryption</a></h3> + <p class="description">Get the current encryption mode of a connection.</p> +<p class="code"> +<a href="#http_encryption_t">http_encryption_t</a> httpGetEncryption (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Current encryption mode</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function returns the encryption mode for the connection. Use the +<a href="#httpIsEncrypted"><code>httpIsEncrypted</code></a> function to determine whether a TLS session has +been established. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpGetExpect">httpGetExpect</a></h3> + <p class="description">Get the value of the Expect header, if any.</p> +<p class="code"> +http_status_t httpGetExpect (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Expect: status, if any</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Returns <code>HTTP_STATUS_NONE</code> if there is no Expect header, otherwise +returns the expected HTTP status code, typically <code>HTTP_STATUS_CONTINUE</code>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetFd">httpGetFd</a></h3> + <p class="description">Get the file descriptor associated with a connection.</p> +<p class="code"> +int httpGetFd (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">File descriptor or -1 if none</p> +<h3 class="function"><a id="httpGetField">httpGetField</a></h3> + <p class="description">Get a field value from a request/response.</p> +<p class="code"> +const char *httpGetField (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#http_field_t">http_field_t</a> field<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>field</dt> + <dd class="description">Field to get</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Field value</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpGetHostByName">httpGetHostByName</a></h3> + <p class="description">Lookup a hostname or IPv4 address, and return +address records for the specified name.</p> +<p class="code"> +struct hostent *httpGetHostByName (<br> +    const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Hostname or IP address</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Host entry</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetHostname">httpGetHostname</a></h3> + <p class="description">Get the FQDN for the connection or local system.</p> +<p class="code"> +const char *httpGetHostname (<br> +    <a href="#http_t">http_t</a> *http,<br> +    char *s,<br> +    int slen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection or NULL</dd> +<dt>s</dt> + <dd class="description">String buffer for name</dd> +<dt>slen</dt> + <dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">FQDN for connection or system</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">When "http" points to a connected socket, return the hostname or +address that was used in the call to httpConnect() or httpConnectEncrypt(), +or the address of the client for the connection from httpAcceptConnection(). +Otherwise, return the FQDN for the local system using both gethostname() +and gethostbyname() to get the local hostname with domain. + +</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetKeepAlive">httpGetKeepAlive</a></h3> + <p class="description">Get the current Keep-Alive state of the connection.</p> +<p class="code"> +<a href="#http_keepalive_t">http_keepalive_t</a> httpGetKeepAlive (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Keep-Alive state</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpGetLength">httpGetLength</a></h3> + <p class="description">Get the amount of data remaining from the +content-length or transfer-encoding fields.</p> +<p class="code"> +int httpGetLength (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Content length</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is deprecated and will not return lengths larger than +2^31 - 1; use httpGetLength2() instead. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetLength2">httpGetLength2</a></h3> + <p class="description">Get the amount of data remaining from the +content-length or transfer-encoding fields.</p> +<p class="code"> +off_t httpGetLength2 (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Content length</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function returns the complete content length, even for +content larger than 2^31 - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetPending">httpGetPending</a></h3> + <p class="description">Get the number of bytes that are buffered for writing.</p> +<p class="code"> +size_t httpGetPending (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes buffered</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetReady">httpGetReady</a></h3> + <p class="description">Get the number of bytes that can be read without blocking.</p> +<p class="code"> +size_t httpGetReady (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes available</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpGetRemaining">httpGetRemaining</a></h3> + <p class="description">Get the number of remaining bytes in the message +body or current chunk.</p> +<p class="code"> +size_t httpGetRemaining (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Remaining bytes</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <a href="#httpIsChunked"><code>httpIsChunked</code></a> function can be used to determine whether the +message body is chunked or fixed-length. + +</p> +<h3 class="function"><a id="httpGetState">httpGetState</a></h3> + <p class="description">Get the current state of the HTTP request.</p> +<p class="code"> +<a href="#http_state_t">http_state_t</a> httpGetState (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">HTTP state</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetStatus">httpGetStatus</a></h3> + <p class="description">Get the status of the last HTTP request.</p> +<p class="code"> +http_status_t httpGetStatus (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">HTTP status</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpGetSubField">httpGetSubField</a></h3> + <p class="description">Get a sub-field value.</p> +<p class="code"> +char *httpGetSubField (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#http_field_t">http_field_t</a> field,<br> +    const char *name,<br> +    char *value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>field</dt> + <dd class="description">Field index</dd> +<dt>name</dt> + <dd class="description">Name of sub-field</dd> +<dt>value</dt> + <dd class="description">Value string</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Value or NULL</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpGetSubField2">httpGetSubField2</a></h3> + <p class="description">Get a sub-field value.</p> +<p class="code"> +char *httpGetSubField2 (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#http_field_t">http_field_t</a> field,<br> +    const char *name,<br> +    char *value,<br> +    int valuelen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>field</dt> + <dd class="description">Field index</dd> +<dt>name</dt> + <dd class="description">Name of sub-field</dd> +<dt>value</dt> + <dd class="description">Value string</dd> +<dt>valuelen</dt> + <dd class="description">Size of value buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Value or NULL</p> +<h3 class="function"><a id="httpGetVersion">httpGetVersion</a></h3> + <p class="description">Get the HTTP version at the other end.</p> +<p class="code"> +<a href="#http_version_t">http_version_t</a> httpGetVersion (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Version number</p> +<h3 class="function"><a id="httpGets">httpGets</a></h3> + <p class="description">Get a line of text from a HTTP connection.</p> +<p class="code"> +char *httpGets (<br> +    char *line,<br> +    int length,<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>line</dt> + <dd class="description">Line to read into</dd> +<dt>length</dt> + <dd class="description">Max length of buffer</dd> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Line or NULL</p> +<h3 class="function"><a id="httpHead">httpHead</a></h3> + <p class="description">Send a HEAD request to the server.</p> +<p class="code"> +int httpHead (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *uri<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>uri</dt> + <dd class="description">URI for head</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of call (0 = success)</p> +<h3 class="function"><a id="httpInitialize">httpInitialize</a></h3> + <p class="description">Initialize the HTTP interface library and set the +default HTTP proxy (if any).</p> +<p class="code"> +void httpInitialize (void);</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpIsChunked">httpIsChunked</a></h3> + <p class="description">Report whether a message body is chunked.</p> +<p class="code"> +int httpIsChunked (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if chunked, 0 if not</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function returns non-zero if the message body is composed of +variable-length chunks. + +</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpIsEncrypted">httpIsEncrypted</a></h3> + <p class="description">Report whether a connection is encrypted.</p> +<p class="code"> +int httpIsEncrypted (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if encrypted, 0 if not</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function returns non-zero if the connection is currently encrypted. + +</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpLoadCredentials">httpLoadCredentials</a></h3> + <p class="description">Load X.509 credentials from a keychain file.</p> +<p class="code"> +int httpLoadCredentials (<br> +    const char *path,<br> +    <a href="#cups_array_t">cups_array_t</a> **credentials,<br> +    const char *common_name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>path</dt> + <dd class="description">Keychain path or <code>NULL</code> for default</dd> +<dt>credentials</dt> + <dd class="description">Credentials</dd> +<dt>common_name</dt> + <dd class="description">Common name for credentials</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, -1 on error</p> +<h3 class="function"><a id="httpOptions">httpOptions</a></h3> + <p class="description">Send an OPTIONS request to the server.</p> +<p class="code"> +int httpOptions (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *uri<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>uri</dt> + <dd class="description">URI for options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of call (0 = success)</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpPeek">httpPeek</a></h3> + <p class="description">Peek at data from a HTTP connection.</p> +<p class="code"> +ssize_t httpPeek (<br> +    <a href="#http_t">http_t</a> *http,<br> +    char *buffer,<br> +    size_t length<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>buffer</dt> + <dd class="description">Buffer for data</dd> +<dt>length</dt> + <dd class="description">Maximum number of bytes</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes copied</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function copies available data from the given HTTP connection, reading +a buffer as needed. The data is still available for reading using +<a href="#httpRead"><code>httpRead</code></a> or <a href="#httpRead2"><code>httpRead2</code></a>.<br> +<br> +For non-blocking connections the usual timeouts apply. + +</p> +<h3 class="function"><a id="httpPost">httpPost</a></h3> + <p class="description">Send a POST request to the server.</p> +<p class="code"> +int httpPost (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *uri<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>uri</dt> + <dd class="description">URI for post</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of call (0 = success)</p> +<h3 class="function"><a id="httpPut">httpPut</a></h3> + <p class="description">Send a PUT request to the server.</p> +<p class="code"> +int httpPut (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *uri<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>uri</dt> + <dd class="description">URI to put</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of call (0 = success)</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpRead">httpRead</a></h3> + <p class="description">Read data from a HTTP connection.</p> +<p class="code"> +int httpRead (<br> +    <a href="#http_t">http_t</a> *http,<br> +    char *buffer,<br> +    int length<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>buffer</dt> + <dd class="description">Buffer for data</dd> +<dt>length</dt> + <dd class="description">Maximum number of bytes</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes read</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is deprecated. Use the httpRead2() function which can +read more than 2GB of data. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpRead2">httpRead2</a></h3> + <p class="description">Read data from a HTTP connection.</p> +<p class="code"> +ssize_t httpRead2 (<br> +    <a href="#http_t">http_t</a> *http,<br> +    char *buffer,<br> +    size_t length<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>buffer</dt> + <dd class="description">Buffer for data</dd> +<dt>length</dt> + <dd class="description">Maximum number of bytes</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes read</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpReadRequest">httpReadRequest</a></h3> + <p class="description">Read a HTTP request from a connection.</p> +<p class="code"> +<a href="#http_state_t">http_state_t</a> httpReadRequest (<br> +    <a href="#http_t">http_t</a> *http,<br> +    char *uri,<br> +    size_t urilen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>uri</dt> + <dd class="description">URI buffer</dd> +<dt>urilen</dt> + <dd class="description">Size of URI buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New state of connection</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpReconnect">httpReconnect</a></h3> + <p class="description">Reconnect to a HTTP server.</p> +<p class="code"> +int httpReconnect (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, non-zero on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is deprecated. Please use the <a href="#httpReconnect2"><code>httpReconnect2</code></a> function +instead. + +</p> +<h3 class="function"><a id="httpReconnect2">httpReconnect2</a></h3> + <p class="description">Reconnect to a HTTP server with timeout and optional +cancel.</p> +<p class="code"> +int httpReconnect2 (<br> +    <a href="#http_t">http_t</a> *http,<br> +    int msec,<br> +    int *cancel<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>msec</dt> + <dd class="description">Timeout in milliseconds</dd> +<dt>cancel</dt> + <dd class="description">Pointer to "cancel" variable</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, non-zero on failure</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpResolveHostname">httpResolveHostname</a></h3> + <p class="description">Resolve the hostname of the HTTP connection +address.</p> +<p class="code"> +const char *httpResolveHostname (<br> +    <a href="#http_t">http_t</a> *http,<br> +    char *buffer,<br> +    size_t bufsize<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>buffer</dt> + <dd class="description">Hostname buffer</dd> +<dt>bufsize</dt> + <dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Resolved hostname or <code>NULL</code></p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpSaveCredentials">httpSaveCredentials</a></h3> + <p class="description">Save X.509 credentials to a keychain file.</p> +<p class="code"> +int httpSaveCredentials (<br> +    const char *path,<br> +    <a href="#cups_array_t">cups_array_t</a> *credentials,<br> +    const char *common_name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>path</dt> + <dd class="description">Keychain path or <code>NULL</code> for default</dd> +<dt>credentials</dt> + <dd class="description">Credentials</dd> +<dt>common_name</dt> + <dd class="description">Common name for credentials</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">-1 on error, 0 on success</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpSeparate">httpSeparate</a></h3> + <p class="description">Separate a Universal Resource Identifier into its +components.</p> +<p class="code"> +void httpSeparate (<br> +    const char *uri,<br> +    char *scheme,<br> +    char *username,<br> +    char *host,<br> +    int *port,<br> +    char *resource<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>uri</dt> + <dd class="description">Universal Resource Identifier</dd> +<dt>scheme</dt> + <dd class="description">Scheme [32] (http, https, etc.)</dd> +<dt>username</dt> + <dd class="description">Username [1024]</dd> +<dt>host</dt> + <dd class="description">Hostname [1024]</dd> +<dt>port</dt> + <dd class="description">Port number to use</dd> +<dt>resource</dt> + <dd class="description">Resource/filename [1024]</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is deprecated; use the httpSeparateURI() function instead. + +</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/macOS 10.4 </span><a id="httpSeparate2">httpSeparate2</a></h3> + <p class="description">Separate a Universal Resource Identifier into its +components.</p> +<p class="code"> +void httpSeparate2 (<br> +    const char *uri,<br> +    char *scheme,<br> +    int schemelen,<br> +    char *username,<br> +    int usernamelen,<br> +    char *host,<br> +    int hostlen,<br> +    int *port,<br> +    char *resource,<br> +    int resourcelen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>uri</dt> + <dd class="description">Universal Resource Identifier</dd> +<dt>scheme</dt> + <dd class="description">Scheme (http, https, etc.)</dd> +<dt>schemelen</dt> + <dd class="description">Size of scheme buffer</dd> +<dt>username</dt> + <dd class="description">Username</dd> +<dt>usernamelen</dt> + <dd class="description">Size of username buffer</dd> +<dt>host</dt> + <dd class="description">Hostname</dd> +<dt>hostlen</dt> + <dd class="description">Size of hostname buffer</dd> +<dt>port</dt> + <dd class="description">Port number to use</dd> +<dt>resource</dt> + <dd class="description">Resource/filename</dd> +<dt>resourcelen</dt> + <dd class="description">Size of resource buffer</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is deprecated; use the httpSeparateURI() function instead. + + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpSeparateURI">httpSeparateURI</a></h3> + <p class="description">Separate a Universal Resource Identifier into its +components.</p> +<p class="code"> +<a href="#http_uri_status_t">http_uri_status_t</a> httpSeparateURI (<br> +    <a href="#http_uri_coding_t">http_uri_coding_t</a> decoding,<br> +    const char *uri,<br> +    char *scheme,<br> +    int schemelen,<br> +    char *username,<br> +    int usernamelen,<br> +    char *host,<br> +    int hostlen,<br> +    int *port,<br> +    char *resource,<br> +    int resourcelen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>decoding</dt> + <dd class="description">Decoding flags</dd> +<dt>uri</dt> + <dd class="description">Universal Resource Identifier</dd> +<dt>scheme</dt> + <dd class="description">Scheme (http, https, etc.)</dd> +<dt>schemelen</dt> + <dd class="description">Size of scheme buffer</dd> +<dt>username</dt> + <dd class="description">Username</dd> +<dt>usernamelen</dt> + <dd class="description">Size of username buffer</dd> +<dt>host</dt> + <dd class="description">Hostname</dd> +<dt>hostlen</dt> + <dd class="description">Size of hostname buffer</dd> +<dt>port</dt> + <dd class="description">Port number to use</dd> +<dt>resource</dt> + <dd class="description">Resource/filename</dd> +<dt>resourcelen</dt> + <dd class="description">Size of resource buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Result of separation</p> +<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a id="httpSetAuthString">httpSetAuthString</a></h3> + <p class="description">Set the current authorization string.</p> +<p class="code"> +void httpSetAuthString (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *scheme,<br> +    const char *data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>scheme</dt> + <dd class="description">Auth scheme (NULL to clear it)</dd> +<dt>data</dt> + <dd class="description">Auth data (NULL for none)</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function just stores a copy of the current authorization string in +the HTTP connection object. You must still call httpSetField() to set +HTTP_FIELD_AUTHORIZATION prior to issuing a HTTP request using httpGet(), +httpHead(), httpOptions(), httpPost, or httpPut(). + +</p> +<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="httpSetCookie">httpSetCookie</a></h3> + <p class="description">Set the cookie value(s).</p> +<p class="code"> +void httpSetCookie (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *cookie<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">Connection</dd> +<dt>cookie</dt> + <dd class="description">Cookie string</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="httpSetCredentials">httpSetCredentials</a></h3> + <p class="description">Set the credentials associated with an encrypted +connection.</p> +<p class="code"> +int httpSetCredentials (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#cups_array_t">cups_array_t</a> *credentials<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>credentials</dt> + <dd class="description">Array of credentials</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of call (0 = success)</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpSetDefaultField">httpSetDefaultField</a></h3> + <p class="description">Set the default value of an HTTP header.</p> +<p class="code"> +void httpSetDefaultField (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#http_field_t">http_field_t</a> field,<br> +    const char *value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>field</dt> + <dd class="description">Field index</dd> +<dt>value</dt> + <dd class="description">Value</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Currently only <code>HTTP_FIELD_ACCEPT_ENCODING</code>, <code>HTTP_FIELD_SERVER</code>, +and <code>HTTP_FIELD_USER_AGENT</code> can be set. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpSetExpect">httpSetExpect</a></h3> + <p class="description">Set the Expect: header in a request.</p> +<p class="code"> +void httpSetExpect (<br> +    <a href="#http_t">http_t</a> *http,<br> +    http_status_t expect<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>expect</dt> + <dd class="description">HTTP status to expect +(<code>HTTP_STATUS_CONTINUE</code>)</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Currently only <code>HTTP_STATUS_CONTINUE</code> is supported for the "expect" +argument. + +</p> +<h3 class="function"><a id="httpSetField">httpSetField</a></h3> + <p class="description">Set the value of an HTTP header.</p> +<p class="code"> +void httpSetField (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#http_field_t">http_field_t</a> field,<br> +    const char *value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>field</dt> + <dd class="description">Field index</dd> +<dt>value</dt> + <dd class="description">Value</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpSetKeepAlive">httpSetKeepAlive</a></h3> + <p class="description">Set the current Keep-Alive state of a connection.</p> +<p class="code"> +void httpSetKeepAlive (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#http_keepalive_t">http_keepalive_t</a> keep_alive<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>keep_alive</dt> + <dd class="description">New Keep-Alive value</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpSetLength">httpSetLength</a></h3> + <p class="description">Set the content-length and content-encoding.</p> +<p class="code"> +void httpSetLength (<br> +    <a href="#http_t">http_t</a> *http,<br> +    size_t length<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>length</dt> + <dd class="description">Length (0 for chunked)</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="httpSetTimeout">httpSetTimeout</a></h3> + <p class="description">Set read/write timeouts and an optional callback.</p> +<p class="code"> +void httpSetTimeout (<br> +    <a href="#http_t">http_t</a> *http,<br> +    double timeout,<br> +    <a href="#http_timeout_cb_t">http_timeout_cb_t</a> cb,<br> +    void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>timeout</dt> + <dd class="description">Number of seconds for timeout, +must be greater than 0</dd> +<dt>cb</dt> + <dd class="description">Callback function or NULL</dd> +<dt>user_data</dt> + <dd class="description">User data pointer</dd> +</dl> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The optional timeout callback receives both the HTTP connection and a user +data pointer and must return 1 to continue or 0 to error (time) out. + +</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpShutdown">httpShutdown</a></h3> + <p class="description">Shutdown one side of an HTTP connection.</p> +<p class="code"> +void httpShutdown (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpStateString">httpStateString</a></h3> + <p class="description">Return the string describing a HTTP state value.</p> +<p class="code"> +const char *httpStateString (<br> +    <a href="#http_state_t">http_state_t</a> state<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>state</dt> + <dd class="description">HTTP state value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">State string</p> +<h3 class="function"><a id="httpStatus">httpStatus</a></h3> + <p class="description">Return a short string describing a HTTP status code.</p> +<p class="code"> +const char *httpStatus (<br> +    http_status_t status<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>status</dt> + <dd class="description">HTTP status code</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Localized status string</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The returned string is localized to the current POSIX locale and is based +on the status strings defined in RFC 2616.</p> +<h3 class="function"><a id="httpTrace">httpTrace</a></h3> + <p class="description">Send an TRACE request to the server.</p> +<p class="code"> +int httpTrace (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *uri<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>uri</dt> + <dd class="description">URI for trace</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status of call (0 = success)</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="httpURIStatusString">httpURIStatusString</a></h3> + <p class="description">Return a string describing a URI status code.</p> +<p class="code"> +const char *httpURIStatusString (<br> +    <a href="#http_uri_status_t">http_uri_status_t</a> status<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>status</dt> + <dd class="description">URI status code</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Localized status string</p> +<h3 class="function"><a id="httpUpdate">httpUpdate</a></h3> + <p class="description">Update the current HTTP state for incoming data.</p> +<p class="code"> +http_status_t httpUpdate (<br> +    <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">HTTP status</p> +<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="httpWait">httpWait</a></h3> + <p class="description">Wait for data available on a connection.</p> +<p class="code"> +int httpWait (<br> +    <a href="#http_t">http_t</a> *http,<br> +    int msec<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>msec</dt> + <dd class="description">Milliseconds to wait</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if data is available, 0 otherwise</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a id="httpWrite">httpWrite</a></h3> + <p class="description">Write data to a HTTP connection.</p> +<p class="code"> +int httpWrite (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *buffer,<br> +    int length<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>buffer</dt> + <dd class="description">Buffer for data</dd> +<dt>length</dt> + <dd class="description">Number of bytes to write</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes written</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function is deprecated. Use the httpWrite2() function which can +write more than 2GB of data. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="httpWrite2">httpWrite2</a></h3> + <p class="description">Write data to a HTTP connection.</p> +<p class="code"> +ssize_t httpWrite2 (<br> +    <a href="#http_t">http_t</a> *http,<br> +    const char *buffer,<br> +    size_t length<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>buffer</dt> + <dd class="description">Buffer for data</dd> +<dt>length</dt> + <dd class="description">Number of bytes to write</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes written</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="httpWriteResponse">httpWriteResponse</a></h3> + <p class="description">Write a HTTP response to a client connection.</p> +<p class="code"> +int httpWriteResponse (<br> +    <a href="#http_t">http_t</a> *http,<br> +    http_status_t status<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>status</dt> + <dd class="description">Status code</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">0 on success, -1 on error</p> +<h3 class="function"><a id="ippAddBoolean">ippAddBoolean</a></h3> + <p class="description">Add a boolean attribute to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBoolean (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    const char *name,<br> +    char value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>value</dt> + <dd class="description">Value of attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> +<h3 class="function"><a id="ippAddBooleans">ippAddBooleans</a></h3> + <p class="description">Add an array of boolean values.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBooleans (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    const char *name,<br> +    int num_values,<br> +    const char *values<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>num_values</dt> + <dd class="description">Number of values</dd> +<dt>values</dt> + <dd class="description">Values</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> +<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ippAddCollection">ippAddCollection</a></h3> + <p class="description">Add a collection value.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollection (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    const char *name,<br> +    <a href="#ipp_t">ipp_t</a> *value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>value</dt> + <dd class="description">Value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). + +</p> +<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ippAddCollections">ippAddCollections</a></h3> + <p class="description">Add an array of collection values.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollections (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    const char *name,<br> +    int num_values,<br> +    const <a href="#ipp_t">ipp_t</a> **values<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>num_values</dt> + <dd class="description">Number of values</dd> +<dt>values</dt> + <dd class="description">Values</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). + +</p> +<h3 class="function"><a id="ippAddDate">ippAddDate</a></h3> + <p class="description">Add a date attribute to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddDate (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    const char *name,<br> +    const <a href="#ipp_uchar_t">ipp_uchar_t</a> *value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>value</dt> + <dd class="description">Value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> +<h3 class="function"><a id="ippAddInteger">ippAddInteger</a></h3> + <p class="description">Add a integer attribute to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddInteger (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    ipp_tag_t value_tag,<br> +    const char *name,<br> +    int value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>value_tag</dt> + <dd class="description">Type of attribute</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>value</dt> + <dd class="description">Value of attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported values include enum (<code>IPP_TAG_ENUM</code>) and integer +(<code>IPP_TAG_INTEGER</code>).</p> +<h3 class="function"><a id="ippAddIntegers">ippAddIntegers</a></h3> + <p class="description">Add an array of integer values.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddIntegers (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    ipp_tag_t value_tag,<br> +    const char *name,<br> +    int num_values,<br> +    const int *values<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>value_tag</dt> + <dd class="description">Type of attribute</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>num_values</dt> + <dd class="description">Number of values</dd> +<dt>values</dt> + <dd class="description">Values</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported values include enum (<code>IPP_TAG_ENUM</code>) and integer +(<code>IPP_TAG_INTEGER</code>).</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippAddOctetString">ippAddOctetString</a></h3> + <p class="description">Add an octetString value to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddOctetString (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    const char *name,<br> +    const void *data,<br> +    int datalen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>data</dt> + <dd class="description">octetString data</dd> +<dt>datalen</dt> + <dd class="description">Length of data in bytes</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippAddOutOfBand">ippAddOutOfBand</a></h3> + <p class="description">Add an out-of-band value to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddOutOfBand (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    ipp_tag_t value_tag,<br> +    const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>value_tag</dt> + <dd class="description">Type of attribute</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported out-of-band values include unsupported-value +(<code>IPP_TAG_UNSUPPORTED_VALUE</code>), default (<code>IPP_TAG_DEFAULT</code>), unknown +(<code>IPP_TAG_UNKNOWN</code>), no-value (<code>IPP_TAG_NOVALUE</code>), not-settable +(<code>IPP_TAG_NOTSETTABLE</code>), delete-attribute (<code>IPP_TAG_DELETEATTR</code>), and +admin-define (<code>IPP_TAG_ADMINDEFINE</code>). + +</p> +<h3 class="function"><a id="ippAddRange">ippAddRange</a></h3> + <p class="description">Add a range of values to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRange (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    const char *name,<br> +    int lower,<br> +    int upper<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>lower</dt> + <dd class="description">Lower value</dd> +<dt>upper</dt> + <dd class="description">Upper value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +The <code>lower</code> parameter must be less than or equal to the <code>upper</code> parameter.</p> +<h3 class="function"><a id="ippAddRanges">ippAddRanges</a></h3> + <p class="description">Add ranges of values to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRanges (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    const char *name,<br> +    int num_values,<br> +    const int *lower,<br> +    const int *upper<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>num_values</dt> + <dd class="description">Number of values</dd> +<dt>lower</dt> + <dd class="description">Lower values</dd> +<dt>upper</dt> + <dd class="description">Upper values</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> +<h3 class="function"><a id="ippAddResolution">ippAddResolution</a></h3> + <p class="description">Add a resolution value to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolution (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    const char *name,<br> +    <a href="#ipp_res_t">ipp_res_t</a> units,<br> +    int xres,<br> +    int yres<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>units</dt> + <dd class="description">Units for resolution</dd> +<dt>xres</dt> + <dd class="description">X resolution</dd> +<dt>yres</dt> + <dd class="description">Y resolution</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> +<h3 class="function"><a id="ippAddResolutions">ippAddResolutions</a></h3> + <p class="description">Add resolution values to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolutions (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    const char *name,<br> +    int num_values,<br> +    <a href="#ipp_res_t">ipp_res_t</a> units,<br> +    const int *xres,<br> +    const int *yres<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>num_values</dt> + <dd class="description">Number of values</dd> +<dt>units</dt> + <dd class="description">Units for resolution</dd> +<dt>xres</dt> + <dd class="description">X resolutions</dd> +<dt>yres</dt> + <dd class="description">Y resolutions</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> +<h3 class="function"><a id="ippAddSeparator">ippAddSeparator</a></h3> + <p class="description">Add a group separator to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddSeparator (<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.</p> +<h3 class="function"><a id="ippAddString">ippAddString</a></h3> + <p class="description">Add a language-encoded string to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddString (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    ipp_tag_t value_tag,<br> +    const char *name,<br> +    const char *language,<br> +    const char *value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>value_tag</dt> + <dd class="description">Type of attribute</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>language</dt> + <dd class="description">Language code</dd> +<dt>value</dt> + <dd class="description">Value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword +(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType +(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage +(<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage +(<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme +(<code>IPP_TAG_URISCHEME</code>).<br> +<br> +The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage and +textWithLanguage string values and must be <code>NULL</code> for all other string values.</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippAddStringf">ippAddStringf</a></h3> + <p class="description">Add a formatted string to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStringf (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    ipp_tag_t value_tag,<br> +    const char *name,<br> +    const char *language,<br> +    const char *format,<br> +    ...<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>value_tag</dt> + <dd class="description">Type of attribute</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>language</dt> + <dd class="description">Language code (<code>NULL</code> for default)</dd> +<dt>format</dt> + <dd class="description">Printf-style format string</dd> +<dt>...</dt> + <dd class="description">Additional arguments as needed</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document +(<code>IPP_TAG_DOCUMENT</code>), event notification +(<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation (<code>IPP_TAG_OPERATION</code>), +printer (<code>IPP_TAG_PRINTER</code>), subscription (<code>IPP_TAG_SUBSCRIPTION</code>), +or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword +(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType +(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage +(<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage +(<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme +(<code>IPP_TAG_URISCHEME</code>).<br> +<br> +The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage +and textWithLanguage string values and must be <code>NULL</code> for all other +string values.<br> +<br> +The <code>format</code> parameter uses formatting characters compatible with the +printf family of standard functions. Additional arguments follow it as +needed. The formatted string is truncated as needed to the maximum length of +the corresponding value type. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippAddStringfv">ippAddStringfv</a></h3> + <p class="description">Add a formatted string to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStringfv (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    ipp_tag_t value_tag,<br> +    const char *name,<br> +    const char *language,<br> +    const char *format,<br> +    va_list ap<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>value_tag</dt> + <dd class="description">Type of attribute</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>language</dt> + <dd class="description">Language code (<code>NULL</code> for default)</dd> +<dt>format</dt> + <dd class="description">Printf-style format string</dd> +<dt>ap</dt> + <dd class="description">Additional arguments</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document +(<code>IPP_TAG_DOCUMENT</code>), event notification +(<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation (<code>IPP_TAG_OPERATION</code>), +printer (<code>IPP_TAG_PRINTER</code>), subscription (<code>IPP_TAG_SUBSCRIPTION</code>), +or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword +(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType +(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage +(<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage +(<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme +(<code>IPP_TAG_URISCHEME</code>).<br> +<br> +The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage +and textWithLanguage string values and must be <code>NULL</code> for all other +string values.<br> +<br> +The <code>format</code> parameter uses formatting characters compatible with the +printf family of standard functions. Additional arguments are passed in the +stdarg pointer <code>ap</code>. The formatted string is truncated as needed to the +maximum length of the corresponding value type. + +</p> +<h3 class="function"><a id="ippAddStrings">ippAddStrings</a></h3> + <p class="description">Add language-encoded strings to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStrings (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_tag_t group,<br> +    ipp_tag_t value_tag,<br> +    const char *name,<br> +    int num_values,<br> +    const char *language,<br> +    const char *const *values<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>group</dt> + <dd class="description">IPP group</dd> +<dt>value_tag</dt> + <dd class="description">Type of attribute</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>num_values</dt> + <dd class="description">Number of values</dd> +<dt>language</dt> + <dd class="description">Language code (<code>NULL</code> for default)</dd> +<dt>values</dt> + <dd class="description">Values</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword +(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType +(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage +(<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage +(<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme +(<code>IPP_TAG_URISCHEME</code>).<br> +<br> +The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage and +textWithLanguage string values and must be <code>NULL</code> for all other string values.</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippAttributeString">ippAttributeString</a></h3> + <p class="description">Convert the attribute's value to a string.</p> +<p class="code"> +size_t ippAttributeString (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> +    char *buffer,<br> +    size_t bufsize<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">Attribute</dd> +<dt>buffer</dt> + <dd class="description">String buffer or NULL</dd> +<dt>bufsize</dt> + <dd class="description">Size of string buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of bytes less nul</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Returns the number of bytes that would be written, not including the +trailing nul. The buffer pointer can be NULL to get the required length, +just like (v)snprintf. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippContainsInteger">ippContainsInteger</a></h3> + <p class="description">Determine whether an attribute contains the +specified value or is within the list of ranges.</p> +<p class="code"> +int ippContainsInteger (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> +    int value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">Attribute</dd> +<dt>value</dt> + <dd class="description">Integer/enum value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on a match, 0 on no match</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Returns non-zero when the attribute contains either a matching integer or +enum value, or the value falls within one of the rangeOfInteger values for +the attribute. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippContainsString">ippContainsString</a></h3> + <p class="description">Determine whether an attribute contains the +specified string value.</p> +<p class="code"> +int ippContainsString (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> +    const char *value<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">Attribute</dd> +<dt>value</dt> + <dd class="description">String value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on a match, 0 on no match</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Returns non-zero when the attribute contains a matching charset, keyword, +language, mimeMediaType, name, text, URI, or URI scheme value. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippCopyAttribute">ippCopyAttribute</a></h3> + <p class="description">Copy an attribute.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippCopyAttribute (<br> +    <a href="#ipp_t">ipp_t</a> *dst,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *srcattr,<br> +    int quickcopy<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dst</dt> + <dd class="description">Destination IPP message</dd> +<dt>srcattr</dt> + <dd class="description">Attribute to copy</dd> +<dt>quickcopy</dt> + <dd class="description">1 for a referenced copy, 0 for normal</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The specified attribute, <code>attr</code>, is copied to the destination IPP message. +When <code>quickcopy</code> is non-zero, a "shallow" reference copy of the attribute is +created - this should only be done as long as the original source IPP message will +not be freed for the life of the destination. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippCopyAttributes">ippCopyAttributes</a></h3> + <p class="description">Copy attributes from one IPP message to another.</p> +<p class="code"> +int ippCopyAttributes (<br> +    <a href="#ipp_t">ipp_t</a> *dst,<br> +    <a href="#ipp_t">ipp_t</a> *src,<br> +    int quickcopy,<br> +    <a href="#ipp_copycb_t">ipp_copycb_t</a> cb,<br> +    void *context<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dst</dt> + <dd class="description">Destination IPP message</dd> +<dt>src</dt> + <dd class="description">Source IPP message</dd> +<dt>quickcopy</dt> + <dd class="description">1 for a referenced copy, 0 for normal</dd> +<dt>cb</dt> + <dd class="description">Copy callback or <code>NULL</code> for none</dd> +<dt>context</dt> + <dd class="description">Context pointer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Zero or more attributes are copied from the source IPP message, <code>src</code>, to the +destination IPP message, <code>dst</code>. When <code>quickcopy</code> is non-zero, a "shallow" +reference copy of the attribute is created - this should only be done as long as the +original source IPP message will not be freed for the life of the destination.<br> +<br> +The <code>cb</code> and <code>context</code> parameters provide a generic way to "filter" the +attributes that are copied - the function must return 1 to copy the attribute or +0 to skip it. The function may also choose to do a partial copy of the source attribute +itself. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippCreateRequestedArray">ippCreateRequestedArray</a></h3> + <p class="description">Create a CUPS array of attribute names from the +given requested-attributes attribute.</p> +<p class="code"> +<a href="#cups_array_t">cups_array_t</a> *ippCreateRequestedArray (<br> +    <a href="#ipp_t">ipp_t</a> *request<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>request</dt> + <dd class="description">IPP request</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">CUPS array or <code>NULL</code> if all</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function creates a (sorted) CUPS array of attribute names matching the +list of "requested-attribute" values supplied in an IPP request. All IANA- +registered values are supported in addition to the CUPS IPP extension +attributes.<br> +<br> +The <code>request</code> parameter specifies the request message that was read from +the client. + +<code>NULL</code> is returned if all attributes should be returned. Otherwise, the +result is a sorted array of attribute names, where <code>cupsArrayFind(array, +"attribute-name")</code> will return a non-NULL pointer. The array must be freed +using the <code>cupsArrayDelete</code> function. + +</p> +<h3 class="function"><a id="ippDateToTime">ippDateToTime</a></h3> + <p class="description">Convert from RFC 1903 Date/Time format to UNIX time +in seconds.</p> +<p class="code"> +time_t ippDateToTime (<br> +    const <a href="#ipp_uchar_t">ipp_uchar_t</a> *date<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>date</dt> + <dd class="description">RFC 1903 date info</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">UNIX time value</p> +<h3 class="function"><a id="ippDelete">ippDelete</a></h3> + <p class="description">Delete an IPP message.</p> +<p class="code"> +void ippDelete (<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ippDeleteAttribute">ippDeleteAttribute</a></h3> + <p class="description">Delete a single attribute in an IPP message.</p> +<p class="code"> +void ippDeleteAttribute (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">Attribute to delete</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippDeleteValues">ippDeleteValues</a></h3> + <p class="description">Delete values in an attribute.</p> +<p class="code"> +int ippDeleteValues (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    int element,<br> +    int count<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">Attribute</dd> +<dt>element</dt> + <dd class="description">Index of first value to delete (0-based)</dd> +<dt>count</dt> + <dd class="description">Number of values to delete</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>element</code> parameter specifies the first value to delete, starting at +0. It must be less than the number of values returned by <a href="#ippGetCount"><code>ippGetCount</code></a>.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +Deleting all values in an attribute deletes the attribute. + +</p> +<h3 class="function"><a id="ippEnumString">ippEnumString</a></h3> + <p class="description">Return a string corresponding to the enum value.</p> +<p class="code"> +const char *ippEnumString (<br> +    const char *attrname,<br> +    int enumvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attrname</dt> + <dd class="description">Attribute name</dd> +<dt>enumvalue</dt> + <dd class="description">Enum value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Enum string</p> +<h3 class="function"><a id="ippEnumValue">ippEnumValue</a></h3> + <p class="description">Return the value associated with a given enum string.</p> +<p class="code"> +int ippEnumValue (<br> +    const char *attrname,<br> +    const char *enumstring<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attrname</dt> + <dd class="description">Attribute name</dd> +<dt>enumstring</dt> + <dd class="description">Enum string</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Enum value or -1 if unknown</p> +<h3 class="function"><a id="ippErrorString">ippErrorString</a></h3> + <p class="description">Return a name for the given status code.</p> +<p class="code"> +const char *ippErrorString (<br> +    ipp_status_t error<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>error</dt> + <dd class="description">Error status</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Text string</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippErrorValue">ippErrorValue</a></h3> + <p class="description">Return a status code for the given name.</p> +<p class="code"> +ipp_status_t ippErrorValue (<br> +    const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">IPP status code</p> +<h3 class="function"><a id="ippFindAttribute">ippFindAttribute</a></h3> + <p class="description">Find a named attribute in a request.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindAttribute (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    const char *name,<br> +    ipp_tag_t type<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>type</dt> + <dd class="description">Type of attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Matching attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Starting with CUPS 2.0, the attribute name can contain a hierarchical list +of attribute and member names separated by slashes, for example +"media-col/media-size".</p> +<h3 class="function"><a id="ippFindNextAttribute">ippFindNextAttribute</a></h3> + <p class="description">Find the next named attribute in a request.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindNextAttribute (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    const char *name,<br> +    ipp_tag_t type<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>name</dt> + <dd class="description">Name of attribute</dd> +<dt>type</dt> + <dd class="description">Type of attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Matching attribute</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">Starting with CUPS 2.0, the attribute name can contain a hierarchical list +of attribute and member names separated by slashes, for example +"media-col/media-size".</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippFirstAttribute">ippFirstAttribute</a></h3> + <p class="description">Return the first attribute in the message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFirstAttribute (<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">First attribute or <code>NULL</code> if none</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetBoolean">ippGetBoolean</a></h3> + <p class="description">Get a boolean value for an attribute.</p> +<p class="code"> +int ippGetBoolean (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> +    int element<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Boolean value or 0 on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetCollection">ippGetCollection</a></h3> + <p class="description">Get a collection value for an attribute.</p> +<p class="code"> +<a href="#ipp_t">ipp_t</a> *ippGetCollection (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> +    int element<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Collection value or <code>NULL</code> on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetCount">ippGetCount</a></h3> + <p class="description">Get the number of values in an attribute.</p> +<p class="code"> +int ippGetCount (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Number of values or 0 on error</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetDate">ippGetDate</a></h3> + <p class="description">Get a date value for an attribute.</p> +<p class="code"> +const <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippGetDate (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> +    int element<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Date value or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetGroupTag">ippGetGroupTag</a></h3> + <p class="description">Get the group associated with an attribute.</p> +<p class="code"> +ipp_tag_t ippGetGroupTag (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Group tag or <code>IPP_TAG_ZERO</code> on error</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetInteger">ippGetInteger</a></h3> + <p class="description">Get the integer/enum value for an attribute.</p> +<p class="code"> +int ippGetInteger (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> +    int element<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Value or 0 on error</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetName">ippGetName</a></h3> + <p class="description">Get the attribute name.</p> +<p class="code"> +const char *ippGetName (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Attribute name or <code>NULL</code> for separators</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippGetOctetString">ippGetOctetString</a></h3> + <p class="description">Get an octetString value from an IPP attribute.</p> +<p class="code"> +void *ippGetOctetString (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> +    int element,<br> +    int *datalen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>datalen</dt> + <dd class="description">Length of octetString data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Pointer to octetString data</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetOperation">ippGetOperation</a></h3> + <p class="description">Get the operation ID in an IPP message.</p> +<p class="code"> +ipp_op_t ippGetOperation (<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP request message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Operation ID or 0 on error</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetRange">ippGetRange</a></h3> + <p class="description">Get a rangeOfInteger value from an attribute.</p> +<p class="code"> +int ippGetRange (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> +    int element,<br> +    int *uppervalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>uppervalue</dt> + <dd class="description">Upper value of range</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Lower value of range or 0</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetRequestId">ippGetRequestId</a></h3> + <p class="description">Get the request ID from an IPP message.</p> +<p class="code"> +int ippGetRequestId (<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Request ID or 0 on error</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetResolution">ippGetResolution</a></h3> + <p class="description">Get a resolution value for an attribute.</p> +<p class="code"> +int ippGetResolution (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> +    int element,<br> +    int *yres,<br> +    <a href="#ipp_res_t">ipp_res_t</a> *units<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>yres</dt> + <dd class="description">Vertical/feed resolution</dd> +<dt>units</dt> + <dd class="description">Units for resolution</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Horizontal/cross feed resolution or 0</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetState">ippGetState</a></h3> + <p class="description">Get the IPP message state.</p> +<p class="code"> +<a href="#ipp_state_t">ipp_state_t</a> ippGetState (<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">IPP message state value</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetStatusCode">ippGetStatusCode</a></h3> + <p class="description">Get the status code from an IPP response or event message.</p> +<p class="code"> +ipp_status_t ippGetStatusCode (<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP response or event message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Status code in IPP message</p> +<h3 class="function"><a id="ippGetString">ippGetString</a></h3> + <p class="description">Return the value...</p> +<p class="code"> +const char *ippGetString (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> +    int element,<br> +    const char **language<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>language</dt> + <dd class="description">Language code (<code>NULL</code> for don't care)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Get the string and optionally the language code for an attribute.</p> + <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetValueTag">ippGetValueTag</a></h3> + <p class="description">Get the value tag for an attribute.</p> +<p class="code"> +ipp_tag_t ippGetValueTag (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Value tag or <code>IPP_TAG_ZERO</code> on error</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippGetVersion">ippGetVersion</a></h3> + <p class="description">Get the major and minor version number from an IPP message.</p> +<p class="code"> +int ippGetVersion (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    int *minor<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>minor</dt> + <dd class="description">Minor version number or <code>NULL</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Major version number or 0 on error</p> +<h3 class="function"><a id="ippLength">ippLength</a></h3> + <p class="description">Compute the length of an IPP message.</p> +<p class="code"> +size_t ippLength (<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Size of IPP message</p> +<h3 class="function"><a id="ippNew">ippNew</a></h3> + <p class="description">Allocate a new IPP message.</p> +<p class="code"> +<a href="#ipp_t">ipp_t</a> *ippNew (void);</p> +<h4 class="returnvalue">Return Value</h4> + <p class="description">New IPP message</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippNewRequest">ippNewRequest</a></h3> + <p class="description">Allocate a new IPP request message.</p> +<p class="code"> +<a href="#ipp_t">ipp_t</a> *ippNewRequest (<br> +    ipp_op_t op<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>op</dt> + <dd class="description">Operation code</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">IPP request message</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The new request message is initialized with the attributes-charset and +attributes-natural-language attributes added. The +attributes-natural-language value is derived from the current locale. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippNewResponse">ippNewResponse</a></h3> + <p class="description">Allocate a new IPP response message.</p> +<p class="code"> +<a href="#ipp_t">ipp_t</a> *ippNewResponse (<br> +    <a href="#ipp_t">ipp_t</a> *request<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>request</dt> + <dd class="description">IPP request message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">IPP response message</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The new response message is initialized with the same version-number, +request-id, attributes-charset, and attributes-natural-language as the +provided request message. If the attributes-charset or +attributes-natural-language attributes are missing from the request, +"utf-8" and a value derived from the current locale are substituted, +respectively. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippNextAttribute">ippNextAttribute</a></h3> + <p class="description">Return the next attribute in the message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippNextAttribute (<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Next attribute or <code>NULL</code> if none</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippOpString">ippOpString</a></h3> + <p class="description">Return a name for the given operation id.</p> +<p class="code"> +const char *ippOpString (<br> +    ipp_op_t op<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>op</dt> + <dd class="description">Operation ID</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Name</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippOpValue">ippOpValue</a></h3> + <p class="description">Return an operation id for the given name.</p> +<p class="code"> +ipp_op_t ippOpValue (<br> +    const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Textual name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Operation ID</p> +<h3 class="function"><a id="ippPort">ippPort</a></h3> + <p class="description">Return the default IPP port number.</p> +<p class="code"> +int ippPort (void);</p> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Port number</p> +<h3 class="function"><a id="ippRead">ippRead</a></h3> + <p class="description">Read data for an IPP message from a HTTP connection.</p> +<p class="code"> +<a href="#ipp_state_t">ipp_state_t</a> ippRead (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>ipp</dt> + <dd class="description">IPP data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Current state</p> +<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ippReadFile">ippReadFile</a></h3> + <p class="description">Read data for an IPP message from a file.</p> +<p class="code"> +<a href="#ipp_state_t">ipp_state_t</a> ippReadFile (<br> +    int fd,<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fd</dt> + <dd class="description">HTTP data</dd> +<dt>ipp</dt> + <dd class="description">IPP data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Current state</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippReadIO">ippReadIO</a></h3> + <p class="description">Read data for an IPP message.</p> +<p class="code"> +<a href="#ipp_state_t">ipp_state_t</a> ippReadIO (<br> +    void *src,<br> +    <a href="#ipp_iocb_t">ipp_iocb_t</a> cb,<br> +    int blocking,<br> +    <a href="#ipp_t">ipp_t</a> *parent,<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>src</dt> + <dd class="description">Data source</dd> +<dt>cb</dt> + <dd class="description">Read callback function</dd> +<dt>blocking</dt> + <dd class="description">Use blocking IO?</dd> +<dt>parent</dt> + <dd class="description">Parent request, if any</dd> +<dt>ipp</dt> + <dd class="description">IPP data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Current state</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetBoolean">ippSetBoolean</a></h3> + <p class="description">Set a boolean value in an attribute.</p> +<p class="code"> +int ippSetBoolean (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    int element,<br> +    int boolvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>boolvalue</dt> + <dd class="description">Boolean value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetCollection">ippSetCollection</a></h3> + <p class="description">Set a collection value in an attribute.</p> +<p class="code"> +int ippSetCollection (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    int element,<br> +    <a href="#ipp_t">ipp_t</a> *colvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>colvalue</dt> + <dd class="description">Collection value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetDate">ippSetDate</a></h3> + <p class="description">Set a date value in an attribute.</p> +<p class="code"> +int ippSetDate (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    int element,<br> +    const <a href="#ipp_uchar_t">ipp_uchar_t</a> *datevalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>datevalue</dt> + <dd class="description">Date value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetGroupTag">ippSetGroupTag</a></h3> + <p class="description">Set the group tag of an attribute.</p> +<p class="code"> +int ippSetGroupTag (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    ipp_tag_t group_tag<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">Attribute</dd> +<dt>group_tag</dt> + <dd class="description">Group tag</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetInteger">ippSetInteger</a></h3> + <p class="description">Set an integer or enum value in an attribute.</p> +<p class="code"> +int ippSetInteger (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    int element,<br> +    int intvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>intvalue</dt> + <dd class="description">Integer/enum value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetName">ippSetName</a></h3> + <p class="description">Set the name of an attribute.</p> +<p class="code"> +int ippSetName (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>name</dt> + <dd class="description">Attribute name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippSetOctetString">ippSetOctetString</a></h3> + <p class="description">Set an octetString value in an IPP attribute.</p> +<p class="code"> +int ippSetOctetString (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    int element,<br> +    const void *data,<br> +    int datalen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>data</dt> + <dd class="description">Pointer to octetString data</dd> +<dt>datalen</dt> + <dd class="description">Length of octetString data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetOperation">ippSetOperation</a></h3> + <p class="description">Set the operation ID in an IPP request message.</p> +<p class="code"> +int ippSetOperation (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_op_t op<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP request message</dd> +<dt>op</dt> + <dd class="description">Operation ID</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions. + +</p> +<h3 class="function"><a id="ippSetPort">ippSetPort</a></h3> + <p class="description">Set the default port number.</p> +<p class="code"> +void ippSetPort (<br> +    int p<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>p</dt> + <dd class="description">Port number to use</dd> +</dl> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetRange">ippSetRange</a></h3> + <p class="description">Set a rangeOfInteger value in an attribute.</p> +<p class="code"> +int ippSetRange (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    int element,<br> +    int lowervalue,<br> +    int uppervalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>lowervalue</dt> + <dd class="description">Lower bound for range</dd> +<dt>uppervalue</dt> + <dd class="description">Upper bound for range</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetRequestId">ippSetRequestId</a></h3> + <p class="description">Set the request ID in an IPP message.</p> +<p class="code"> +int ippSetRequestId (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    int request_id<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>request_id</dt> + <dd class="description">Request ID</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>request_id</code> parameter must be greater than 0. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetResolution">ippSetResolution</a></h3> + <p class="description">Set a resolution value in an attribute.</p> +<p class="code"> +int ippSetResolution (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    int element,<br> +    <a href="#ipp_res_t">ipp_res_t</a> unitsvalue,<br> +    int xresvalue,<br> +    int yresvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>unitsvalue</dt> + <dd class="description">Resolution units</dd> +<dt>xresvalue</dt> + <dd class="description">Horizontal/cross feed resolution</dd> +<dt>yresvalue</dt> + <dd class="description">Vertical/feed resolution</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetState">ippSetState</a></h3> + <p class="description">Set the current state of the IPP message.</p> +<p class="code"> +int ippSetState (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_state_t">ipp_state_t</a> state<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>state</dt> + <dd class="description">IPP state value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetStatusCode">ippSetStatusCode</a></h3> + <p class="description">Set the status code in an IPP response or event message.</p> +<p class="code"> +int ippSetStatusCode (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    ipp_status_t status<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP response or event message</dd> +<dt>status</dt> + <dd class="description">Status code</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetString">ippSetString</a></h3> + <p class="description">Set a string value in an attribute.</p> +<p class="code"> +int ippSetString (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    int element,<br> +    const char *strvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>strvalue</dt> + <dd class="description">String value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippSetStringf">ippSetStringf</a></h3> + <p class="description">Set a formatted string value of an attribute.</p> +<p class="code"> +int ippSetStringf (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    int element,<br> +    const char *format,<br> +    ...<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>format</dt> + <dd class="description">Printf-style format string</dd> +<dt>...</dt> + <dd class="description">Additional arguments as needed</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.<br> +<br> +The <code>format</code> parameter uses formatting characters compatible with the +printf family of standard functions. Additional arguments follow it as +needed. The formatted string is truncated as needed to the maximum length of +the corresponding value type. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippSetStringfv">ippSetStringfv</a></h3> + <p class="description">Set a formatted string value of an attribute.</p> +<p class="code"> +int ippSetStringfv (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    int element,<br> +    const char *format,<br> +    va_list ap<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>element</dt> + <dd class="description">Value number (0-based)</dd> +<dt>format</dt> + <dd class="description">Printf-style format string</dd> +<dt>ap</dt> + <dd class="description">Pointer to additional arguments</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.<br> +<br> +The <code>format</code> parameter uses formatting characters compatible with the +printf family of standard functions. Additional arguments follow it as +needed. The formatted string is truncated as needed to the maximum length of +the corresponding value type. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetValueTag">ippSetValueTag</a></h3> + <p class="description">Set the value tag of an attribute.</p> +<p class="code"> +int ippSetValueTag (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> +    ipp_tag_t value_tag<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>attr</dt> + <dd class="description">IPP attribute</dd> +<dt>value_tag</dt> + <dd class="description">Value tag</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +Integer (<code>IPP_TAG_INTEGER</code>) values can be promoted to rangeOfInteger +(<code>IPP_TAG_RANGE</code>) values, the various string tags can be promoted to name +(<code>IPP_TAG_NAME</code>) or nameWithLanguage (<code>IPP_TAG_NAMELANG</code>) values, text +(<code>IPP_TAG_TEXT</code>) values can be promoted to textWithLanguage +(<code>IPP_TAG_TEXTLANG</code>) values, and all values can be demoted to the various +out-of-band value tags such as no-value (<code>IPP_TAG_NOVALUE</code>). All other changes +will be rejected.<br> +<br> +Promoting a string attribute to nameWithLanguage or textWithLanguage adds the language +code in the "attributes-natural-language" attribute or, if not present, the language +code for the current locale. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="ippSetVersion">ippSetVersion</a></h3> + <p class="description">Set the version number in an IPP message.</p> +<p class="code"> +int ippSetVersion (<br> +    <a href="#ipp_t">ipp_t</a> *ipp,<br> +    int major,<br> +    int minor<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +<dt>major</dt> + <dd class="description">Major version number (major.minor)</dd> +<dt>minor</dt> + <dd class="description">Minor version number (major.minor)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using +the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br> +<br> +The valid version numbers are currently 1.0, 1.1, 2.0, 2.1, and 2.2. + +</p> +<h3 class="function"><span class="info"> CUPS 2.0/OS 10.10 </span><a id="ippStateString">ippStateString</a></h3> + <p class="description">Return the name corresponding to a state value.</p> +<p class="code"> +const char *ippStateString (<br> +    <a href="#ipp_state_t">ipp_state_t</a> state<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>state</dt> + <dd class="description">State value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">State name</p> +<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="ippTagString">ippTagString</a></h3> + <p class="description">Return the tag name corresponding to a tag value.</p> +<p class="code"> +const char *ippTagString (<br> +    ipp_tag_t tag<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>tag</dt> + <dd class="description">Tag value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Tag name</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The returned names are defined in RFC 2911 and 3382. + +</p> +<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a id="ippTagValue">ippTagValue</a></h3> + <p class="description">Return the tag value corresponding to a tag name.</p> +<p class="code"> +ipp_tag_t ippTagValue (<br> +    const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> + <dd class="description">Tag name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Tag value</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The tag names are defined in RFC 2911 and 3382. + +</p> +<h3 class="function"><a id="ippTimeToDate">ippTimeToDate</a></h3> + <p class="description">Convert from UNIX time to RFC 1903 format.</p> +<p class="code"> +const <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippTimeToDate (<br> +    time_t t<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>t</dt> + <dd class="description">UNIX time value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">RFC-1903 date/time data</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippValidateAttribute">ippValidateAttribute</a></h3> + <p class="description">Validate the contents of an attribute.</p> +<p class="code"> +int ippValidateAttribute (<br> +    <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> + <dd class="description">Attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if valid, 0 otherwise</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function validates the contents of an attribute based on the name and +value tag. 1 is returned if the attribute is valid, 0 otherwise. On +failure, cupsLastErrorString() is set to a human-readable message. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="ippValidateAttributes">ippValidateAttributes</a></h3> + <p class="description">Validate all attributes in an IPP message.</p> +<p class="code"> +int ippValidateAttributes (<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> + <dd class="description">IPP message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if valid, 0 otherwise</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function validates the contents of the IPP message, including each +attribute. Like <a href="#ippValidateAttribute"><code>ippValidateAttribute</code></a>, cupsLastErrorString() is set +to a human-readable message on failure. + +</p> +<h3 class="function"><a id="ippWrite">ippWrite</a></h3> + <p class="description">Write data for an IPP message to a HTTP connection.</p> +<p class="code"> +<a href="#ipp_state_t">ipp_state_t</a> ippWrite (<br> +    <a href="#http_t">http_t</a> *http,<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> + <dd class="description">HTTP connection</dd> +<dt>ipp</dt> + <dd class="description">IPP data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Current state</p> +<h3 class="function"><span class="info"> CUPS 1.1.19/macOS 10.3 </span><a id="ippWriteFile">ippWriteFile</a></h3> + <p class="description">Write data for an IPP message to a file.</p> +<p class="code"> +<a href="#ipp_state_t">ipp_state_t</a> ippWriteFile (<br> +    int fd,<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>fd</dt> + <dd class="description">HTTP data</dd> +<dt>ipp</dt> + <dd class="description">IPP data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Current state</p> +<h3 class="function"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="ippWriteIO">ippWriteIO</a></h3> + <p class="description">Write data for an IPP message.</p> +<p class="code"> +<a href="#ipp_state_t">ipp_state_t</a> ippWriteIO (<br> +    void *dst,<br> +    <a href="#ipp_iocb_t">ipp_iocb_t</a> cb,<br> +    int blocking,<br> +    <a href="#ipp_t">ipp_t</a> *parent,<br> +    <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dst</dt> + <dd class="description">Destination</dd> +<dt>cb</dt> + <dd class="description">Write callback function</dd> +<dt>blocking</dt> + <dd class="description">Use blocking IO?</dd> +<dt>parent</dt> + <dd class="description">Parent IPP message</dd> +<dt>ipp</dt> + <dd class="description">IPP data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Current state</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgFormatSizeName">pwgFormatSizeName</a></h3> + <p class="description">Generate a PWG self-describing media size name.</p> +<p class="code"> +int pwgFormatSizeName (<br> +    char *keyword,<br> +    size_t keysize,<br> +    const char *prefix,<br> +    const char *name,<br> +    int width,<br> +    int length,<br> +    const char *units<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>keyword</dt> + <dd class="description">Keyword buffer</dd> +<dt>keysize</dt> + <dd class="description">Size of keyword buffer</dd> +<dt>prefix</dt> + <dd class="description">Prefix for PWG size or <code>NULL</code> for automatic</dd> +<dt>name</dt> + <dd class="description">Size name or <code>NULL</code></dd> +<dt>width</dt> + <dd class="description">Width of page in 2540ths</dd> +<dt>length</dt> + <dd class="description">Length of page in 2540ths</dd> +<dt>units</dt> + <dd class="description">Units - "in", "mm", or <code>NULL</code> for automatic</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function generates a PWG self-describing media size name of the form +"prefix_name_WIDTHxLENGTHunits". The prefix is typically "custom" or "roll" +for user-supplied sizes but can also be "disc", "iso", "jis", "jpn", "na", +"oe", "om", "prc", or "roc". A value of <code>NULL</code> automatically chooses +"oe" or "om" depending on the units.<br> +<br> +The size name may only contain lowercase letters, numbers, "-", and ".". If +<code>NULL</code> is passed, the size name will contain the formatted dimensions.<br> +<br> +The width and length are specified in hundredths of millimeters, equivalent +to 1/100000th of a meter or 1/2540th of an inch. The width, length, and +units used for the generated size name are calculated automatically if the +units string is <code>NULL</code>, otherwise inches ("in") or millimeters ("mm") +are used. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgInitSize">pwgInitSize</a></h3> + <p class="description">Initialize a pwg_size_t structure using IPP Job Template +attributes.</p> +<p class="code"> +int pwgInitSize (<br> +    <a href="#pwg_size_t">pwg_size_t</a> *size,<br> +    <a href="#ipp_t">ipp_t</a> *job,<br> +    int *margins_set<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>size</dt> + <dd class="description">Size to initialize</dd> +<dt>job</dt> + <dd class="description">Job template attributes</dd> +<dt>margins_set</dt> + <dd class="description">1 if margins were set, 0 otherwise</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">1 if size was initialized, 0 otherwise</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">This function initializes a pwg_size_t structure from an IPP "media" or +"media-col" attribute in the specified IPP message. 0 is returned if neither +attribute is found in the message or the values are not valid.<br> +<br> +The "margins_set" variable is initialized to 1 if any "media-xxx-margin" +member attribute was specified in the "media-col" Job Template attribute, +otherwise it is initialized to 0. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgMediaForLegacy">pwgMediaForLegacy</a></h3> + <p class="description">Find a PWG media size by ISO/IPP legacy name.</p> +<p class="code"> +<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForLegacy (<br> +    const char *legacy<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>legacy</dt> + <dd class="description">Legacy size name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Matching size or NULL</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The "name" argument specifies the legacy ISO media size name, for example +"iso-a4" or "na-letter". + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgMediaForPPD">pwgMediaForPPD</a></h3> + <p class="description">Find a PWG media size by Adobe PPD name.</p> +<p class="code"> +<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForPPD (<br> +    const char *ppd<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ppd</dt> + <dd class="description">PPD size name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Matching size or NULL</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The "ppd" argument specifies an Adobe page size name as defined in Table B.1 +of the Adobe PostScript Printer Description File Format Specification Version +4.3.<br> +<br> +If the name is non-standard, the returned PWG media size is stored in +thread-local storage and is overwritten by each call to the function in the +thread. Custom names can be of the form "Custom.WIDTHxLENGTH[units]" or +"WIDTHxLENGTH[units]". + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgMediaForPWG">pwgMediaForPWG</a></h3> + <p class="description">Find a PWG media size by 5101.1 self-describing name.</p> +<p class="code"> +<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForPWG (<br> +    const char *pwg<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>pwg</dt> + <dd class="description">PWG size name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">Matching size or NULL</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The "pwg" argument specifies a self-describing media size name of the form +"prefix_name_WIDTHxLENGTHunits" as defined in PWG 5101.1.<br> +<br> +If the name is non-standard, the returned PWG media size is stored in +thread-local storage and is overwritten by each call to the function in the +thread. + +</p> +<h3 class="function"><span class="info"> CUPS 1.7/macOS 10.9 </span><a id="pwgMediaForSize">pwgMediaForSize</a></h3> + <p class="description">Get the PWG media size for the given dimensions.</p> +<p class="code"> +<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForSize (<br> +    int width,<br> +    int length<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>width</dt> + <dd class="description">Width in hundredths of millimeters</dd> +<dt>length</dt> + <dd class="description">Length in hundredths of millimeters</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> + <p class="description">PWG media name</p> +<h4 class="discussion">Discussion</h4> + <p class="discussion">The "width" and "length" are in hundredths of millimeters, equivalent to +1/100000th of a meter or 1/2540th of an inch.<br> +<br> +If the dimensions are non-standard, the returned PWG media size is stored in +thread-local storage and is overwritten by each call to the function in the +thread. + +</p> + <h2 class="title"><a id="TYPES">Data Types</a></h2> + <h3 class="typedef"><a id="cups_acopy_func_t">cups_acopy_func_t</a></h3> + <p class="description">Array element copy function</p> + <p class="code"> +typedef void *(*)(void *element, void *data)cups_acopy_func_t; +</p> + <h3 class="typedef"><a id="cups_afree_func_t">cups_afree_func_t</a></h3> + <p class="description">Array element free function</p> + <p class="code"> +typedef void(*)(void *element, void *data)cups_afree_func_t; +</p> + <h3 class="typedef"><a id="cups_ahash_func_t">cups_ahash_func_t</a></h3> + <p class="description">Array hash function</p> + <p class="code"> +typedef int(*)(void *element, void *data)cups_ahash_func_t; +</p> + <h3 class="typedef"><a id="cups_array_func_t">cups_array_func_t</a></h3> + <p class="description">Array comparison function</p> + <p class="code"> +typedef int(*)(void *first, void *second, void *data)cups_array_func_t; +</p> + <h3 class="typedef"><a id="cups_array_t">cups_array_t</a></h3> + <p class="description">CUPS array type</p> + <p class="code"> +typedef struct _cups_array_s cups_array_t; +</p> + <h3 class="typedef"><a id="cups_client_cert_cb_t"><span class="info"> CUPS 1.5/macOS 10.7 </span>cups_client_cert_cb_t</a></h3> + <p class="description">Client credentials callback +</p> + <p class="code"> +typedef int(*)(http_t *http, void *tls, <a href="#cups_array_t">cups_array_t</a> *distinguished_names, void *user_data)cups_client_cert_cb_t; +</p> + <h3 class="typedef"><a id="cups_dentry_t">cups_dentry_t</a></h3> + <p class="description">Directory entry type</p> + <p class="code"> +typedef struct <a href="#cups_dentry_s">cups_dentry_s</a> cups_dentry_t; +</p> + <h3 class="typedef"><a id="cups_dest_block_t"><span class="info"> CUPS 1.6/macOS 10.8 </span>cups_dest_block_t</a></h3> + <p class="description">Destination enumeration block +</p> + <p class="code"> +typedef int()(unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest)cups_dest_block_t; +</p> + <h3 class="typedef"><a id="cups_dest_cb_t"><span class="info"> CUPS 1.6/macOS 10.8 </span>cups_dest_cb_t</a></h3> + <p class="description">Destination enumeration callback +</p> + <p class="code"> +typedef int(*)(void *user_data, unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest)cups_dest_cb_t; +</p> + <h3 class="typedef"><a id="cups_dest_t">cups_dest_t</a></h3> + <p class="description">Destination</p> + <p class="code"> +typedef struct <a href="#cups_dest_s">cups_dest_s</a> cups_dest_t; +</p> + <h3 class="typedef"><a id="cups_dinfo_t"><span class="info"> CUPS 1.6/macOS 10.8 </span>cups_dinfo_t</a></h3> + <p class="description">Destination capability and status +information </p> + <p class="code"> +typedef struct _cups_dinfo_s cups_dinfo_t; +</p> + <h3 class="typedef"><a id="cups_dir_t">cups_dir_t</a></h3> + <p class="description">Directory type</p> + <p class="code"> +typedef struct _cups_dir_s cups_dir_t; +</p> + <h3 class="typedef"><a id="cups_encoding_t">cups_encoding_t</a></h3> + <p class="description">Language Encodings</p> + <p class="code"> +typedef enum <a href="#cups_encoding_e">cups_encoding_e</a> cups_encoding_t; +</p> + <h3 class="typedef"><a id="cups_file_t">cups_file_t</a></h3> + <p class="description">CUPS file type</p> + <p class="code"> +typedef struct _cups_file_s cups_file_t; +</p> + <h3 class="typedef"><a id="cups_job_t">cups_job_t</a></h3> + <p class="description">Job</p> + <p class="code"> +typedef struct <a href="#cups_job_s">cups_job_s</a> cups_job_t; +</p> + <h3 class="typedef"><a id="cups_lang_t">cups_lang_t</a></h3> + <p class="description">Language Cache Structure</p> + <p class="code"> +typedef struct <a href="#cups_lang_s">cups_lang_s</a> cups_lang_t; +</p> + <h3 class="typedef"><a id="cups_option_t">cups_option_t</a></h3> + <p class="description">Printer Options</p> + <p class="code"> +typedef struct <a href="#cups_option_s">cups_option_s</a> cups_option_t; +</p> + <h3 class="typedef"><a id="cups_password_cb2_t"><span class="info"> CUPS 1.4/macOS 10.6 </span>cups_password_cb2_t</a></h3> + <p class="description">New password callback +</p> + <p class="code"> +typedef const char *(*)(const char *prompt, <a href="#http_t">http_t</a> *http, const char *method, const char *resource, void *user_data)cups_password_cb2_t; +</p> + <h3 class="typedef"><a id="cups_password_cb_t">cups_password_cb_t</a></h3> + <p class="description">Password callback</p> + <p class="code"> +typedef const char *(*)(const char *prompt)cups_password_cb_t; +</p> + <h3 class="typedef"><a id="cups_ptype_t">cups_ptype_t</a></h3> + <p class="description">Printer type/capability bits</p> + <p class="code"> +typedef unsigned cups_ptype_t; +</p> + <h3 class="typedef"><a id="cups_server_cert_cb_t"><span class="info"> CUPS 1.5/macOS 10.7 </span>cups_server_cert_cb_t</a></h3> + <p class="description">Server credentials callback +</p> + <p class="code"> +typedef int(*)(http_t *http, void *tls, <a href="#cups_array_t">cups_array_t</a> *certs, void *user_data)cups_server_cert_cb_t; +</p> + <h3 class="typedef"><a id="cups_size_t"><span class="info"> CUPS 1.6/macOS 10.8 </span>cups_size_t</a></h3> + <p class="description">Media Size </p> + <p class="code"> +typedef struct <a href="#cups_size_s">cups_size_s</a> cups_size_t; +</p> + <h3 class="typedef"><a id="gss_auth_identity_desc">gss_auth_identity_desc</a></h3> + <p class="description">Local functions...</p> + <p class="code"> +typedef struct <a href="#gss_auth_identity">gss_auth_identity</a> gss_auth_identity_desc; +</p> + <h3 class="typedef"><a id="http_addr_t"><span class="info"> CUPS 1.2/macOS 10.5 </span>http_addr_t</a></h3> + <p class="description">Socket address union, which +makes using IPv6 and other +address types easier and +more portable. </p> + <p class="code"> +typedef union _http_addr_u / http_addr_t; +</p> + <h3 class="typedef"><a id="http_addrlist_t"><span class="info"> CUPS 1.2/macOS 10.5 </span>http_addrlist_t</a></h3> + <p class="description">Socket address list, which is +used to enumerate all of the +addresses that are associated +with a hostname. </p> + <p class="code"> +typedef struct <a href="#http_addrlist_s">http_addrlist_s</a> / http_addrlist_t; +</p> + <h3 class="typedef"><a id="http_auth_t">http_auth_t</a></h3> + <p class="description">HTTP authentication types</p> + <p class="code"> +typedef enum <a href="#http_auth_e">http_auth_e</a> http_auth_t; +</p> + <h3 class="typedef"><a id="http_credential_t"><span class="info"> CUPS 1.5/macOS 10.7 </span>http_credential_t</a></h3> + <p class="description">HTTP credential data </p> + <p class="code"> +typedef struct <a href="#http_credential_s">http_credential_s</a> http_credential_t; +</p> + <h3 class="typedef"><a id="http_encoding_t">http_encoding_t</a></h3> + <p class="description">HTTP transfer encoding values</p> + <p class="code"> +typedef enum <a href="#http_encoding_e">http_encoding_e</a> http_encoding_t; +</p> + <h3 class="typedef"><a id="http_encryption_t">http_encryption_t</a></h3> + <p class="description">HTTP encryption values</p> + <p class="code"> +typedef enum <a href="#http_encryption_e">http_encryption_e</a> http_encryption_t; +</p> + <h3 class="typedef"><a id="http_field_t">http_field_t</a></h3> + <p class="description">HTTP field names</p> + <p class="code"> +typedef enum <a href="#http_field_e">http_field_e</a> http_field_t; +</p> + <h3 class="typedef"><a id="http_keepalive_t">http_keepalive_t</a></h3> + <p class="description">HTTP keep-alive values</p> + <p class="code"> +typedef enum <a href="#http_keepalive_e">http_keepalive_e</a> http_keepalive_t; +</p> + <h3 class="typedef"><a id="http_state_t">http_state_t</a></h3> + <p class="description">HTTP state values; states +are server-oriented...</p> + <p class="code"> +typedef enum <a href="#http_state_e">http_state_e</a> http_state_t; +</p> + <h3 class="typedef"><a id="http_t">http_t</a></h3> + <p class="description">HTTP connection type</p> + <p class="code"> +typedef struct _http_s http_t; +</p> + <h3 class="typedef"><a id="http_timeout_cb_t"><span class="info"> CUPS 1.5/macOS 10.7 </span>http_timeout_cb_t</a></h3> + <p class="description">HTTP timeout callback </p> + <p class="code"> +typedef int(*)(http_t *http, void *user_data)http_timeout_cb_t; +</p> + <h3 class="typedef"><a id="http_trust_t"><span class="info"> CUPS 2.0/OS 10.10 </span>http_trust_t</a></h3> + <p class="description">Level of trust for credentials </p> + <p class="code"> +typedef enum <a href="#http_trust_e">http_trust_e</a> http_trust_t; +</p> + <h3 class="typedef"><a id="http_uri_coding_t">http_uri_coding_t</a></h3> + <p class="description">URI en/decode flags</p> + <p class="code"> +typedef enum <a href="#http_uri_coding_e">http_uri_coding_e</a> http_uri_coding_t; +</p> + <h3 class="typedef"><a id="http_uri_status_t"><span class="info"> CUPS 1.2 </span>http_uri_status_t</a></h3> + <p class="description">URI separation status </p> + <p class="code"> +typedef enum <a href="#http_uri_status_e">http_uri_status_e</a> http_uri_status_t; +</p> + <h3 class="typedef"><a id="http_version_t">http_version_t</a></h3> + <p class="description">HTTP version numbers</p> + <p class="code"> +typedef enum <a href="#http_version_e">http_version_e</a> http_version_t; +</p> + <h3 class="typedef"><a id="ipp_attribute_t">ipp_attribute_t</a></h3> + <p class="description">IPP attribute</p> + <p class="code"> +typedef struct _ipp_attribute_s ipp_attribute_t; +</p> + <h3 class="typedef"><a id="ipp_copycb_t">ipp_copycb_t</a></h3> + <p class="description">The following structures are PRIVATE starting with CUPS 1.6/macOS 10.8. +Please use the new accessor functions available in CUPS 1.6 and later, as +these definitions will be moved to a private header file in a future release.</p> + <p class="code"> +typedef int(*)(void *context, <a href="#ipp_t">ipp_t</a> *dst, <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr)ipp_copycb_t; +</p> + <h3 class="typedef"><a id="ipp_dstate_t">ipp_dstate_t</a></h3> + <p class="description">Document states</p> + <p class="code"> +typedef enum <a href="#ipp_dstate_e">ipp_dstate_e</a> ipp_dstate_t; +</p> + <h3 class="typedef"><a id="ipp_finish_t">ipp_finish_t</a></h3> + <p class="description">Job collation types</p> + <p class="code"> +typedef enum <a href="#ipp_finishings_e">ipp_finishings_e</a> ipp_finish_t; +</p> + <h3 class="typedef"><a id="ipp_iocb_t"><span class="info"> CUPS 1.2/macOS 10.5 </span>ipp_iocb_t</a></h3> + <p class="description">IPP IO Callback Function </p> + <p class="code"> +typedef ssize_t(*)(void *context, <a href="#ipp_uchar_t">ipp_uchar_t</a> *buffer, size_t bytes) ipp_iocb_t; +</p> + <h3 class="typedef"><a id="ipp_jcollate_t">ipp_jcollate_t</a></h3> + <p class="description">Job collation types</p> + <p class="code"> +typedef enum <a href="#ipp_jcollate_e">ipp_jcollate_e</a> ipp_jcollate_t; +</p> + <h3 class="typedef"><a id="ipp_orient_t">ipp_orient_t</a></h3> + <p class="description">Orientation values</p> + <p class="code"> +typedef enum <a href="#ipp_orient_e">ipp_orient_e</a> ipp_orient_t; +</p> + <h3 class="typedef"><a id="ipp_pstate_t">ipp_pstate_t</a></h3> + <p class="description">Printer states</p> + <p class="code"> +typedef enum <a href="#ipp_pstate_e">ipp_pstate_e</a> ipp_pstate_t; +</p> + <h3 class="typedef"><a id="ipp_quality_t">ipp_quality_t</a></h3> + <p class="description">Qualities</p> + <p class="code"> +typedef enum <a href="#ipp_quality_e">ipp_quality_e</a> ipp_quality_t; +</p> + <h3 class="typedef"><a id="ipp_res_t">ipp_res_t</a></h3> + <p class="description">Resolution units</p> + <p class="code"> +typedef enum <a href="#ipp_res_e">ipp_res_e</a> ipp_res_t; +</p> + <h3 class="typedef"><a id="ipp_state_t">ipp_state_t</a></h3> + <p class="description">IPP states</p> + <p class="code"> +typedef enum <a href="#ipp_state_e">ipp_state_e</a> ipp_state_t; +</p> + <h3 class="typedef"><a id="ipp_t">ipp_t</a></h3> + <p class="description">IPP request/response data</p> + <p class="code"> +typedef struct _ipp_s ipp_t; +</p> + <h3 class="typedef"><a id="ipp_uchar_t">ipp_uchar_t</a></h3> + <p class="description">Unsigned 8-bit integer/character</p> + <p class="code"> +typedef unsigned char ipp_uchar_t; +</p> + <h3 class="typedef"><a id="pwg_map_t">pwg_map_t</a></h3> + <p class="description">Map element - PPD to/from PWG</p> + <p class="code"> +typedef struct <a href="#pwg_map_s">pwg_map_s</a> pwg_map_t; +</p> + <h3 class="typedef"><a id="pwg_media_t">pwg_media_t</a></h3> + <p class="description">Common media size data</p> + <p class="code"> +typedef struct <a href="#pwg_media_s">pwg_media_s</a> pwg_media_t; +</p> + <h3 class="typedef"><a id="pwg_size_t">pwg_size_t</a></h3> + <p class="description">Size element - PPD to/from PWG</p> + <p class="code"> +typedef struct <a href="#pwg_size_s">pwg_size_s</a> pwg_size_t; +</p> + <h2 class="title"><a id="STRUCTURES">Structures</a></h2> +<h3 class="struct"><a id="cups_dentry_s">cups_dentry_s</a></h3> + <p class="description">Directory entry type</p> +<p class="code">struct cups_dentry_s {<br> +    struct stat fileinfo;<br> +    char filename[260];<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>fileinfo </dt> + <dd class="description">File information</dd> +<dt>filename[260] </dt> + <dd class="description">File name</dd> +</dl> +<h3 class="struct"><a id="cups_dest_s">cups_dest_s</a></h3> + <p class="description">Destination</p> +<p class="code">struct cups_dest_s {<br> +    char *name, *instance;<br> +    int is_default;<br> +    int num_options;<br> +    <a href="#cups_option_t">cups_option_t</a> *options;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>instance </dt> + <dd class="description">Local instance name or NULL</dd> +<dt>is_default </dt> + <dd class="description">Is this printer the default?</dd> +<dt>num_options </dt> + <dd class="description">Number of options</dd> +<dt>options </dt> + <dd class="description">Options</dd> +</dl> +<h3 class="struct"><a id="cups_job_s">cups_job_s</a></h3> + <p class="description">Job</p> +<p class="code">struct cups_job_s {<br> +    time_t completed_time;<br> +    time_t creation_time;<br> +    char *dest;<br> +    char *format;<br> +    int id;<br> +    int priority;<br> +    time_t processing_time;<br> +    int size;<br> +    ipp_jstate_t state;<br> +    char *title;<br> +    char *user;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>completed_time </dt> + <dd class="description">Time the job was completed</dd> +<dt>creation_time </dt> + <dd class="description">Time the job was created</dd> +<dt>dest </dt> + <dd class="description">Printer or class name</dd> +<dt>format </dt> + <dd class="description">Document format</dd> +<dt>id </dt> + <dd class="description">The job ID</dd> +<dt>priority </dt> + <dd class="description">Priority (1-100)</dd> +<dt>processing_time </dt> + <dd class="description">Time the job was processed</dd> +<dt>size </dt> + <dd class="description">Size in kilobytes</dd> +<dt>state </dt> + <dd class="description">Job state</dd> +<dt>title </dt> + <dd class="description">Title/job name</dd> +<dt>user </dt> + <dd class="description">User that submitted the job</dd> +</dl> +<h3 class="struct"><a id="cups_lang_s">cups_lang_s</a></h3> + <p class="description">Language Cache Structure</p> +<p class="code">struct cups_lang_s {<br> +    <a href="#cups_encoding_t">cups_encoding_t</a> encoding;<br> +    char language[16];<br> +    struct <a href="#cups_lang_s">cups_lang_s</a> *next;<br> +    int used;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>encoding </dt> + <dd class="description">Text encoding</dd> +<dt>language[16] </dt> + <dd class="description">Language/locale name</dd> +<dt>next </dt> + <dd class="description">Next language in cache</dd> +<dt>used </dt> + <dd class="description">Number of times this entry has been used.</dd> +</dl> +<h3 class="struct"><a id="cups_option_s">cups_option_s</a></h3> + <p class="description">Printer Options</p> +<p class="code">struct cups_option_s {<br> +    char *name;<br> +    char *value;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>name </dt> + <dd class="description">Name of option</dd> +<dt>value </dt> + <dd class="description">Value of option</dd> +</dl> +<h3 class="struct"><span class="info"> CUPS 1.6/macOS 10.8 </span><a id="cups_size_s">cups_size_s</a></h3> + <p class="description">Media Size </p> +<p class="code">struct cups_size_s {<br> +    char media[128];<br> +    int width, length, bottom, left, right, top;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>media[128] </dt> + <dd class="description">Media name to use</dd> +<dt>top </dt> + <dd class="description">Top margin in hundredths of +millimeters</dd> +</dl> +<h3 class="struct"><a id="gss_auth_identity">gss_auth_identity</a></h3> + <p class="description">Local functions...</p> +<p class="code">struct gss_auth_identity {<br> +    gss_buffer_t *credentialsRef;<br> +    uint32_t flags;<br> +    char *password;<br> +    char *realm;<br> +    uint32_t type;<br> +    char *username;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>credentialsRef </dt> +<dt>flags </dt> +<dt>password </dt> +<dt>realm </dt> +<dt>type </dt> +<dt>username </dt> +</dl> +<h3 class="struct"><span class="info"> CUPS 1.2/macOS 10.5 </span><a id="http_addrlist_s">http_addrlist_s</a></h3> + <p class="description">Socket address list, which is +used to enumerate all of the +addresses that are associated +with a hostname. </p> +<p class="code">struct http_addrlist_s {<br> +    <a href="#http_addr_t">http_addr_t</a> addr;<br> +    struct <a href="#http_addrlist_s">http_addrlist_s</a> *next;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>addr </dt> + <dd class="description">Address</dd> +<dt>next </dt> + <dd class="description">Pointer to next address in list</dd> +</dl> +<h3 class="struct"><span class="info"> CUPS 1.5/macOS 10.7 </span><a id="http_credential_s">http_credential_s</a></h3> + <p class="description">HTTP credential data </p> +<p class="code">struct http_credential_s {<br> +    void *data;<br> +    size_t datalen;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>data </dt> + <dd class="description">Pointer to credential data</dd> +<dt>datalen </dt> + <dd class="description">Credential length</dd> +</dl> +<h3 class="struct"><a id="pollfd">pollfd</a></h3> + <p class="description">User data (unused)</p> +<p class="code">struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {<br> +    void) context;<br> +    void) timeout;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>context </dt> +<dt>timeout </dt> +</dl> +<h3 class="struct"><a id="pwg_map_s">pwg_map_s</a></h3> + <p class="description">Map element - PPD to/from PWG</p> +<p class="code">struct pwg_map_s {<br> +    char *pwg, *ppd;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>ppd </dt> + <dd class="description">PPD option keyword</dd> +</dl> +<h3 class="struct"><a id="pwg_media_s">pwg_media_s</a></h3> + <p class="description">Common media size data</p> +<p class="code">struct pwg_media_s {<br> +    int width, length;<br> +    const char *pwg, *legacy, *ppd;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>length </dt> + <dd class="description">Length in 2540ths</dd> +<dt>ppd </dt> + <dd class="description">Standard Adobe PPD name</dd> +</dl> +<h3 class="struct"><a id="pwg_size_s">pwg_size_s</a></h3> + <p class="description">Size element - PPD to/from PWG</p> +<p class="code">struct pwg_size_s {<br> +    <a href="#pwg_map_t">pwg_map_t</a> map;<br> +    int width, length, left, bottom, right, top;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>map </dt> + <dd class="description">Map element</dd> +<dt>top </dt> + <dd class="description">Top margin in 2540ths</dd> +</dl> + <h2 class="title"><a id="VARIABLES">Variables</a></h2> + <h3 class="variable"><a id="CF_RETURNS_RETAINED">CF_RETURNS_RETAINED</a></h3> + <p class="description">Get the Apple language identifier associated with a +locale ID.</p> + <p class="code">const char *locale)CF_RETURNS_RETAINED;</p> + <h3 class="variable"><a id="environ">environ</a></h3> + <p class="description">Constants, very secure stuff...</p> + <p class="code">extern char **environ;</p> + <h2 class="title"><a id="ENUMERATIONS">Constants</a></h2> + <h3 class="enumeration"><a id="cups_encoding_e">cups_encoding_e</a></h3> + <p class="description">Language Encodings</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>CUPS_EUC_CN </dt> + <dd class="description">EUC Simplified Chinese</dd> + <dt>CUPS_EUC_JP </dt> + <dd class="description">EUC Japanese</dd> + <dt>CUPS_EUC_KR </dt> + <dd class="description">EUC Korean</dd> + <dt>CUPS_EUC_TW </dt> + <dd class="description">EUC Traditional Chinese</dd> + <dt>CUPS_ISO8859_1 </dt> + <dd class="description">ISO-8859-1</dd> + <dt>CUPS_ISO8859_10 </dt> + <dd class="description">ISO-8859-10</dd> + <dt>CUPS_ISO8859_11 </dt> + <dd class="description">ISO-8859-11</dd> + <dt>CUPS_ISO8859_13 </dt> + <dd class="description">ISO-8859-13</dd> + <dt>CUPS_ISO8859_14 </dt> + <dd class="description">ISO-8859-14</dd> + <dt>CUPS_ISO8859_15 </dt> + <dd class="description">ISO-8859-15</dd> + <dt>CUPS_ISO8859_16 </dt> + <dd class="description">ISO-8859-16</dd> + <dt>CUPS_ISO8859_2 </dt> + <dd class="description">ISO-8859-2</dd> + <dt>CUPS_ISO8859_3 </dt> + <dd class="description">ISO-8859-3</dd> + <dt>CUPS_ISO8859_4 </dt> + <dd class="description">ISO-8859-4</dd> + <dt>CUPS_ISO8859_5 </dt> + <dd class="description">ISO-8859-5</dd> + <dt>CUPS_ISO8859_6 </dt> + <dd class="description">ISO-8859-6</dd> + <dt>CUPS_ISO8859_7 </dt> + <dd class="description">ISO-8859-7</dd> + <dt>CUPS_ISO8859_8 </dt> + <dd class="description">ISO-8859-8</dd> + <dt>CUPS_ISO8859_9 </dt> + <dd class="description">ISO-8859-9</dd> + <dt>CUPS_JIS_X0213 </dt> + <dd class="description">JIS X0213 aka Shift JIS</dd> + <dt>CUPS_KOI8_R </dt> + <dd class="description">KOI-8-R</dd> + <dt>CUPS_KOI8_U </dt> + <dd class="description">KOI-8-U</dd> + <dt>CUPS_MAC_ROMAN </dt> + <dd class="description">MacRoman</dd> + <dt>CUPS_US_ASCII </dt> + <dd class="description">US ASCII</dd> + <dt>CUPS_UTF8 </dt> + <dd class="description">UTF-8</dd> + <dt>CUPS_WINDOWS_1250 </dt> + <dd class="description">CP-1250</dd> + <dt>CUPS_WINDOWS_1251 </dt> + <dd class="description">CP-1251</dd> + <dt>CUPS_WINDOWS_1252 </dt> + <dd class="description">CP-1252</dd> + <dt>CUPS_WINDOWS_1253 </dt> + <dd class="description">CP-1253</dd> + <dt>CUPS_WINDOWS_1254 </dt> + <dd class="description">CP-1254</dd> + <dt>CUPS_WINDOWS_1255 </dt> + <dd class="description">CP-1255</dd> + <dt>CUPS_WINDOWS_1256 </dt> + <dd class="description">CP-1256</dd> + <dt>CUPS_WINDOWS_1257 </dt> + <dd class="description">CP-1257</dd> + <dt>CUPS_WINDOWS_1258 </dt> + <dd class="description">CP-1258</dd> + <dt>CUPS_WINDOWS_1361 </dt> + <dd class="description">Korean Johab</dd> + <dt>CUPS_WINDOWS_874 </dt> + <dd class="description">CP-874</dd> + <dt>CUPS_WINDOWS_932 </dt> + <dd class="description">Japanese JIS X0208-1990</dd> + <dt>CUPS_WINDOWS_936 </dt> + <dd class="description">Simplified Chinese GB 2312-80</dd> + <dt>CUPS_WINDOWS_949 </dt> + <dd class="description">Korean KS C5601-1992</dd> + <dt>CUPS_WINDOWS_950 </dt> + <dd class="description">Traditional Chinese Big Five</dd> +</dl> + <h3 class="enumeration"><a id="cups_ptype_e">cups_ptype_e</a></h3> + <p class="description">Printer type/capability bit +constants</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Printer requires authentication +</dd> + <dt>CUPS_PRINTER_BIND </dt> + <dd class="description">Can bind output</dd> + <dt>CUPS_PRINTER_BW </dt> + <dd class="description">Can do B&W printing</dd> + <dt>CUPS_PRINTER_CLASS </dt> + <dd class="description">Printer class</dd> + <dt>CUPS_PRINTER_COLLATE </dt> + <dd class="description">Can quickly collate copies</dd> + <dt>CUPS_PRINTER_COLOR </dt> + <dd class="description">Can do color printing</dd> + <dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Printer supports maintenance commands +</dd> + <dt>CUPS_PRINTER_COPIES </dt> + <dd class="description">Can do copies in hardware</dd> + <dt>CUPS_PRINTER_COVER </dt> + <dd class="description">Can cover output</dd> + <dt>CUPS_PRINTER_DEFAULT </dt> + <dd class="description">Default printer on network</dd> + <dt>CUPS_PRINTER_DELETE <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Delete printer +</dd> + <dt>CUPS_PRINTER_DUPLEX </dt> + <dd class="description">Can do two-sided printing</dd> + <dt>CUPS_PRINTER_FAX </dt> + <dd class="description">Fax queue</dd> + <dt>CUPS_PRINTER_LARGE </dt> + <dd class="description">Can print on D/E/A1/A0-size media</dd> + <dt>CUPS_PRINTER_LOCAL </dt> + <dd class="description">Local printer or class</dd> + <dt>CUPS_PRINTER_MEDIUM </dt> + <dd class="description">Can print on Tabloid/B/C/A3/A2-size media</dd> + <dt>CUPS_PRINTER_MFP <span class="info"> CUPS 1.4/macOS 10.6 </span></dt> + <dd class="description">Printer with scanning capabilities +</dd> + <dt>CUPS_PRINTER_NOT_SHARED <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Printer is not shared +</dd> + <dt>CUPS_PRINTER_PUNCH </dt> + <dd class="description">Can punch output</dd> + <dt>CUPS_PRINTER_REJECTING </dt> + <dd class="description">Printer is rejecting jobs</dd> + <dt>CUPS_PRINTER_REMOTE </dt> + <dd class="description">Remote printer or class</dd> + <dt>CUPS_PRINTER_SCANNER <span class="info"> CUPS 1.4/macOS 10.6 </span></dt> + <dd class="description">Scanner-only device +</dd> + <dt>CUPS_PRINTER_SMALL </dt> + <dd class="description">Can print on Letter/Legal/A4-size media</dd> + <dt>CUPS_PRINTER_SORT </dt> + <dd class="description">Can sort output</dd> + <dt>CUPS_PRINTER_STAPLE </dt> + <dd class="description">Can staple output</dd> + <dt>CUPS_PRINTER_VARIABLE </dt> + <dd class="description">Can print on rolls and custom-size media</dd> +</dl> + <h3 class="enumeration"><a id="http_auth_e">http_auth_e</a></h3> + <p class="description">HTTP authentication types</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>HTTP_AUTH_BASIC </dt> + <dd class="description">Basic authentication in use</dd> + <dt>HTTP_AUTH_MD5 </dt> + <dd class="description">Digest authentication in use</dd> + <dt>HTTP_AUTH_MD5_INT </dt> + <dd class="description">Digest authentication in use for body</dd> + <dt>HTTP_AUTH_MD5_SESS </dt> + <dd class="description">MD5-session authentication in use</dd> + <dt>HTTP_AUTH_MD5_SESS_INT </dt> + <dd class="description">MD5-session authentication in use for body</dd> + <dt>HTTP_AUTH_NEGOTIATE <span class="info"> CUPS 1.3/macOS 10.5 </span></dt> + <dd class="description">GSSAPI authentication in use </dd> + <dt>HTTP_AUTH_NONE </dt> + <dd class="description">No authentication in use</dd> +</dl> + <h3 class="enumeration"><a id="http_encoding_e">http_encoding_e</a></h3> + <p class="description">HTTP transfer encoding values</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>HTTP_ENCODING_CHUNKED </dt> + <dd class="description">Data is chunked</dd> + <dt>HTTP_ENCODING_FIELDS </dt> + <dd class="description">Sending HTTP fields</dd> + <dt>HTTP_ENCODING_LENGTH </dt> + <dd class="description">Data is sent with Content-Length</dd> +</dl> + <h3 class="enumeration"><a id="http_encryption_e">http_encryption_e</a></h3> + <p class="description">HTTP encryption values</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>HTTP_ENCRYPTION_ALWAYS </dt> + <dd class="description">Always encrypt (SSL)</dd> + <dt>HTTP_ENCRYPTION_IF_REQUESTED </dt> + <dd class="description">Encrypt if requested (TLS upgrade)</dd> + <dt>HTTP_ENCRYPTION_NEVER </dt> + <dd class="description">Never encrypt</dd> + <dt>HTTP_ENCRYPTION_REQUIRED </dt> + <dd class="description">Encryption is required (TLS upgrade)</dd> +</dl> + <h3 class="enumeration"><a id="http_field_e">http_field_e</a></h3> + <p class="description">HTTP field names</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>HTTP_FIELD_ACCEPT_ENCODING <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> + <dd class="description">Accepting-Encoding field </dd> + <dt>HTTP_FIELD_ACCEPT_LANGUAGE </dt> + <dd class="description">Accept-Language field</dd> + <dt>HTTP_FIELD_ACCEPT_RANGES </dt> + <dd class="description">Accept-Ranges field</dd> + <dt>HTTP_FIELD_ALLOW <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> + <dd class="description">Allow field </dd> + <dt>HTTP_FIELD_AUTHORIZATION </dt> + <dd class="description">Authorization field</dd> + <dt>HTTP_FIELD_CONNECTION </dt> + <dd class="description">Connection field</dd> + <dt>HTTP_FIELD_CONTENT_ENCODING </dt> + <dd class="description">Content-Encoding field</dd> + <dt>HTTP_FIELD_CONTENT_LANGUAGE </dt> + <dd class="description">Content-Language field</dd> + <dt>HTTP_FIELD_CONTENT_LENGTH </dt> + <dd class="description">Content-Length field</dd> + <dt>HTTP_FIELD_CONTENT_LOCATION </dt> + <dd class="description">Content-Location field</dd> + <dt>HTTP_FIELD_CONTENT_MD5 </dt> + <dd class="description">Content-MD5 field</dd> + <dt>HTTP_FIELD_CONTENT_RANGE </dt> + <dd class="description">Content-Range field</dd> + <dt>HTTP_FIELD_CONTENT_TYPE </dt> + <dd class="description">Content-Type field</dd> + <dt>HTTP_FIELD_CONTENT_VERSION </dt> + <dd class="description">Content-Version field</dd> + <dt>HTTP_FIELD_DATE </dt> + <dd class="description">Date field</dd> + <dt>HTTP_FIELD_HOST </dt> + <dd class="description">Host field</dd> + <dt>HTTP_FIELD_IF_MODIFIED_SINCE </dt> + <dd class="description">If-Modified-Since field</dd> + <dt>HTTP_FIELD_IF_UNMODIFIED_SINCE </dt> + <dd class="description">If-Unmodified-Since field</dd> + <dt>HTTP_FIELD_KEEP_ALIVE </dt> + <dd class="description">Keep-Alive field</dd> + <dt>HTTP_FIELD_LAST_MODIFIED </dt> + <dd class="description">Last-Modified field</dd> + <dt>HTTP_FIELD_LINK </dt> + <dd class="description">Link field</dd> + <dt>HTTP_FIELD_LOCATION </dt> + <dd class="description">Location field</dd> + <dt>HTTP_FIELD_MAX </dt> + <dd class="description">Maximum field index</dd> + <dt>HTTP_FIELD_RANGE </dt> + <dd class="description">Range field</dd> + <dt>HTTP_FIELD_REFERER </dt> + <dd class="description">Referer field</dd> + <dt>HTTP_FIELD_RETRY_AFTER </dt> + <dd class="description">Retry-After field</dd> + <dt>HTTP_FIELD_SERVER <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> + <dd class="description">Server field </dd> + <dt>HTTP_FIELD_TRANSFER_ENCODING </dt> + <dd class="description">Transfer-Encoding field</dd> + <dt>HTTP_FIELD_UNKNOWN </dt> + <dd class="description">Unknown field</dd> + <dt>HTTP_FIELD_UPGRADE </dt> + <dd class="description">Upgrade field</dd> + <dt>HTTP_FIELD_USER_AGENT </dt> + <dd class="description">User-Agent field</dd> + <dt>HTTP_FIELD_WWW_AUTHENTICATE </dt> + <dd class="description">WWW-Authenticate field</dd> +</dl> + <h3 class="enumeration"><a id="http_keepalive_e">http_keepalive_e</a></h3> + <p class="description">HTTP keep-alive values</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>HTTP_KEEPALIVE_OFF </dt> + <dd class="description">No keep alive support</dd> + <dt>HTTP_KEEPALIVE_ON </dt> + <dd class="description">Use keep alive</dd> +</dl> + <h3 class="enumeration"><a id="http_state_e">http_state_e</a></h3> + <p class="description">HTTP state values; states +are server-oriented...</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>HTTP_STATE_CONNECT </dt> + <dd class="description">CONNECT command, waiting for blank line</dd> + <dt>HTTP_STATE_DELETE </dt> + <dd class="description">DELETE command, waiting for blank line</dd> + <dt>HTTP_STATE_ERROR </dt> + <dd class="description">Error on socket</dd> + <dt>HTTP_STATE_GET </dt> + <dd class="description">GET command, waiting for blank line</dd> + <dt>HTTP_STATE_GET_SEND </dt> + <dd class="description">GET command, sending data</dd> + <dt>HTTP_STATE_HEAD </dt> + <dd class="description">HEAD command, waiting for blank line</dd> + <dt>HTTP_STATE_OPTIONS </dt> + <dd class="description">OPTIONS command, waiting for blank line</dd> + <dt>HTTP_STATE_POST </dt> + <dd class="description">POST command, waiting for blank line</dd> + <dt>HTTP_STATE_POST_RECV </dt> + <dd class="description">POST command, receiving data</dd> + <dt>HTTP_STATE_POST_SEND </dt> + <dd class="description">POST command, sending data</dd> + <dt>HTTP_STATE_PUT </dt> + <dd class="description">PUT command, waiting for blank line</dd> + <dt>HTTP_STATE_PUT_RECV </dt> + <dd class="description">PUT command, receiving data</dd> + <dt>HTTP_STATE_STATUS </dt> + <dd class="description">Command complete, sending status</dd> + <dt>HTTP_STATE_TRACE </dt> + <dd class="description">TRACE command, waiting for blank line</dd> + <dt>HTTP_STATE_UNKNOWN_METHOD <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> + <dd class="description">Unknown request method, waiting for blank line </dd> + <dt>HTTP_STATE_UNKNOWN_VERSION <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> + <dd class="description">Unknown request method, waiting for blank line </dd> + <dt>HTTP_STATE_WAITING </dt> + <dd class="description">Waiting for command</dd> +</dl> + <h3 class="enumeration"><a id="http_status_e">http_status_e</a></h3> + <p class="description">HTTP status codes</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>HTTP_STATUS_ACCEPTED </dt> + <dd class="description">DELETE command was successful</dd> + <dt>HTTP_STATUS_BAD_GATEWAY </dt> + <dd class="description">Bad gateway</dd> + <dt>HTTP_STATUS_BAD_REQUEST </dt> + <dd class="description">Bad request</dd> + <dt>HTTP_STATUS_CONFLICT </dt> + <dd class="description">Request is self-conflicting</dd> + <dt>HTTP_STATUS_CONTINUE </dt> + <dd class="description">Everything OK, keep going...</dd> + <dt>HTTP_STATUS_CREATED </dt> + <dd class="description">PUT command was successful</dd> + <dt>HTTP_STATUS_CUPS_AUTHORIZATION_CANCELED <span class="info"> CUPS 1.4 </span></dt> + <dd class="description">User canceled authorization </dd> + <dt>HTTP_STATUS_CUPS_PKI_ERROR <span class="info"> CUPS 1.5/macOS 10.7 </span></dt> + <dd class="description">Error negotiating a secure connection </dd> + <dt>HTTP_STATUS_ERROR </dt> + <dd class="description">An error response from httpXxxx()</dd> + <dt>HTTP_STATUS_EXPECTATION_FAILED </dt> + <dd class="description">The expectation given in an Expect header field was not met</dd> + <dt>HTTP_STATUS_FORBIDDEN </dt> + <dd class="description">Forbidden to access this URI</dd> + <dt>HTTP_STATUS_GATEWAY_TIMEOUT </dt> + <dd class="description">Gateway connection timed out</dd> + <dt>HTTP_STATUS_GONE </dt> + <dd class="description">Server has gone away</dd> + <dt>HTTP_STATUS_LENGTH_REQUIRED </dt> + <dd class="description">A content length or encoding is required</dd> + <dt>HTTP_STATUS_METHOD_NOT_ALLOWED </dt> + <dd class="description">Method is not allowed</dd> + <dt>HTTP_STATUS_MOVED_PERMANENTLY </dt> + <dd class="description">Document has moved permanently</dd> + <dt>HTTP_STATUS_MOVED_TEMPORARILY </dt> + <dd class="description">Document has moved temporarily</dd> + <dt>HTTP_STATUS_MULTIPLE_CHOICES </dt> + <dd class="description">Multiple files match request</dd> + <dt>HTTP_STATUS_NONE <span class="info"> CUPS 1.7/macOS 10.9 </span></dt> + <dd class="description">No Expect value </dd> + <dt>HTTP_STATUS_NOT_ACCEPTABLE </dt> + <dd class="description">Not Acceptable</dd> + <dt>HTTP_STATUS_NOT_AUTHORITATIVE </dt> + <dd class="description">Information isn't authoritative</dd> + <dt>HTTP_STATUS_NOT_FOUND </dt> + <dd class="description">URI was not found</dd> + <dt>HTTP_STATUS_NOT_IMPLEMENTED </dt> + <dd class="description">Feature not implemented</dd> + <dt>HTTP_STATUS_NOT_MODIFIED </dt> + <dd class="description">File not modified</dd> + <dt>HTTP_STATUS_NOT_SUPPORTED </dt> + <dd class="description">HTTP version not supported</dd> + <dt>HTTP_STATUS_NO_CONTENT </dt> + <dd class="description">Successful command, no new data</dd> + <dt>HTTP_STATUS_OK </dt> + <dd class="description">OPTIONS/GET/HEAD/POST/TRACE command was successful</dd> + <dt>HTTP_STATUS_PARTIAL_CONTENT </dt> + <dd class="description">Only a partial file was received/sent</dd> + <dt>HTTP_STATUS_PAYMENT_REQUIRED </dt> + <dd class="description">Payment required</dd> + <dt>HTTP_STATUS_PRECONDITION </dt> + <dd class="description">Precondition failed</dd> + <dt>HTTP_STATUS_PROXY_AUTHENTICATION </dt> + <dd class="description">Proxy Authentication is Required</dd> + <dt>HTTP_STATUS_REQUESTED_RANGE </dt> + <dd class="description">The requested range is not satisfiable</dd> + <dt>HTTP_STATUS_REQUEST_TIMEOUT </dt> + <dd class="description">Request timed out</dd> + <dt>HTTP_STATUS_REQUEST_TOO_LARGE </dt> + <dd class="description">Request entity too large</dd> + <dt>HTTP_STATUS_RESET_CONTENT </dt> + <dd class="description">Content was reset/recreated</dd> + <dt>HTTP_STATUS_SEE_OTHER </dt> + <dd class="description">See this other link...</dd> + <dt>HTTP_STATUS_SERVER_ERROR </dt> + <dd class="description">Internal server error</dd> + <dt>HTTP_STATUS_SERVICE_UNAVAILABLE </dt> + <dd class="description">Service is unavailable</dd> + <dt>HTTP_STATUS_SWITCHING_PROTOCOLS </dt> + <dd class="description">HTTP upgrade to TLS/SSL</dd> + <dt>HTTP_STATUS_UNAUTHORIZED </dt> + <dd class="description">Unauthorized to access host</dd> + <dt>HTTP_STATUS_UNSUPPORTED_MEDIATYPE </dt> + <dd class="description">The requested media type is unsupported</dd> + <dt>HTTP_STATUS_UPGRADE_REQUIRED </dt> + <dd class="description">Upgrade to SSL/TLS required</dd> + <dt>HTTP_STATUS_URI_TOO_LONG </dt> + <dd class="description">URI too long</dd> + <dt>HTTP_STATUS_USE_PROXY </dt> + <dd class="description">Must use a proxy to access this URI</dd> +</dl> + <h3 class="enumeration"><a id="http_trust_e"><span class="info"> CUPS 2.0/OS 10.10 </span>http_trust_e</a></h3> + <p class="description">Level of trust for credentials </p> + <h4 class="constants">Constants</h4> + <dl> + <dt>HTTP_TRUST_CHANGED </dt> + <dd class="description">Credentials have changed</dd> + <dt>HTTP_TRUST_EXPIRED </dt> + <dd class="description">Credentials are expired</dd> + <dt>HTTP_TRUST_INVALID </dt> + <dd class="description">Credentials are invalid</dd> + <dt>HTTP_TRUST_OK </dt> + <dd class="description">Credentials are OK/trusted</dd> + <dt>HTTP_TRUST_RENEWED </dt> + <dd class="description">Credentials have been renewed</dd> + <dt>HTTP_TRUST_UNKNOWN </dt> + <dd class="description">Credentials are unknown/new</dd> +</dl> + <h3 class="enumeration"><a id="http_uri_coding_e">http_uri_coding_e</a></h3> + <p class="description">URI en/decode flags</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>HTTP_URI_CODING_ALL </dt> + <dd class="description">En/decode everything</dd> + <dt>HTTP_URI_CODING_HOSTNAME </dt> + <dd class="description">En/decode the hostname portion</dd> + <dt>HTTP_URI_CODING_MOST </dt> + <dd class="description">En/decode all but the query</dd> + <dt>HTTP_URI_CODING_NONE </dt> + <dd class="description">Don't en/decode anything</dd> + <dt>HTTP_URI_CODING_QUERY </dt> + <dd class="description">En/decode the query portion</dd> + <dt>HTTP_URI_CODING_RESOURCE </dt> + <dd class="description">En/decode the resource portion</dd> + <dt>HTTP_URI_CODING_RFC6874 </dt> + <dd class="description">Use RFC 6874 address format</dd> + <dt>HTTP_URI_CODING_USERNAME </dt> + <dd class="description">En/decode the username portion</dd> +</dl> + <h3 class="enumeration"><a id="http_uri_status_e"><span class="info"> CUPS 1.2 </span>http_uri_status_e</a></h3> + <p class="description">URI separation status </p> + <h4 class="constants">Constants</h4> + <dl> + <dt>HTTP_URI_STATUS_BAD_ARGUMENTS </dt> + <dd class="description">Bad arguments to function (error)</dd> + <dt>HTTP_URI_STATUS_BAD_HOSTNAME </dt> + <dd class="description">Bad hostname in URI (error)</dd> + <dt>HTTP_URI_STATUS_BAD_PORT </dt> + <dd class="description">Bad port number in URI (error)</dd> + <dt>HTTP_URI_STATUS_BAD_RESOURCE </dt> + <dd class="description">Bad resource in URI (error)</dd> + <dt>HTTP_URI_STATUS_BAD_SCHEME </dt> + <dd class="description">Bad scheme in URI (error)</dd> + <dt>HTTP_URI_STATUS_BAD_URI </dt> + <dd class="description">Bad/empty URI (error)</dd> + <dt>HTTP_URI_STATUS_BAD_USERNAME </dt> + <dd class="description">Bad username in URI (error)</dd> + <dt>HTTP_URI_STATUS_MISSING_RESOURCE </dt> + <dd class="description">Missing resource in URI (warning)</dd> + <dt>HTTP_URI_STATUS_MISSING_SCHEME </dt> + <dd class="description">Missing scheme in URI (warning)</dd> + <dt>HTTP_URI_STATUS_OK </dt> + <dd class="description">URI decoded OK</dd> + <dt>HTTP_URI_STATUS_OVERFLOW </dt> + <dd class="description">URI buffer for httpAssembleURI is too small</dd> + <dt>HTTP_URI_STATUS_UNKNOWN_SCHEME </dt> + <dd class="description">Unknown scheme in URI (warning)</dd> +</dl> + <h3 class="enumeration"><a id="http_version_e">http_version_e</a></h3> + <p class="description">HTTP version numbers</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>HTTP_VERSION_0_9 </dt> + <dd class="description">HTTP/0.9</dd> + <dt>HTTP_VERSION_1_0 </dt> + <dd class="description">HTTP/1.0</dd> + <dt>HTTP_VERSION_1_1 </dt> + <dd class="description">HTTP/1.1</dd> +</dl> + <h3 class="enumeration"><a id="ipp_dstate_e">ipp_dstate_e</a></h3> + <p class="description">Document states</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_DOCUMENT_ABORTED </dt> + <dd class="description">Document is aborted</dd> + <dt>IPP_DOCUMENT_CANCELED </dt> + <dd class="description">Document is canceled</dd> + <dt>IPP_DOCUMENT_COMPLETED </dt> + <dd class="description">Document is completed</dd> + <dt>IPP_DOCUMENT_PENDING </dt> + <dd class="description">Document is pending</dd> + <dt>IPP_DOCUMENT_PROCESSING </dt> + <dd class="description">Document is processing</dd> +</dl> + <h3 class="enumeration"><a id="ipp_finishings_e">ipp_finishings_e</a></h3> + <p class="description">Finishings</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_FINISHINGS_BALE </dt> + <dd class="description">Bale (any type)</dd> + <dt>IPP_FINISHINGS_BIND </dt> + <dd class="description">Bind</dd> + <dt>IPP_FINISHINGS_BIND_BOTTOM </dt> + <dd class="description">Bind on bottom</dd> + <dt>IPP_FINISHINGS_BIND_LEFT </dt> + <dd class="description">Bind on left</dd> + <dt>IPP_FINISHINGS_BIND_RIGHT </dt> + <dd class="description">Bind on right</dd> + <dt>IPP_FINISHINGS_BIND_TOP </dt> + <dd class="description">Bind on top</dd> + <dt>IPP_FINISHINGS_BOOKLET_MAKER </dt> + <dd class="description">Fold to make booklet</dd> + <dt>IPP_FINISHINGS_COAT </dt> + <dd class="description">Apply protective liquid or powder coating</dd> + <dt>IPP_FINISHINGS_COVER </dt> + <dd class="description">Add cover</dd> + <dt>IPP_FINISHINGS_CUPS_FOLD_ACCORDIAN </dt> + <dd class="description">Accordian-fold the paper vertically into four sections</dd> + <dt>IPP_FINISHINGS_CUPS_FOLD_DOUBLE_GATE </dt> + <dd class="description">Fold the top and bottom quarters of the paper towards the midline, then fold in half vertically</dd> + <dt>IPP_FINISHINGS_CUPS_FOLD_GATE </dt> + <dd class="description">Fold the top and bottom quarters of the paper towards the midline</dd> + <dt>IPP_FINISHINGS_CUPS_FOLD_HALF </dt> + <dd class="description">Fold the paper in half vertically</dd> + <dt>IPP_FINISHINGS_CUPS_FOLD_HALF_Z </dt> + <dd class="description">Fold the paper in half horizontally, then Z-fold the paper vertically</dd> + <dt>IPP_FINISHINGS_CUPS_FOLD_LEFT_GATE </dt> + <dd class="description">Fold the top quarter of the paper towards the midline</dd> + <dt>IPP_FINISHINGS_CUPS_FOLD_LETTER </dt> + <dd class="description">Fold the paper into three sections vertically; sometimes also known as a C fold</dd> + <dt>IPP_FINISHINGS_CUPS_FOLD_PARALLEL </dt> + <dd class="description">Fold the paper in half vertically two times, yielding four sections</dd> + <dt>IPP_FINISHINGS_CUPS_FOLD_POSTER </dt> + <dd class="description">Fold the paper in half horizontally and vertically; sometimes also called a cross fold</dd> + <dt>IPP_FINISHINGS_CUPS_FOLD_RIGHT_GATE </dt> + <dd class="description">Fold the bottom quarter of the paper towards the midline</dd> + <dt>IPP_FINISHINGS_CUPS_FOLD_Z </dt> + <dd class="description">Fold the paper vertically into three sections, forming a Z</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_BOTTOM_LEFT </dt> + <dd class="description">Punch 1 hole bottom left</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_BOTTOM_RIGHT </dt> + <dd class="description">Punch 1 hole bottom right</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_BOTTOM </dt> + <dd class="description">Punch 2 holes bottom edge</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_LEFT </dt> + <dd class="description">Punch 2 holes left side</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_RIGHT </dt> + <dd class="description">Punch 2 holes right side</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_TOP </dt> + <dd class="description">Punch 2 holes top edge</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_BOTTOM </dt> + <dd class="description">Punch 4 holes bottom edge</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_LEFT </dt> + <dd class="description">Punch 4 holes left side</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_RIGHT </dt> + <dd class="description">Punch 4 holes right side</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_TOP </dt> + <dd class="description">Punch 4 holes top edge</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_TOP_LEFT </dt> + <dd class="description">Punch 1 hole top left</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_TOP_RIGHT </dt> + <dd class="description">Punch 1 hole top right</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_BOTTOM </dt> + <dd class="description">Punch 3 holes bottom edge</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_LEFT </dt> + <dd class="description">Punch 3 holes left side</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_RIGHT </dt> + <dd class="description">Punch 3 holes right side</dd> + <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_TOP </dt> + <dd class="description">Punch 3 holes top edge</dd> + <dt>IPP_FINISHINGS_EDGE_STITCH </dt> + <dd class="description">Stitch along any side</dd> + <dt>IPP_FINISHINGS_EDGE_STITCH_BOTTOM </dt> + <dd class="description">Stitch along bottom edge</dd> + <dt>IPP_FINISHINGS_EDGE_STITCH_LEFT </dt> + <dd class="description">Stitch along left side</dd> + <dt>IPP_FINISHINGS_EDGE_STITCH_RIGHT </dt> + <dd class="description">Stitch along right side</dd> + <dt>IPP_FINISHINGS_EDGE_STITCH_TOP </dt> + <dd class="description">Stitch along top edge</dd> + <dt>IPP_FINISHINGS_FOLD </dt> + <dd class="description">Fold (any type)</dd> + <dt>IPP_FINISHINGS_FOLD_ACCORDIAN </dt> + <dd class="description">Accordian-fold the paper vertically into four sections</dd> + <dt>IPP_FINISHINGS_FOLD_DOUBLE_GATE </dt> + <dd class="description">Fold the top and bottom quarters of the paper towards the midline, then fold in half vertically</dd> + <dt>IPP_FINISHINGS_FOLD_ENGINEERING_Z </dt> + <dd class="description">Fold the paper vertically into two small sections and one larger, forming an elongated Z</dd> + <dt>IPP_FINISHINGS_FOLD_GATE </dt> + <dd class="description">Fold the top and bottom quarters of the paper towards the midline</dd> + <dt>IPP_FINISHINGS_FOLD_HALF </dt> + <dd class="description">Fold the paper in half vertically</dd> + <dt>IPP_FINISHINGS_FOLD_HALF_Z </dt> + <dd class="description">Fold the paper in half horizontally, then Z-fold the paper vertically</dd> + <dt>IPP_FINISHINGS_FOLD_LEFT_GATE </dt> + <dd class="description">Fold the top quarter of the paper towards the midline</dd> + <dt>IPP_FINISHINGS_FOLD_LETTER </dt> + <dd class="description">Fold the paper into three sections vertically; sometimes also known as a C fold</dd> + <dt>IPP_FINISHINGS_FOLD_PARALLEL </dt> + <dd class="description">Fold the paper in half vertically two times, yielding four sections</dd> + <dt>IPP_FINISHINGS_FOLD_POSTER </dt> + <dd class="description">Fold the paper in half horizontally and vertically; sometimes also called a cross fold</dd> + <dt>IPP_FINISHINGS_FOLD_RIGHT_GATE </dt> + <dd class="description">Fold the bottom quarter of the paper towards the midline</dd> + <dt>IPP_FINISHINGS_FOLD_Z </dt> + <dd class="description">Fold the paper vertically into three sections, forming a Z</dd> + <dt>IPP_FINISHINGS_JOG_OFFSET </dt> + <dd class="description">Offset for binding (any type)</dd> + <dt>IPP_FINISHINGS_LAMINATE </dt> + <dd class="description">Apply protective (solid) material</dd> + <dt>IPP_FINISHINGS_NONE </dt> + <dd class="description">No finishing</dd> + <dt>IPP_FINISHINGS_PUNCH </dt> + <dd class="description">Punch (any location/count)</dd> + <dt>IPP_FINISHINGS_PUNCH_BOTTOM_LEFT </dt> + <dd class="description">Punch 1 hole bottom left</dd> + <dt>IPP_FINISHINGS_PUNCH_BOTTOM_RIGHT </dt> + <dd class="description">Punch 1 hole bottom right</dd> + <dt>IPP_FINISHINGS_PUNCH_DUAL_BOTTOM </dt> + <dd class="description">Punch 2 holes bottom edge</dd> + <dt>IPP_FINISHINGS_PUNCH_DUAL_LEFT </dt> + <dd class="description">Punch 2 holes left side</dd> + <dt>IPP_FINISHINGS_PUNCH_DUAL_RIGHT </dt> + <dd class="description">Punch 2 holes right side</dd> + <dt>IPP_FINISHINGS_PUNCH_DUAL_TOP </dt> + <dd class="description">Punch 2 holes top edge</dd> + <dt>IPP_FINISHINGS_PUNCH_MULTIPLE_BOTTOM </dt> + <dd class="description">Pucnh multiple holes bottom edge</dd> + <dt>IPP_FINISHINGS_PUNCH_MULTIPLE_LEFT </dt> + <dd class="description">Pucnh multiple holes left side</dd> + <dt>IPP_FINISHINGS_PUNCH_MULTIPLE_RIGHT </dt> + <dd class="description">Pucnh multiple holes right side</dd> + <dt>IPP_FINISHINGS_PUNCH_MULTIPLE_TOP </dt> + <dd class="description">Pucnh multiple holes top edge</dd> + <dt>IPP_FINISHINGS_PUNCH_QUAD_BOTTOM </dt> + <dd class="description">Punch 4 holes bottom edge</dd> + <dt>IPP_FINISHINGS_PUNCH_QUAD_LEFT </dt> + <dd class="description">Punch 4 holes left side</dd> + <dt>IPP_FINISHINGS_PUNCH_QUAD_RIGHT </dt> + <dd class="description">Punch 4 holes right side</dd> + <dt>IPP_FINISHINGS_PUNCH_QUAD_TOP </dt> + <dd class="description">Punch 4 holes top edge</dd> + <dt>IPP_FINISHINGS_PUNCH_TOP_LEFT </dt> + <dd class="description">Punch 1 hole top left</dd> + <dt>IPP_FINISHINGS_PUNCH_TOP_RIGHT </dt> + <dd class="description">Punch 1 hole top right</dd> + <dt>IPP_FINISHINGS_PUNCH_TRIPLE_BOTTOM </dt> + <dd class="description">Punch 3 holes bottom edge</dd> + <dt>IPP_FINISHINGS_PUNCH_TRIPLE_LEFT </dt> + <dd class="description">Punch 3 holes left side</dd> + <dt>IPP_FINISHINGS_PUNCH_TRIPLE_RIGHT </dt> + <dd class="description">Punch 3 holes right side</dd> + <dt>IPP_FINISHINGS_PUNCH_TRIPLE_TOP </dt> + <dd class="description">Punch 3 holes top edge</dd> + <dt>IPP_FINISHINGS_SADDLE_STITCH </dt> + <dd class="description">Staple interior</dd> + <dt>IPP_FINISHINGS_STAPLE </dt> + <dd class="description">Staple (any location)</dd> + <dt>IPP_FINISHINGS_STAPLE_BOTTOM_LEFT </dt> + <dd class="description">Staple bottom left corner</dd> + <dt>IPP_FINISHINGS_STAPLE_BOTTOM_RIGHT </dt> + <dd class="description">Staple bottom right corner</dd> + <dt>IPP_FINISHINGS_STAPLE_DUAL_BOTTOM </dt> + <dd class="description">Two staples on bottom</dd> + <dt>IPP_FINISHINGS_STAPLE_DUAL_LEFT </dt> + <dd class="description">Two staples on left</dd> + <dt>IPP_FINISHINGS_STAPLE_DUAL_RIGHT </dt> + <dd class="description">Two staples on right</dd> + <dt>IPP_FINISHINGS_STAPLE_DUAL_TOP </dt> + <dd class="description">Two staples on top</dd> + <dt>IPP_FINISHINGS_STAPLE_TOP_LEFT </dt> + <dd class="description">Staple top left corner</dd> + <dt>IPP_FINISHINGS_STAPLE_TOP_RIGHT </dt> + <dd class="description">Staple top right corner</dd> + <dt>IPP_FINISHINGS_STAPLE_TRIPLE_BOTTOM </dt> + <dd class="description">Three staples on bottom</dd> + <dt>IPP_FINISHINGS_STAPLE_TRIPLE_LEFT </dt> + <dd class="description">Three staples on left</dd> + <dt>IPP_FINISHINGS_STAPLE_TRIPLE_RIGHT </dt> + <dd class="description">Three staples on right</dd> + <dt>IPP_FINISHINGS_STAPLE_TRIPLE_TOP </dt> + <dd class="description">Three staples on top</dd> + <dt>IPP_FINISHINGS_TRIM </dt> + <dd class="description">Trim (any type)</dd> + <dt>IPP_FINISHINGS_TRIM_AFTER_COPIES </dt> + <dd class="description">Trim output after each copy</dd> + <dt>IPP_FINISHINGS_TRIM_AFTER_DOCUMENTS </dt> + <dd class="description">Trim output after each document</dd> + <dt>IPP_FINISHINGS_TRIM_AFTER_JOB </dt> + <dd class="description">Trim output after job</dd> + <dt>IPP_FINISHINGS_TRIM_AFTER_PAGES </dt> + <dd class="description">Trim output after each page</dd> +</dl> + <h3 class="enumeration"><a id="ipp_jcollate_e">ipp_jcollate_e</a></h3> + <p class="description">Job collation types</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_JCOLLATE_COLLATED_DOCUMENTS </dt> + <dt>IPP_JCOLLATE_UNCOLLATED_DOCUMENTS </dt> + <dt>IPP_JCOLLATE_UNCOLLATED_SHEETS </dt> +</dl> + <h3 class="enumeration"><a id="ipp_jstate_e">ipp_jstate_e</a></h3> + <p class="description">Job states</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_JSTATE_ABORTED </dt> + <dd class="description">Job has aborted due to error</dd> + <dt>IPP_JSTATE_CANCELED </dt> + <dd class="description">Job has been canceled</dd> + <dt>IPP_JSTATE_COMPLETED </dt> + <dd class="description">Job has completed successfully</dd> + <dt>IPP_JSTATE_HELD </dt> + <dd class="description">Job is held for printing</dd> + <dt>IPP_JSTATE_PENDING </dt> + <dd class="description">Job is waiting to be printed</dd> + <dt>IPP_JSTATE_PROCESSING </dt> + <dd class="description">Job is currently printing</dd> + <dt>IPP_JSTATE_STOPPED </dt> + <dd class="description">Job has been stopped</dd> +</dl> + <h3 class="enumeration"><a id="ipp_op_e">ipp_op_e</a></h3> + <p class="description">IPP operations</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_OP_ACKNOWLEDGE_DOCUMENT </dt> + <dd class="description">Acknowledge-Document</dd> + <dt>IPP_OP_ACKNOWLEDGE_IDENTIFY_PRINTER </dt> + <dd class="description">Acknowledge-Identify-Printer</dd> + <dt>IPP_OP_ACKNOWLEDGE_JOB </dt> + <dd class="description">Acknowledge-Job</dd> + <dt>IPP_OP_ACTIVATE_PRINTER </dt> + <dd class="description">Start a printer</dd> + <dt>IPP_OP_ADD_DOCUMENT_IMAGES </dt> + <dd class="description">Add-Document-Images</dd> + <dt>IPP_OP_CANCEL_CURRENT_JOB </dt> + <dd class="description">Cancel the current job</dd> + <dt>IPP_OP_CANCEL_DOCUMENT </dt> + <dd class="description">Cancel-Document</dd> + <dt>IPP_OP_CANCEL_JOB </dt> + <dd class="description">Cancel a job</dd> + <dt>IPP_OP_CANCEL_JOBS </dt> + <dd class="description">Cancel-Jobs</dd> + <dt>IPP_OP_CANCEL_MY_JOBS </dt> + <dd class="description">Cancel-My-Jobs</dd> + <dt>IPP_OP_CANCEL_SUBSCRIPTION <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Cancel a subscription </dd> + <dt>IPP_OP_CLOSE_JOB </dt> + <dd class="description">Close-Job</dd> + <dt>IPP_OP_CREATE_JOB </dt> + <dd class="description">Create an empty print job</dd> + <dt>IPP_OP_CREATE_JOB_SUBSCRIPTIONS <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Create one of more job subscriptions </dd> + <dt>IPP_OP_CREATE_PRINTER_SUBSCRIPTIONS <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Create one or more printer subscriptions </dd> + <dt>IPP_OP_CUPS_ACCEPT_JOBS </dt> + <dd class="description">Accept new jobs on a printer</dd> + <dt>IPP_OP_CUPS_ADD_MODIFY_CLASS </dt> + <dd class="description">Add or modify a class</dd> + <dt>IPP_OP_CUPS_ADD_MODIFY_PRINTER </dt> + <dd class="description">Add or modify a printer</dd> + <dt>IPP_OP_CUPS_AUTHENTICATE_JOB <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Authenticate a job </dd> + <dt>IPP_OP_CUPS_CREATE_LOCAL_PRINTER <span class="info"> CUPS 2.2 </span></dt> + <dd class="description">Create a local (temporary) printer <dt>IPP_OP_CUPS_DELETE_CLASS </dt> + <dd class="description">Delete a class</dd> + <dt>IPP_OP_CUPS_DELETE_PRINTER </dt> + <dd class="description">Delete a printer</dd> + <dt>IPP_OP_CUPS_GET_CLASSES <span class="info"> DEPRECATED </span></dt> + <dd class="description">Get a list of classes </dd> + <dt>IPP_OP_CUPS_GET_DEFAULT </dt> + <dd class="description">Get the default printer</dd> + <dt>IPP_OP_CUPS_GET_DEVICES <span class="info"> DEPRECATED </span></dt> + <dd class="description">Get a list of supported devices </dd> + <dt>IPP_OP_CUPS_GET_DOCUMENT <span class="info"> CUPS 1.4/macOS 10.6 </span></dt> + <dd class="description">Get a document file </dd> + <dt>IPP_OP_CUPS_GET_PPD <span class="info"> DEPRECATED </span></dt> + <dd class="description">Get a PPD file </dd> + <dt>IPP_OP_CUPS_GET_PPDS <span class="info"> DEPRECATED </span></dt> + <dd class="description">Get a list of supported drivers </dd> + <dt>IPP_OP_CUPS_GET_PRINTERS </dt> + <dd class="description">Get a list of printers and/or classes</dd> + <dt>IPP_OP_CUPS_INVALID </dt> + <dd class="description">Invalid operation name for <a href="#ippOpValue"><code>ippOpValue</code></a></dd> + <dt>IPP_OP_CUPS_MOVE_JOB </dt> + <dd class="description">Move a job to a different printer</dd> + <dt>IPP_OP_CUPS_REJECT_JOBS </dt> + <dd class="description">Reject new jobs on a printer</dd> + <dt>IPP_OP_CUPS_SET_DEFAULT </dt> + <dd class="description">Set the default printer</dd> + <dt>IPP_OP_DEACTIVATE_PRINTER </dt> + <dd class="description">Stop a printer</dd> + <dt>IPP_OP_DELETE_DOCUMENT </dt> + <dd class="description">Delete-Document</dd> + <dt>IPP_OP_DEREGISTER_OUTPUT_DEVICE </dt> + <dd class="description">Deregister-Output-Device</dd> + <dt>IPP_OP_DISABLE_PRINTER </dt> + <dd class="description">Stop a printer</dd> + <dt>IPP_OP_ENABLE_PRINTER </dt> + <dd class="description">Start a printer</dd> + <dt>IPP_OP_FETCH_DOCUMENT </dt> + <dd class="description">Fetch-Document</dd> + <dt>IPP_OP_FETCH_JOB </dt> + <dd class="description">Fetch-Job</dd> + <dt>IPP_OP_GET_DOCUMENTS </dt> + <dd class="description">Get-Documents</dd> + <dt>IPP_OP_GET_DOCUMENT_ATTRIBUTES </dt> + <dd class="description">Get-Document-Attributes</dd> + <dt>IPP_OP_GET_JOBS </dt> + <dd class="description">Get a list of jobs</dd> + <dt>IPP_OP_GET_JOB_ATTRIBUTES </dt> + <dd class="description">Get job attributes</dd> + <dt>IPP_OP_GET_NEXT_DOCUMENT_DATA </dt> + <dd class="description">Get-Next-Document-Data</dd> + <dt>IPP_OP_GET_NOTIFICATIONS <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Get notification events </dd> + <dt>IPP_OP_GET_OUTPUT_DEVICE_ATTRIBUTES </dt> + <dd class="description">Get-Output-Device-Attributes</dd> + <dt>IPP_OP_GET_PRINTER_ATTRIBUTES </dt> + <dd class="description">Get printer attributes</dd> + <dt>IPP_OP_GET_PRINTER_SUPPORTED_VALUES </dt> + <dd class="description">Get supported attribute values</dd> + <dt>IPP_OP_GET_SUBSCRIPTIONS <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Get list of subscriptions </dd> + <dt>IPP_OP_GET_SUBSCRIPTION_ATTRIBUTES <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Get subscription attributes </dd> + <dt>IPP_OP_HOLD_JOB </dt> + <dd class="description">Hold a job for printing</dd> + <dt>IPP_OP_HOLD_NEW_JOBS </dt> + <dd class="description">Hold new jobs</dd> + <dt>IPP_OP_IDENTIFY_PRINTER </dt> + <dd class="description">Identify-Printer</dd> + <dt>IPP_OP_PAUSE_PRINTER </dt> + <dd class="description">Stop a printer</dd> + <dt>IPP_OP_PAUSE_PRINTER_AFTER_CURRENT_JOB </dt> + <dd class="description">Stop printer after the current job</dd> + <dt>IPP_OP_PRINT_JOB </dt> + <dd class="description">Print a single file</dd> + <dt>IPP_OP_PRINT_URI </dt> + <dd class="description">Print a single URL</dd> + <dt>IPP_OP_PROMOTE_JOB </dt> + <dd class="description">Promote a job to print sooner</dd> + <dt>IPP_OP_PURGE_JOBS </dt> + <dd class="description">Cancel all jobs</dd> + <dt>IPP_OP_RELEASE_HELD_NEW_JOBS </dt> + <dd class="description">Release new jobs</dd> + <dt>IPP_OP_RELEASE_JOB </dt> + <dd class="description">Release a job for printing</dd> + <dt>IPP_OP_RENEW_SUBSCRIPTION <span class="info"> CUPS 1.2/macOS 10.5 </span></dt> + <dd class="description">Renew a printer subscription </dd> + <dt>IPP_OP_REPROCESS_JOB </dt> + <dd class="description">Reprint a job</dd> + <dt>IPP_OP_RESTART_JOB </dt> + <dd class="description">Reprint a job</dd> + <dt>IPP_OP_RESTART_PRINTER </dt> + <dd class="description">Restart a printer</dd> + <dt>IPP_OP_RESUBMIT_JOB </dt> + <dd class="description">Resubmit-Job</dd> + <dt>IPP_OP_RESUME_JOB </dt> + <dd class="description">Resume the current job</dd> + <dt>IPP_OP_RESUME_PRINTER </dt> + <dd class="description">Start a printer</dd> + <dt>IPP_OP_SCHEDULE_JOB_AFTER </dt> + <dd class="description">Schedule a job to print after another</dd> + <dt>IPP_OP_SEND_DOCUMENT </dt> + <dd class="description">Add a file to a job</dd> + <dt>IPP_OP_SEND_URI </dt> + <dd class="description">Add a URL to a job</dd> + <dt>IPP_OP_SET_DOCUMENT_ATTRIBUTES </dt> + <dd class="description">Set-Document-Attributes</dd> + <dt>IPP_OP_SET_JOB_ATTRIBUTES </dt> + <dd class="description">Set job attributes</dd> + <dt>IPP_OP_SET_PRINTER_ATTRIBUTES </dt> + <dd class="description">Set printer attributes</dd> + <dt>IPP_OP_SHUTDOWN_PRINTER </dt> + <dd class="description">Turn a printer off</dd> + <dt>IPP_OP_STARTUP_PRINTER </dt> + <dd class="description">Turn a printer on</dd> + <dt>IPP_OP_SUSPEND_CURRENT_JOB </dt> + <dd class="description">Suspend the current job</dd> + <dt>IPP_OP_UPDATE_ACTIVE_JOBS </dt> + <dd class="description">Update-Active-Jobs</dd> + <dt>IPP_OP_UPDATE_DOCUMENT_STATUS </dt> + <dd class="description">Update-Document-Status</dd> + <dt>IPP_OP_UPDATE_JOB_STATUS </dt> + <dd class="description">Update-Job-Status</dd> + <dt>IPP_OP_UPDATE_OUTPUT_DEVICE_ATTRIBUTES </dt> + <dd class="description">Update-Output-Device-Attributes</dd> + <dt>IPP_OP_VALIDATE_DOCUMENT </dt> + <dd class="description">Validate-Document</dd> + <dt>IPP_OP_VALIDATE_JOB </dt> + <dd class="description">Validate job options</dd> +</dl> + <h3 class="enumeration"><a id="ipp_orient_e">ipp_orient_e</a></h3> + <p class="description">Orientation values</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_ORIENT_LANDSCAPE </dt> + <dd class="description">90 degrees counter-clockwise</dd> + <dt>IPP_ORIENT_NONE </dt> + <dd class="description">No rotation</dd> + <dt>IPP_ORIENT_PORTRAIT </dt> + <dd class="description">No rotation</dd> + <dt>IPP_ORIENT_REVERSE_LANDSCAPE </dt> + <dd class="description">90 degrees clockwise</dd> + <dt>IPP_ORIENT_REVERSE_PORTRAIT </dt> + <dd class="description">180 degrees</dd> +</dl> + <h3 class="enumeration"><a id="ipp_pstate_e">ipp_pstate_e</a></h3> + <p class="description">Printer states</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_PSTATE_IDLE </dt> + <dd class="description">Printer is idle</dd> + <dt>IPP_PSTATE_PROCESSING </dt> + <dd class="description">Printer is working</dd> + <dt>IPP_PSTATE_STOPPED </dt> + <dd class="description">Printer is stopped</dd> +</dl> + <h3 class="enumeration"><a id="ipp_quality_e">ipp_quality_e</a></h3> + <p class="description">Qualities</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_QUALITY_DRAFT </dt> + <dd class="description">Draft quality</dd> + <dt>IPP_QUALITY_HIGH </dt> + <dd class="description">High quality</dd> + <dt>IPP_QUALITY_NORMAL </dt> + <dd class="description">Normal quality</dd> +</dl> + <h3 class="enumeration"><a id="ipp_res_e">ipp_res_e</a></h3> + <p class="description">Resolution units</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_RES_PER_CM </dt> + <dd class="description">Pixels per centimeter</dd> + <dt>IPP_RES_PER_INCH </dt> + <dd class="description">Pixels per inch</dd> +</dl> + <h3 class="enumeration"><a id="ipp_state_e">ipp_state_e</a></h3> + <p class="description">IPP states</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_STATE_ATTRIBUTE </dt> + <dd class="description">One or more attributes need to be sent/received</dd> + <dt>IPP_STATE_DATA </dt> + <dd class="description">IPP request data needs to be sent/received</dd> + <dt>IPP_STATE_ERROR </dt> + <dd class="description">An error occurred</dd> + <dt>IPP_STATE_HEADER </dt> + <dd class="description">The request header needs to be sent/received</dd> + <dt>IPP_STATE_IDLE </dt> + <dd class="description">Nothing is happening/request completed</dd> +</dl> + <h3 class="enumeration"><a id="ipp_status_e">ipp_status_e</a></h3> + <p class="description">IPP status codes</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_STATUS_CUPS_INVALID </dt> + <dd class="description">Invalid status name for <a href="#ippErrorValue"><code>ippErrorValue</code></a></dd> + <dt>IPP_STATUS_CUPS_SEE_OTHER </dt> + <dd class="description">cups-see-other</dd> + <dt>IPP_STATUS_ERROR_ACCOUNT_AUTHORIZATION_FAILED </dt> + <dd class="description">client-error-account-authorization-failed</dd> + <dt>IPP_STATUS_ERROR_ACCOUNT_CLOSED </dt> + <dd class="description">client-error-account-closed</dd> + <dt>IPP_STATUS_ERROR_ACCOUNT_INFO_NEEDED </dt> + <dd class="description">client-error-account-info-needed</dd> + <dt>IPP_STATUS_ERROR_ACCOUNT_LIMIT_REACHED </dt> + <dd class="description">client-error-account-limit-reached</dd> + <dt>IPP_STATUS_ERROR_ATTRIBUTES_NOT_SETTABLE </dt> + <dd class="description">client-error-attributes-not-settable</dd> + <dt>IPP_STATUS_ERROR_ATTRIBUTES_OR_VALUES </dt> + <dd class="description">client-error-attributes-or-values-not-supported</dd> + <dt>IPP_STATUS_ERROR_BAD_REQUEST </dt> + <dd class="description">client-error-bad-request</dd> + <dt>IPP_STATUS_ERROR_BUSY </dt> + <dd class="description">server-error-busy</dd> + <dt>IPP_STATUS_ERROR_CHARSET </dt> + <dd class="description">client-error-charset-not-supported</dd> + <dt>IPP_STATUS_ERROR_COMPRESSION_ERROR </dt> + <dd class="description">client-error-compression-error</dd> + <dt>IPP_STATUS_ERROR_COMPRESSION_NOT_SUPPORTED </dt> + <dd class="description">client-error-compression-not-supported</dd> + <dt>IPP_STATUS_ERROR_CONFLICTING </dt> + <dd class="description">client-error-conflicting-attributes</dd> + <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_AUTHORIZATION_FAILED <span class="info"> DEPRECATED </span></dt> + <dd class="description">cups-error-account-authorization-failed </dd> + <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_CLOSED </dt> + <dd class="description">cups-error-account-closed @deprecate@</dd> + <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_INFO_NEEDED <span class="info"> DEPRECATED </span></dt> + <dd class="description">cups-error-account-info-needed </dd> + <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_LIMIT_REACHED <span class="info"> DEPRECATED </span></dt> + <dd class="description">cups-error-account-limit-reached </dd> + <dt>IPP_STATUS_ERROR_CUPS_AUTHENTICATION_CANCELED <span class="info"> CUPS 1.5/macOS 10.7 </span></dt> + <dd class="description">cups-authentication-canceled - Authentication canceled by user </dd> + <dt>IPP_STATUS_ERROR_CUPS_PKI <span class="info"> CUPS 1.5/macOS 10.7 </span></dt> + <dd class="description">cups-pki-error - Error negotiating a secure connection </dd> + <dt>IPP_STATUS_ERROR_CUPS_UPGRADE_REQUIRED </dt> + <dd class="description">cups-upgrade-required - TLS upgrade required</dd> + <dt>IPP_STATUS_ERROR_DEVICE </dt> + <dd class="description">server-error-device-error</dd> + <dt>IPP_STATUS_ERROR_DOCUMENT_ACCESS </dt> + <dd class="description">client-error-document-access-error</dd> + <dt>IPP_STATUS_ERROR_DOCUMENT_FORMAT_ERROR </dt> + <dd class="description">client-error-document-format-error</dd> + <dt>IPP_STATUS_ERROR_DOCUMENT_FORMAT_NOT_SUPPORTED </dt> + <dd class="description">client-error-document-format-not-supported</dd> + <dt>IPP_STATUS_ERROR_DOCUMENT_PASSWORD </dt> + <dd class="description">client-error-document-password-error</dd> + <dt>IPP_STATUS_ERROR_DOCUMENT_PERMISSION </dt> + <dd class="description">client-error-document-permission-error</dd> + <dt>IPP_STATUS_ERROR_DOCUMENT_SECURITY </dt> + <dd class="description">client-error-document-security-error</dd> + <dt>IPP_STATUS_ERROR_DOCUMENT_UNPRINTABLE </dt> + <dd class="description">client-error-document-unprintable-error</dd> + <dt>IPP_STATUS_ERROR_FORBIDDEN </dt> + <dd class="description">client-error-forbidden</dd> + <dt>IPP_STATUS_ERROR_GONE </dt> + <dd class="description">client-error-gone</dd> + <dt>IPP_STATUS_ERROR_IGNORED_ALL_SUBSCRIPTIONS </dt> + <dd class="description">client-error-ignored-all-subscriptions</dd> + <dt>IPP_STATUS_ERROR_INTERNAL </dt> + <dd class="description">server-error-internal-error</dd> + <dt>IPP_STATUS_ERROR_JOB_CANCELED </dt> + <dd class="description">server-error-job-canceled</dd> + <dt>IPP_STATUS_ERROR_MULTIPLE_JOBS_NOT_SUPPORTED </dt> + <dd class="description">server-error-multiple-document-jobs-not-supported</dd> + <dt>IPP_STATUS_ERROR_NOT_ACCEPTING_JOBS </dt> + <dd class="description">server-error-not-accepting-jobs</dd> + <dt>IPP_STATUS_ERROR_NOT_AUTHENTICATED </dt> + <dd class="description">client-error-not-authenticated</dd> + <dt>IPP_STATUS_ERROR_NOT_AUTHORIZED </dt> + <dd class="description">client-error-not-authorized</dd> + <dt>IPP_STATUS_ERROR_NOT_FETCHABLE </dt> + <dd class="description">client-error-not-fetchable</dd> + <dt>IPP_STATUS_ERROR_NOT_FOUND </dt> + <dd class="description">client-error-not-found</dd> + <dt>IPP_STATUS_ERROR_NOT_POSSIBLE </dt> + <dd class="description">client-error-not-possible</dd> + <dt>IPP_STATUS_ERROR_OPERATION_NOT_SUPPORTED </dt> + <dd class="description">server-error-operation-not-supported</dd> + <dt>IPP_STATUS_ERROR_PRINTER_IS_DEACTIVATED </dt> + <dd class="description">server-error-printer-is-deactivated</dd> + <dt>IPP_STATUS_ERROR_REQUEST_ENTITY </dt> + <dd class="description">client-error-request-entity-too-large</dd> + <dt>IPP_STATUS_ERROR_REQUEST_VALUE </dt> + <dd class="description">client-error-request-value-too-long</dd> + <dt>IPP_STATUS_ERROR_SERVICE_UNAVAILABLE </dt> + <dd class="description">server-error-service-unavailable</dd> + <dt>IPP_STATUS_ERROR_TEMPORARY </dt> + <dd class="description">server-error-temporary-error</dd> + <dt>IPP_STATUS_ERROR_TIMEOUT </dt> + <dd class="description">client-error-timeout</dd> + <dt>IPP_STATUS_ERROR_TOO_MANY_DOCUMENTS </dt> + <dd class="description">server-error-too-many-documents</dd> + <dt>IPP_STATUS_ERROR_TOO_MANY_JOBS </dt> + <dd class="description">server-error-too-many-jobs</dd> + <dt>IPP_STATUS_ERROR_TOO_MANY_SUBSCRIPTIONS </dt> + <dd class="description">client-error-too-many-subscriptions</dd> + <dt>IPP_STATUS_ERROR_URI_SCHEME </dt> + <dd class="description">client-error-uri-scheme-not-supported</dd> + <dt>IPP_STATUS_ERROR_VERSION_NOT_SUPPORTED </dt> + <dd class="description">server-error-version-not-supported</dd> + <dt>IPP_STATUS_OK </dt> + <dd class="description">successful-ok</dd> + <dt>IPP_STATUS_OK_CONFLICTING </dt> + <dd class="description">successful-ok-conflicting-attributes</dd> + <dt>IPP_STATUS_OK_EVENTS_COMPLETE </dt> + <dd class="description">successful-ok-events-complete</dd> + <dt>IPP_STATUS_OK_IGNORED_OR_SUBSTITUTED </dt> + <dd class="description">successful-ok-ignored-or-substituted-attributes</dd> + <dt>IPP_STATUS_OK_IGNORED_SUBSCRIPTIONS </dt> + <dd class="description">successful-ok-ignored-subscriptions</dd> + <dt>IPP_STATUS_OK_TOO_MANY_EVENTS </dt> + <dd class="description">successful-ok-too-many-events</dd> +</dl> + <h3 class="enumeration"><a id="ipp_tag_e">ipp_tag_e</a></h3> + <p class="description">Format tags for attributes</p> + <h4 class="constants">Constants</h4> + <dl> + <dt>IPP_TAG_ADMINDEFINE </dt> + <dd class="description">Admin-defined value</dd> + <dt>IPP_TAG_BEGIN_COLLECTION </dt> + <dd class="description">Beginning of collection value</dd> + <dt>IPP_TAG_BOOLEAN </dt> + <dd class="description">Boolean value</dd> + <dt>IPP_TAG_CHARSET </dt> + <dd class="description">Character set value</dd> + <dt>IPP_TAG_CUPS_INVALID </dt> + <dd class="description">Invalid tag name for <a href="#ippTagValue"><code>ippTagValue</code></a></dd> + <dt>IPP_TAG_DATE </dt> + <dd class="description">Date/time value</dd> + <dt>IPP_TAG_DEFAULT </dt> + <dd class="description">Default value</dd> + <dt>IPP_TAG_DELETEATTR </dt> + <dd class="description">Delete-attribute value</dd> + <dt>IPP_TAG_DOCUMENT </dt> + <dd class="description">Document group</dd> + <dt>IPP_TAG_END </dt> + <dd class="description">End-of-attributes</dd> + <dt>IPP_TAG_END_COLLECTION </dt> + <dd class="description">End of collection value</dd> + <dt>IPP_TAG_ENUM </dt> + <dd class="description">Enumeration value</dd> + <dt>IPP_TAG_EVENT_NOTIFICATION </dt> + <dd class="description">Event group</dd> + <dt>IPP_TAG_EXTENSION </dt> + <dd class="description">Extension point for 32-bit tags</dd> + <dt>IPP_TAG_INTEGER </dt> + <dd class="description">Integer value</dd> + <dt>IPP_TAG_JOB </dt> + <dd class="description">Job group</dd> + <dt>IPP_TAG_KEYWORD </dt> + <dd class="description">Keyword value</dd> + <dt>IPP_TAG_LANGUAGE </dt> + <dd class="description">Language value</dd> + <dt>IPP_TAG_MEMBERNAME </dt> + <dd class="description">Collection member name value</dd> + <dt>IPP_TAG_MIMETYPE </dt> + <dd class="description">MIME media type value</dd> + <dt>IPP_TAG_NAME </dt> + <dd class="description">Name value</dd> + <dt>IPP_TAG_NAMELANG </dt> + <dd class="description">Name-with-language value</dd> + <dt>IPP_TAG_NOTSETTABLE </dt> + <dd class="description">Not-settable value</dd> + <dt>IPP_TAG_NOVALUE </dt> + <dd class="description">No-value value</dd> + <dt>IPP_TAG_OPERATION </dt> + <dd class="description">Operation group</dd> + <dt>IPP_TAG_PRINTER </dt> + <dd class="description">Printer group</dd> + <dt>IPP_TAG_RANGE </dt> + <dd class="description">Range value</dd> + <dt>IPP_TAG_RESOLUTION </dt> + <dd class="description">Resolution value</dd> + <dt>IPP_TAG_STRING </dt> + <dd class="description">Octet string value</dd> + <dt>IPP_TAG_SUBSCRIPTION </dt> + <dd class="description">Subscription group</dd> + <dt>IPP_TAG_TEXT </dt> + <dd class="description">Text value</dd> + <dt>IPP_TAG_TEXTLANG </dt> + <dd class="description">Text-with-language value</dd> + <dt>IPP_TAG_UNKNOWN </dt> + <dd class="description">Unknown value</dd> + <dt>IPP_TAG_UNSUPPORTED_GROUP </dt> + <dd class="description">Unsupported attributes group</dd> + <dt>IPP_TAG_UNSUPPORTED_VALUE </dt> + <dd class="description">Unsupported value</dd> + <dt>IPP_TAG_URI </dt> + <dd class="description">URI value</dd> + <dt>IPP_TAG_URISCHEME </dt> + <dd class="description">URI scheme value</dd> + <dt>IPP_TAG_ZERO </dt> + <dd class="description">Zero tag - used for separators</dd> +</dl> + </div> + </body> +</html> diff --git a/packaging/cups.list.in b/packaging/cups.list.in index 132d2b587..27cea18e0 100644 --- a/packaging/cups.list.in +++ b/packaging/cups.list.in @@ -13,7 +13,7 @@ # Product information %product CUPS -%copyright 2007-2016 by Apple Inc. +%copyright 2007-2017` by Apple Inc. %vendor Apple Inc. #%license LICENSE.txt %readme LICENSE.txt @@ -557,6 +557,7 @@ f 0444 root sys $LIBDIR/libcupsimage.a filter/libcupsimage.a d 0755 root sys $DOCDIR/help - f 0444 root sys $DOCDIR/help doc/help/api*.html +f 0444 root sys $DOCDIR/help/cupspm.html doc/help/cupspm.html f 0444 root sys $DOCDIR/help/postscript-driver.html doc/help/postscript-driver.html f 0444 root sys $DOCDIR/help/ppd-compiler.html doc/help/ppd-compiler.html f 0444 root sys $DOCDIR/help/raster-driver.html doc/help/raster-driver.html diff --git a/packaging/cups.spec.in b/packaging/cups.spec.in index 45c40ed1c..55713006b 100644 --- a/packaging/cups.spec.in +++ b/packaging/cups.spec.in @@ -377,6 +377,7 @@ rm -rf $RPM_BUILD_ROOT %dir /usr/share/doc/cups/help /usr/share/doc/cups/help/api*.html +/usr/share/doc/cups/help/cupspm.html /usr/share/doc/cups/help/postscript-driver.html /usr/share/doc/cups/help/ppd-compiler.html /usr/share/doc/cups/help/raster-driver.html |