Michael R Sweet
Copyright © 2007-2017 by Apple Inc. All Rights Reserved.
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 to provide any feedback.
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 <cups/cups.h>
header.
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 http_t
. The CUPS_HTTP_DEFAULT
constant can be used when you want to talk to the CUPS scheduler.
When writing software that uses the "cups" library:
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.
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.
A Destination is a printer or print queue that accepts print jobs. A Print Job is one or more documents that are processed by a destination using options supplied when creating the job. A Document is a file (JPEG image, PDF file, etc.) suitable for printing. An Option controls some aspect of printing, such as the media used. Media is the sheets or roll that is printed on. An Attribute is an option encoded for an Internet Printing Protocol (IPP) request.
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.
The following simple program lists the available destinations:
#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);
}
In Xcode, choose New Project... from the File menu (or press SHIFT+CMD+N), then select the Command Line Tool under the macOS Application project type. Click Next and enter a name for the project, for example "firstcups". Click Next and choose a project directory. The click Next to create the project.
In the project window, click on the Build Phases group and expand the Link Binary with Libraries section. Click +, type "libcups" to show the library, and then double-click on libcups.tbd
.
Finally, click on the main.c
file in the sidebar and copy the example program to the file. Build and run (CMD+R) to see the list of destinations.
From the command-line, create a file called sample.c
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:
gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
./simple
The cups-config
command provides the compiler flags (cups-config --cflags
) and libraries (cups-config --libs
) needed for the local system.
Destinations, which in CUPS represent individual printers or classes (collections or pools) 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 basic information associated with that destination (num_options
and options
).
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.
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_DISCOVERED
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
or CUPS_PRINTER_DISCOVERED
constant passed in the mask
argument.CUPS_PRINTER_REMOTE
: A remote (shared) printer or class.CUPS_PRINTER_DISCOVERED
: An available network 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;
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);
}
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:
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);
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.
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));
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');
}
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);
For example, the following code lists the ready finishing processes:
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.");
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:
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))
{
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.");
You can also enumerate all of the sizes that match a given flags
value using the cupsGetDestMediaByIndex
and cupsGetDestMediaCount
functions:
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);
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);
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);
}
}
Finally, the cupsGetDestMediaDefault
function returns the default media size:
int
cupsGetDestMediaDefault(http_t *http, cups_dest_t *dest,
cups_dinfo_t *dinfo, unsigned flags,
cups_size_t *size);
CUPS provides three functions to get localized versions of options and values: cupsLocalizeDestMedia
, cupsLocalizeDestOption
, and cupsLocalizeDestValue
:
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);
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)
{
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);
Add a destination to the list of destinations.
int cupsAddDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t **dests
);
NULL
for none/primaryNew number of destinations
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.
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.
Use the cupsSaveDests
function to save the updated list of
destinations to the user's lpoptions file.
Add an integer option to an option array.
int cupsAddIntegerOption (
const char *name,
int value,
int num_options,
cups_option_t **options
);
Number of options
New option arrays can be initialized simply by passing 0 for the "num_options" parameter.
Add an option to an option array.
int cupsAddOption (
const char *name,
const char *value,
int num_options,
cups_option_t **options
);
Number of options
New option arrays can be initialized simply by passing 0 for the "num_options" parameter.
Include necessary headers...
ipp_status_t cupsCancelDestJob (
http_t *http,
cups_dest_t *dest,
int job_id
);
Cancel a job on a destination.
The "job_id" is the number returned by cupsCreateDestJob.
Returns IPP_STATUS_OK
on success and
IPP_STATUS_ERRPR_NOT_AUTHORIZED
or
IPP_STATUS_ERROR_FORBIDDEN
on failure.
Check that the option and value are supported by the destination.
int cupsCheckDestSupported (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option,
const char *value
);
1 if supported, 0 otherwise
Returns 1 if supported, 0 otherwise.
Close a job and start printing.
ipp_status_t cupsCloseDestJob (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *info,
int job_id
);
IPP status code
Use when the last call to cupsStartDocument passed 0 for "last_document".
"job_id" is the job ID returned by cupsCreateDestJob. Returns IPP_STATUS_OK
on success.
Connect to the server for a destination.
http_t *cupsConnectDest (
cups_dest_t *dest,
unsigned flags,
int msec,
int *cancel,
char *resource,
size_t resourcesize,
cups_dest_cb_t cb,
void *user_data
);
Connection to server or NULL
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.
Copy a destination.
int cupsCopyDest (
cups_dest_t *dest,
int num_dests,
cups_dest_t **dests
);
New number of destinations
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).
Get conflicts and resolutions for a new option/value pair.
int cupsCopyDestConflicts (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
int num_options,
cups_option_t *options,
const char *new_option,
const char *new_value,
int *num_conflicts,
cups_option_t **conflicts,
int *num_resolved,
cups_option_t **resolved
);
1 if there is a conflict, 0 if none, -1 on error
"num_options" and "options" represent the currently selected options by the
user. "new_option" and "new_value" are the setting the user has just
changed.
Returns 1 if there is a conflict, 0 if there are no conflicts, and -1 if
there was an unrecoverable error such as a resolver loop.
If "num_conflicts" and "conflicts" are not NULL
, they are set to
contain the list of conflicting option/value pairs. Similarly, if
"num_resolved" and "resolved" are not NULL
they will be set to the
list of changes needed to resolve the conflict.
If cupsCopyDestConflicts returns 1 but "num_resolved" and "resolved" are set
to 0 and NULL
, respectively, then the conflict cannot be resolved.
Get the supported values/capabilities for the destination.
cups_dinfo_t *cupsCopyDestInfo (
http_t *http,
cups_dest_t *dest
);
Destination information
The caller is responsible for calling cupsFreeDestInfo
on the return
value. NULL
is returned on error.
Create a job on a destination.
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
);
IPP status code
Returns IPP_STATUS_OK
or IPP_STATUS_OK_SUBST
on success, saving the job ID
in the variable pointed to by "job_id".
Authenticate a request.
int cupsDoAuthentication (
http_t *http,
const char *method,
const char *resource
);
CUPS_HTTP_DEFAULT
0 on success, -1 on error
This function should be called in response to a HTTP_STATUS_UNAUTHORIZED
status, prior to resubmitting your request.
void cupsEncodeOptions (
ipp_t *ipp,
int num_options,
cups_option_t *options
);
Encode printer options into IPP attributes.
This function adds operation, job, and then subscription attributes, in that order. Use the cupsEncodeOptions2() function to add attributes for a single group.
Add the options in the proper groups & order...
void cupsEncodeOptions2 (
ipp_t *ipp,
int num_options,
cups_option_t *options,
ipp_tag_t group_tag
);
Encode printer options into IPP attributes for a group.
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.
Get the current encryption settings.
http_encryption_t cupsEncryption (void);
Encryption settings
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
HTTP_ENCRYPTION_IF_REQUESTED
.
Note: The current encryption setting is tracked separately for each thread
in a program. Multi-threaded programs that override the setting via the
cupsSetEncryption
function need to do so in each thread for the same
setting to be used.
Enumerate available destinations with a callback function.
int cupsEnumDests (
unsigned flags,
int msec,
int *cancel,
cups_ptype_t type,
cups_ptype_t mask,
cups_dest_cb_t cb,
void *user_data
);
1 on success, 0 on failure
Destinations are enumerated from one or more sources. The callback function
receives the user_data
pointer and the destination pointer which can
be used as input to the cupsCopyDest
function. The function must
return 1 to continue enumeration or 0 to stop.
The type
and mask
arguments allow the caller to filter the
destinations that are enumerated. Passing 0 for both will enumerate all
printers. The constant CUPS_PRINTER_DISCOVERED
is used to filter on
destinations that are available but have not yet been added locally.
Enumeration happens on the current thread and does not return until all
destinations have been enumerated or the callback function returns 0.
Find the default value(s) for the given option.
ipp_attribute_t *cupsFindDestDefault (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option
);
Default attribute or NULL
for none
The returned value is an IPP attribute. Use the ippGetBoolean
,
ippGetCollection
, ippGetCount
, ippGetDate
,
ippGetInteger
, ippGetOctetString
, ippGetRange
,
ippGetResolution
, ippGetString
, and ippGetValueTag
functions to inspect the default value(s) as needed.
Find the default value(s) for the given option.
ipp_attribute_t *cupsFindDestReady (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option
);
Default attribute or NULL
for none
The returned value is an IPP attribute. Use the ippGetBoolean
,
ippGetCollection
, ippGetCount
, ippGetDate
,
ippGetInteger
, ippGetOctetString
, ippGetRange
,
ippGetResolution
, ippGetString
, and ippGetValueTag
functions to inspect the default value(s) as needed.
Find the default value(s) for the given option.
ipp_attribute_t *cupsFindDestSupported (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option
);
Default attribute or NULL
for none
The returned value is an IPP attribute. Use the ippGetBoolean
,
ippGetCollection
, ippGetCount
, ippGetDate
,
ippGetInteger
, ippGetOctetString
, ippGetRange
,
ippGetResolution
, ippGetString
, and ippGetValueTag
functions to inspect the default value(s) as needed.
Finish the current document.
ipp_status_t cupsFinishDestDocument (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *info
);
Status of document submission
Returns IPP_STATUS_OK
or IPP_STATUS_OK_SUBST
on success.
Find and return the attribute...
void cupsFreeDestInfo (
cups_dinfo_t *dinfo
);
Free destination information obtained using
cupsCopyDestInfo
.
Block
void cupsFreeDests (
int num_dests,
cups_dest_t *dests
);
Free the memory used by the list of destinations.
Printer resource
void cupsFreeJobs (
int num_jobs,
cups_job_t *jobs
);
Free memory used by job data.
Match found; free the old value...
void cupsFreeOptions (
int num_options,
cups_option_t *options
);
Free all memory used by options.
Get the named destination from the list.
cups_dest_t *cupsGetDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t *dests
);
NULL
for the default destinationNULL
Destination pointer or NULL
Use the cupsGetDests
or cupsGetDests2
functions to get a
list of supported destinations for the current user.
Get a media name, dimension, and margins for a specific size.
int cupsGetDestMediaByIndex (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
int n,
unsigned flags,
cups_size_t *size
);
1 on success, 0 on failure
The flags
parameter determines which set of media are indexed. For
example, passing CUPS_MEDIA_FLAGS_BORDERLESS
will get the Nth
borderless size supported by the printer.
Get media names, dimensions, and margins.
int cupsGetDestMediaByName (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *media,
unsigned flags,
cups_size_t *size
);
1 on match, 0 on failure
The "media" string is a PWG media name. "Flags" provides some matching
guidance (multiple flags can be combined):
CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
size amongst the "ready" media.
The matching result (if any) is returned in the "cups_size_t" structure.
Returns 1 when there is a match and 0 if there is not a match.
Get media names, dimensions, and margins.
int cupsGetDestMediaBySize (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
int width,
int length,
unsigned flags,
cups_size_t *size
);
1 on match, 0 on failure
"Width" and "length" are the dimensions in hundredths of millimeters.
"Flags" provides some matching guidance (multiple flags can be combined):
CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
size amongst the "ready" media.
The matching result (if any) is returned in the "cups_size_t" structure.
Returns 1 when there is a match and 0 if there is not a match.
Get the number of sizes supported by a destination.
int cupsGetDestMediaCount (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
unsigned flags
);
Number of sizes
The flags
parameter determines the set of media sizes that are
counted. For example, passing CUPS_MEDIA_FLAGS_BORDERLESS
will return
the number of borderless sizes.
Get the default size for a destination.
int cupsGetDestMediaDefault (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
unsigned flags,
cups_size_t *size
);
1 on success, 0 on failure
The flags
parameter determines which default size is returned. For
example, passing CUPS_MEDIA_FLAGS_BORDERLESS
will return the default
borderless size, typically US Letter or A4, but sometimes 4x6 photo media.
Get a destination associated with a URI.
cups_dest_t *cupsGetDestWithURI (
const char *name,
const char *uri
);
NULL
Destination or NULL
"name" is the desired name for the printer. If NULL
, a name will be
created using the URI.
"uri" is the "ipp" or "ipps" URI for the printer.
Get an integer option value.
int cupsGetIntegerOption (
const char *name,
int num_options,
cups_option_t *options
);
Option value or INT_MIN
INT_MIN is returned when the option does not exist, is not an integer, or exceeds the range of values for the "int" type.
Get the jobs from the specified server.
int cupsGetJobs2 (
http_t *http,
cups_job_t **jobs,
const char *name,
int myjobs,
int whichjobs
);
CUPS_HTTP_DEFAULT
NULL
= all destinations, otherwise show jobs for named destinationCUPS_WHICHJOBS_ALL
, CUPS_WHICHJOBS_ACTIVE
, or CUPS_WHICHJOBS_COMPLETED
Number of jobs
A "whichjobs" value of CUPS_WHICHJOBS_ALL
returns all jobs regardless
of state, while CUPS_WHICHJOBS_ACTIVE
returns jobs that are
pending, processing, or held and CUPS_WHICHJOBS_COMPLETED
returns
jobs that are stopped, canceled, aborted, or completed.
Get options for the named destination.
cups_dest_t *cupsGetNamedDest (
http_t *http,
const char *name,
const char *instance
);
CUPS_HTTP_DEFAULT
NULL
for the default destinationNULL
Destination or NULL
This function is optimized for retrieving a single destination and should
be used instead of cupsGetDests
and cupsGetDest
when you either
know the name of the destination or want to print to the default destination.
If NULL
is returned, the destination does not exist or there is no
default destination.
If "http" is CUPS_HTTP_DEFAULT
, the connection to the default print
server will be used.
If "name" is NULL
, the default printer for the current user will be
returned.
The returned destination must be freed using cupsFreeDests
with a
"num_dests" value of 1.
Get an option value.
const char *cupsGetOption (
const char *name,
int num_options,
cups_option_t *options
);
Option value or NULL
Get a password from the user using the advanced password callback.
const char *cupsGetPassword2 (
const char *prompt,
http_t *http,
const char *method,
const char *resource
);
CUPS_HTTP_DEFAULT
Password
Uses the current password callback function. Returns NULL
if the
user does not provide a password.
Note: The current password callback function is tracked separately for each
thread in a program. Multi-threaded programs that override the setting via
the cupsSetPasswordCB
or cupsSetPasswordCB2
functions need to
do so in each thread for the same function to be used.
Return the default language.
cups_lang_t *cupsLangDefault (void);
Language data
Return the character encoding (us-ascii, etc.) for the given language.
const char *cupsLangEncoding (
cups_lang_t *lang
);
Character encoding
Language data
void cupsLangFlush (void);
Flush all language data out of the cache.
Then free the language structure itself...
void cupsLangFree (
cups_lang_t *lang
);
Free language data.
This does not actually free anything; use cupsLangFlush
for that.
Get a language.
cups_lang_t *cupsLangGet (
const char *language
);
Language data
Get the localized string for a destination media size.
const char *cupsLocalizeDestMedia (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
unsigned flags,
cups_size_t *size
);
Localized string
The returned string is stored in the destination information and will become invalid if the destination information is deleted.
Get the localized string for a destination option.
const char *cupsLocalizeDestOption (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option
);
Localized string
The returned string is stored in the destination information and will become invalid if the destination information is deleted.
Get the localized string for a destination option+value pair.
const char *cupsLocalizeDestValue (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option,
const char *value
);
Localized string
The returned string is stored in the destination information and will become invalid if the destination information is deleted.
Make a self-signed certificate and private key pair.
int cupsMakeServerCredentials (
const char *path,
const char *common_name,
int num_alt_names,
const char **alt_names,
time_t expiration_date
);
NULL
for default1 on success, 0 on failure
Return the subject for the given notification message.
char *cupsNotifySubject (
cups_lang_t *lang,
ipp_t *event
);
Subject string or NULL
The returned string must be freed by the caller using free
.
Return the text for the given notification message.
char *cupsNotifyText (
cups_lang_t *lang,
ipp_t *event
);
Message text or NULL
The returned string must be freed by the caller using free
.
Parse options from a command-line argument.
int cupsParseOptions (
const char *arg,
int num_options,
cups_option_t **options
);
Number of options found
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 cupsParseOptions
on the value to extract the
collection attributes.
Remove a destination from the destination list.
int cupsRemoveDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t **dests
);
NULL
New number of destinations
Removing a destination/instance does not delete the class or printer
queue, merely the lpoptions for that destination/instance. Use the
cupsSetDests
or cupsSetDests2
functions to save the new
options for the user.
Remove an option from an option array.
int cupsRemoveOption (
const char *name,
int num_options,
cups_option_t **options
);
New number of options
Return the hostname/address of the current server.
const char *cupsServer (void);
Server name
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.
The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6
address, or a domain socket pathname.
Note: The current server is tracked separately for each thread in a program.
Multi-threaded programs that override the server via the
cupsSetServer
function need to do so in each thread for the same
server to be used.
Pointer to library globals
void cupsSetClientCertCB (
cups_client_cert_cb_t cb,
void *user_data
);
Set the client certificate callback.
Pass NULL
to restore the default callback.
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.
Set the default credentials to be used for SSL/TLS connections.
int cupsSetCredentials (
cups_array_t *credentials
);
Status of call (0 = success)
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.
Remove the destination from the array...
void cupsSetDefaultDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t *dests
);
NULL
Set the default destination.
Loop through the array and set the "is_default" flag for the matching destination...
void cupsSetDests (
int num_dests,
cups_dest_t *dests
);
Save the list of destinations for the default server.
This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.
Save the list of destinations for the specified server.
int cupsSetDests2 (
http_t *http,
int num_dests,
cups_dest_t *dests
);
CUPS_HTTP_DEFAULT
0 on success, -1 on error
This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.
Pointer to library globals
void cupsSetEncryption (
http_encryption_t e
);
Set the encryption preference.
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
HTTP_ENCRYPTION_IF_REQUESTED
.
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.
Pointer to library globals
void cupsSetPasswordCB (
cups_password_cb_t cb
);
Set the password callback for CUPS.
Pass NULL
to restore the default (console) password callback, which
reads the password from the console. Programs should call either this
function or cupsSetPasswordCB2
, as only one callback can be registered
by a program per thread.
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.
Pointer to library globals
void cupsSetPasswordCB2 (
cups_password_cb2_t cb,
void *user_data
);
Set the advanced password callback for CUPS.
Pass NULL
to restore the default (console) password callback, which
reads the password from the console. Programs should call either this
function or cupsSetPasswordCB2
, as only one callback can be registered
by a program per thread.
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.
Pointer to library globals
void cupsSetServer (
const char *server
);
Set the default server name and port.
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 NULL
to restore the
default server name and port.
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.
Pointer to library globals
void cupsSetServerCertCB (
cups_server_cert_cb_t cb,
void *user_data
);
Set the server certificate callback.
Pass NULL
to restore the default callback.
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.
Set the default server credentials.
int cupsSetServerCredentials (
const char *path,
const char *common_name,
int auto_create
);
NULL
for default1 on success, 0 on failure
Note: The server credentials are used by all threads in the running process. This function is threadsafe.
Pointer to library globals
void cupsSetUser (
const char *user
);
Set the default user name.
Pass NULL
to restore the default user name.
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.
Pointer to library globals
void cupsSetUserAgent (
const char *user_agent
);
NULL
Set the default HTTP User-Agent string.
Setting the string to NULL forces the default value containing the CUPS version, IPP version, and operating system version and architecture.
Start a new document.
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
);
Status of document creation
"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
HTTP_CONTINUE
on success.
Return the current user's name.
const char *cupsUser (void);
User name
Note: The current user name is tracked separately for each thread in a
program. Multi-threaded programs that override the user name with the
cupsSetUser
function need to do so in each thread for the same user
name to be used.
Return the default HTTP User-Agent string.
const char *cupsUserAgent (void);
User-Agent string
Accept a new HTTP client connection from the specified listening socket.
http_t *httpAcceptConnection (
int fd,
int blocking
);
HTTP connection or NULL
Allocates and adds a single credential to an array.
int httpAddCredential (
cups_array_t *credentials,
const void *data,
size_t datalen
);
0 on success, -1 on error
Use cupsArrayNew(NULL, NULL)
to create a credentials array.
Check for the "any" address.
int httpAddrAny (
const http_addr_t *addr
);
1 if "any", 0 otherwise
Close a socket created by httpAddrConnect
or
httpAddrListen
.
int httpAddrClose (
http_addr_t *addr,
int fd
);
NULL
0 on success, -1 on failure
Pass NULL
for sockets created with httpAddrConnect
and the
listen address for sockets created with httpAddrListen
. This will
ensure that domain sockets are removed when closed.
Connect to any of the addresses in the list with a timeout and optional cancel.
http_addrlist_t *httpAddrConnect2 (
http_addrlist_t *addrlist,
int *sock,
int msec,
int *cancel
);
Connected address or NULL on failure
Copy an address list.
http_addrlist_t *httpAddrCopyList (
http_addrlist_t *src
);
New address list or NULL
on error
Compare two addresses.
int httpAddrEqual (
const http_addr_t *addr1,
const http_addr_t *addr2
);
1 if equal, 0 if not
Get the address family of an address.
int httpAddrFamily (
http_addr_t *addr
);
Address family
Current list entry
void httpAddrFreeList (
http_addrlist_t *addrlist
);
Free an address list.
Get a list of addresses for a hostname.
http_addrlist_t *httpAddrGetList (
const char *hostname,
int family,
const char *service
);
List of addresses or NULL
Return the length of the address in bytes.
int httpAddrLength (
const http_addr_t *addr
);
Length in bytes
Create a listening socket bound to the specified address and port.
int httpAddrListen (
http_addr_t *addr,
int port
);
Socket or -1 on error
Check for the local loopback address.
int httpAddrLocalhost (
const http_addr_t *addr
);
1 if local host, 0 otherwise
Lookup the hostname associated with the address.
char *httpAddrLookup (
const http_addr_t *addr,
char *name,
int namelen
);
Host name
Get the port number associated with an address.
int httpAddrPort (
http_addr_t *addr
);
Port number
Convert an address to a numeric string.
char *httpAddrString (
const http_addr_t *addr,
char *s,
int slen
);
Numeric address string
Assemble a uniform resource identifier from its components.
http_uri_status_t httpAssembleURI (
http_uri_coding_t encoding,
char *uri,
int urilen,
const char *scheme,
const char *username,
const char *host,
int port,
const char *resource
);
URI status
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.
Assemble a uniform resource identifier from its components with a formatted resource.
http_uri_status_t httpAssembleURIf (
http_uri_coding_t encoding,
char *uri,
int urilen,
const char *scheme,
const char *username,
const char *host,
int port,
const char *resourcef,
...
);
URI status
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.
Assemble a name-based UUID URN conforming to RFC 4122.
char *httpAssembleUUID (
const char *server,
int port,
const char *name,
int number,
char *buffer,
size_t bufsize
);
UUID string
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.
The buffer needs to be at least 46 bytes in size.
Credential data
void httpBlocking (
http_t *http,
int b
);
Set blocking/non-blocking behavior on a connection.
Check to see if there is a pending response from the server.
int httpCheck (
http_t *http
);
0 = no data, 1 = data available
HTTP connection
void httpClearCookie (
http_t *http
);
Clear the cookie value(s).
HTTP connection
void httpClearFields (
http_t *http
);
Clear HTTP request fields.
HTTP connection
void httpClose (
http_t *http
);
Close an HTTP connection.
Compare two sets of X.509 credentials.
int httpCompareCredentials (
cups_array_t *cred1,
cups_array_t *cred2
);
1 if they match, 0 if they do not
Connect to a HTTP server.
http_t *httpConnect2 (
const char *host,
int port,
http_addrlist_t *addrlist,
int family,
http_encryption_t encryption,
int blocking,
int msec,
int *cancel
);
AF_UNSPEC
for anyNew HTTP connection
Copy the credentials associated with the peer in an encrypted connection.
int httpCopyCredentials (
http_t *http,
cups_array_t **credentials
);
Status of call (0 = success)
Return whether the credentials are valid for the given name.
int httpCredentialsAreValidForName (
cups_array_t *credentials,
const char *common_name
);
1 if valid, 0 otherwise
Return the expiration date of the credentials.
time_t httpCredentialsGetExpiration (
cups_array_t *credentials
);
Expiration date of credentials
Return the trust of credentials.
http_trust_t httpCredentialsGetTrust (
cups_array_t *credentials,
const char *common_name
);
Level of trust
Return a string representing the credentials.
size_t httpCredentialsString (
cups_array_t *credentials,
char *buffer,
size_t bufsize
);
NULL
Total size of credentials string
Base64-decode a string.
char *httpDecode64_2 (
char *out,
int *outlen,
const char *in
);
Decoded string
Send a DELETE request to the server.
int httpDelete (
http_t *http,
const char *uri
);
Status of call (0 = success)
Base64-encode a string.
char *httpEncode64_2 (
char *out,
int outlen,
const char *in,
int inlen
);
Encoded string
Set the required encryption on the link.
int httpEncryption (
http_t *http,
http_encryption_t e
);
-1 on error, 0 on success
Get the last error on a connection.
int httpError (
http_t *http
);
Error code (errno) value
Return the HTTP field enumeration value for a field name.
http_field_t httpFieldValue (
const char *name
);
Field index
Looping var
void httpFlush (
http_t *http
);
Flush data from a HTTP connection.
Flush data in write buffer.
int httpFlushWrite (
http_t *http
);
Bytes written or -1 on error
Bytes written
void httpFreeCredentials (
cups_array_t *credentials
);
Free an array of credentials.
Send a GET request to the server.
int httpGet (
http_t *http,
const char *uri
);
Status of call (0 = success)
Get the most recent activity for a connection.
time_t httpGetActivity (
http_t *http
);
Time of last read or write
The return value is the UNIX time of the last read or write.
Get the address of the connected peer of a connection.
http_addr_t *httpGetAddress (
http_t *http
);
Connected address or NULL
Returns NULL
if the socket is currently unconnected.
Get the current authorization string.
char *httpGetAuthString (
http_t *http
);
Authorization string
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.
Get the blocking/non-block state of a connection.
int httpGetBlocking (
http_t *http
);
1 if blocking, 0 if non-blocking
Get a common content encoding, if any, between the client and server.
const char *httpGetContentEncoding (
http_t *http
);
Content-Coding value or
NULL
for the identity
coding.
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.
Get any cookie data from the response.
const char *httpGetCookie (
http_t *http
);
Cookie data or NULL
Get a formatted date/time string from a time value.
const char *httpGetDateString2 (
time_t t,
char *s,
int slen
);
Date/time string
Get a time value from a formatted date/time string.
time_t httpGetDateTime (
const char *s
);
UNIX time
Get the current encryption mode of a connection.
http_encryption_t httpGetEncryption (
http_t *http
);
Current encryption mode
This function returns the encryption mode for the connection. Use the
httpIsEncrypted
function to determine whether a TLS session has
been established.
Get the value of the Expect header, if any.
http_status_t httpGetExpect (
http_t *http
);
Expect: status, if any
Returns HTTP_STATUS_NONE
if there is no Expect header, otherwise
returns the expected HTTP status code, typically HTTP_STATUS_CONTINUE
.
Get the file descriptor associated with a connection.
int httpGetFd (
http_t *http
);
File descriptor or -1 if none
Get a field value from a request/response.
const char *httpGetField (
http_t *http,
http_field_t field
);
Field value
Lookup a hostname or IPv4 address, and return address records for the specified name.
struct hostent *httpGetHostByName (
const char *name
);
Host entry
Get the FQDN for the connection or local system.
const char *httpGetHostname (
http_t *http,
char *s,
int slen
);
FQDN for connection or system
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.
Get the current Keep-Alive state of the connection.
http_keepalive_t httpGetKeepAlive (
http_t *http
);
Keep-Alive state
Get the amount of data remaining from the content-length or transfer-encoding fields.
off_t httpGetLength2 (
http_t *http
);
Content length
This function returns the complete content length, even for content larger than 2^31 - 1.
Get the number of bytes that are buffered for writing.
size_t httpGetPending (
http_t *http
);
Number of bytes buffered
Get the number of bytes that can be read without blocking.
size_t httpGetReady (
http_t *http
);
Number of bytes available
Get the number of remaining bytes in the message body or current chunk.
size_t httpGetRemaining (
http_t *http
);
Remaining bytes
The httpIsChunked
function can be used to determine whether the
message body is chunked or fixed-length.
Get the current state of the HTTP request.
http_state_t httpGetState (
http_t *http
);
HTTP state
Get the status of the last HTTP request.
http_status_t httpGetStatus (
http_t *http
);
HTTP status
Get a sub-field value.
char *httpGetSubField2 (
http_t *http,
http_field_t field,
const char *name,
char *value,
int valuelen
);
Value or NULL
Get the HTTP version at the other end.
http_version_t httpGetVersion (
http_t *http
);
Version number
Get a line of text from a HTTP connection.
char *httpGets (
char *line,
int length,
http_t *http
);
Line or NULL
Send a HEAD request to the server.
int httpHead (
http_t *http,
const char *uri
);
Status of call (0 = success)
URI for head
void httpInitialize (void);
Initialize the HTTP interface library and set the default HTTP proxy (if any).
Report whether a message body is chunked.
int httpIsChunked (
http_t *http
);
1 if chunked, 0 if not
This function returns non-zero if the message body is composed of variable-length chunks.
Report whether a connection is encrypted.
int httpIsEncrypted (
http_t *http
);
1 if encrypted, 0 if not
This function returns non-zero if the connection is currently encrypted.
Load X.509 credentials from a keychain file.
int httpLoadCredentials (
const char *path,
cups_array_t **credentials,
const char *common_name
);
NULL
for default0 on success, -1 on error
Send an OPTIONS request to the server.
int httpOptions (
http_t *http,
const char *uri
);
Status of call (0 = success)
Peek at data from a HTTP connection.
ssize_t httpPeek (
http_t *http,
char *buffer,
size_t length
);
Number of bytes copied
This function copies available data from the given HTTP connection, reading
a buffer as needed. The data is still available for reading using
httpRead
or httpRead2
.
For non-blocking connections the usual timeouts apply.
Send a POST request to the server.
int httpPost (
http_t *http,
const char *uri
);
Status of call (0 = success)
Send a PUT request to the server.
int httpPut (
http_t *http,
const char *uri
);
Status of call (0 = success)
Read data from a HTTP connection.
ssize_t httpRead2 (
http_t *http,
char *buffer,
size_t length
);
Number of bytes read
Read a HTTP request from a connection.
http_state_t httpReadRequest (
http_t *http,
char *uri,
size_t urilen
);
New state of connection
Reconnect to a HTTP server with timeout and optional cancel.
int httpReconnect2 (
http_t *http,
int msec,
int *cancel
);
0 on success, non-zero on failure
Resolve the hostname of the HTTP connection address.
const char *httpResolveHostname (
http_t *http,
char *buffer,
size_t bufsize
);
Resolved hostname or NULL
Save X.509 credentials to a keychain file.
int httpSaveCredentials (
const char *path,
cups_array_t *credentials,
const char *common_name
);
NULL
for default-1 on error, 0 on success
+ 400 year days
void httpSeparate (
const char *uri,
char *scheme,
char *username,
char *host,
int *port,
char *resource
);
Separate a Universal Resource Identifier into its components.
This function is deprecated; use the httpSeparateURI() function instead.
Resource/filename [1024]
void httpSeparate2 (
const char *uri,
char *scheme,
int schemelen,
char *username,
int usernamelen,
char *host,
int hostlen,
int *port,
char *resource,
int resourcelen
);
Separate a Universal Resource Identifier into its components.
This function is deprecated; use the httpSeparateURI() function instead.
Separate a Universal Resource Identifier into its components.
http_uri_status_t httpSeparateURI (
http_uri_coding_t decoding,
const char *uri,
char *scheme,
int schemelen,
char *username,
int usernamelen,
char *host,
int hostlen,
int *port,
char *resource,
int resourcelen
);
Result of separation
Always do encryption via SSL.
void httpSetAuthString (
http_t *http,
const char *scheme,
const char *data
);
Set the current authorization string.
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().
Array of credentials
void httpSetCookie (
http_t *http,
const char *cookie
);
Set the cookie value(s).
Set the credentials associated with an encrypted connection.
int httpSetCredentials (
http_t *http,
cups_array_t *credentials
);
Status of call (0 = success)
Cookie string
void httpSetDefaultField (
http_t *http,
http_field_t field,
const char *value
);
Set the default value of an HTTP header.
Currently only HTTP_FIELD_ACCEPT_ENCODING
, HTTP_FIELD_SERVER
,
and HTTP_FIELD_USER_AGENT
can be set.
Value
void httpSetExpect (
http_t *http,
http_status_t expect
);
HTTP_STATUS_CONTINUE
)Set the Expect: header in a request.
Currently only HTTP_STATUS_CONTINUE
is supported for the "expect"
argument.
HTTP status to expect
(HTTP_STATUS_CONTINUE
)
void httpSetField (
http_t *http,
http_field_t field,
const char *value
);
Set the value of an HTTP header.
Check for a trailing dot on the hostname...
void httpSetKeepAlive (
http_t *http,
http_keepalive_t keep_alive
);
Set the current Keep-Alive state of a connection.
New Keep-Alive value
void httpSetLength (
http_t *http,
size_t length
);
Set the content-length and content-encoding.
Length (0 for chunked)
void httpSetTimeout (
http_t *http,
double timeout,
http_timeout_cb_t cb,
void *user_data
);
Set read/write timeouts and an optional callback.
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.
User data pointer
void httpShutdown (
http_t *http
);
Shutdown one side of an HTTP connection.
Return the string describing a HTTP state value.
const char *httpStateString (
http_state_t state
);
State string
Return a short string describing a HTTP status code.
const char *httpStatus (
http_status_t status
);
Localized status string
The returned string is localized to the current POSIX locale and is based on the status strings defined in RFC 2616.
Send an TRACE request to the server.
int httpTrace (
http_t *http,
const char *uri
);
Status of call (0 = success)
Return a string describing a URI status code.
const char *httpURIStatusString (
http_uri_status_t status
);
Localized status string
Update the current HTTP state for incoming data.
http_status_t httpUpdate (
http_t *http
);
HTTP status
Wait for data available on a connection.
int httpWait (
http_t *http,
int msec
);
1 if data is available, 0 otherwise
Write data to a HTTP connection.
ssize_t httpWrite2 (
http_t *http,
const char *buffer,
size_t length
);
Number of bytes written
Write a HTTP response to a client connection.
int httpWriteResponse (
http_t *http,
http_status_t status
);
0 on success, -1 on error
Add a boolean attribute to an IPP message.
ipp_attribute_t *ippAddBoolean (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
char value
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add an array of boolean values.
ipp_attribute_t *ippAddBooleans (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
int num_values,
const char *values
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add a collection value.
ipp_attribute_t *ippAddCollection (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
ipp_t *value
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add an array of collection values.
ipp_attribute_t *ippAddCollections (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
int num_values,
const ipp_t **values
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add a date attribute to an IPP message.
ipp_attribute_t *ippAddDate (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
const ipp_uchar_t *value
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add a integer attribute to an IPP message.
ipp_attribute_t *ippAddInteger (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
int value
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported values include enum (IPP_TAG_ENUM
) and integer
(IPP_TAG_INTEGER
).
Add an array of integer values.
ipp_attribute_t *ippAddIntegers (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
int num_values,
const int *values
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported values include enum (IPP_TAG_ENUM
) and integer
(IPP_TAG_INTEGER
).
Add an octetString value to an IPP message.
ipp_attribute_t *ippAddOctetString (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
const void *data,
int datalen
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add an out-of-band value to an IPP message.
ipp_attribute_t *ippAddOutOfBand (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported out-of-band values include unsupported-value
(IPP_TAG_UNSUPPORTED_VALUE
), default (IPP_TAG_DEFAULT
), unknown
(IPP_TAG_UNKNOWN
), no-value (IPP_TAG_NOVALUE
), not-settable
(IPP_TAG_NOTSETTABLE
), delete-attribute (IPP_TAG_DELETEATTR
), and
admin-define (IPP_TAG_ADMINDEFINE
).
Add a range of values to an IPP message.
ipp_attribute_t *ippAddRange (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
int lower,
int upper
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
The lower
parameter must be less than or equal to the upper
parameter.
Add ranges of values to an IPP message.
ipp_attribute_t *ippAddRanges (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
int num_values,
const int *lower,
const int *upper
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add a resolution value to an IPP message.
ipp_attribute_t *ippAddResolution (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
ipp_res_t units,
int xres,
int yres
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add resolution values to an IPP message.
ipp_attribute_t *ippAddResolutions (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
int num_values,
ipp_res_t units,
const int *xres,
const int *yres
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add a group separator to an IPP message.
ipp_attribute_t *ippAddSeparator (
ipp_t *ipp
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
Add a language-encoded string to an IPP message.
ipp_attribute_t *ippAddString (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
const char *language,
const char *value
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported string values include charset (IPP_TAG_CHARSET
), keyword
(IPP_TAG_KEYWORD
), language (IPP_TAG_LANGUAGE
), mimeMediaType
(IPP_TAG_MIMETYPE
), name (IPP_TAG_NAME
), nameWithLanguage
(IPP_TAG_NAMELANG), text (
code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG
), uri (IPP_TAG_URI
), and uriScheme
(IPP_TAG_URISCHEME
).
The language
parameter must be non-NULL
for nameWithLanguage and
textWithLanguage string values and must be NULL
for all other string values.
Add a formatted string to an IPP message.
ipp_attribute_t *ippAddStringf (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
const char *language,
const char *format,
...
);
NULL
for default)New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document
(IPP_TAG_DOCUMENT
), event notification
(IPP_TAG_EVENT_NOTIFICATION
), operation (IPP_TAG_OPERATION
),
printer (IPP_TAG_PRINTER
), subscription (IPP_TAG_SUBSCRIPTION
),
or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported string values include charset (IPP_TAG_CHARSET
), keyword
(IPP_TAG_KEYWORD
), language (IPP_TAG_LANGUAGE
), mimeMediaType
(IPP_TAG_MIMETYPE
), name (IPP_TAG_NAME
), nameWithLanguage
(IPP_TAG_NAMELANG), text (
code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG
), uri (IPP_TAG_URI
), and uriScheme
(IPP_TAG_URISCHEME
).
The language
parameter must be non-NULL
for nameWithLanguage
and textWithLanguage string values and must be NULL
for all other
string values.
The format
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.
Add a formatted string to an IPP message.
ipp_attribute_t *ippAddStringfv (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
const char *language,
const char *format,
va_list ap
);
NULL
for default)New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document
(IPP_TAG_DOCUMENT
), event notification
(IPP_TAG_EVENT_NOTIFICATION
), operation (IPP_TAG_OPERATION
),
printer (IPP_TAG_PRINTER
), subscription (IPP_TAG_SUBSCRIPTION
),
or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported string values include charset (IPP_TAG_CHARSET
), keyword
(IPP_TAG_KEYWORD
), language (IPP_TAG_LANGUAGE
), mimeMediaType
(IPP_TAG_MIMETYPE
), name (IPP_TAG_NAME
), nameWithLanguage
(IPP_TAG_NAMELANG), text (
code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG
), uri (IPP_TAG_URI
), and uriScheme
(IPP_TAG_URISCHEME
).
The language
parameter must be non-NULL
for nameWithLanguage
and textWithLanguage string values and must be NULL
for all other
string values.
The format
parameter uses formatting characters compatible with the
printf family of standard functions. Additional arguments are passed in the
stdarg pointer ap
. The formatted string is truncated as needed to the
maximum length of the corresponding value type.
Add language-encoded strings to an IPP message.
ipp_attribute_t *ippAddStrings (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
int num_values,
const char *language,
const char *const *values
);
NULL
for default)New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported string values include charset (IPP_TAG_CHARSET
), keyword
(IPP_TAG_KEYWORD
), language (IPP_TAG_LANGUAGE
), mimeMediaType
(IPP_TAG_MIMETYPE
), name (IPP_TAG_NAME
), nameWithLanguage
(IPP_TAG_NAMELANG), text (
code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG
), uri (IPP_TAG_URI
), and uriScheme
(IPP_TAG_URISCHEME
).
The language
parameter must be non-NULL
for nameWithLanguage and
textWithLanguage string values and must be NULL
for all other string values.
Convert the attribute's value to a string.
size_t ippAttributeString (
ipp_attribute_t *attr,
char *buffer,
size_t bufsize
);
Number of bytes less nul
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.
Determine whether an attribute contains the specified value or is within the list of ranges.
int ippContainsInteger (
ipp_attribute_t *attr,
int value
);
1 on a match, 0 on no match
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.
Determine whether an attribute contains the specified string value.
int ippContainsString (
ipp_attribute_t *attr,
const char *value
);
1 on a match, 0 on no match
Returns non-zero when the attribute contains a matching charset, keyword, language, mimeMediaType, name, text, URI, or URI scheme value.
Copy an attribute.
ipp_attribute_t *ippCopyAttribute (
ipp_t *dst,
ipp_attribute_t *srcattr,
int quickcopy
);
New attribute
The specified attribute, attr
, is copied to the destination IPP message.
When quickcopy
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.
Copy attributes from one IPP message to another.
int ippCopyAttributes (
ipp_t *dst,
ipp_t *src,
int quickcopy,
ipp_copycb_t cb,
void *context
);
NULL
for none1 on success, 0 on error
Zero or more attributes are copied from the source IPP message, src
, to the
destination IPP message, dst
. When quickcopy
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.
The cb
and context
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.
Create a CUPS array of attribute names from the given requested-attributes attribute.
cups_array_t *ippCreateRequestedArray (
ipp_t *request
);
CUPS array or NULL
if all
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.
The request
parameter specifies the request message that was read from
the client.
NULL
is returned if all attributes should be returned. Otherwise, the
result is a sorted array of attribute names, where cupsArrayFind(array,
"attribute-name")
will return a non-NULL pointer. The array must be freed
using the cupsArrayDelete
function.
Convert from RFC 1903 Date/Time format to UNIX time in seconds.
time_t ippDateToTime (
const ipp_uchar_t *date
);
UNIX time value
RFC-1903 date/time format is:
void ippDelete (
ipp_t *ipp
);
Delete an IPP message.
Byte(s) Description ------- ----------- 0-1 Year (0 to 65535) 2 Month (1 to 12) 3 Day (1 to 31) 4 Hours (0 to 23) 5 Minutes (0 to 59) 6 Seconds (0 to 60, 60 = "leap second") 7 Deciseconds (0 to 9) 8 +/- UTC 9 UTC hours (0 to 11) 10 UTC minutes (0 to 59)
Next attribute
void ippDeleteAttribute (
ipp_t *ipp,
ipp_attribute_t *attr
);
Delete a single attribute in an IPP message.
Delete values in an attribute.
int ippDeleteValues (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int count
);
1 on success, 0 on failure
The element
parameter specifies the first value to delete, starting at
0. It must be less than the number of values returned by ippGetCount
.
The attr
parameter may be modified as a result of setting the value.
Deleting all values in an attribute deletes the attribute.
Return a string corresponding to the enum value.
const char *ippEnumString (
const char *attrname,
int enumvalue
);
Enum string
Return the value associated with a given enum string.
int ippEnumValue (
const char *attrname,
const char *enumstring
);
Enum value or -1 if unknown
Return a name for the given status code.
const char *ippErrorString (
ipp_status_t error
);
Text string
Return a status code for the given name.
ipp_status_t ippErrorValue (
const char *name
);
IPP status code
Find a named attribute in a request.
ipp_attribute_t *ippFindAttribute (
ipp_t *ipp,
const char *name,
ipp_tag_t type
);
Matching attribute
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".
Find the next named attribute in a request.
ipp_attribute_t *ippFindNextAttribute (
ipp_t *ipp,
const char *name,
ipp_tag_t type
);
Matching attribute
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".
Return the first attribute in the message.
ipp_attribute_t *ippFirstAttribute (
ipp_t *ipp
);
First attribute or NULL
if none
Get a boolean value for an attribute.
int ippGetBoolean (
ipp_attribute_t *attr,
int element
);
Boolean value or 0 on error
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get a collection value for an attribute.
ipp_t *ippGetCollection (
ipp_attribute_t *attr,
int element
);
Collection value or NULL
on error
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the number of values in an attribute.
int ippGetCount (
ipp_attribute_t *attr
);
Number of values or 0 on error
Get a date value for an attribute.
const ipp_uchar_t *ippGetDate (
ipp_attribute_t *attr,
int element
);
Date value or NULL
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the group associated with an attribute.
ipp_tag_t ippGetGroupTag (
ipp_attribute_t *attr
);
Group tag or IPP_TAG_ZERO
on error
Get the integer/enum value for an attribute.
int ippGetInteger (
ipp_attribute_t *attr,
int element
);
Value or 0 on error
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the attribute name.
const char *ippGetName (
ipp_attribute_t *attr
);
Attribute name or NULL
for separators
Get an octetString value from an IPP attribute.
void *ippGetOctetString (
ipp_attribute_t *attr,
int element,
int *datalen
);
Pointer to octetString data
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the operation ID in an IPP message.
ipp_op_t ippGetOperation (
ipp_t *ipp
);
Operation ID or 0 on error
Get a rangeOfInteger value from an attribute.
int ippGetRange (
ipp_attribute_t *attr,
int element,
int *uppervalue
);
Lower value of range or 0
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the request ID from an IPP message.
int ippGetRequestId (
ipp_t *ipp
);
Request ID or 0 on error
Get a resolution value for an attribute.
int ippGetResolution (
ipp_attribute_t *attr,
int element,
int *yres,
ipp_res_t *units
);
Horizontal/cross feed resolution or 0
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the IPP message state.
ipp_state_t ippGetState (
ipp_t *ipp
);
IPP message state value
Get the status code from an IPP response or event message.
ipp_status_t ippGetStatusCode (
ipp_t *ipp
);
Status code in IPP message
Return the value...
const char *ippGetString (
ipp_attribute_t *attr,
int element,
const char **language
);
NULL
for don't care)Get the string and optionally the language code for an attribute.
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the value tag for an attribute.
ipp_tag_t ippGetValueTag (
ipp_attribute_t *attr
);
Value tag or IPP_TAG_ZERO
on error
Get the major and minor version number from an IPP message.
int ippGetVersion (
ipp_t *ipp,
int *minor
);
NULL
Major version number or 0 on error
Compute the length of an IPP message.
size_t ippLength (
ipp_t *ipp
);
Size of IPP message
Allocate a new IPP message.
ipp_t *ippNew (void);
New IPP message
Allocate a new IPP request message.
ipp_t *ippNewRequest (
ipp_op_t op
);
IPP request message
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.
Allocate a new IPP response message.
ipp_t *ippNewResponse (
ipp_t *request
);
IPP response message
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.
Return the next attribute in the message.
ipp_attribute_t *ippNextAttribute (
ipp_t *ipp
);
Next attribute or NULL
if none
Return a name for the given operation id.
const char *ippOpString (
ipp_op_t op
);
Name
Return an operation id for the given name.
ipp_op_t ippOpValue (
const char *name
);
Operation ID
Return the default IPP port number.
int ippPort (void);
Port number
Read data for an IPP message from a HTTP connection.
ipp_state_t ippRead (
http_t *http,
ipp_t *ipp
);
Current state
Read data for an IPP message from a file.
ipp_state_t ippReadFile (
int fd,
ipp_t *ipp
);
Current state
Read data for an IPP message.
ipp_state_t ippReadIO (
void *src,
ipp_iocb_t cb,
int blocking,
ipp_t *parent,
ipp_t *ipp
);
Current state
Set a boolean value in an attribute.
int ippSetBoolean (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int boolvalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set a collection value in an attribute.
int ippSetCollection (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
ipp_t *colvalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set a date value in an attribute.
int ippSetDate (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const ipp_uchar_t *datevalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set the group tag of an attribute.
int ippSetGroupTag (
ipp_t *ipp,
ipp_attribute_t **attr,
ipp_tag_t group_tag
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Set an integer or enum value in an attribute.
int ippSetInteger (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int intvalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set the name of an attribute.
int ippSetName (
ipp_t *ipp,
ipp_attribute_t **attr,
const char *name
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
Set an octetString value in an IPP attribute.
int ippSetOctetString (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const void *data,
int datalen
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set the operation ID in an IPP request message.
int ippSetOperation (
ipp_t *ipp,
ipp_op_t op
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
Pointer to library globals
void ippSetPort (
int p
);
Set the default port number.
Set a rangeOfInteger value in an attribute.
int ippSetRange (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int lowervalue,
int uppervalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set the request ID in an IPP message.
int ippSetRequestId (
ipp_t *ipp,
int request_id
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The request_id
parameter must be greater than 0.
Set a resolution value in an attribute.
int ippSetResolution (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
ipp_res_t unitsvalue,
int xresvalue,
int yresvalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set the current state of the IPP message.
int ippSetState (
ipp_t *ipp,
ipp_state_t state
);
1 on success, 0 on failure
Set the status code in an IPP response or event message.
int ippSetStatusCode (
ipp_t *ipp,
ipp_status_t status
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
Set a string value in an attribute.
int ippSetString (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const char *strvalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set a formatted string value of an attribute.
int ippSetStringf (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const char *format,
...
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
The format
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.
Set a formatted string value of an attribute.
int ippSetStringfv (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const char *format,
va_list ap
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
The format
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.
Set the value tag of an attribute.
int ippSetValueTag (
ipp_t *ipp,
ipp_attribute_t **attr,
ipp_tag_t value_tag
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
Integer (IPP_TAG_INTEGER
) values can be promoted to rangeOfInteger
(IPP_TAG_RANGE
) values, the various string tags can be promoted to name
(IPP_TAG_NAME
) or nameWithLanguage (IPP_TAG_NAMELANG
) values, text
(IPP_TAG_TEXT
) values can be promoted to textWithLanguage
(IPP_TAG_TEXTLANG
) values, and all values can be demoted to the various
out-of-band value tags such as no-value (IPP_TAG_NOVALUE
). All other changes
will be rejected.
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.
Set the version number in an IPP message.
int ippSetVersion (
ipp_t *ipp,
int major,
int minor
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The valid version numbers are currently 1.0, 1.1, 2.0, 2.1, and 2.2.
Return the name corresponding to a state value.
const char *ippStateString (
ipp_state_t state
);
State name
Return the tag name corresponding to a tag value.
const char *ippTagString (
ipp_tag_t tag
);
Tag name
The returned names are defined in RFC 2911 and 3382.
Return the tag value corresponding to a tag name.
ipp_tag_t ippTagValue (
const char *name
);
Tag value
The tag names are defined in RFC 2911 and 3382.
Convert from UNIX time to RFC 1903 format.
const ipp_uchar_t *ippTimeToDate (
time_t t
);
RFC-1903 date/time data
Validate the contents of an attribute.
int ippValidateAttribute (
ipp_attribute_t *attr
);
1 if valid, 0 otherwise
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.
Validate all attributes in an IPP message.
int ippValidateAttributes (
ipp_t *ipp
);
1 if valid, 0 otherwise
This function validates the contents of the IPP message, including each
attribute. Like ippValidateAttribute
, cupsLastErrorString() is set
to a human-readable message on failure.
Write data for an IPP message to a HTTP connection.
ipp_state_t ippWrite (
http_t *http,
ipp_t *ipp
);
Current state
Write data for an IPP message to a file.
ipp_state_t ippWriteFile (
int fd,
ipp_t *ipp
);
Current state
Write data for an IPP message.
ipp_state_t ippWriteIO (
void *dst,
ipp_iocb_t cb,
int blocking,
ipp_t *parent,
ipp_t *ipp
);
Current state
Generate a PWG self-describing media size name.
int pwgFormatSizeName (
char *keyword,
size_t keysize,
const char *prefix,
const char *name,
int width,
int length,
const char *units
);
NULL
for automaticNULL
NULL
for automatic1 on success, 0 on failure
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 NULL
automatically chooses
"oe" or "om" depending on the units.
The size name may only contain lowercase letters, numbers, "-", and ".". If
NULL
is passed, the size name will contain the formatted dimensions.
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 NULL
, otherwise inches ("in") or millimeters ("mm")
are used.
Initialize a pwg_size_t structure using IPP Job Template attributes.
int pwgInitSize (
pwg_size_t *size,
ipp_t *job,
int *margins_set
);
1 if size was initialized, 0 otherwise
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.
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.
Find a PWG media size by ISO/IPP legacy name.
pwg_media_t *pwgMediaForLegacy (
const char *legacy
);
Matching size or NULL
The "name" argument specifies the legacy ISO media size name, for example "iso-a4" or "na-letter".
Find a PWG media size by Adobe PPD name.
pwg_media_t *pwgMediaForPPD (
const char *ppd
);
Matching size or NULL
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.
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]".
Find a PWG media size by 5101.1 self-describing name.
pwg_media_t *pwgMediaForPWG (
const char *pwg
);
Matching size or NULL
The "pwg" argument specifies a self-describing media size name of the form
"prefix_name_WIDTHxLENGTHunits" as defined in PWG 5101.1.
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.
Get the PWG media size for the given dimensions.
pwg_media_t *pwgMediaForSize (
int width,
int length
);
PWG media name
The "width" and "length" are in hundredths of millimeters, equivalent to
1/100000th of a meter or 1/2540th of an inch.
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.
Client credentials callback
typedef int(*)(http_t *http, void *tls, cups_array_t *distinguished_names, void *user_data)cups_client_cert_cb_t;
Destination enumeration callback
typedef int(*)(void *user_data, unsigned flags, cups_dest_t *dest)cups_dest_cb_t;
Destination
typedef struct cups_dest_s cups_dest_t;
Destination capability and status information
typedef struct _cups_dinfo_s cups_dinfo_t;
Language Encodings
typedef enum cups_encoding_e cups_encoding_t;
Job
typedef struct cups_job_s cups_job_t;
Language Cache Structure
typedef struct cups_lang_s cups_lang_t;
Printer Options
typedef struct cups_option_s cups_option_t;
New password callback
typedef const char *(*)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data)cups_password_cb2_t;
Printer type/capability bits
typedef unsigned cups_ptype_t;
Server credentials callback
typedef int(*)(http_t *http, void *tls, cups_array_t *certs, void *user_data)cups_server_cert_cb_t;
Media Size
typedef struct cups_size_s cups_size_t;
Socket address union, which makes using IPv6 and other address types easier and more portable.
typedef union _http_addr_u / http_addr_t;
Socket address list, which is used to enumerate all of the addresses that are associated with a hostname.
typedef struct http_addrlist_s / http_addrlist_t;
HTTP authentication types
typedef enum http_auth_e http_auth_t;
HTTP credential data
typedef struct http_credential_s http_credential_t;
HTTP transfer encoding values
typedef enum http_encoding_e http_encoding_t;
HTTP encryption values
typedef enum http_encryption_e http_encryption_t;
HTTP field names
typedef enum http_field_e http_field_t;
HTTP keep-alive values
typedef enum http_keepalive_e http_keepalive_t;
HTTP state values; states are server-oriented...
typedef enum http_state_e http_state_t;
HTTP connection type
typedef struct _http_s http_t;
HTTP timeout callback
typedef int(*)(http_t *http, void *user_data)http_timeout_cb_t;
Level of trust for credentials
typedef enum http_trust_e http_trust_t;
URI en/decode flags
typedef enum http_uri_coding_e http_uri_coding_t;
URI separation status
typedef enum http_uri_status_e http_uri_status_t;
HTTP version numbers
typedef enum http_version_e http_version_t;
IPP attribute
typedef struct _ipp_attribute_s ipp_attribute_t;
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.
typedef int(*)(void *context, ipp_t *dst, ipp_attribute_t *attr)ipp_copycb_t;
Document states
typedef enum ipp_dstate_e ipp_dstate_t;
Job collation types
typedef enum ipp_finishings_e ipp_finish_t;
IPP IO Callback Function
typedef ssize_t(*)(void *context, ipp_uchar_t *buffer, size_t bytes) ipp_iocb_t;
Job collation types
typedef enum ipp_jcollate_e ipp_jcollate_t;
Orientation values
typedef enum ipp_orient_e ipp_orient_t;
Printer states
typedef enum ipp_pstate_e ipp_pstate_t;
Qualities
typedef enum ipp_quality_e ipp_quality_t;
Resolution units
typedef enum ipp_res_e ipp_res_t;
IPP states
typedef enum ipp_state_e ipp_state_t;
IPP request/response data
typedef struct _ipp_s ipp_t;
Unsigned 8-bit integer/character
typedef unsigned char ipp_uchar_t;
Map element - PPD to/from PWG
typedef struct pwg_map_s pwg_map_t;
Common media size data
typedef struct pwg_media_s pwg_media_t;
Size element - PPD to/from PWG
typedef struct pwg_size_s pwg_size_t;
Destination
struct cups_dest_s {
char *name, *instance;
int is_default;
int num_options;
cups_option_t *options;
};
Job
struct cups_job_s {
time_t completed_time;
time_t creation_time;
char *dest;
char *format;
int id;
int priority;
time_t processing_time;
int size;
ipp_jstate_t state;
char *title;
char *user;
};
Language Cache Structure
struct cups_lang_s {
cups_encoding_t encoding;
char language[16];
struct cups_lang_s *next;
int used;
};
Printer Options
struct cups_option_s {
char *name;
char *value;
};
Media Size
struct cups_size_s {
char media[128];
int width, length, bottom, left, right, top;
};
Socket address list, which is used to enumerate all of the addresses that are associated with a hostname.
struct http_addrlist_s {
http_addr_t addr;
struct http_addrlist_s *next;
};
HTTP credential data
struct http_credential_s {
void *data;
size_t datalen;
};
Map element - PPD to/from PWG
struct pwg_map_s {
char *pwg, *ppd;
};
Common media size data
struct pwg_media_s {
int width, length;
const char *pwg, *legacy, *ppd;
};
Size element - PPD to/from PWG
struct pwg_size_s {
pwg_map_t map;
int width, length, left, bottom, right, top;
};
Language Encodings
Printer type/capability bit constants
HTTP authentication types
HTTP transfer encoding values
HTTP encryption values
HTTP field names
HTTP keep-alive values
HTTP state values; states are server-oriented...
HTTP status codes
Level of trust for credentials
URI en/decode flags
URI separation status
HTTP version numbers
Document states
Finishings
Job collation types
Job states
IPP operations
ippOpValue
Orientation values
Printer states
Qualities
Resolution units
IPP states
IPP status codes
ippErrorValue
Format tags for attributes
ippTagValue