<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <HTML> <HEAD> <TITLE>CUPS Software Programmers Manual</TITLE> <META NAME="author" CONTENT="Easy Software Products"> <META NAME="copyright" CONTENT="Copyright 1997-2005, All Rights Reserved"> <META NAME="docnumber" CONTENT="CUPS-SPM-1.1.23"> <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1"> <STYLE TYPE="text/css"><!-- BODY { font-family: serif } H1 { font-family: sans-serif } H2 { font-family: sans-serif } H3 { font-family: sans-serif } H4 { font-family: sans-serif } H5 { font-family: sans-serif } H6 { font-family: sans-serif } SUB { font-size: smaller } SUP { font-size: smaller } PRE { font-family: monospace } --></STYLE> </HEAD> <BODY BGCOLOR="white"> <CENTER><A HREF="#CONTENTS"><IMG SRC="images/cups-large.gif" BORDER="0" WIDTH="431" HEIGHT="511" ALT="CUPS Software Programmers Manual"><BR> <H1>CUPS Software Programmers Manual</H1></A><BR> CUPS-SPM-1.1.23<BR> Easy Software Products<BR> Copyright 1997-2005, All Rights Reserved<BR> </CENTER> <HR NOSHADE> <H1 ALIGN="CENTER"><A NAME="CONTENTS">Table of Contents</A></H1> <BR> <BR><B><A HREF="#1">Preface</A></B> <UL> <LI><A HREF="#1_1">System Overview</A></LI> <LI><A HREF="#1_2">Document Overview</A></LI> <LI><A HREF="#1_3">Notation Conventions</A></LI> <LI><A HREF="#1_4">Abbreviations</A></LI> <LI><A HREF="#1_5">Other References</A></LI> </UL> <B><A HREF="#OVERVIEW">1 - Printing System Overview</A></B> <UL> <LI><A HREF="#2_1">The Printing Problem</A></LI> <LI><A HREF="#2_2">The Technology</A></LI> <LI><A HREF="#2_3">Jobs</A></LI> <LI><A HREF="#2_4">Classes</A></LI> <LI><A HREF="#2_5">Filters</A></LI> <LI><A HREF="#2_6">Backends</A></LI> <LI><A HREF="#2_7">Printer Drivers</A></LI> <LI><A HREF="#2_8">Networking</A></LI> </UL> <B><A HREF="#CUPS_API">2 - The CUPS API</A></B> <UL> <LI><A HREF="#3_1">The CUPS API Library</A> <UL> <LI><A HREF="#3_1_1">Detecting the CUPS API Library in GNU Autoconf</A></LI> </UL> </LI> <LI><A HREF="#3_2">Printing Services</A> <UL> <LI><A HREF="#3_2_1">Include Files</A></LI> <LI><A HREF="#3_2_2">Printing a File</A></LI> <LI><A HREF="#3_2_3">Printing Multiple Files</A></LI> <LI><A HREF="#3_2_4">Cancelling Jobs</A></LI> <LI><A HREF="#3_2_5">Getting the Available Printers and Classes</A></LI> <LI><A HREF="#3_2_6">Printing with Options</A></LI> <LI><A HREF="#3_2_7">Setting Printer Options</A></LI> <LI><A HREF="#3_2_8">Getting Errors</A></LI> <LI><A HREF="#3_2_9">Passwords and Authentication</A></LI> </UL> </LI> <LI><A HREF="#3_3">PPD Services</A> <UL> <LI><A HREF="#3_3_1">Include Files</A></LI> <LI><A HREF="#3_3_2">Getting a PPD File for a Printer</A></LI> <LI><A HREF="#3_3_3">Loading a PPD File</A></LI> <LI><A HREF="#3_3_4">Freeing PPD File Information</A></LI> <LI><A HREF="#3_3_5">The PPD File Structure</A></LI> <LI><A HREF="#3_3_6">Marking Options</A></LI> <LI><A HREF="#3_3_7">Checking for Conflicts</A></LI> </UL> </LI> </UL> <B><A HREF="#WRITING_FILTERS">3 - Writing Filters</A></B> <UL> <LI><A HREF="#4_1">Overview</A> <UL> <LI><A HREF="#4_1_1">Security Considerations</A></LI> <LI><A HREF="#4_1_2">Users and Groups</A></LI> <LI><A HREF="#4_1_3">Temporary Files</A></LI> <LI><A HREF="#4_1_4">Sending Messages to the User</A></LI> <LI><A HREF="#4_1_5">Page Accounting</A></LI> <LI><A HREF="#4_1_6">Command-Line Arguments</A></LI> <LI><A HREF="#4_1_7">Copy Generation</A></LI> <LI><A HREF="#4_1_8">Environment Variables</A></LI> </UL> </LI> <LI><A HREF="#4_2">Dissecting the HP-GL/2 Filter</A> <UL> <LI><A HREF="#4_2_1">Initializing the Filter</A></LI> </UL> </LI> <LI><A HREF="#4_3">PostScript Output</A></LI> </UL> <B><A HREF="#WRITING_DRIVERS">4 - Writing Printer Drivers</A></B> <UL> <LI><A HREF="#5_1">Overview</A> <UL> <LI><A HREF="#5_1_1">CUPS Raster Data</A></LI> <LI><A HREF="#5_1_2">Page Accounting</A></LI> <LI><A HREF="#5_1_3">Color Management</A></LI> <LI><A HREF="#5_1_4">Device and Bitmap Variables</A></LI> </UL> </LI> <LI><A HREF="#5_2">Dissecting the HP-PCL Driver</A> <UL> <LI><A HREF="#5_2_1">PPD Files</A></LI> <LI><A HREF="#5_2_2">Reading Raster Data</A></LI> </UL> </LI> </UL> <B><A HREF="#WRITING_BACKENDS">5 - Writing Backends</A></B> <UL> <LI><A HREF="#6_1">Overview</A> <UL> <LI><A HREF="#6_1_1">Security Considerations</A></LI> <LI><A HREF="#6_1_2">Command-Line Arguments</A></LI> <LI><A HREF="#6_1_3">Copy Generation</A></LI> <LI><A HREF="#6_1_4">Page Accounting</A></LI> <LI><A HREF="#6_1_5">Exclusive Access</A></LI> <LI><A HREF="#6_1_6">Retries</A></LI> </UL> </LI> <LI><A HREF="#6_2">Dissecting the Serial Port Backend</A> <UL> <LI><A HREF="#6_2_1">Supporting Device Discovery</A></LI> <LI><A HREF="#6_2_2">Opening the Serial Port</A></LI> <LI><A HREF="#6_2_3">Writing Data to the Port</A></LI> <LI><A HREF="#6_2_4">Finishing Up</A></LI> </UL> </LI> </UL> <B><A HREF="#LICENSE">A - Software License Agreement</A></B> <UL> <LI><A HREF="#7_1">Common UNIX Printing System License Agreement</A> <UL> <LI><A HREF="#7_1_1">Introduction</A></LI> <LI><A HREF="#7_1_2">License Exceptions</A></LI> <LI><A HREF="#7_1_3">Trademarks</A></LI> <LI><A HREF="#7_1_4">Binary Distribution Rights</A></LI> <LI><A HREF="#7_1_5">Support</A></LI> </UL> </LI> <LI><A HREF="#7_2">GNU GENERAL PUBLIC LICENSE</A> <UL> <LI><A HREF="#7_2_1">Preamble</A></LI> </UL> </LI> <LI><A HREF="#7_3">GNU LIBRARY GENERAL PUBLIC LICENSE</A> <UL> <LI><A HREF="#7_3_1">Preamble</A></LI> </UL> </LI> </UL> <B><A HREF="#CONSTANTS">B - Constants</A></B> <UL> <LI><A HREF="#8_1">CUPS Constants</A> <UL> <LI><A HREF="#8_1_1">Version Number</A></LI> <LI><A HREF="#8_1_2">Printer Capabilities</A></LI> <LI><A HREF="#8_1_3">Encodings</A></LI> </UL> </LI> <LI><A HREF="#8_2">HTTP Constants</A> <UL> <LI><A HREF="#8_2_1">Limits</A></LI> <LI><A HREF="#8_2_2">Status Codes</A></LI> <LI><A HREF="#8_2_3">Fields</A></LI> </UL> </LI> <LI><A HREF="#8_3">IPP Constants</A> <UL> <LI><A HREF="#8_3_1">Limits</A></LI> <LI><A HREF="#8_3_2">Tags</A></LI> <LI><A HREF="#8_3_3">Resolution Units</A></LI> <LI><A HREF="#8_3_4">Finishings</A></LI> <LI><A HREF="#8_3_5">Orientations</A></LI> <LI><A HREF="#8_3_6">Qualities</A></LI> <LI><A HREF="#8_3_7">Job States</A></LI> <LI><A HREF="#8_3_8">Printer States</A></LI> <LI><A HREF="#8_3_9">Operations</A></LI> <LI><A HREF="#8_3_10">Status Codes</A></LI> </UL> </LI> <LI><A HREF="#8_4">PPD Constants</A> <UL> <LI><A HREF="#8_4_1">PPD Format Version</A></LI> <LI><A HREF="#8_4_2">PPD User-Interface Types</A></LI> <LI><A HREF="#8_4_3">PPD Sections</A></LI> <LI><A HREF="#8_4_4">PPD Colorspaces</A></LI> </UL> </LI> <LI><A HREF="#8_5">Raster Constants</A> <UL> <LI><A HREF="#8_5_1">Raster Sync Words</A></LI> <LI><A HREF="#8_5_2">Raster Stream Modes</A></LI> <LI><A HREF="#8_5_3">Raster Boolean Constants</A></LI> <LI><A HREF="#8_5_4">Raster Jog Values</A></LI> <LI><A HREF="#8_5_5">Raster Orientation Values</A></LI> <LI><A HREF="#8_5_6">Raster CutMedia Values</A></LI> <LI><A HREF="#8_5_7">Raster AdvanceMedia Values</A></LI> <LI><A HREF="#8_5_8">Raster LeadingEdge Values</A></LI> <LI><A HREF="#8_5_9">Raster Color Order Values</A></LI> <LI><A HREF="#8_5_10">Raster Colorspace Values</A></LI> </UL> </LI> </UL> <B><A HREF="#STRUCTURES">C - Structures</A></B> <UL> <LI><A HREF="#9_1">CUPS Structures</A> <UL> <LI><A HREF="#cups_dest_t">CUPS Destinations</A></LI> <LI><A HREF="#cups_job_t">CUPS Jobs</A></LI> <LI><A HREF="#cups_lang_t">CUPS Messages</A></LI> <LI><A HREF="#cups_option_t">CUPS Options</A></LI> </UL> </LI> <LI><A HREF="#9_2">Networking Structures</A> <UL> <LI><A HREF="#http_t">HTTP State</A></LI> <LI><A HREF="#ipp_t">IPP State</A></LI> <LI><A HREF="#ipp_attribute_t">IPP Attribute</A></LI> </UL> </LI> <LI><A HREF="#9_3">PPD Structures</A> <UL> <LI><A HREF="#ppd_file_t">PPD File</A></LI> <LI><A HREF="#ppd_choice_t">PPD Choice</A></LI> </UL> </LI> <LI><A HREF="#9_4">Raster Structures</A> <UL> <LI><A HREF="#cups_raster_t">Raster Stream</A></LI> <LI><A HREF="#cups_raster_header_t">Raster Page Header</A></LI> </UL> </LI> </UL> <B><A HREF="#FUNCTIONS">D - Functions</A></B> <UL> <LI><A HREF="#cupsAddDest">cupsAddDest()</A> <UL> <LI><A HREF="#10_1_1">Usage</A></LI> <LI><A HREF="#10_1_2">Arguments</A></LI> <LI><A HREF="#10_1_3">Returns</A></LI> <LI><A HREF="#10_1_4">Description</A></LI> <LI><A HREF="#10_1_5">Example</A></LI> <LI><A HREF="#10_1_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsAddOption">cupsAddOption()</A> <UL> <LI><A HREF="#10_2_1">Usage</A></LI> <LI><A HREF="#10_2_2">Arguments</A></LI> <LI><A HREF="#10_2_3">Returns</A></LI> <LI><A HREF="#10_2_4">Description</A></LI> <LI><A HREF="#10_2_5">Example</A></LI> <LI><A HREF="#10_2_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsCancelJob">cupsCancelJob()</A> <UL> <LI><A HREF="#10_3_1">Usage</A></LI> <LI><A HREF="#10_3_2">Arguments</A></LI> <LI><A HREF="#10_3_3">Returns</A></LI> <LI><A HREF="#10_3_4">Description</A></LI> <LI><A HREF="#10_3_5">Example</A></LI> <LI><A HREF="#10_3_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsDoAuthentication">cupsDoAuthentication()</A> <UL> <LI><A HREF="#10_4_1">Usage</A></LI> <LI><A HREF="#10_4_2">Arguments</A></LI> <LI><A HREF="#10_4_3">Returns</A></LI> <LI><A HREF="#10_4_4">Description</A></LI> <LI><A HREF="#10_4_5">Example</A></LI> <LI><A HREF="#10_4_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsDoFileRequest">cupsDoFileRequest()</A> <UL> <LI><A HREF="#10_5_1">Usage</A></LI> <LI><A HREF="#10_5_2">Arguments</A></LI> <LI><A HREF="#10_5_3">Returns</A></LI> <LI><A HREF="#10_5_4">Description</A></LI> <LI><A HREF="#10_5_5">Example</A></LI> <LI><A HREF="#10_5_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsDoRequest">cupsDoRequest()</A> <UL> <LI><A HREF="#10_6_1">Usage</A></LI> <LI><A HREF="#10_6_2">Arguments</A></LI> <LI><A HREF="#10_6_3">Returns</A></LI> <LI><A HREF="#10_6_4">Description</A></LI> <LI><A HREF="#10_6_5">Example</A></LI> <LI><A HREF="#10_6_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsEncodeOptions">cupsEncodeOptions()</A> <UL> <LI><A HREF="#10_7_1">Usage</A></LI> <LI><A HREF="#10_7_2">Arguments</A></LI> <LI><A HREF="#10_7_3">Description</A></LI> <LI><A HREF="#10_7_4">Example</A></LI> <LI><A HREF="#10_7_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsEncryption">cupsEncryption()</A> <UL> <LI><A HREF="#10_8_1">Usage</A></LI> <LI><A HREF="#10_8_2">Returns</A></LI> <LI><A HREF="#10_8_3">Description</A></LI> <LI><A HREF="#10_8_4">Example</A></LI> <LI><A HREF="#10_8_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsFreeDests">cupsFreeDests()</A> <UL> <LI><A HREF="#10_9_1">Usage</A></LI> <LI><A HREF="#10_9_2">Arguments</A></LI> <LI><A HREF="#10_9_3">Description</A></LI> <LI><A HREF="#10_9_4">Example</A></LI> <LI><A HREF="#10_9_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsFreeJobs">cupsFreeJobs()</A> <UL> <LI><A HREF="#10_10_1">Usage</A></LI> <LI><A HREF="#10_10_2">Arguments</A></LI> <LI><A HREF="#10_10_3">Description</A></LI> <LI><A HREF="#10_10_4">Example</A></LI> <LI><A HREF="#10_10_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsFreeOptions">cupsFreeOptions()</A> <UL> <LI><A HREF="#10_11_1">Usage</A></LI> <LI><A HREF="#10_11_2">Arguments</A></LI> <LI><A HREF="#10_11_3">Description</A></LI> <LI><A HREF="#10_11_4">Example</A></LI> <LI><A HREF="#10_11_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsGetClasses">cupsGetClasses()</A> <UL> <LI><A HREF="#10_12_1">Usage</A></LI> <LI><A HREF="#10_12_2">Arguments</A></LI> <LI><A HREF="#10_12_3">Returns</A></LI> <LI><A HREF="#10_12_4">Description</A></LI> <LI><A HREF="#10_12_5">Example</A></LI> <LI><A HREF="#10_12_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsGetDefault">cupsGetDefault()</A> <UL> <LI><A HREF="#10_13_1">Usage</A></LI> <LI><A HREF="#10_13_2">Returns</A></LI> <LI><A HREF="#10_13_3">Description</A></LI> <LI><A HREF="#10_13_4">Example</A></LI> <LI><A HREF="#10_13_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsGetDest">cupsGetDest()</A> <UL> <LI><A HREF="#10_14_1">Usage</A></LI> <LI><A HREF="#10_14_2">Arguments</A></LI> <LI><A HREF="#10_14_3">Returns</A></LI> <LI><A HREF="#10_14_4">Description</A></LI> <LI><A HREF="#10_14_5">Example</A></LI> <LI><A HREF="#10_14_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsGetDests">cupsGetDests()</A> <UL> <LI><A HREF="#10_15_1">Usage</A></LI> <LI><A HREF="#10_15_2">Arguments</A></LI> <LI><A HREF="#10_15_3">Returns</A></LI> <LI><A HREF="#10_15_4">Description</A></LI> <LI><A HREF="#10_15_5">Example</A></LI> <LI><A HREF="#10_15_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsGetFd">cupsGetFd()</A> <UL> <LI><A HREF="#10_16_1">Usage</A></LI> <LI><A HREF="#10_16_2">Arguments</A></LI> <LI><A HREF="#10_16_3">Returns</A></LI> <LI><A HREF="#10_16_4">Description</A></LI> <LI><A HREF="#10_16_5">Example</A></LI> <LI><A HREF="#10_16_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsGetFile">cupsGetFile()</A> <UL> <LI><A HREF="#10_17_1">Usage</A></LI> <LI><A HREF="#10_17_2">Arguments</A></LI> <LI><A HREF="#10_17_3">Returns</A></LI> <LI><A HREF="#10_17_4">Description</A></LI> <LI><A HREF="#10_17_5">Example</A></LI> <LI><A HREF="#10_17_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsGetJobs">cupsGetJobs()</A> <UL> <LI><A HREF="#10_18_1">Usage</A></LI> <LI><A HREF="#10_18_2">Arguments</A></LI> <LI><A HREF="#10_18_3">Returns</A></LI> <LI><A HREF="#10_18_4">Description</A></LI> <LI><A HREF="#10_18_5">Example</A></LI> <LI><A HREF="#10_18_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsGetOption">cupsGetOption()</A> <UL> <LI><A HREF="#10_19_1">Usage</A></LI> <LI><A HREF="#10_19_2">Arguments</A></LI> <LI><A HREF="#10_19_3">Returns</A></LI> <LI><A HREF="#10_19_4">Description</A></LI> <LI><A HREF="#10_19_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsGetPassword">cupsGetPassword()</A> <UL> <LI><A HREF="#10_20_1">Usage</A></LI> <LI><A HREF="#10_20_2">Arguments</A></LI> <LI><A HREF="#10_20_3">Returns</A></LI> <LI><A HREF="#10_20_4">Description</A></LI> <LI><A HREF="#10_20_5">Example</A></LI> <LI><A HREF="#10_20_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsGetPPD">cupsGetPPD()</A> <UL> <LI><A HREF="#10_21_1">Usage</A></LI> <LI><A HREF="#10_21_2">Arguments</A></LI> <LI><A HREF="#10_21_3">Returns</A></LI> <LI><A HREF="#10_21_4">Description</A></LI> <LI><A HREF="#10_21_5">Example</A></LI> </UL> </LI> <LI><A HREF="#cupsGetPrinters">cupsGetPrinters()</A> <UL> <LI><A HREF="#10_22_1">Usage</A></LI> <LI><A HREF="#10_22_2">Arguments</A></LI> <LI><A HREF="#10_22_3">Returns</A></LI> <LI><A HREF="#10_22_4">Description</A></LI> <LI><A HREF="#10_22_5">Example</A></LI> <LI><A HREF="#10_22_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsLangDefault">cupsLangDefault()</A> <UL> <LI><A HREF="#10_23_1">Usage</A></LI> <LI><A HREF="#10_23_2">Returns</A></LI> <LI><A HREF="#10_23_3">Description</A></LI> <LI><A HREF="#10_23_4">Example</A></LI> <LI><A HREF="#10_23_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsLangEncoding">cupsLangEncoding()</A> <UL> <LI><A HREF="#10_24_1">Usage</A></LI> <LI><A HREF="#10_24_2">Arguments</A></LI> <LI><A HREF="#10_24_3">Returns</A></LI> <LI><A HREF="#10_24_4">Description</A></LI> <LI><A HREF="#10_24_5">Example</A></LI> <LI><A HREF="#10_24_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsLangFlush">cupsLangFlush()</A> <UL> <LI><A HREF="#10_25_1">Usage</A></LI> <LI><A HREF="#10_25_2">Description</A></LI> <LI><A HREF="#10_25_3">Example</A></LI> <LI><A HREF="#10_25_4">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsLangFree">cupsLangFree()</A> <UL> <LI><A HREF="#10_26_1">Usage</A></LI> <LI><A HREF="#10_26_2">Arguments</A></LI> <LI><A HREF="#10_26_3">Description</A></LI> <LI><A HREF="#10_26_4">Example</A></LI> <LI><A HREF="#10_26_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsLangGet">cupsLangGet()</A> <UL> <LI><A HREF="#10_27_1">Usage</A></LI> <LI><A HREF="#10_27_2">Arguments</A></LI> <LI><A HREF="#10_27_3">Returns</A></LI> <LI><A HREF="#10_27_4">Description</A></LI> <LI><A HREF="#10_27_5">Example</A></LI> <LI><A HREF="#10_27_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsLangString">cupsLangString()</A> <UL> <LI><A HREF="#10_28_1">Usage</A></LI> <LI><A HREF="#10_28_2">Arguments</A></LI> <LI><A HREF="#10_28_3">Returns</A></LI> <LI><A HREF="#10_28_4">Description</A></LI> <LI><A HREF="#10_28_5">Example</A></LI> <LI><A HREF="#10_28_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsLastError">cupsLastError()</A> <UL> <LI><A HREF="#10_29_1">Usage</A></LI> <LI><A HREF="#10_29_2">Returns</A></LI> <LI><A HREF="#10_29_3">Description</A></LI> <LI><A HREF="#10_29_4">Example</A></LI> <LI><A HREF="#10_29_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsMarkOptions">cupsMarkOptions()</A> <UL> <LI><A HREF="#10_30_1">Usage</A></LI> <LI><A HREF="#10_30_2">Arguments</A></LI> <LI><A HREF="#10_30_3">Returns</A></LI> <LI><A HREF="#10_30_4">Description</A></LI> <LI><A HREF="#10_30_5">Example</A></LI> <LI><A HREF="#10_30_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsParseOptions">cupsParseOptions()</A> <UL> <LI><A HREF="#10_31_1">Usage</A></LI> <LI><A HREF="#10_31_2">Arguments</A></LI> <LI><A HREF="#10_31_3">Returns</A></LI> <LI><A HREF="#10_31_4">Description</A></LI> <LI><A HREF="#10_31_5">Example</A></LI> <LI><A HREF="#10_31_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsPrintFile">cupsPrintFile()</A> <UL> <LI><A HREF="#10_32_1">Usage</A></LI> <LI><A HREF="#10_32_2">Arguments</A></LI> <LI><A HREF="#10_32_3">Returns</A></LI> <LI><A HREF="#10_32_4">Description</A></LI> <LI><A HREF="#10_32_5">Example</A></LI> <LI><A HREF="#10_32_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsPrintFiles">cupsPrintFiles()</A> <UL> <LI><A HREF="#10_33_1">Usage</A></LI> <LI><A HREF="#10_33_2">Arguments</A></LI> <LI><A HREF="#10_33_3">Returns</A></LI> <LI><A HREF="#10_33_4">Description</A></LI> <LI><A HREF="#10_33_5">Example</A></LI> <LI><A HREF="#10_33_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsPutFd">cupsPutFd()</A> <UL> <LI><A HREF="#10_34_1">Usage</A></LI> <LI><A HREF="#10_34_2">Arguments</A></LI> <LI><A HREF="#10_34_3">Returns</A></LI> <LI><A HREF="#10_34_4">Description</A></LI> <LI><A HREF="#10_34_5">Example</A></LI> <LI><A HREF="#10_34_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsPutFile">cupsPutFile()</A> <UL> <LI><A HREF="#10_35_1">Usage</A></LI> <LI><A HREF="#10_35_2">Arguments</A></LI> <LI><A HREF="#10_35_3">Returns</A></LI> <LI><A HREF="#10_35_4">Description</A></LI> <LI><A HREF="#10_35_5">Example</A></LI> <LI><A HREF="#10_35_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsRasterClose">cupsRasterClose()</A> <UL> <LI><A HREF="#10_36_1">Usage</A></LI> <LI><A HREF="#10_36_2">Arguments</A></LI> <LI><A HREF="#10_36_3">Description</A></LI> <LI><A HREF="#10_36_4">Example</A></LI> <LI><A HREF="#10_36_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsRasterOpen">cupsRasterOpen()</A> <UL> <LI><A HREF="#10_37_1">Usage</A></LI> <LI><A HREF="#10_37_2">Arguments</A></LI> <LI><A HREF="#10_37_3">Returns</A></LI> <LI><A HREF="#10_37_4">Description</A></LI> <LI><A HREF="#10_37_5">Example</A></LI> <LI><A HREF="#10_37_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsRasterReadHeader">cupsRasterReadHeader()</A> <UL> <LI><A HREF="#10_38_1">Usage</A></LI> <LI><A HREF="#10_38_2">Arguments</A></LI> <LI><A HREF="#10_38_3">Returns</A></LI> <LI><A HREF="#10_38_4">Description</A></LI> <LI><A HREF="#10_38_5">Example</A></LI> <LI><A HREF="#10_38_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsRasterReadPixels">cupsRasterReadPixels()</A> <UL> <LI><A HREF="#10_39_1">Usage</A></LI> <LI><A HREF="#10_39_2">Arguments</A></LI> <LI><A HREF="#10_39_3">Returns</A></LI> <LI><A HREF="#10_39_4">Description</A></LI> <LI><A HREF="#10_39_5">Example</A></LI> <LI><A HREF="#10_39_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsRasterWriteHeader">cupsRasterWriteHeader()</A> <UL> <LI><A HREF="#10_40_1">Usage</A></LI> <LI><A HREF="#10_40_2">Arguments</A></LI> <LI><A HREF="#10_40_3">Returns</A></LI> <LI><A HREF="#10_40_4">Description</A></LI> <LI><A HREF="#10_40_5">Example</A></LI> <LI><A HREF="#10_40_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsRasterWritePixels">cupsRasterWritePixels()</A> <UL> <LI><A HREF="#10_41_1">Usage</A></LI> <LI><A HREF="#10_41_2">Arguments</A></LI> <LI><A HREF="#10_41_3">Returns</A></LI> <LI><A HREF="#10_41_4">Description</A></LI> <LI><A HREF="#10_41_5">Example</A></LI> <LI><A HREF="#10_41_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsServer">cupsServer()</A> <UL> <LI><A HREF="#10_42_1">Usage</A></LI> <LI><A HREF="#10_42_2">Returns</A></LI> <LI><A HREF="#10_42_3">Description</A></LI> <LI><A HREF="#10_42_4">Example</A></LI> <LI><A HREF="#10_42_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsSetDests">cupsSetDests()</A> <UL> <LI><A HREF="#10_43_1">Usage</A></LI> <LI><A HREF="#10_43_2">Arguments</A></LI> <LI><A HREF="#10_43_3">Description</A></LI> <LI><A HREF="#10_43_4">Example</A></LI> <LI><A HREF="#10_43_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsSetEncryption">cupsSetEncryption()</A> <UL> <LI><A HREF="#10_44_1">Usage</A></LI> <LI><A HREF="#10_44_2">Arguments</A></LI> <LI><A HREF="#10_44_3">Description</A></LI> <LI><A HREF="#10_44_4">Example</A></LI> <LI><A HREF="#10_44_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsSetPasswordCB">cupsSetPasswordCB()</A> <UL> <LI><A HREF="#10_45_1">Usage</A></LI> <LI><A HREF="#10_45_2">Arguments</A></LI> <LI><A HREF="#10_45_3">Description</A></LI> <LI><A HREF="#10_45_4">Example</A></LI> <LI><A HREF="#10_45_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsSetServer">cupsSetServer()</A> <UL> <LI><A HREF="#10_46_1">Usage</A></LI> <LI><A HREF="#10_46_2">Arguments</A></LI> <LI><A HREF="#10_46_3">Description</A></LI> <LI><A HREF="#10_46_4">Example</A></LI> <LI><A HREF="#10_46_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsSetUser">cupsSetUser()</A> <UL> <LI><A HREF="#10_47_1">Usage</A></LI> <LI><A HREF="#10_47_2">Arguments</A></LI> <LI><A HREF="#10_47_3">Description</A></LI> <LI><A HREF="#10_47_4">Example</A></LI> <LI><A HREF="#10_47_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsTempFd">cupsTempFd()</A> <UL> <LI><A HREF="#10_48_1">Usage</A></LI> <LI><A HREF="#10_48_2">Arguments</A></LI> <LI><A HREF="#10_48_3">Returns</A></LI> <LI><A HREF="#10_48_4">Description</A></LI> <LI><A HREF="#10_48_5">Example</A></LI> <LI><A HREF="#10_48_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsTempFile">cupsTempFile()</A> <UL> <LI><A HREF="#10_49_1">Usage</A></LI> <LI><A HREF="#10_49_2">Arguments</A></LI> <LI><A HREF="#10_49_3">Returns</A></LI> <LI><A HREF="#10_49_4">Description</A></LI> <LI><A HREF="#10_49_5">Example</A></LI> <LI><A HREF="#10_49_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#cupsUser">cupsUser()</A> <UL> <LI><A HREF="#10_50_1">Usage</A></LI> <LI><A HREF="#10_50_2">Returns</A></LI> <LI><A HREF="#10_50_3">Description</A></LI> <LI><A HREF="#10_50_4">Example</A></LI> <LI><A HREF="#10_50_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpBlocking">httpBlocking()</A> <UL> <LI><A HREF="#10_51_1">Usage</A></LI> <LI><A HREF="#10_51_2">Arguments</A></LI> <LI><A HREF="#10_51_3">Description</A></LI> <LI><A HREF="#10_51_4">Example</A></LI> <LI><A HREF="#10_51_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpCheck">httpCheck()</A> <UL> <LI><A HREF="#10_52_1">Usage</A></LI> <LI><A HREF="#10_52_2">Arguments</A></LI> <LI><A HREF="#10_52_3">Returns</A></LI> <LI><A HREF="#10_52_4">Description</A></LI> <LI><A HREF="#10_52_5">Example</A></LI> <LI><A HREF="#10_52_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpClearFields">httpClearFields()</A> <UL> <LI><A HREF="#10_53_1">Usage</A></LI> <LI><A HREF="#10_53_2">Arguments</A></LI> <LI><A HREF="#10_53_3">Description</A></LI> <LI><A HREF="#10_53_4">Example</A></LI> <LI><A HREF="#10_53_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpClose">httpClose()</A> <UL> <LI><A HREF="#10_54_1">Usage</A></LI> <LI><A HREF="#10_54_2">Arguments</A></LI> <LI><A HREF="#10_54_3">Description</A></LI> <LI><A HREF="#10_54_4">Example</A></LI> <LI><A HREF="#10_54_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpConnect">httpConnect()</A> <UL> <LI><A HREF="#10_55_1">Usage</A></LI> <LI><A HREF="#10_55_2">Arguments</A></LI> <LI><A HREF="#10_55_3">Returns</A></LI> <LI><A HREF="#10_55_4">Description</A></LI> <LI><A HREF="#10_55_5">Example</A></LI> <LI><A HREF="#10_55_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpConnectEncrypt">httpConnectEncrypt()</A> <UL> <LI><A HREF="#10_56_1">Usage</A></LI> <LI><A HREF="#10_56_2">Arguments</A></LI> <LI><A HREF="#10_56_3">Returns</A></LI> <LI><A HREF="#10_56_4">Description</A></LI> <LI><A HREF="#10_56_5">Example</A></LI> <LI><A HREF="#10_56_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpDecode64">httpDecode64()</A> <UL> <LI><A HREF="#10_57_1">Usage</A></LI> <LI><A HREF="#10_57_2">Arguments</A></LI> <LI><A HREF="#10_57_3">Returns</A></LI> <LI><A HREF="#10_57_4">Description</A></LI> <LI><A HREF="#10_57_5">Example</A></LI> <LI><A HREF="#10_57_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpDelete">httpDelete()</A> <UL> <LI><A HREF="#10_58_1">Usage</A></LI> <LI><A HREF="#10_58_2">Arguments</A></LI> <LI><A HREF="#10_58_3">Returns</A></LI> <LI><A HREF="#10_58_4">Description</A></LI> <LI><A HREF="#10_58_5">Example</A></LI> <LI><A HREF="#10_58_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpEncode64">httpEncode64()</A> <UL> <LI><A HREF="#10_59_1">Usage</A></LI> <LI><A HREF="#10_59_2">Arguments</A></LI> <LI><A HREF="#10_59_3">Returns</A></LI> <LI><A HREF="#10_59_4">Description</A></LI> <LI><A HREF="#10_59_5">Example</A></LI> <LI><A HREF="#10_59_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpEncryption">httpEncryption()</A> <UL> <LI><A HREF="#10_60_1">Usage</A></LI> <LI><A HREF="#10_60_2">Arguments</A></LI> <LI><A HREF="#10_60_3">Returns</A></LI> <LI><A HREF="#10_60_4">Description</A></LI> <LI><A HREF="#10_60_5">Example</A></LI> <LI><A HREF="#10_60_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpError">httpError()</A> <UL> <LI><A HREF="#10_61_1">Usage</A></LI> <LI><A HREF="#10_61_2">Arguments</A></LI> <LI><A HREF="#10_61_3">Returns</A></LI> <LI><A HREF="#10_61_4">Description</A></LI> <LI><A HREF="#10_61_5">Example</A></LI> <LI><A HREF="#10_61_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpFlush">httpFlush()</A> <UL> <LI><A HREF="#10_62_1">Usage</A></LI> <LI><A HREF="#10_62_2">Arguments</A></LI> <LI><A HREF="#10_62_3">Description</A></LI> <LI><A HREF="#10_62_4">Example</A></LI> <LI><A HREF="#10_62_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpGet">httpGet()</A> <UL> <LI><A HREF="#10_63_1">Usage</A></LI> <LI><A HREF="#10_63_2">Arguments</A></LI> <LI><A HREF="#10_63_3">Returns</A></LI> <LI><A HREF="#10_63_4">Description</A></LI> <LI><A HREF="#10_63_5">Example</A></LI> <LI><A HREF="#10_63_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpGets">httpGets()</A> <UL> <LI><A HREF="#10_64_1">Usage</A></LI> <LI><A HREF="#10_64_2">Arguments</A></LI> <LI><A HREF="#10_64_3">Returns</A></LI> <LI><A HREF="#10_64_4">Description</A></LI> <LI><A HREF="#10_64_5">Example</A></LI> <LI><A HREF="#10_64_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpGetDateString">httpGetDateString()</A> <UL> <LI><A HREF="#10_65_1">Usage</A></LI> <LI><A HREF="#10_65_2">Arguments</A></LI> <LI><A HREF="#10_65_3">Returns</A></LI> <LI><A HREF="#10_65_4">Description</A></LI> <LI><A HREF="#10_65_5">Example</A></LI> <LI><A HREF="#10_65_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpGetDateTime">httpGetDateTime()</A> <UL> <LI><A HREF="#10_66_1">Usage</A></LI> <LI><A HREF="#10_66_2">Arguments</A></LI> <LI><A HREF="#10_66_3">Returns</A></LI> <LI><A HREF="#10_66_4">Description</A></LI> <LI><A HREF="#10_66_5">Example</A></LI> <LI><A HREF="#10_66_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpGetField">httpGetField()</A> <UL> <LI><A HREF="#10_67_1">Usage</A></LI> <LI><A HREF="#10_67_2">Arguments</A></LI> <LI><A HREF="#10_67_3">Returns</A></LI> <LI><A HREF="#10_67_4">Description</A></LI> <LI><A HREF="#10_67_5">Example</A></LI> <LI><A HREF="#10_67_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpGetHostByName">httpGetHostByName()</A> <UL> <LI><A HREF="#10_68_1">Usage</A></LI> <LI><A HREF="#10_68_2">Arguments</A></LI> <LI><A HREF="#10_68_3">Returns</A></LI> <LI><A HREF="#10_68_4">Description</A></LI> <LI><A HREF="#10_68_5">Example</A></LI> </UL> </LI> <LI><A HREF="#httpGetLength">httpGetLength()</A> <UL> <LI><A HREF="#10_69_1">Usage</A></LI> <LI><A HREF="#10_69_2">Arguments</A></LI> <LI><A HREF="#10_69_3">Returns</A></LI> <LI><A HREF="#10_69_4">Description</A></LI> <LI><A HREF="#10_69_5">Example</A></LI> <LI><A HREF="#10_69_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpGetSubField">httpGetSubField()</A> <UL> <LI><A HREF="#10_70_1">Usage</A></LI> <LI><A HREF="#10_70_2">Arguments</A></LI> <LI><A HREF="#10_70_3">Returns</A></LI> <LI><A HREF="#10_70_4">Description</A></LI> <LI><A HREF="#10_70_5">Example</A></LI> <LI><A HREF="#10_70_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpHead">httpHead()</A> <UL> <LI><A HREF="#10_71_1">Usage</A></LI> <LI><A HREF="#10_71_2">Arguments</A></LI> <LI><A HREF="#10_71_3">Returns</A></LI> <LI><A HREF="#10_71_4">Description</A></LI> <LI><A HREF="#10_71_5">Example</A></LI> <LI><A HREF="#10_71_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpInitialize">httpInitialize()</A> <UL> <LI><A HREF="#10_72_1">Usage</A></LI> <LI><A HREF="#10_72_2">Description</A></LI> <LI><A HREF="#10_72_3">Example</A></LI> <LI><A HREF="#10_72_4">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpMD5">httpMD5()</A> <UL> <LI><A HREF="#10_73_1">Usage</A></LI> <LI><A HREF="#10_73_2">Arguments</A></LI> <LI><A HREF="#10_73_3">Returns</A></LI> <LI><A HREF="#10_73_4">Description</A></LI> <LI><A HREF="#10_73_5">Example</A></LI> <LI><A HREF="#10_73_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpMD5Final">httpMD5Final()</A> <UL> <LI><A HREF="#10_74_1">Usage</A></LI> <LI><A HREF="#10_74_2">Arguments</A></LI> <LI><A HREF="#10_74_3">Returns</A></LI> <LI><A HREF="#10_74_4">Description</A></LI> <LI><A HREF="#10_74_5">Example</A></LI> <LI><A HREF="#10_74_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpMD5String">httpMD5String()</A> <UL> <LI><A HREF="#10_75_1">Usage</A></LI> <LI><A HREF="#10_75_2">Arguments</A></LI> <LI><A HREF="#10_75_3">Returns</A></LI> <LI><A HREF="#10_75_4">Description</A></LI> <LI><A HREF="#10_75_5">Example</A></LI> <LI><A HREF="#10_75_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpOptions">httpOptions()</A> <UL> <LI><A HREF="#10_76_1">Usage</A></LI> <LI><A HREF="#10_76_2">Arguments</A></LI> <LI><A HREF="#10_76_3">Returns</A></LI> <LI><A HREF="#10_76_4">Description</A></LI> <LI><A HREF="#10_76_5">Example</A></LI> <LI><A HREF="#10_76_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpPost">httpPost()</A> <UL> <LI><A HREF="#10_77_1">Usage</A></LI> <LI><A HREF="#10_77_2">Arguments</A></LI> <LI><A HREF="#10_77_3">Returns</A></LI> <LI><A HREF="#10_77_4">Description</A></LI> <LI><A HREF="#10_77_5">Example</A></LI> <LI><A HREF="#10_77_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpPrintf">httpPrintf()</A> <UL> <LI><A HREF="#10_78_1">Usage</A></LI> <LI><A HREF="#10_78_2">Arguments</A></LI> <LI><A HREF="#10_78_3">Returns</A></LI> <LI><A HREF="#10_78_4">Description</A></LI> <LI><A HREF="#10_78_5">Example</A></LI> <LI><A HREF="#10_78_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpPut">httpPut()</A> <UL> <LI><A HREF="#10_79_1">Usage</A></LI> <LI><A HREF="#10_79_2">Arguments</A></LI> <LI><A HREF="#10_79_3">Returns</A></LI> <LI><A HREF="#10_79_4">Description</A></LI> <LI><A HREF="#10_79_5">Example</A></LI> <LI><A HREF="#10_79_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpRead">httpRead()</A> <UL> <LI><A HREF="#10_80_1">Usage</A></LI> <LI><A HREF="#10_80_2">Arguments</A></LI> <LI><A HREF="#10_80_3">Returns</A></LI> <LI><A HREF="#10_80_4">Description</A></LI> <LI><A HREF="#10_80_5">Example</A></LI> <LI><A HREF="#10_80_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpReconnect">httpReconnect()</A> <UL> <LI><A HREF="#10_81_1">Usage</A></LI> <LI><A HREF="#10_81_2">Arguments</A></LI> <LI><A HREF="#10_81_3">Returns</A></LI> <LI><A HREF="#10_81_4">Description</A></LI> <LI><A HREF="#10_81_5">Example</A></LI> <LI><A HREF="#10_81_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpSeparate">httpSeparate()</A> <UL> <LI><A HREF="#10_82_1">Usage</A></LI> <LI><A HREF="#10_82_2">Arguments</A></LI> <LI><A HREF="#10_82_3">Description</A></LI> <LI><A HREF="#10_82_4">Example</A></LI> <LI><A HREF="#10_82_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpSetField">httpSetField()</A> <UL> <LI><A HREF="#10_83_1">Usage</A></LI> <LI><A HREF="#10_83_2">Arguments</A></LI> <LI><A HREF="#10_83_3">Description</A></LI> <LI><A HREF="#10_83_4">Example</A></LI> <LI><A HREF="#10_83_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpStatus">httpStatus()</A> <UL> <LI><A HREF="#10_84_1">Usage</A></LI> <LI><A HREF="#10_84_2">Arguments</A></LI> <LI><A HREF="#10_84_3">Returns</A></LI> <LI><A HREF="#10_84_4">Description</A></LI> <LI><A HREF="#10_84_5">Example</A></LI> </UL> </LI> <LI><A HREF="#httpTrace">httpTrace()</A> <UL> <LI><A HREF="#10_85_1">Usage</A></LI> <LI><A HREF="#10_85_2">Arguments</A></LI> <LI><A HREF="#10_85_3">Returns</A></LI> <LI><A HREF="#10_85_4">Description</A></LI> <LI><A HREF="#10_85_5">Example</A></LI> <LI><A HREF="#10_85_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpUpdate">httpUpdate()</A> <UL> <LI><A HREF="#10_86_1">Usage</A></LI> <LI><A HREF="#10_86_2">Arguments</A></LI> <LI><A HREF="#10_86_3">Returns</A></LI> <LI><A HREF="#10_86_4">Description</A></LI> <LI><A HREF="#10_86_5">Example</A></LI> <LI><A HREF="#10_86_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#httpWrite">httpWrite()</A> <UL> <LI><A HREF="#10_87_1">Usage</A></LI> <LI><A HREF="#10_87_2">Arguments</A></LI> <LI><A HREF="#10_87_3">Returns</A></LI> <LI><A HREF="#10_87_4">Description</A></LI> <LI><A HREF="#10_87_5">Example</A></LI> <LI><A HREF="#10_87_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddBoolean">ippAddBoolean()</A> <UL> <LI><A HREF="#10_88_1">Usage</A></LI> <LI><A HREF="#10_88_2">Arguments</A></LI> <LI><A HREF="#10_88_3">Returns</A></LI> <LI><A HREF="#10_88_4">Description</A></LI> <LI><A HREF="#10_88_5">Example</A></LI> <LI><A HREF="#10_88_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddBooleans">ippAddBooleans()</A> <UL> <LI><A HREF="#10_89_1">Usage</A></LI> <LI><A HREF="#10_89_2">Arguments</A></LI> <LI><A HREF="#10_89_3">Returns</A></LI> <LI><A HREF="#10_89_4">Description</A></LI> <LI><A HREF="#10_89_5">Example</A></LI> <LI><A HREF="#10_89_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddDate">ippAddDate()</A> <UL> <LI><A HREF="#10_90_1">Usage</A></LI> <LI><A HREF="#10_90_2">Arguments</A></LI> <LI><A HREF="#10_90_3">Returns</A></LI> <LI><A HREF="#10_90_4">Description</A></LI> <LI><A HREF="#10_90_5">Example</A></LI> <LI><A HREF="#10_90_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddInteger">ippAddInteger()</A> <UL> <LI><A HREF="#10_91_1">Usage</A></LI> <LI><A HREF="#10_91_2">Arguments</A></LI> <LI><A HREF="#10_91_3">Returns</A></LI> <LI><A HREF="#10_91_4">Description</A></LI> <LI><A HREF="#10_91_5">Example</A></LI> <LI><A HREF="#10_91_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddIntegers">ippAddIntegers()</A> <UL> <LI><A HREF="#10_92_1">Usage</A></LI> <LI><A HREF="#10_92_2">Arguments</A></LI> <LI><A HREF="#10_92_3">Returns</A></LI> <LI><A HREF="#10_92_4">Description</A></LI> <LI><A HREF="#10_92_5">Example</A></LI> <LI><A HREF="#10_92_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddRange">ippAddRange()</A> <UL> <LI><A HREF="#10_93_1">Usage</A></LI> <LI><A HREF="#10_93_2">Arguments</A></LI> <LI><A HREF="#10_93_3">Returns</A></LI> <LI><A HREF="#10_93_4">Description</A></LI> <LI><A HREF="#10_93_5">Example</A></LI> <LI><A HREF="#10_93_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddRanges">ippAddRanges()</A> <UL> <LI><A HREF="#10_94_1">Usage</A></LI> <LI><A HREF="#10_94_2">Arguments</A></LI> <LI><A HREF="#10_94_3">Returns</A></LI> <LI><A HREF="#10_94_4">Description</A></LI> <LI><A HREF="#10_94_5">Example</A></LI> <LI><A HREF="#10_94_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddResolution">ippAddResolution()</A> <UL> <LI><A HREF="#10_95_1">Usage</A></LI> <LI><A HREF="#10_95_2">Arguments</A></LI> <LI><A HREF="#10_95_3">Returns</A></LI> <LI><A HREF="#10_95_4">Description</A></LI> <LI><A HREF="#10_95_5">Example</A></LI> <LI><A HREF="#10_95_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddResolutions">ippAddResolutions()</A> <UL> <LI><A HREF="#10_96_1">Usage</A></LI> <LI><A HREF="#10_96_2">Arguments</A></LI> <LI><A HREF="#10_96_3">Returns</A></LI> <LI><A HREF="#10_96_4">Description</A></LI> <LI><A HREF="#10_96_5">Example</A></LI> <LI><A HREF="#10_96_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddSeparator">ippAddSeparator()</A> <UL> <LI><A HREF="#10_97_1">Usage</A></LI> <LI><A HREF="#10_97_2">Arguments</A></LI> <LI><A HREF="#10_97_3">Returns</A></LI> <LI><A HREF="#10_97_4">Description</A></LI> <LI><A HREF="#10_97_5">Example</A></LI> <LI><A HREF="#10_97_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddString">ippAddString()</A> <UL> <LI><A HREF="#10_98_1">Usage</A></LI> <LI><A HREF="#10_98_2">Arguments</A></LI> <LI><A HREF="#10_98_3">Returns</A></LI> <LI><A HREF="#10_98_4">Description</A></LI> <LI><A HREF="#10_98_5">Example</A></LI> <LI><A HREF="#10_98_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippAddStrings">ippAddStrings()</A> <UL> <LI><A HREF="#10_99_1">Usage</A></LI> <LI><A HREF="#10_99_2">Arguments</A></LI> <LI><A HREF="#10_99_3">Returns</A></LI> <LI><A HREF="#10_99_4">Description</A></LI> <LI><A HREF="#10_99_5">Example</A></LI> <LI><A HREF="#10_99_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippDateToTime">ippDateToTime()</A> <UL> <LI><A HREF="#10_100_1">Usage</A></LI> <LI><A HREF="#10_100_2">Arguments</A></LI> <LI><A HREF="#10_100_3">Returns</A></LI> <LI><A HREF="#10_100_4">Description</A></LI> <LI><A HREF="#10_100_5">Example</A></LI> <LI><A HREF="#10_100_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippDelete">ippDelete()</A> <UL> <LI><A HREF="#10_101_1">Usage</A></LI> <LI><A HREF="#10_101_2">Arguments</A></LI> <LI><A HREF="#10_101_3">Description</A></LI> <LI><A HREF="#10_101_4">Example</A></LI> <LI><A HREF="#10_101_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippErrorString">ippErrorString()</A> <UL> <LI><A HREF="#10_102_1">Usage</A></LI> <LI><A HREF="#10_102_2">Arguments</A></LI> <LI><A HREF="#10_102_3">Returns</A></LI> <LI><A HREF="#10_102_4">Description</A></LI> <LI><A HREF="#10_102_5">Example</A></LI> <LI><A HREF="#10_102_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippFindAttribute">ippFindAttribute()</A> <UL> <LI><A HREF="#10_103_1">Usage</A></LI> <LI><A HREF="#10_103_2">Arguments</A></LI> <LI><A HREF="#10_103_3">Returns</A></LI> <LI><A HREF="#10_103_4">Description</A></LI> <LI><A HREF="#10_103_5">Example</A></LI> <LI><A HREF="#10_103_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippFindNextAttribute">ippFindNextAttribute()</A> <UL> <LI><A HREF="#10_104_1">Usage</A></LI> <LI><A HREF="#10_104_2">Arguments</A></LI> <LI><A HREF="#10_104_3">Returns</A></LI> <LI><A HREF="#10_104_4">Description</A></LI> <LI><A HREF="#10_104_5">Example</A></LI> <LI><A HREF="#10_104_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippLength">ippLength()</A> <UL> <LI><A HREF="#10_105_1">Usage</A></LI> <LI><A HREF="#10_105_2">Arguments</A></LI> <LI><A HREF="#10_105_3">Returns</A></LI> <LI><A HREF="#10_105_4">Description</A></LI> <LI><A HREF="#10_105_5">Example</A></LI> <LI><A HREF="#10_105_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippNew">ippNew()</A> <UL> <LI><A HREF="#10_106_1">Usage</A></LI> <LI><A HREF="#10_106_2">Returns</A></LI> <LI><A HREF="#10_106_3">Description</A></LI> <LI><A HREF="#10_106_4">Example</A></LI> <LI><A HREF="#10_106_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippPort">ippPort()</A> <UL> <LI><A HREF="#10_107_1">Usage</A></LI> <LI><A HREF="#10_107_2">Returns</A></LI> <LI><A HREF="#10_107_3">Description</A></LI> <LI><A HREF="#10_107_4">Example</A></LI> <LI><A HREF="#10_107_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippRead">ippRead()</A> <UL> <LI><A HREF="#10_108_1">Usage</A></LI> <LI><A HREF="#10_108_2">Arguments</A></LI> <LI><A HREF="#10_108_3">Returns</A></LI> <LI><A HREF="#10_108_4">Description</A></LI> <LI><A HREF="#10_108_5">Example</A></LI> <LI><A HREF="#10_108_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippSetPort">ippSetPort()</A> <UL> <LI><A HREF="#10_109_1">Usage</A></LI> <LI><A HREF="#10_109_2">Arguments</A></LI> <LI><A HREF="#10_109_3">Description</A></LI> <LI><A HREF="#10_109_4">Example</A></LI> <LI><A HREF="#10_109_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippTimeToDate">ippTimeToDate()</A> <UL> <LI><A HREF="#10_110_1">Usage</A></LI> <LI><A HREF="#10_110_2">Arguments</A></LI> <LI><A HREF="#10_110_3">Returns</A></LI> <LI><A HREF="#10_110_4">Description</A></LI> <LI><A HREF="#10_110_5">Example</A></LI> <LI><A HREF="#10_110_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ippWrite">ippWrite()</A> <UL> <LI><A HREF="#10_111_1">Usage</A></LI> <LI><A HREF="#10_111_2">Arguments</A></LI> <LI><A HREF="#10_111_3">Returns</A></LI> <LI><A HREF="#10_111_4">Description</A></LI> <LI><A HREF="#10_111_5">Example</A></LI> <LI><A HREF="#10_111_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdClose">ppdClose()</A> <UL> <LI><A HREF="#10_112_1">Usage</A></LI> <LI><A HREF="#10_112_2">Arguments</A></LI> <LI><A HREF="#10_112_3">Description</A></LI> <LI><A HREF="#10_112_4">Example</A></LI> <LI><A HREF="#10_112_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdCollect">ppdCollect()</A> <UL> <LI><A HREF="#10_113_1">Usage</A></LI> <LI><A HREF="#10_113_2">Arguments</A></LI> <LI><A HREF="#10_113_3">Returns</A></LI> <LI><A HREF="#10_113_4">Description</A></LI> <LI><A HREF="#10_113_5">Example</A></LI> <LI><A HREF="#10_113_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdConflicts">ppdConflicts()</A> <UL> <LI><A HREF="#10_114_1">Usage</A></LI> <LI><A HREF="#10_114_2">Arguments</A></LI> <LI><A HREF="#10_114_3">Returns</A></LI> <LI><A HREF="#10_114_4">Description</A></LI> <LI><A HREF="#10_114_5">Example</A></LI> <LI><A HREF="#10_114_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdEmit">ppdEmit()</A> <UL> <LI><A HREF="#10_115_1">Usage</A></LI> <LI><A HREF="#10_115_2">Arguments</A></LI> <LI><A HREF="#10_115_3">Returns</A></LI> <LI><A HREF="#10_115_4">Description</A></LI> <LI><A HREF="#10_115_5">Example</A></LI> <LI><A HREF="#10_115_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdEmitFd">ppdEmitFd()</A> <UL> <LI><A HREF="#10_116_1">Usage</A></LI> <LI><A HREF="#10_116_2">Arguments</A></LI> <LI><A HREF="#10_116_3">Returns</A></LI> <LI><A HREF="#10_116_4">Description</A></LI> <LI><A HREF="#10_116_5">Example</A></LI> <LI><A HREF="#10_116_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdEmitJCL">ppdEmitJCL()</A> <UL> <LI><A HREF="#10_117_1">Usage</A></LI> <LI><A HREF="#10_117_2">Arguments</A></LI> <LI><A HREF="#10_117_3">Returns</A></LI> <LI><A HREF="#10_117_4">Description</A></LI> <LI><A HREF="#10_117_5">Example</A></LI> <LI><A HREF="#10_117_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdFindAttr">ppdFindAttr()</A> <UL> <LI><A HREF="#10_118_1">Usage</A></LI> <LI><A HREF="#10_118_2">Arguments</A></LI> <LI><A HREF="#10_118_3">Returns</A></LI> <LI><A HREF="#10_118_4">Description</A></LI> <LI><A HREF="#10_118_5">Example</A></LI> <LI><A HREF="#10_118_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdFindChoice">ppdFindChoice()</A> <UL> <LI><A HREF="#10_119_1">Usage</A></LI> <LI><A HREF="#10_119_2">Arguments</A></LI> <LI><A HREF="#10_119_3">Returns</A></LI> <LI><A HREF="#10_119_4">Description</A></LI> <LI><A HREF="#10_119_5">Example</A></LI> <LI><A HREF="#10_119_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdFindMarkedChoice">ppdFindMarkedChoice()</A> <UL> <LI><A HREF="#10_120_1">Usage</A></LI> <LI><A HREF="#10_120_2">Arguments</A></LI> <LI><A HREF="#10_120_3">Returns</A></LI> <LI><A HREF="#10_120_4">Description</A></LI> <LI><A HREF="#10_120_5">Example</A></LI> <LI><A HREF="#10_120_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdFindNextAttr">ppdFindNextAttr()</A> <UL> <LI><A HREF="#10_121_1">Usage</A></LI> <LI><A HREF="#10_121_2">Arguments</A></LI> <LI><A HREF="#10_121_3">Returns</A></LI> <LI><A HREF="#10_121_4">Description</A></LI> <LI><A HREF="#10_121_5">Example</A></LI> <LI><A HREF="#10_121_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdFindOption">ppdFindOption()</A> <UL> <LI><A HREF="#10_122_1">Usage</A></LI> <LI><A HREF="#10_122_2">Arguments</A></LI> <LI><A HREF="#10_122_3">Returns</A></LI> <LI><A HREF="#10_122_4">Description</A></LI> <LI><A HREF="#10_122_5">Example</A></LI> <LI><A HREF="#10_122_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdIsMarked">ppdIsMarked()</A> <UL> <LI><A HREF="#10_123_1">Usage</A></LI> <LI><A HREF="#10_123_2">Arguments</A></LI> <LI><A HREF="#10_123_3">Returns</A></LI> <LI><A HREF="#10_123_4">Description</A></LI> <LI><A HREF="#10_123_5">Example</A></LI> <LI><A HREF="#10_123_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdMarkDefaults">ppdMarkDefaults()</A> <UL> <LI><A HREF="#10_124_1">Usage</A></LI> <LI><A HREF="#10_124_2">Arguments</A></LI> <LI><A HREF="#10_124_3">Description</A></LI> <LI><A HREF="#10_124_4">Example</A></LI> <LI><A HREF="#10_124_5">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdMarkOption">ppdMarkOption()</A> <UL> <LI><A HREF="#10_125_1">Usage</A></LI> <LI><A HREF="#10_125_2">Arguments</A></LI> <LI><A HREF="#10_125_3">Returns</A></LI> <LI><A HREF="#10_125_4">Description</A></LI> <LI><A HREF="#10_125_5">Example</A></LI> <LI><A HREF="#10_125_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdOpen">ppdOpen()</A> <UL> <LI><A HREF="#10_126_1">Usage</A></LI> <LI><A HREF="#10_126_2">Arguments</A></LI> <LI><A HREF="#10_126_3">Returns</A></LI> <LI><A HREF="#10_126_4">Description</A></LI> <LI><A HREF="#10_126_5">Example</A></LI> <LI><A HREF="#10_126_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdOpenFd">ppdOpenFd()</A> <UL> <LI><A HREF="#10_127_1">Usage</A></LI> <LI><A HREF="#10_127_2">Arguments</A></LI> <LI><A HREF="#10_127_3">Returns</A></LI> <LI><A HREF="#10_127_4">Description</A></LI> <LI><A HREF="#10_127_5">Example</A></LI> <LI><A HREF="#10_127_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdOpenFile">ppdOpenFile()</A> <UL> <LI><A HREF="#10_128_1">Usage</A></LI> <LI><A HREF="#10_128_2">Arguments</A></LI> <LI><A HREF="#10_128_3">Returns</A></LI> <LI><A HREF="#10_128_4">Description</A></LI> <LI><A HREF="#10_128_5">Example</A></LI> <LI><A HREF="#10_128_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdPageLength">ppdPageLength()</A> <UL> <LI><A HREF="#10_129_1">Usage</A></LI> <LI><A HREF="#10_129_2">Arguments</A></LI> <LI><A HREF="#10_129_3">Returns</A></LI> <LI><A HREF="#10_129_4">Description</A></LI> <LI><A HREF="#10_129_5">Example</A></LI> <LI><A HREF="#10_129_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdPageSize">ppdPageSize()</A> <UL> <LI><A HREF="#10_130_1">Usage</A></LI> <LI><A HREF="#10_130_2">Arguments</A></LI> <LI><A HREF="#10_130_3">Returns</A></LI> <LI><A HREF="#10_130_4">Description</A></LI> <LI><A HREF="#10_130_5">Example</A></LI> <LI><A HREF="#10_130_6">See Also</A></LI> </UL> </LI> <LI><A HREF="#ppdPageWidth">ppdPageWidth()</A> <UL> <LI><A HREF="#10_131_1">Usage</A></LI> <LI><A HREF="#10_131_2">Arguments</A></LI> <LI><A HREF="#10_131_3">Returns</A></LI> <LI><A HREF="#10_131_4">Description</A></LI> <LI><A HREF="#10_131_5">Example</A></LI> <LI><A HREF="#10_131_6">See Also</A></LI> </UL> </LI> </UL> <HR NOSHADE> <H1 ALIGN="RIGHT"><A NAME="1">Preface</A></H1> <P>This software programmers manual provides software programming information for the Common UNIX Printing System ("CUPS") Version 1.1.23.</P> <H2><A NAME="1_1">System Overview</A></H2> <P>CUPS provides a portable printing layer for UNIX®-based operating systems. It has been developed by <A HREF="http://www.easysw.com">Easy Software Products</A> to promote a standard printing solution for all UNIX vendors and users. CUPS provides the System V and Berkeley command-line interfaces.</P> <P>CUPS uses the Internet Printing Protocol ("IPP") as the basis for managing print jobs and queues. The Line Printer Daemon ("LPD") Server Message Block ("SMB"), and AppSocket (a.k.a. JetDirect) protocols are also supported with reduced functionality. CUPS adds network printer browsing and PostScript Printer Description ("PPD") based printing options to support real-world printing under UNIX.</P> <P>CUPS includes an image file RIP that supports printing of image files to non-PostScript printers. A customized version of GNU Ghostscript 7.05 for CUPS called ESP Ghostscript is available separately to support printing of PostScript files within the CUPS driver framework. Sample drivers for Dymo, EPSON, HP, and OKIDATA printers are included that use these filters.</P> <P>Drivers for thousands of printers are provided with our ESP Print Pro software, available at:</P> <PRE> <A HREF="http://www.easysw.com/printpro/">http://www.easysw.com/printpro/</A> </PRE> <P>CUPS is licensed under the GNU General Public License and GNU Library General Public License. Please contact Easy Software Products for commercial support and "binary distribution" rights.</P> <!-- NEED 2in --> <H2><A NAME="1_2">Document Overview</A></H2> <P>This software programmers manual is organized into the following sections:</P> <UL> <LI><A HREF="#OVERVIEW">1 - Printing System Overview</A></LI> <LI><A HREF="#CUPS_API">2 - The CUPS API</A></LI> <LI><A HREF="#WRITING_FILTERS">3 - Writing Filters</A></LI> <LI><A HREF="#WRITING_DRIVERS">4 - Writing Printer Drivers</A></LI> <LI><A HREF="#WRITING_BACKENDS">5 - Writing Backends</A></LI> <LI><A HREF="#LICENSE">A - Software License Agreement</A></LI> <LI><A HREF="#CONSTANTS">B - Constants</A></LI> <LI><A HREF="#STRUCTURES">C - Structures</A></LI> <LI><A HREF="#FUNCTIONS">D - Functions</A></LI> </UL> <H2><A NAME="1_3">Notation Conventions</A></H2> <P>Various font and syntax conventions are used in this guide. Examples and their meanings and uses are explained below: <CENTER> <TABLE WIDTH="80%"> <TR><TH>Example</TH><TD> </TD><TH>Description</TH></TR> <TR><TD> </TD></TR> <TR VALIGN="TOP"><TD><CODE>lpstat</CODE> <BR> <CODE>lpstat(1)</CODE></TD><TD> </TD><TD>The names of commands; the first mention of a command or function in a chapter is followed by a manual page section number.</TD></TR> <TR><TD> </TD></TR> <TR VALIGN="TOP"><TD><VAR>/var</VAR> <BR><VAR> /usr/share/cups/data/testprint.ps</VAR></TD><TD> </TD><TD> File and directory names.</TD></TR> <TR><TD> </TD></TR> <TR VALIGN="TOP"><TD NOWRAP><TT>Request ID is Printer-123</TT></TD><TD> </TD><TD>Screen output.</TD></TR> <TR><TD> </TD></TR> <TR VALIGN="TOP"><TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD><TD> </TD><TD>Literal user input; special keys like <KBD>ENTER</KBD> are in ALL CAPS.</TD></TR> <TR><TD> </TD></TR> <TR VALIGN="TOP"><TD>12.3</TD><TD> </TD><TD>Numbers in the text are written using the period (.) to indicate the decimal point.</TD></TR> </TABLE> </CENTER> <!-- NEED 3in --> </P> <H2><A NAME="1_4">Abbreviations</A></H2> The following abbreviations are used throughout this manual: <UL> <DL> <DT>kb</DT> <DD>Kilobytes, or 1024 bytes <BR> </DD> <DT>Mb</DT> <DD>Megabytes, or 1048576 bytes <BR> </DD> <DT>Gb</DT> <DD>Gigabytes, or 1073741824 bytes <BR> </DD> </DL> </UL> <H2><A NAME="1_5">Other References</A></H2> <UL> <DL> <DT>CUPS Software Administrators Manual</DT> <DD>An administration guide for the CUPS software. <BR> </DD> <DT>CUPS Software Users Manual</DT> <DD>An end-user guide for using the CUPS software. <BR> </DD> </DL> </UL> <H1 ALIGN="RIGHT"><A NAME="OVERVIEW">1 - Printing System Overview</A></H1> <P>This chapter provides an overview of how the Common UNIX Printing System works.</P> <H2><A NAME="2_1">The Printing Problem</A></H2> <P>For years<I> the printing problem</I> has plagued UNIX. Unlike Microsoft® Windows® or Mac OS, UNIX has no standard interface or system in place for supporting printers. Among the solutions currently available, the Berkeley and System V printing systems are the most prevalent.</P> <P>These printing systems support line printers (text only) or PostScript printers (text and graphics), and with some coaxing they can be made to support a full range of printers and file formats. However, because each varient of the UNIX operating system uses a different printing system than the next developing printer drivers for a wide range of printers and operating systems is extremely difficult. That combined with the limited volume of customers for each UNIX varient has forced most printer vendors to give up supporting UNIX entirely.</P> <P>CUPS is designed to eliminate<I> the printing problem</I>. One common printing system can be used by all UNIX varients to support the printing needs of users. Printer vendors can use its modular filter interface to develop a single driver program that supports a wide range of file formats with little or no effort. Since CUPS provides both the System V and Berkeley printing commands, users (and applications) can reap the benefits of this new technology with no changes.</P> <H2><A NAME="2_2">The Technology</A></H2> <P>CUPS is based upon an emerging Internet standard called the Internet Printing Protocol. IPP has been embraced by dozens of printer and printer server manufacturers and is supported by Microsoft Windows 2000.</P> <P>IPP defines a standard protocol for printing as well as managing print jobs and printer options like media size, resolution, and so forth. Like all IP-based protocols, IPP can be used locally or over the Internet to printers hundreds or thousands of miles away. Unlike other protocols, however, IPP also supports access control, authentication, and encryption, making it a much more capable and secure printing solution than older ones.</P> <P>IPP is layered on top of the Hyper-Text Transport Protocol ("HTTP") which is the basis of web servers on the Internet. This allows users to view documentation, check status information on a printer or server, and manage their printers, classes, and jobs using their web browser.</P> <P>CUPS provides a complete IPP/1.1 based printing system that provides Basic, Digest, and local certificate authentication and user, domain, or IP-based access control. TLS encryption will be available in future versions of CUPS.</P> <H2><A NAME="2_3">Jobs</A></H2> <P>Each file or set of files that is submitted for printing is called a<I> job</I>. Jobs are identified by a unique number starting at 1 and are assigned to a particular destination, usually a printer. Jobs can also have options associated with them such as media size, number of copies, and priority.</P> <H2><A NAME="2_4">Classes</A></H2> <P>CUPS supports collections of printers known as<I> classes</I>. Jobs sent to a class are forwarded to the first available printer in the class.</P> <H2><A NAME="2_5">Filters</A></H2> <P>Filters allow a user or application to print many types of files without extra effort. Print jobs sent to a CUPS server are filtered before sending them to a printer. Some filters convert job files to different formats that the printer can understand. Others perform page selection and ordering tasks.</P> <P>CUPS provides filters for printing many types of image files, HP-GL/2 files, PDF files, and text files. CUPS also supplies PostScript and image file Raster Image Processor ("RIP") filters that convert PostScript or image files into bitmaps that can be sent to a raster printer.</P> <H2><A NAME="2_6">Backends</A></H2> <P>Backends perform the most important task of all - they send the filtered print data to the printer.</P> <P>CUPS provides backends for printing over parallel, serial, and USB ports, and over the network via the IPP, JetDirect (AppSocket), and Line Printer Daemon ("LPD") protocols. Additional backends are available in network service packages such as the SMB backend included with the popular SAMBA software.</P> <P>Backends are also used to determine the available devices. On startup each backend is asked for a list of devices it supports, and any information that is available. This allows the parallel backend to tell CUPS that an EPSON Stylus Color 600 printer is attached to parallel port 1, for example.</P> <H2><A NAME="2_7">Printer Drivers</A></H2> <P>Printer drivers in CUPS consist of one of more filters specific to a printer. CUPS includes sample printer drivers for Hewlett-Packard LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color, and Stylus Photo printers. While these drivers do not generate optimal output for the different printer models, they do provide basic printing and demonstrate how you can write your own printer drivers and incorporate them into CUPS.</P> <H2><A NAME="2_8">Networking</A></H2> <P>Printers and classes on the local system are automatically shared with other systems on the network. This allows you to setup one system to print to a printer and use this system as a printer server or spool host for all of the others. Users may then select a local printer by name or a remote printer using "name@server".</P> <P>CUPS also provides<I> implicit classes</I>, which are collections of printers and/or classes with the same name. This allows you to setup multiple servers pointing to the same physical network printer, for example, so that you aren't relying on a single system for printing. Because this also works with printer classes, you can setup multiple servers and printers and never worry about a single point of failure unless all of the printers and servers go down!</P> <H1 ALIGN="RIGHT"><A NAME="CUPS_API">2 - The CUPS API</A></H1> <P>This chapter describes the CUPS Application Programmers Interface ("API").</P> <H2><A NAME="3_1">The CUPS API Library</A></H2> <P>The CUPS library provides a whole collection of interfaces needed to support the internal needs of the CUPS software as well as the needs of applications, filters, printer drivers, and backends.</P> <P>Unlike the rest of CUPS, the CUPS API library is provided under the GNU Library General Public License. This means that you can use the CUPS API library in both proprietary and open-source programs.</P> <P>Programs that use the CUPS API library typically will include the <CODE> <cups/cups.h></CODE> header file:</P> <UL> <PRE> #include <cups/cups.h> ... jobid = cupsPrintFile("myprinter", "filename.ps", "title", num_options, options); </PRE> </UL> <P>Use the <CODE>-lcups</CODE> compiler option when linking to the CUPS API library:</P> <UL> <PRE> <B>cc -o program program.c -lcups ENTER</B> </PRE> </UL> <P>Additional options and libraries may be required depending on the operating system and the location of the CUPS API library.</P> <H3><A NAME="3_1_1">Detecting the CUPS API Library in GNU Autoconf</A></H3> <P>GNU autoconf is a popular configuration tool used by many programs. Add the following lines to your<VAR> configure.in</VAR> file to check for the CUPS API library in your configuration script:</P> <UL> <PRE> AC_CHECK_LIB(socket,socket, if test "$uname" != "IRIX"; then LIBS="-lsocket $LIBS" else echo "Not using -lsocket since you are running IRIX." fi) AC_CHECK_LIB(nsl,gethostbyaddr, if test "$uname" != "IRIX"; then LIBS="-lnsl $LIBS" else echo "Not using -lnsl since you are running IRIX." fi) AC_CHECK_LIB(cups,httpConnect) </PRE> </UL> <H2><A NAME="3_2">Printing Services</A></H2> <P>The CUPS API library provides some basic printing services for applications that need to print files.</P> <H3><A NAME="3_2_1">Include Files</A></H3> <P>The include file used by all of these functions is <CODE> <cups/cups.h></CODE>:</P> <UL> <PRE> #include <cups/cups.h> </PRE> </UL> <H3><A NAME="3_2_2">Printing a File</A></H3> <P>The CUPS API provides two functions for printing files. The first is <CODE> cupsPrintFile</CODE> which prints a single named file:</P> <UL> <PRE> #include <cups/cups.h> ... int jobid; ... jobid = cupsPrintFile("<I>name</I>", "<I>filename</I>", "<I>title</I>", 0, NULL); </PRE> </UL> <P>The <CODE>name</CODE> string is the name of the printer or class to print to. The <CODE>filename</CODE> string is the name of the file to print. The <CODE>title</CODE> string is the name of the print job, e.g. "Acme Word Document".</P> <P>The return value is a unique ID number for the print job or 0 if there was an error.</P> <H3><A NAME="3_2_3">Printing Multiple Files</A></H3> <P>The second printing function is <CODE>cupsPrintFiles</CODE>:</P> <UL> <PRE> #include <cups/cups.h> ... int jobid; int num_files; const char *files[100]; ... jobid = cupsPrintFiles("name", <I>num_files</I>, <I>files</I>, "title", 0, NULL); </PRE> </UL> <P>Instead of passing a filename string as with <CODE>cupsPrintFile()</CODE> you pass a file count (<CODE>num_files</CODE>) and filename pointer array (<CODE>files</CODE>) for each file that you want to print.</P> <P>As with <CODE>cupsPrintFile()</CODE> the return value is a unique ID for the print job.</P> <H3><A NAME="3_2_4">Cancelling Jobs</A></H3> <P>The <CODE>cupsCancelJob()</CODE> function cancels a queued print job:</P> <UL> <PRE> #include <cups/cups.h> ... int jobid; int status; ... status = cupsCancelJob("<I>name</I>", <I>jobid</I>); </PRE> </UL> <P>The <CODE>name</CODE> string specifies the destination and is used to determine the server to send the request to. The <CODE>jobid</CODE> value is the integer returned from a previous <CODE>cupsPrintFile()</CODE> or <CODE>cupsPrintFiles()</CODE> call.</P> <P><CODE>cupsCancelJob()</CODE> returns <CODE>1</CODE> if the job was successfully cancelled and <CODE>0</CODE> if there was an error.</P> <H3><A NAME="3_2_5">Getting the Available Printers and Classes</A></H3> <P>The <CODE>cupsGetDests()</CODE> function can be used to get a list of the available printers, classes, and instances that a user has defined:</P> <UL> <PRE> #include <cups/cups.h> ... int num_dests; cups_dest_t *dests; ... num_dests = cupsGetDests(&dests); </PRE> </UL> <P>Each destination is stored in a <CODE>cups_dest_t</CODE> structure which defines the printer or class name, the instance name (if any), if it is the default destination, and the default options the user has defined for the destination:</P> <UL> <PRE> typedef struct /**** Destination ****/ { char *name, /* Printer or class name */ *instance; /* Local instance name or NULL */ int is_default; /* Is this printer the default? */ int num_options; /* Number of options */ cups_option_t *options; /* Options */ } cups_dest_t; </PRE> </UL> <P>The destinations are sorted by name and instance for your convenience. Once you have the list of available destinations, you can lookup a specific destination using the <CODE>cupsGetDest()</CODE> function:</P> <UL> <PRE> #include <cups/cups.h> ... int num_dests; cups_dest_t *dests; cups_dest_t *mydest; ... mydest = cupsGetDest("<I>name</I>", "<I>instance</I>", num_dests, dests); </PRE> </UL> <P>The <CODE>name</CODE> string is the printer or class name. You can pass a value of <CODE>NULL</CODE> to get the default destination.</P> <P>The <CODE>instance</CODE> string is the user-defined instance name. Pass <CODE>NULL</CODE> to select the default instance, e.g. "name" instead of "name/instance".</P> <H3><A NAME="3_2_6">Printing with Options</A></H3> <P>All of the previous printing examples have passed <CODE>0</CODE> and <CODE> NULL</CODE> for the last two arguments to the <CODE>cupsPrintFile()</CODE> and <CODE>cupsPrintFiles()</CODE> functions. These last two arguments are the number of options and a pointer to the option array:</P> <UL> <PRE> int cupsPrintFile(const char *name, const char *filename, const char *title, int num_options, cups_option_t *options); int cupsPrintFiles(const char *name, int num_files, const char **files, const char *title, int num_options, cups_option_t *options); </PRE> </UL> <P>The <CODE>cups_option_t</CODE> structure holds each option and its value. These are converted as needed and passed to the CUPS server when printing a file.</P> <P>The simplest way of handling options is to use the <CODE>num_options</CODE> and <CODE>options</CODE> members of the <CODE>cups_dest_t</CODE> structure described earlier:</P> <UL> <PRE> #include <cups/cups.h> ... int jobid; int num_dests; cups_dest_t *dests; cups_dest_t *mydest; ... mydest = cupsGetDest("<I>name</I>", "<I>instance</I>", num_dests, dests); jobid = cupsPrintFile(mydest->name, "filename", "title", mydest->num_options, mydest->options); </PRE> </UL> <P>This effectively uses the options a user has previous selected without a lot of code.</P> <H3><A NAME="3_2_7">Setting Printer Options</A></H3> <P>Options can also be set by your program using the <CODE> cupsAddOption()</CODE> function:</P> <UL> <PRE> #include <cups/cups.h> ... int num_options; cups_option_t *options; ... num_options = 0; options = NULL; ... num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options); num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options); num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options); num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options); </PRE> </UL> <P>The <CODE>name</CODE> string is the name of the option, and the <CODE> value</CODE> string is the value for that option.</P> <P>Each call to <CODE>cupsAddOption()</CODE> returns the new number of options. Since adding two options with the same name overwrites the first value with the second, do not assume that calling <CODE> cupsAddOptions()</CODE> 20 times will result in 20 options.</P> <P>Call <CODE>cupsFreeOptions</CODE> once you are done using the options:</P> <UL> <PRE> #include <cups/cups.h> ... int num_options; cups_option_t *options; ... cupsFreeOptions(num_options, options); </PRE> </UL> <H3><A NAME="3_2_8">Getting Errors</A></H3> <P>If any of the CUPS API printing functions returns an error, the reason for that error can be found by calling <CODE>cupsLastError()</CODE> and <CODE>ippErrorString()</CODE>. <CODE>cupsLastError()</CODE> returns the last IPP error code that was encountered. <CODE>ippErrorString()</CODE> converts the error code to a localized message string suitable for presentation to the user:</P> <UL> <PRE> #include <cups/cups.h> ... int jobid; ... if (jobid == 0) puts(ippErrorString(cupsLastError())); </PRE> </UL> <H3><A NAME="3_2_9">Passwords and Authentication</A></H3> <P>CUPS supports authentication of any request, including submission of print jobs. The default mechanism for getting the username and password is to use the login user and a password from the console.</P> <P>To support other types of applications, in particular Graphical User Interfaces ("GUIs"), the CUPS API provides functions to set the default username and to register a callback function that returns a password string.</P> <P>The <A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A> function is used to set a password callback in your program. Only one function can be used at any time.</P> <P>The <A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A> function sets the current username for authentication. This function can be called by your password callback function to change the current username as needed.</P> <P>The following example shows a simple password callback that gets a username and password from the user:</P> <UL> <PRE> #include <cups/cups.h> const char * my_password_cb(const char *prompt) { char user[65]; puts(prompt); /* Get a username from the user */ printf("Username: "); if (fgets(user, sizeof(user), stdin) == NULL) return (NULL); /* Strip the newline from the string and set the user */ user[strlen(user) - 1] = '\0'; cupsSetUser(user); /* Use getpass() to ask for the password... */ return (getpass("Password: ")); } ... cupsSetPasswordCB(my_password_cb); </PRE> </UL> <P>Similarly, a GUI interface could display the prompt string in a window with input fields for the username and password. The username should probably default to the value of <A HREF="#cupsUser"><CODE> cupsUser()</CODE></A> to make things easier on the user.</P> <H2><A NAME="3_3">PPD Services</A></H2> <P>CUPS includes functions to access and manipulate PostScript Printer Description ("PPD") files that are used with the printer drivers in CUPS.</P> <P>Each PPD file enumerates the available features provided by a printer, including conflict information for specific options (e.g. can't duplex output on envelopes.)</P> <H3><A NAME="3_3_1">Include Files</A></H3> <P>Include the <CODE><cups/ppd.h></CODE> header file to use the PPD functions:</P> <UL> <PRE> #include <cups/ppd.h> </PRE> </UL> <P>This header file is also included by the <CODE><cups/cups.h></CODE> header file.</P> <H3><A NAME="3_3_2">Getting a PPD File for a Printer</A></H3> <P>The <CODE>cupsGetPPD()</CODE> function retrieves the PPD file for the named printer or class:</P> <UL> <PRE> #include <cups/cups.h> ... const char *filename; filename = cupsGetPPD("<I>name</I>"); </PRE> </UL> <P>The <CODE>name</CODE> string is the name of the printer or class, including the remote server name as appropriate (e.g. "printer@server".)</P> <P>The return value is a pointer to a filename in static storage; this value is overwritten with each call to <CODE>cupsGetPPD()</CODE>. If the printer or class does not exist, a <CODE>NULL</CODE> pointer will be returned.</P> <H3><A NAME="3_3_3">Loading a PPD File</A></H3> <P>The <CODE>ppdOpenFile()</CODE> function "opens" a PPD file and loads it into memory:</P> <UL> <PRE> #include <cups/ppd.h> ... ppd_file_t *ppd; ppd = ppdOpenFile("<I>filename</I>"); </PRE> </UL> <P>The <CODE>filename</CODE> string is the name of the file to load, such as the value returned by the <CODE>cupsGetPPD()</CODE> function.</P> <P>The return value is a pointer to a structure describing the contents of the PPD file or NULL if the PPD file could not be read.</P> <H3><A NAME="3_3_4">Freeing PPD File Information</A></H3> <P>Once you are done using a PPD file, call the <CODE>ppdClose()</CODE> function to free all memory that has been used:</P> <UL> <PRE> #include <cups/ppd.h> ... ppd_file_t *ppd; ... ppdClose(ppd); </PRE> </UL> <H3><A NAME="3_3_5">The PPD File Structure</A></H3> <P>Each PPD file contains a number of capability attributes, printer options, and conflict definitions. The page size options also include the physical margins for the printer and the minimum and maximum sizes for the printer. All of this information is stored in the <CODE> ppd_file_t</CODE> structure.</P> <H4>Capabilities</H4> <P>Each PPD file contains a number of informational attributes that describe the capabilities of the printer. These are provided in the <CODE> ppd_file_t</CODE> structure in the following members: <CENTER> <TABLE BORDER="1" WIDTH="80%"> <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR> <TR><TD><CODE>accurate_screens</CODE></TD><TD><CODE>int</CODE></TD><TD>1 = supports accurate screens</TD></TR> <TR><TD><CODE>color_device</CODE></TD><TD><CODE>int</CODE></TD><TD>1 = color device</TD></TR> <TR><TD><CODE>colorspace</CODE></TD><TD><CODE>ppd_cs_t</CODE></TD><TD> Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB, PPD_CS_RGBK, PPD_CS_N</TD></TR> <TR><TD><CODE>contone_only</CODE></TD><TD><CODE>int</CODE></TD><TD>1 = printer is continuous tone only</TD></TR> <TR><TD><CODE>num_emulations <BR> emulations</CODE></TD><TD><CODE>int <BR> ppd_emul_t *</CODE></TD><TD>Emulations supported by the printer</TD> </TR> <TR><TD><CODE>flip_duplex</CODE></TD><TD><CODE>int</CODE></TD><TD>1 = need to flip odd pages when duplexing</TD></TR> <TR><TD><CODE>num_fonts <BR> fonts</CODE></TD><TD><CODE>int <BR> char **</CODE></TD><TD>The fonts available on the printer.</TD></TR> <TR><TD><CODE>jcl_begin <BR> jcl_ps <BR> jcl_end</CODE></TD><TD><CODE>char *</CODE></TD><TD>Job Control Language commands for PostScript output</TD></TR> <TR><TD><CODE>landscape</CODE></TD><TD><CODE>int</CODE></TD><TD> Landscape orientation, -90 or 90 degrees</TD></TR> <TR><TD><CODE>lang_encoding</CODE></TD><TD><CODE>char *</CODE></TD><TD> The character used for the option strings</TD></TR> <TR><TD><CODE>lang_version</CODE></TD><TD><CODE>char *</CODE></TD><TD> The language used for the options strings (English, French, etc.)</TD></TR> <TR><TD><CODE>language_level</CODE></TD><TD><CODE>int</CODE></TD><TD> PostScript language level, 1 to 3</TD></TR> <TR><TD><CODE>manual_copies</CODE></TD><TD><CODE>int</CODE></TD><TD>1 = Copies are done manually</TD></TR> <TR><TD><CODE>model_number</CODE></TD><TD><CODE>int</CODE></TD><TD> Driver-specific model number.</TD></TR> <TR><TD><CODE>patches</CODE></TD><TD><CODE>char *</CODE></TD><TD>Patch commands to send to the printer</TD></TR> <TR><TD><CODE>manufacturer</CODE></TD><TD><CODE>char *</CODE></TD><TD> The Manufacturer attribute from the PPD file, if any</TD></TR> <TR><TD><CODE>modelname</CODE></TD><TD><CODE>char *</CODE></TD><TD>The ModelName attribute from the PPD file</TD></TR> <TR><TD><CODE>nickname</CODE></TD><TD><CODE>char *</CODE></TD><TD>The NickName attribute from the PPD file, if any</TD></TR> <TR><TD><CODE>product</CODE></TD><TD><CODE>char *</CODE></TD><TD>The Product attribute from the PPD file, if any</TD></TR> <TR><TD><CODE>shortnickname</CODE></TD><TD><CODE>char *</CODE></TD><TD> The ShortNickName attribute from the PPD file, if any</TD></TR> <TR><TD><CODE>throughput</CODE></TD><TD><CODE>int</CODE></TD><TD>Number of pages per minute</TD></TR> <TR><TD><CODE>ttrasterizer</CODE></TD><TD><CODE>char *</CODE></TD><TD> The TruType font rasterizer (Type42)</TD></TR> <TR><TD><CODE>variable_sizes</CODE></TD><TD><CODE>int</CODE></TD><TD>1 = supports variable sizes</TD></TR> </TABLE> </CENTER> </P> <H4>Options and Groups</H4> <P>PPD files support multiple options, which are stored in <CODE> ppd_option_t</CODE> and <CODE>ppd_choice_t</CODE> structures by the PPD functions.</P> <P>Each option in turn is associated with a group stored in the <CODE> ppd_group_t</CODE> structure. Groups can be specified in the PPD file; if an option is not associated with a group then it is put in a "General" or "Extra" group depending on the option.</P> <P>Groups can also have sub-groups; CUPS currently limits the depth of sub-groups to 1 level to reduce programming complexity.</P> <H4>Conflicts</H4> <P>PPD files support specification of conflict conditions between different options. Conflicts are stored in <CODE>ppd_conflict_t</CODE> structures which specify the options that conflict with each other.</P> <H4>Page Sizes</H4> <P>PPD files specify all of the available pages sizes and the physical margins associated with them. These sizes are stored in <CODE> ppd_size_t</CODE> structures and are available in the <CODE>num_sizes</CODE> and <CODE>sizes</CODE> members of the <CODE>ppd_file_t</CODE> structure. You can lookup a particular page size with the <CODE> ppdPageWidth()</CODE>, <CODE>ppdPageLength()</CODE>, and <CODE> ppdPageSize()</CODE> functions:</P> <UL> <PRE> #include <cups/ppd.h> ... ppd_file_t *ppd; ppd_size_t *size; float width; float length; ... size = ppdPageSize(ppd, "<I>size</I>"); width = ppdPageWidth(ppd, "<I>size</I>"); length = ppdPageLength(ppd, "<I>size</I>"); </PRE> </UL> <P>The <CODE>size</CODE> string is the named page size option. The width and length are in points; there are 72 points per inch. The <CODE> ppd_size_t</CODE> structure contains the width, length, and margin information:</P> <UL> <PRE> typedef struct /**** Page Sizes ****/ { int marked; /* Page size selected? */ char name[41]; /* Media size option */ float width, /* Width of media in points */ length, /* Length of media in points */ left, /* Left printable margin in points */ bottom, /* Bottom printable margin in points */ right, /* Right printable margin in points */ top; /* Top printable margin in points */ } ppd_size_t; </PRE> </UL> <H4>Custom Page Sizes</H4> <P>Besides the standard page sizes listed in a PPD file, some printers support variable or custom page sizes. If <CODE>variables_sizes</CODE> is non-zero, the <CODE>custom_min</CODE>, <CODE>custom_max</CODE>, and <CODE> custom_margins</CODE> members of the <CODE>ppd_file_t</CODE> structure define the limits of the variable sizes.</P> <P>To get the resulting media size, use a page size string of <CODE> Custom.<I>width</I>x<I>length</I></CODE>, where <CODE>width</CODE> and <CODE> length</CODE> are integer values in points:</P> <UL> <PRE> Custom.612x792 [8.5 inches wide, 11 inches long] Custom.1224x792 [17 inches wide, 11 inches long] </PRE> </UL> <H3><A NAME="3_3_6">Marking Options</A></H3> <P>Before marking any user-defined options, call the <CODE> ppdMarkDefaults()</CODE> function to mark the default options from the PPD file:</P> <UL> <PRE> #include <cups/ppd.h> ... ppd_file_t *ppd; ... ppdMarkDefaults(ppd); </PRE> </UL> <P>Then call the <CODE>ppdMarkOption()</CODE> function to mark individual options:</P> <UL> <PRE> #include <cups/ppd.h> ... ppd_file_t *ppd; int conflicts; ... conflicts = ppdMarkOption(ppd, "<I>name</I>", "<I>value</I>"); </PRE> </UL> <P>The <CODE>name</CODE> and <CODE>value</CODE> strings choose a particular option and choice, respectively. The return value is 0 if there are not conflicts created by the selection.</P> <P>CUPS also provides a convenience function for marking all options in the <CODE>cups_option_t</CODE> structure:</P> <UL> <PRE> #include <cups/cups.h> ... ppd_file_t *ppd; int num_options; cups_option_t *options; int conflicts; ... conflicts = cupsMarkOptions(ppd, num_options, options); </PRE> </UL> <P>The <CODE>cupsMarkOptions()</CODE> function also handles mapping the IPP job template attributes to PPD options. The return value is the number of conflicts present.</P> <H3><A NAME="3_3_7">Checking for Conflicts</A></H3> <P>The <CODE>ppdMarkOption()</CODE> and <CODE>cupsMarkOptions()</CODE> functions return the number of conflicts with the currently marked options.</P> <P>Call the <CODE>ppdConflicts()</CODE> function to get the number of conflicts after you have marked all of the options:</P> <UL> <PRE> #include <cups/cups.h> ... ppd_file_t *ppd; int conflicts; ... conflicts = ppdConflicts(ppd); </PRE> </UL> <P>The return value is the number of conflicting options, or 0 if there are no conflicts.</P> <H1 ALIGN="RIGHT"><A NAME="WRITING_FILTERS">3 - Writing Filters</A></H1> <P>This chapter describes how to write a file filter for CUPS.</P> <H2><A NAME="4_1">Overview</A></H2> <P>File filters are programs that convert from one or more MIME types to another type. Filters use a common command-line and environment interface that allows them to be joined as needed to print files to any type of printer.</P> <H3><A NAME="4_1_1">Security Considerations</A></H3> <P>Filters are normally run as a non-priviledged user, so the major security consideration is resource utilization - filters should not depend on unlimited amounts of memory and disk space.</P> <H3><A NAME="4_1_2">Users and Groups</A></H3> <P>The default CUPS configuration runs filters as user "lp" and group "other".</P> <H3><A NAME="4_1_3">Temporary Files</A></H3> <P>Temporary files should be created in the directory specified by the "TMPDIR" environment variable. The <A HREF="#cupsTempFile"><CODE> cupsTempFile()</CODE></A> function can be used to safely choose temporary files in this directory.</P> <H3><A NAME="4_1_4">Sending Messages to the User</A></H3> <P>The CUPS scheduler collects messages sent to the standard error file by the filter. These messages are relayed to the user based upon the scheduler <CODE>LogLevel</CODE> directive.</P> <P>The type of message is determined by an initial prefix sent on each line:</P> <UL> <LI><CODE>DEBUG:</CODE> - a debug message</LI> <LI><CODE>INFO:</CODE> - an informational message</LI> <LI><CODE>WARNING:</CODE> - a warning message</LI> <LI><CODE>ERROR:</CODE> - an error message</LI> <LI><CODE>PAGE:</CODE> - a page accounting message</LI> </UL> <P>If the line of text does not begin with any of the above prefixes, it is treated as a debug message. Text following the prefix is copied to the <CODE>printer-state-message</CODE> attribute for the printer, and also added to the<VAR> error_log</VAR> unless it is an informational or page accounting message.</P> <H3><A NAME="4_1_5">Page Accounting</A></H3> <P>Page accounting messages are used to inform the server when one or more pages are printed. Each line has the form:</P> <UL> <PRE> PAGE: page-number copy-count </PRE> </UL> <P>The<I> page-number</I> field is the current page number, starting at 1. The<I> copy-count</I> field specifies the number of copies of that page that was produced.</P> <P>Page account messages are added to the<VAR> page_log</VAR> file and cause the <CODE>job-sheets-completed</CODE> attribute to be updated for the job.</P> <H3><A NAME="4_1_6">Command-Line Arguments</A></H3> <P>Every filter accepts exactly 6 or 7 command-line arguments:</P> <UL> <PRE> printer job user title copies options [filename] </PRE> <LI><CODE>printer</CODE> - The name of the printer queue (normally this is the name of the program being run)</LI> <LI><CODE>job</CODE> - The numeric job ID for the job being printed</LI> <LI><CODE>user</CODE> - The string from the <CODE>originating-user-name</CODE> attribute</LI> <LI><CODE>title</CODE> - The string from the <CODE>job-name</CODE> attribute</LI> <LI><CODE>copies</CODE> - The numeric value from the <CODE>number-copies</CODE> attribute</LI> <LI><CODE>options</CODE> - String representations of the job template attributes, separated by spaces. Boolean attributes are provided as "name" for true values and "noname" for false values. All other attributes are provided as "name=value" for single-valued attributes and "name=value1,value2,...,valueN" for set attributes</LI> <LI><CODE>filename</CODE> - The request file</LI> </UL> <P>The<I> filename</I> argument is only provided to the first filter in the chain; all filters<B> must</B> be prepared to read the print file from the standard input if the<I> filename</I> argument is omitted.</P> <H3><A NAME="4_1_7">Copy Generation</A></H3> <P>The<I> copies</I> argument specifies the number of copies to produce of the input file. In general, you should only generate copies if the<I> filename</I> argument is supplied. The only exception to this are filters that produce device-independent PostScript output (without any printer commands from the printer's PPD file), since the PostScript filter <CODE>pstops</CODE> is responsible for copy generation.</P> <H3><A NAME="4_1_8">Environment Variables</A></H3> <P>Every filter receives a fixed set of environment variables that can be used by the filter:</P> <UL> <LI><CODE>CHARSET</CODE> - The character set used by the client for this print file</LI> <LI><CODE>CONTENT_TYPE</CODE> - The original document type, such as "application/postscript"</LI> <LI><CODE>CUPS_DATADIR</CODE> - The location of CUPS data files</LI> <LI><CODE>CUPS_SERVERROOT</CODE> - The location of CUPS configuration files</LI> <LI><CODE>DEVICE_URI</CODE> - The output device URI</LI> <LI><CODE>LANG</CODE> - The language used by the client for this print file</LI> <LI><CODE>PATH</CODE> - The execution path exported to the filter</LI> <LI><CODE>PPD</CODE> - The full filename of the printer's PPD file</LI> <LI><CODE>PRINTER</CODE> - The name of the printer queue</LI> <LI><CODE>RIP_CACHE</CODE> - The maximum amount of memory each filter should use</LI> <LI><CODE>SOFTWARE</CODE> - The name of the CUPS software, typically "CUPS/1.1"</LI> <LI><CODE>TZ</CODE> - The local timezone</LI> <LI><CODE>USER</CODE> - The name of the current user</LI> </UL> <H2><A NAME="4_2">Dissecting the HP-GL/2 Filter</A></H2> <P>The HP-GL/2 filter (<CODE>hpgltops</CODE>) provided with CUPS is a complex program that converts HP-GL/2 files into device-independent PostScript output. Since it produces device-independent PostScript output, it does not need to handle copy generation or writing printer options from the printer's PPD file.</P> <H3><A NAME="4_2_1">Initializing the Filter</A></H3> <P>The first task of any filter is to ensure that the correct number of command-line arguments are present:</P> <UL> <PRE> if (argc < 6 || argc > 7) { fputs("ERROR: hpgltops job-id user title copies options [file]\n", stderr); return (1); } </PRE> </UL> <P>After this you open the print file or read from the standard input as needed:</P> <UL> <PRE> FILE *fp; /* * If we have 7 arguments, print the file named on the command-line. * Otherwise, send stdin instead... */ if (argc == 6) fp = stdin; else { /* * Try to open the print file... */ if ((fp = fopen(argv[6], "rb")) == NULL) { perror("ERROR: unable to open print file - "); return (1); } } </PRE> </UL> <P>Once the print file has been opened, options can be processed using the <A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A> and <A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A> functions:</P> <UL> <PRE> int num_options; cups_option_t *options; const char *val; /* * Process command-line options and write the prolog... */ options = NULL; num_options = cupsParseOptions(argv[5], 0, &options); if ((val = cupsGetOption("blackplot", num_options, options)) != NULL) shading = 0; if ((val = cupsGetOption("fitplot", num_options, options)) != NULL) FitPlot = 1; if ((val = cupsGetOption("penwidth", num_options, options)) != NULL) PenWidth = (float)atoi(val) * 0.001f; </PRE> </UL> <P>After the options have been processed, the filter writes PostScript code to the standard output based on the print file, closes the print file (as needed), and returns 0 to the scheduler.</P> <H2><A NAME="4_3">PostScript Output</A></H2> <P>Filters that produce PostScript output must generate output conforming to the Adobe Document Structuring Conventions, 3.0. In general this means the beginning of each file must begin with:</P> <UL> <PRE> %!PS-Adobe-3.0 %%BoundingBox: left bottom right top %%Pages: (atend) %%EndComments </PRE> </UL> <P>The<I> left</I>,<I> bottom</I>,<I> right</I>, and<I> top</I> values are integers in points from the lower-lefthand corner of the page.</P> <P>Pages must be surrounded by:</P> <UL> <PRE> %%Page: number number gsave ... grestore showpage </PRE> </UL> <P>And the end of each file must contain:</P> <UL> <PRE> %%Trailer %%Pages: number-pages %%EOF </PRE> </UL> <P>These comments allow the PostScript filter to correctly perform page accounting, copy generation, N-up printing, and so forth.</P> <H1 ALIGN="RIGHT"><A NAME="WRITING_DRIVERS">4 - Writing Printer Drivers</A> </H1> <P>This chapter discusses how to write a printer driver, which is a special filter program that converts CUPS raster data into the appropriate commands and data required for a printer.</P> <H2><A NAME="5_1">Overview</A></H2> <P>Raster printers utilitize PPD files that specify one or more device-specific filters that handle converting print files for the printer. The simplest raster printer drivers provide a single filter that converts CUPS raster data to the printer's native format.</P> <H3><A NAME="5_1_1">CUPS Raster Data</A></H3> <P>CUPS raster data (<CODE>application/vnd.cups-raster</CODE>) consists of a stream of raster page descriptions produced by one of the RIP filters, such as <CODE>pstoraster</CODE> or <CODE>imagetoraster</CODE>.</P> <P>Each page of data begins with a page dictionary structure called <A HREF="#cups_raster_header_t"> <CODE>cups_raster_header_t</CODE></A>. This structure contains the colorspace, bits per color, media size, media type, hardware resolution, and so forth.</P> <P>After the page dictionary comes the page data which is a full-resolution, uncompressed bitmap representing the page in the printer's output colorspace.</P> <H3><A NAME="5_1_2">Page Accounting</A></H3> <P>Printer drivers must handle all page accounting. This means they must send "PAGE:" messages to the standard error file for each page (and in many cases, copy) sent to the printer.</P> <H3><A NAME="5_1_3">Color Management</A></H3> <P>Printer drivers can implement their color management via the <CODE> cupsColorProfile</CODE> attributes in the PPD file or internally in the driver from a device-independent colorspace. In general, color management performed by the RIP filters is more efficient than that performed inside printer drivers.</P> <P>For example, the <CODE>pstoraster</CODE> filter often only has to perform a color conversion once each time the color is used for multiple output pixels, while the raster filter must convert every pixel on the page.</P> <H3><A NAME="5_1_4">Device and Bitmap Variables</A></H3> <P>Besides the standard PostScript page device dictionary variables defined in the Adobe PostScript Level 3 reference manual, the CUPS filters support additional variables that are passed in the page device dictionary header for the page and in some cases control the type of raster data that is generated: <CENTER> <TABLE BORDER="1" WIDTH="90%"> <TR><TH>Variable</TH><TH>Type</TH><TH>Description</TH></TR> <TR><TD>cupsWidth</TD><TD>read-only integer</TD><TD>Width of bitmap in pixels</TD></TR> <TR><TD>cupsHeight</TD><TD>read-only integer</TD><TD>Height of bitmap in pixels</TD></TR> <TR><TD>cupsMediaType</TD><TD>read-write integer</TD><TD>Device-specific media type code</TD></TR> <TR><TD>cupsBitsPerColor</TD><TD>read-write integer</TD><TD>Number of bits per color; 1, 2, 4, and 8 are currently supported</TD></TR> <TR><TD>cupsBitsPerPixel</TD><TD>read-only integer</TD><TD>Number of bits per pixel; 1 to 32</TD></TR> <TR><TD>cupsBytesPerLine</TD><TD>read-only integer</TD><TD>Number of bytes per line of raster graphics</TD></TR> <TR><TD>cupsColorOrder</TD><TD>read-write enum</TD><TD>The order of color values in the bitmap: <UL> <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK CMYK CMYK</LI> <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC MMM YYY KKK</LI> <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC ... MMM ... YYY ... KKK ...</LI> </UL> </TD></TR> <TR><TD>cupsColorSpace</TD><TD>read-write enum</TD><TD>The colorspace of the bitmap: <UL> <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)</LI> <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue</LI> <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha</LI> <LI><CODE>CUPS_CSPACE_K</CODE> - Black</LI> <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow</LI> <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan</LI> <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black</LI> <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black</LI> <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow</LI> <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow, light cyan, light magenta</LI> <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic magenta, metallic cyan, black</LI> <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic magenta, metallic cyan, metallic grey (silver)</LI> <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white pigment)</LI> <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)</LI> <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)</LI> </UL> </TD></TR> <TR><TD>cupsCompression</TD><TD>read-write integer</TD><TD> Device-specific compression type code</TD></TR> <TR><TD>cupsRowCount</TD><TD>read-write integer</TD><TD>Device-specific row count value</TD></TR> <TR><TD>cupsRowFeed</TD><TD>read-write integer</TD><TD>Device-specific row feed value</TD></TR> <TR><TD>cupsRowStep</TD><TD>read-write integer</TD><TD>Device-specific row step value</TD></TR> </TABLE> </CENTER> </P> <P>Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit per color are transmitted to the raster driver in KCMY colorspace; the driver is responsible for producing the correct separation of normal and light cyan and magenta inks.</P> <H2><A NAME="5_2">Dissecting the HP-PCL Driver</A></H2> <P>The HP-PCL driver provided with CUPS (<CODE>rastertohp</CODE>) converts bitmap data from the raster filters into HP-PCL commands for most PCL-compatible printers. The actual format of the raster data is controlled by the PPD file being used -<VAR> deskjet.ppd</VAR> or<VAR> laserjet.ppd</VAR>.</P> <H3><A NAME="5_2_1">PPD Files</A></H3> <P>PPD files play an important part of all raster printer drivers. Options defined in the PPD file contain PostScript commands that control the raster data that is sent to the printer driver.</P> <P>A typical CUPS printer driver will include <CODE>ColorModel</CODE>, <CODE> InputSlot</CODE>, <CODE>PageSize</CODE>, <CODE>PageRegion</CODE>, and <CODE> Resolution</CODE> options. Each option is shown using the standard PPD format:</P> <UL> <PRE> *OpenUI *PageSize/Media Size: PickOne *OrderDependency: 10 AnySetup *PageSize *DefaultPageSize: Letter *PageSize Letter/US Letter: "<< /PageSize [612 792] /ImagingBBox null >> setpagedevice" *End *PageSize Legal/US Legal: "<< /PageSize [612 1008] /ImagingBBox null >> setpagedevice" *End *PageSize A4/A4: "<< /PageSize [595 842] /ImagingBBox null >> setpagedevice" *End *CloseUI: *PageSize </PRE> </UL> <P>The <CODE>OpenUI</CODE> keyword specifies the new option. The first name is the option with an asterisk (*) in front of it. The first name is usually followed by a slash (/) and a human-readable version of the option name.</P> <P>Every option<B> must</B> have a default value, specified using the <CODE> Default<I>Option</I></CODE> keyword.</P> <P>Each option begins with the option name followed by the computer and human-readable values. The PostScript commands follow these inside double quotes. PostScript commands can be provided on a single line:</P> <UL> <PRE> *PageSize A4/A4: "<</PageSize[595 842]/ImagingBBox null>> setpagedevice" </PRE> </UL> <P>or broken down on separate lines using the <CODE>End</CODE> keyword to terminate them:</P> <UL> <PRE> *PageSize A4/A4: "<< /PageSize [595 842] /ImagingBBox null >> setpagedevice" *End </PRE> </UL> <P>The choice of the two formats is usually esthetic. However, each line in a PPD file must not exceed 255 characters, so if your PostScript commands are long you may need to break them up on separate lines.</P> <H3><A NAME="5_2_2">Reading Raster Data</A></H3> <P>As with any filter, your printer driver should handle raster data from a filename specified on the command-line or from the standard input. The <A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A> function opens a raster stream for printing:</P> <UL> <PRE> int fd; /* File descriptor */ cups_raster_t *ras; /* Raster stream for printing */ /* * Check for valid arguments... */ if (argc < 6 || argc > 7) { /* * We don't have the correct number of arguments; write an error message * and return. */ fputs("ERROR: rastertopcl job-id user title copies options [file]\n", stderr); return (1); } /* * Open the page stream... */ if (argc == 7) { if ((fd = open(argv[6], O_RDONLY)) == -1) { perror("ERROR: Unable to open raster file - "); sleep(1); return (1); } } else fd = 0; ras = cupsRasterOpen(fd, CUPS_RASTER_READ); </PRE> </UL> <P>Once you have opened the raster stream you just need to read each page and print it:</P> <UL> <PRE> cups_raster_header_t header; int y; unsigned char data[8192]; while (cupsRasterReadHeader(ras, &header)) { ... initialize the printer ... for (y = header.cupsHeight; y > 0; y ++) { cupsRasterReadPixels(ras, data, header.cupsBytesPerLine); ... send raster line to printer ... } } </PRE> </UL> <P>After you have processed all pages, close the raster stream and return:</P> <UL> <PRE> cupsRasterClose(ras); return (0); </PRE> </UL> <H1 ALIGN="RIGHT"><A NAME="WRITING_BACKENDS">5 - Writing Backends</A></H1> <P>This chapter describes how to write a backend for CUPS. Backends communicate directly with printers and allow printer drivers and filters to send data using any type of connection transparently.</P> <H2><A NAME="6_1">Overview</A></H2> <P>Backends are special filters that communicate with printers directly. They are treated slightly differently than filters, however, and have some unique requirements.</P> <H3><A NAME="6_1_1">Security Considerations</A></H3> <P>Backends are run as the root user, so special care must be taken to avoid potential security violations. In particular, remember that a backend will be able to manipulate disk files, devices, and other resources that potentially could damage a system or printer.</P> <H3><A NAME="6_1_2">Command-Line Arguments</A></H3> <P>Besides the standard filter arguments, backends are also run with no arguments to get a list of available devices. This discovery process is described later in this chapter.</P> <H3><A NAME="6_1_3">Copy Generation</A></H3> <P>Like filters, backends should send multiple copies of the print file only if a filename is supplied on the command-line. Otherwise the backend should assume that the upstream filter has already added the necessary commands or data to produce the multiple copies.</P> <H3><A NAME="6_1_4">Page Accounting</A></H3> <P>Backend filters generally do not do page accounting, however they should at a minimum produce a single page message for each copy that is produced when a filename is present on the command-line. This is because the user selected "raw" printing and no other accounting information is possible.</P> <H3><A NAME="6_1_5">Exclusive Access</A></H3> <P>Backends that talk to local character or block devices should open the device file in exclusive mode (<CODE>O_EXCL</CODE>) to cooperate with other printers defined for the same device.</P> <H3><A NAME="6_1_6">Retries</A></H3> <P>All backends<B> must</B> retry connections to the device. This includes backends that talk to local character or block devices, as the user may define more than one printer queue pointing at the same physical device.</P> <P>To prevent excess CPU utilitization, the backend should go to sleep for an amount of time between retries; the CUPS-supplied backends retry once every 30 seconds.</P> <H2><A NAME="6_2">Dissecting the Serial Port Backend</A></H2> <P>The serial port backend provides support for serial printers. Since it does everything a good backend needs to do, it provides an excellent example of what to do.</P> <H3><A NAME="6_2_1">Supporting Device Discovery</A></H3> <P>As previously noted, backends are special filter programs that talk to printer devices. Another task a backend must perform is to list the available devices it supports. The backend lists the available devices when no additioanl arguments are supplied on the command-line (i.e. just the command name...)</P> <P>The serial backend lists devices by looking at serial port files in the<VAR> /dev</VAR> directory, by consulting a hardware inventory (IRIX), and in some cases by trying to open the ports to see if they actually exist.</P> <P>Once it finds a serial port it writes a single line for each port to the standard output file. Each line looks like this:</P> <UL> <PRE> serial serial:/dev/ttyS0?baud=115200 "Unknown" "Serial Port 1" </PRE> </UL> <P>The first word "serial" is the<I> device class</I>; this identifies the class of device which can be used to categorize it in user interfaces. CUPS currently recognizes the following classes:</P> <UL> <LI>"file" - a disk file.</LI> <LI>"direct" - a parallel or fixed-rate serial data port, currently used for Centronics, IEEE-1284, and USB printer ports.</LI> <LI>"serial" - a variable-rate serial port.</LI> <LI>"network" - a network connection, typically via AppSocket, HTTP, IPP, LPD, or SMB/CIFS protocols.</LI> </UL> <P>After the device class is the<I> device URI</I>, in this case "serial:/dev/ttyS0?baud=115200". This is the URI that should be used by the user to select this port. For serial ports, the "baud=115200" specifies the maximum baud rate supported by the port - the actual value will vary based on the speed the user selects for the printer.</P> <P>The last two strings are the model and description for the port. The "Unknown" string means that the printer model is unknown - some devices are able to provide a make and model such as "HP DeskJet" that allows users and software to choose an appropriate printer driver more easily. Both the model and description must be enclosed inside double quotes.</P> <H3><A NAME="6_2_2">Opening the Serial Port</A></H3> <P>As noted previously, all backends should open device files in exclusive mode, and retry as needed until the port is available. The serial port does this using a <CODE>do-while</CODE> loop:</P> <UL> <PRE> do { if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1) { if (errno == EBUSY) { fputs("INFO: Serial port busy; will retry in 30 seconds...\n", stderr); sleep(30); } else { perror("ERROR: Unable to open serial port device file"); return (1); } } } while (fd < 0); </PRE> </UL> <P>If the port is busy or in use by another process, the backend will go to sleep for 30 seconds and try again. If another error is detected a message is sent to the user and the backend aborts the print job until the problem can be corrected.</P> <H3><A NAME="6_2_3">Writing Data to the Port</A></H3> <P>Network and character devices pose an interesting problem when writing data to the port - they may not be able to write all of the bytes in your buffer before returning. To work around this problem you must loop until all bytes have been written:</P> <UL> <PRE> while (nbytes > 0) { if ((wbytes = write(fd, bufptr, nbytes)) < 0) if (errno == ENOTTY) wbytes = write(fd, bufptr, nbytes); if (wbytes < 0) { perror("ERROR: Unable to send print file to printer"); break; } nbytes -= wbytes; bufptr += wbytes; } </PRE> </UL> <P>The check for the <CODE>ENOTTY</CODE> error is needed on some platforms to clear an error from a previous <CODE>ioctl()</CODE> call.</P> <H3><A NAME="6_2_4">Finishing Up</A></H3> <P>Once you have sent the print file, return 0 if the file printed successfully or 1 if it did not. This will allow the scheduler to stop the print job if there is a device error, preserving the print job for later printing once the problem has been corrected.</P> <H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1> <H2 ALIGN="CENTER"><A NAME="7_1">Common UNIX Printing System License Agreement</A></H2> <P ALIGN="CENTER">Copyright 1997-2005 by Easy Software Products <BR> 44141 AIRPORT VIEW DR STE 204 <BR> HOLLYWOOD, MARYLAND 20636 USA <BR> <BR> Voice: +1.301.373.9600 <BR> Email: <A HREF="mailto:cups-info@cups.org">cups-info@cups.org</A> <BR> WWW: <A HREF="http://www.cups.org">http://www.cups.org</A></P> <H3><A NAME="7_1_1">Introduction</A></H3> <P>The Common UNIX Printing System<SUP>TM</SUP>, ("CUPS<SUP>TM</SUP>"), is provided under the GNU General Public License ("GPL") and GNU Library General Public License ("LGPL"), Version 2, with exceptions for Apple operating systems and the OpenSSL toolkit. A copy of the exceptions and licenses follow this introduction.</P> <P>The GNU LGPL applies to the CUPS API library, located in the "cups" subdirectory of the CUPS source distribution and in the "cups" include directory and library files in the binary distributions. The GNU GPL applies to the remainder of the CUPS distribution, including the "pdftops" filter which is based upon Xpdf and the CUPS imaging library.</P> <P>For those not familiar with the GNU GPL, the license basically allows you to:</P> <UL> <LI>Use the CUPS software at no charge.</LI> <LI>Distribute verbatim copies of the software in source or binary form.</LI> <LI>Sell verbatim copies of the software for a media fee, or sell support for the software.</LI> <LI>Distribute or sell printer drivers and filters that use CUPS so long as source code is made available under the GPL.</LI> </UL> <P>What this license<B> does not</B> allow you to do is make changes or add features to CUPS and then sell a binary distribution without source code. You must provide source for any new drivers, changes, or additions to the software, and all code must be provided under the GPL or LGPL as appropriate. The only exceptions to this are the portions of the CUPS software covered by the Apple operating system license exceptions outlined later in this license agreement.</P> <P>The GNU LGPL relaxes the "link-to" restriction, allowing you to develop applications that use the CUPS API library under other licenses and/or conditions as appropriate for your application.</P> <H3><A NAME="7_1_2">License Exceptions</A></H3> <P>In addition, as the copyright holder of CUPS, Easy Software Products grants the following special exceptions:</P> <OL> <LI><B>Apple Operating System Development License Exception</B>; <OL TYPE="a"> <LI>Software that is developed by any person or entity for an Apple Operating System ("Apple OS-Developed Software"), including but not limited to Apple and third party printer drivers, filters, and backends for an Apple Operating System, that is linked to the CUPS imaging library or based on any sample filters or backends provided with CUPS shall not be considered to be a derivative work or collective work based on the CUPS program and is exempt from the mandatory source code release clauses of the GNU GPL. You may therefore distribute linked combinations of the CUPS imaging library with Apple OS-Developed Software without releasing the source code of the Apple OS-Developed Software. You may also use sample filters and backends provided with CUPS to develop Apple OS-Developed Software without releasing the source code of the Apple OS-Developed Software.</LI> <LI>An Apple Operating System means any operating system software developed and/or marketed by Apple Computer, Inc., including but not limited to all existing releases and versions of Apple's Darwin, Mac OS X, and Mac OS X Server products and all follow-on releases and future versions thereof.</LI> <LI>This exception is only available for Apple OS-Developed Software and does not apply to software that is distributed for use on other operating systems.</LI> <LI>All CUPS software that falls under this license exception have the following text at the top of each source file:<BLOCKQUOTE>This file is subject to the Apple OS-Developed Software exception.</BLOCKQUOTE></LI> </OL> </LI> <LI><B>OpenSSL Toolkit License Exception</B>; <OL TYPE="a"> <LI>Easy Software Products explicitly allows the compilation and distribution of the CUPS software with the OpenSSL Toolkit.</LI> </OL> </LI> </OL> <P>No developer is required to provide these exceptions in a derived work.</P> <H3><A NAME="7_1_3">Trademarks</A></H3> <P>Easy Software Products has trademarked the Common UNIX Printing System, CUPS, and CUPS logo. You may use these names and logos in any direct port or binary distribution of CUPS. Please contact Easy Software Products for written permission to use them in derivative products. Our intention is to protect the value of these trademarks and ensure that any derivative product meets the same high-quality standards as the original.</P> <H3><A NAME="7_1_4">Binary Distribution Rights</A></H3> <P>Easy Software Products also sells rights to the CUPS source code under a binary distribution license for vendors that are unable to release source code for their drivers, additions, and modifications to CUPS under the GNU GPL and LGPL. For information please contact us at the address shown above.</P> <P>The Common UNIX Printing System provides a "pdftops" filter that is based on the Xpdf software. For binary distribution licensing of this software, please contact:<BLOCKQUOTE> Derek B. Noonburg <BR> Email: <A HREF="mailto:derekn@foolabs.com">derekn@foolabs.com</A> <BR> WWW: <A HREF="http://www.foolabs.com/xpdf/"> http://www.foolabs.com/xpdf/</A></BLOCKQUOTE></P> <H3><A NAME="7_1_5">Support</A></H3> <P>Easy Software Products sells software support for CUPS as well as a commercial printing product based on CUPS called ESP Print Pro. You can find out more at our web site:</P> <UL> <PRE> <A HREF="http://www.easysw.com/">http://www.easysw.com/</A> </PRE> </UL> <!-- NEW PAGE --> <H2><A NAME="7_2">GNU GENERAL PUBLIC LICENSE</A></H2> <P>Version 2, June 1991</P> <PRE> Copyright 1989, 1991 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. </PRE> <H3><A NAME="7_2_1">Preamble</A></H3> <P>The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.</P> <P>When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.</P> <P>To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.</P> <P>For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.</P> <P>We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.</P> <P>Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.</P> <P>Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.</P> <P>The precise terms and conditions for copying, distribution and modification follow.</P> <H4>GNU GENERAL PUBLIC LICENSE <BR> TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H4> <OL START="0"> <LI>This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". <P>Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.</P> </LI> <LI>You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. <P>You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.</P> </LI> <LI>You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: <OL TYPE="a"> <LI>You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.</LI> <LI>You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.</LI> <LI>if the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)</LI> </OL> <P>These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.</P> <P>Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.</P> <P>In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.</P> </LI> <LI>You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: <OL TYPE="a"> <LI>Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,</LI> <LI>Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,</LI> <LI>Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)</LI> </OL> <P>The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.</P> <P>If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.</P> </LI> <LI>You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.</LI> <LI>You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.</LI> <LI>Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.</LI> <LI>If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. <P>If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.</P> <P>It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.</P> <P>This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.</P> </LI> <LI>If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.</LI> <LI>The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. <P>Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.</P> </LI> <LI>If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.</LI> </OL> <H4>NO WARRANTY</H4> <OL START="11"> <LI>BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</LI> <LI>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.</LI> </OL> <H4>END OF TERMS AND CONDITIONS</H4> <H4>How to Apply These Terms to Your New Programs</H4> <P>If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.</P> <P>To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.</P> <PRE> <VAR>one line to give the program's name and an idea of what it does.</VAR> Copyright (C) <VAR>yyyy</VAR> <VAR>name of author</VAR> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. </PRE> <P>Also add information on how to contact you by electronic and paper mail.</P> <P>If the program is interactive, make it output a short notice like this when it starts in an interactive mode:</P> <PRE> Gnomovision version 69, Copyright (C) <VAR>year</VAR> <VAR>name of author</VAR> Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. </PRE> <P>The hypothetical commands <SAMP>`show w'</SAMP> and <SAMP>`show c'</SAMP> should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than <SAMP> `show w'</SAMP> and <SAMP>`show c'</SAMP>; they could even be mouse-clicks or menu items--whatever suits your program.</P> <P>You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:</P> <PRE> Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. <VAR>signature of Ty Coon</VAR>, 1 April 1989 Ty Coon, President of Vice </PRE> <!-- NEW PAGE --> <H2><A NAME="7_3">GNU LIBRARY GENERAL PUBLIC LICENSE</A></H2> <P>Version 2, June 1991</P> <PRE> Copyright (C) 1991 Free Software Foundation, Inc. 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the library GPL. It is numbered 2 because it goes with version 2 of the ordinary GPL.] </PRE> <H3><A NAME="7_3_1">Preamble</A></H3> <P>The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users.</P> <P>This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too.</P> <P>When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.</P> <P>To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it.</P> <P>For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link a program with the library, you must provide complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights.</P> <P>Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library.</P> <P>Also, for each distributor's protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recipients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors' reputations.</P> <P>Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.</P> <P>Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don't assume that anything in it is the same as in the ordinary license.</P> <P>The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without changing the library, is in some sense simply using the library, and is analogous to running a utility program or application program. However, in a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such.</P> <P>Because of this blurred distinction, using the ordinary General Public License for libraries did not effectively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better.</P> <P>However, unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries, while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries.</P> <P>The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, while the latter only works together with the library.</P> <P>Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one.</P> <H4>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H4> <P><STRONG>0.</STRONG> This License Agreement applies to any software library which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Library General Public License (also called "this License"). Each licensee is addressed as "you".</P> <P>A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.</P> <P>The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".)</P> <P>"Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library.</P> <P>Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does.</P> <P><STRONG>1.</STRONG> You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.</P> <P>You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.</P> <P><STRONG>2.</STRONG> You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:</P> <OL TYPE="a"> <LI>The modified work must itself be a software library. <P></P> </LI> <LI>You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. <P></P> </LI> <LI>You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. <P></P> </LI> <LI>If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. <P>(For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)</P> </LI> </OL> <P>These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.</P> <P>Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.</P> <P>In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.</P> <P><STRONG>3.</STRONG> You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices.</P> <P>Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.</P> <P>This option is useful when you wish to copy part of the code of the Library into a program that is not a library.</P> <P><STRONG>4.</STRONG> You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange.</P> <P>If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code.</P> <P><STRONG>5.</STRONG> A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License.</P> <P>However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables.</P> <P>When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law.</P> <P>If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.)</P> <P>Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself.</P> <P><STRONG>6.</STRONG> As an exception to the Sections above, you may also compile or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications.</P> <P>You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:</P> <OL TYPE="a"> <LI>Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.) <P></P> </LI> <LI>Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution. <P></P> </LI> <LI>If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place. <P></P> </LI> <LI>Verify that the user has already received a copy of these materials or that you have already sent this user a copy.</LI> </OL> <P>For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.</P> <P>It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.</P> <P><STRONG>7.</STRONG> You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things:</P> <OL TYPE="a"> <LI>Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above. <P></P> </LI> <LI>Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.</LI> </OL> <P><STRONG>8.</STRONG> You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.</P> <P><STRONG>9.</STRONG> You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it.</P> <P><STRONG>10.</STRONG> Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.</P> <P><STRONG>11.</STRONG> If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library.</P> <P>If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.</P> <P>It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.</P> <P>This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.</P> <P><STRONG>12.</STRONG> If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.</P> <P><STRONG>13.</STRONG> The Free Software Foundation may publish revised and/or new versions of the Library General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.</P> <P>Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation.</P> <P><STRONG>14.</STRONG> If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.</P> <P><STRONG>NO WARRANTY</STRONG></P> <P><STRONG>15.</STRONG> BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</P> <P><STRONG>16.</STRONG> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.</P> <H4>END OF TERMS AND CONDITIONS</H4> <H4>How to Apply These Terms to Your New Libraries</H4> <P>If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License).</P> <P>To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.</P> <PRE> <VAR>one line to give the library's name and an idea of what it does.</VAR> Copyright (C) <VAR>year</VAR> <VAR>name of author</VAR> This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA </PRE> <P>Also add information on how to contact you by electronic and paper mail.</P> <P>You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names:</P> <PRE> Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker. <VAR>signature of Ty Coon</VAR>, 1 April 1990 Ty Coon, President of Vice </PRE> <P>That's all there is to it!</P> <H1 ALIGN="RIGHT"><A NAME="CONSTANTS">B - Constants</A></H1> <P>This appendix lists all of the constants that are defined by the CUPS API.</P> <H2><A NAME="8_1">CUPS Constants</A></H2> <H3><A NAME="8_1_1">Version Number</A></H3> <P>The <CODE>CUPS_VERSION</CODE> constant is a floating-point number representing the API version number. The current version number is 1.0100 which represents CUPS version 1.1.0.</P> <H3><A NAME="8_1_2">Printer Capabilities</A></H3> <P>The <CODE>CUPS_PRINTER</CODE> constants represent capability bits for printers and classes:</P> <UL> <LI><CODE>CUPS_PRINTER_LOCAL</CODE> - Is a local printer or class.</LI> <LI><CODE>CUPS_PRINTER_REMOTE</CODE> - Is a remote printer or class.</LI> <LI><CODE>CUPS_PRINTER_CLASS</CODE> - Is a class.</LI> <LI><CODE>CUPS_PRINTER_BW</CODE> - Printer prints in black and white.</LI> <LI><CODE>CUPS_PRINTER_COLOR</CODE> - Printer prints in color.</LI> <LI><CODE>CUPS_PRINTER_DUPLEX</CODE> - Printer can print double-sided.</LI> <LI><CODE>CUPS_PRINTER_STAPLE</CODE> - Printer can staple output.</LI> <LI><CODE>CUPS_PRINTER_COPIES</CODE> - Printer can produce multiple copies on its own.</LI> <LI><CODE>CUPS_PRINTER_COLLATE</CODE> - Printer can collate copies.</LI> <LI><CODE>CUPS_PRINTER_PUNCH</CODE> - Printer can punch holes in output.</LI> <LI><CODE>CUPS_PRINTER_COVER</CODE> - Printer can put covers on output.</LI> <LI><CODE>CUPS_PRINTER_BIND</CODE> - Printer can bind output.</LI> <LI><CODE>CUPS_PRINTER_SORT</CODE> - Printer can sort output.</LI> <LI><CODE>CUPS_PRINTER_SMALL</CODE> - Printer can print on media up to 9x14 inches.</LI> <LI><CODE>CUPS_PRINTER_MEDIUM</CODE> - Printer can print on media from 9x14 to 18x24 inches.</LI> <LI><CODE>CUPS_PRINTER_LARGE</CODE> - Printer can print on media larger than 18x24 inches.</LI> <LI><CODE>CUPS_PRINTER_VARIABLE</CODE> - Printer can print on variable or custom media sizes.</LI> <LI><CODE>CUPS_PRINTER_IMPLICIT</CODE> - Is an implicit class.</LI> <LI><CODE>CUPS_PRINTER_OPTIONS</CODE> - All of the printer capability and option bits.</LI> </UL> <H3><A NAME="8_1_3">Encodings</A></H3> <P>CUPS defines the following character set encoding constants:</P> <UL> <LI><CODE>CUPS_US_ASCII</CODE> - US ASCII character set.</LI> <LI><CODE>CUPS_UTF_8</CODE> - UTF-8 encoding of Unicode.</LI> <LI><CODE>CUPS_ISO8859_1</CODE> - ISO-8859-1 character set.</LI> <LI><CODE>CUPS_ISO8859_2</CODE> - ISO-8859-2 character set.</LI> <LI><CODE>CUPS_ISO8859_3</CODE> - ISO-8859-3 character set.</LI> <LI><CODE>CUPS_ISO8859_4</CODE> - ISO-8859-4 character set.</LI> <LI><CODE>CUPS_ISO8859_5</CODE> - ISO-8859-5 character set.</LI> <LI><CODE>CUPS_ISO8859_6</CODE> - ISO-8859-6 character set.</LI> <LI><CODE>CUPS_ISO8859_7</CODE> - ISO-8859-7 character set.</LI> <LI><CODE>CUPS_ISO8859_8</CODE> - ISO-8859-8 character set.</LI> <LI><CODE>CUPS_ISO8859_9</CODE> - ISO-8859-9 character set.</LI> <LI><CODE>CUPS_ISO8859_10</CODE> - ISO-8859-10 character set.</LI> <LI><CODE>CUPS_ISO8859_13</CODE> - ISO-8859-13 character set.</LI> <LI><CODE>CUPS_ISO8859_14</CODE> - ISO-8859-14 character set.</LI> <LI><CODE>CUPS_ISO8859_15</CODE> - ISO-8859-15 character set.</LI> <LI><CODE>CUPS_WINDOWS_874</CODE> - Windows code page 874.</LI> <LI><CODE>CUPS_WINDOWS_1250</CODE> - Windows code page 1250.</LI> <LI><CODE>CUPS_WINDOWS_1251</CODE> - Windows code page 1251.</LI> <LI><CODE>CUPS_WINDOWS_1252</CODE> - Windows code page 1252.</LI> <LI><CODE>CUPS_WINDOWS_1253</CODE> - Windows code page 1253.</LI> <LI><CODE>CUPS_WINDOWS_1254</CODE> - Windows code page 1254.</LI> <LI><CODE>CUPS_WINDOWS_1255</CODE> - Windows code page 1255.</LI> <LI><CODE>CUPS_WINDOWS_1256</CODE> - Windows code page 1256.</LI> <LI><CODE>CUPS_WINDOWS_1257</CODE> - Windows code page 1257.</LI> <LI><CODE>CUPS_WINDOWS_1258</CODE> - Windows code page 1258.</LI> <LI><CODE>CUPS_KOI8_R</CODE> - Russian code page koi8-r.</LI> <LI><CODE>CUPS_KOI8_U</CODE> - Ukrainian code page koi8-r.</LI> </UL> <H2><A NAME="8_2">HTTP Constants</A></H2> <H3><A NAME="8_2_1">Limits</A></H3> <P>The following constants define the limits for strings:</P> <UL> <LI><CODE>HTTP_MAX_BUFFER</CODE> - Size of socket buffer.</LI> <LI><CODE>HTTP_MAX_HOST</CODE> - Maximum length of hostname.</LI> <LI><CODE>HTTP_MAX_URI</CODE> - Maximum length of URI.</LI> <LI><CODE>HTTP_MAX_VALUE</CODE> - Maximum length of field values.</LI> </UL> <H3><A NAME="8_2_2">Status Codes</A></H3> <P>The following status codes can be returned by <CODE>httpUpdate()</CODE> :</P> <UL> <LI><CODE>HTTP_ERROR</CODE> - A network error occurred</LI> <LI><CODE>HTTP_CONTINUE</CODE> - Continue response from HTTP proxy</LI> <LI><CODE>HTTP_OK</CODE> - OPTIONS/GET/HEAD/POST/TRACE command was successful</LI> <LI><CODE>HTTP_CREATED</CODE> - PUT command was successful</LI> <LI><CODE>HTTP_ACCEPTED</CODE> - DELETE command was successful</LI> <LI><CODE>HTTP_NOT_AUTHORITATIVE</CODE> - Information isn't authoritative</LI> <LI><CODE>HTTP_NO_CONTENT</CODE> - Successful command</LI> <LI><CODE>HTTP_RESET_CONTENT</CODE> - Content was reset/recreated</LI> <LI><CODE>HTTP_PARTIAL_CONTENT</CODE> - Only a partial file was recieved/sent</LI> <LI><CODE>HTTP_MULTIPLE_CHOICES</CODE> - Multiple files match request</LI> <LI><CODE>HTTP_MOVED_PERMANENTLY</CODE> - Document has moved permanently</LI> <LI><CODE>HTTP_MOVED_TEMPORARILY</CODE> - Document has moved temporarily</LI> <LI><CODE>HTTP_SEE_OTHER</CODE> - See this other link...</LI> <LI><CODE>HTTP_NOT_MODIFIED</CODE> - File not modified</LI> <LI><CODE>HTTP_USE_PROXY</CODE> - Must use a proxy to access this URI</LI> <LI><CODE>HTTP_BAD_REQUEST</CODE> - Bad request</LI> <LI><CODE>HTTP_UNAUTHORIZED</CODE> - Unauthorized to access host</LI> <LI><CODE>HTTP_PAYMENT_REQUIRED</CODE> - Payment required</LI> <LI><CODE>HTTP_FORBIDDEN</CODE> - Forbidden to access this URI</LI> <LI><CODE>HTTP_NOT_FOUND</CODE> - URI was not found</LI> <LI><CODE>HTTP_METHOD_NOT_ALLOWED</CODE> - Method is not allowed</LI> <LI><CODE>HTTP_NOT_ACCEPTABLE</CODE> - Not Acceptable</LI> <LI><CODE>HTTP_PROXY_AUTHENTICATION</CODE> - Proxy Authentication is Required</LI> <LI><CODE>HTTP_REQUEST_TIMEOUT</CODE> - Request timed out</LI> <LI><CODE>HTTP_CONFLICT</CODE> - Request is self-conflicting</LI> <LI><CODE>HTTP_GONE</CODE> - Server has gone away</LI> <LI><CODE>HTTP_LENGTH_REQUIRED</CODE> - A content length or encoding is required</LI> <LI><CODE>HTTP_PRECONDITION</CODE> - Precondition failed</LI> <LI><CODE>HTTP_REQUEST_TOO_LARGE</CODE> - Request entity too large</LI> <LI><CODE>HTTP_URI_TOO_LONG</CODE> - URI too long</LI> <LI><CODE>HTTP_UNSUPPORTED_MEDIATYPE</CODE> - The requested media type is unsupported</LI> <LI><CODE>HTTP_SERVER_ERROR</CODE> - Internal server error</LI> <LI><CODE>HTTP_NOT_IMPLEMENTED</CODE> - Feature not implemented</LI> <LI><CODE>HTTP_BAD_GATEWAY</CODE> - Bad gateway</LI> <LI><CODE>HTTP_SERVICE_UNAVAILABLE</CODE> - Service is unavailable</LI> <LI><CODE>HTTP_GATEWAY_TIMEOUT</CODE> - Gateway connection timed out</LI> <LI><CODE>HTTP_NOT_SUPPORTED</CODE> - HTTP version not supported</LI> </UL> <H3><A NAME="8_2_3">Fields</A></H3> <P>The following fields are indices for each of the standard HTTP fields in HTTP 1/1:</P> <UL> <LI><CODE>HTTP_FIELD_ACCEPT_LANGUAGE</CODE> - Accept-Language</LI> <LI><CODE>HTTP_FIELD_ACCEPT_RANGES</CODE> - Accept-Ranges</LI> <LI><CODE>HTTP_FIELD_AUTHORIZATION</CODE> - Authorization</LI> <LI><CODE>HTTP_FIELD_CONNECTION</CODE> - Connection</LI> <LI><CODE>HTTP_FIELD_CONTENT_ENCODING</CODE> - Content-Encoding</LI> <LI><CODE>HTTP_FIELD_CONTENT_LANGUAGE</CODE> - Content-Language</LI> <LI><CODE>HTTP_FIELD_CONTENT_LENGTH</CODE> - Content-Length</LI> <LI><CODE>HTTP_FIELD_CONTENT_LOCATION</CODE> - Content-Location</LI> <LI><CODE>HTTP_FIELD_CONTENT_MD5</CODE> - Content-MD5</LI> <LI><CODE>HTTP_FIELD_CONTENT_RANGE</CODE> - Content-Range</LI> <LI><CODE>HTTP_FIELD_CONTENT_TYPE</CODE> - Content-Type</LI> <LI><CODE>HTTP_FIELD_CONTENT_VERSION</CODE> - Content-Version</LI> <LI><CODE>HTTP_FIELD_DATE</CODE> - Date</LI> <LI><CODE>HTTP_FIELD_HOST</CODE> - Host</LI> <LI><CODE>HTTP_FIELD_IF_MODIFIED_SINCE</CODE> - If-Modified-Since</LI> <LI><CODE>HTTP_FIELD_IF_UNMODIFIED_SINCE</CODE> - If-Unmodified-Since</LI> <LI><CODE>HTTP_FIELD_KEEP_ALIVE</CODE> - Keep-Alive</LI> <LI><CODE>HTTP_FIELD_LAST_MODIFIED</CODE> - Last-Modified</LI> <LI><CODE>HTTP_FIELD_LINK</CODE> - Link</LI> <LI><CODE>HTTP_FIELD_LOCATION</CODE> - Location</LI> <LI><CODE>HTTP_FIELD_RANGE</CODE> - Range</LI> <LI><CODE>HTTP_FIELD_REFERER</CODE> - Referer</LI> <LI><CODE>HTTP_FIELD_RETRY_AFTER</CODE> - Retry-After</LI> <LI><CODE>HTTP_FIELD_TRANSFER_ENCODING</CODE> - Transfer-Encoding</LI> <LI><CODE>HTTP_FIELD_UPGRADE</CODE> - Upgrade</LI> <LI><CODE>HTTP_FIELD_USER_AGENT</CODE> - User-Agent</LI> <LI><CODE>HTTP_FIELD_WWW_AUTHENTICATE</CODE> - WWW-Authenticate</LI> </UL> <H2><A NAME="8_3">IPP Constants</A></H2> <H3><A NAME="8_3_1">Limits</A></H3> <P>The following constants define array limits for IPP data:</P> <UL> <LI><CODE>IPP_MAX_NAME</CODE> - Maximum length of an attribute name</LI> <LI><CODE>IPP_MAX_VALUES</CODE> - Maximum number of set-of values that can be read in a request.</LI> </UL> <H3><A NAME="8_3_2">Tags</A></H3> <UL> <LI><CODE>IPP_TAG_ZERO</CODE> - Wildcard tag value for searches; also used to separate groups of attributes</LI> <LI><CODE>IPP_TAG_OPERATION</CODE> - Tag for values of type operation</LI> <LI><CODE>IPP_TAG_JOB</CODE> - Tag for values of type job</LI> <LI><CODE>IPP_TAG_END</CODE> - Tag for values of type end</LI> <LI><CODE>IPP_TAG_PRINTER</CODE> - Tag for values of type printer</LI> <LI><CODE>IPP_TAG_UNSUPPORTED_GROUP</CODE> - Tag for values of type unsupported_group</LI> <LI><CODE>IPP_TAG_UNSUPPORTED_VALUE</CODE> - Tag for values of type unsupported_value</LI> <LI><CODE>IPP_TAG_DEFAULT</CODE> - Tag for values of type default</LI> <LI><CODE>IPP_TAG_UNKNOWN</CODE> - Tag for values of type unknown</LI> <LI><CODE>IPP_TAG_NOVALUE</CODE> - Tag for values of type novalue</LI> <LI><CODE>IPP_TAG_NOTSETTABLE</CODE> - Tag for values of type notsettable</LI> <LI><CODE>IPP_TAG_DELETEATTR</CODE> - Tag for values of type deleteattr</LI> <LI><CODE>IPP_TAG_ANYVALUE</CODE> - Tag for values of type anyvalue</LI> <LI><CODE>IPP_TAG_INTEGER</CODE> - Tag for values of type integer</LI> <LI><CODE>IPP_TAG_BOOLEAN</CODE> - Tag for values of type boolean</LI> <LI><CODE>IPP_TAG_ENUM</CODE> - Tag for values of type enum</LI> <LI><CODE>IPP_TAG_STRING</CODE> - Tag for values of type string</LI> <LI><CODE>IPP_TAG_DATE</CODE> - Tag for values of type date</LI> <LI><CODE>IPP_TAG_RESOLUTION</CODE> - Tag for values of type resolution</LI> <LI><CODE>IPP_TAG_RANGE</CODE> - Tag for values of type range</LI> <LI><CODE>IPP_TAG_COLLECTION</CODE> - Tag for values of type collection</LI> <LI><CODE>IPP_TAG_TEXTLANG</CODE> - Tag for values of type textlang</LI> <LI><CODE>IPP_TAG_NAMELANG</CODE> - Tag for values of type namelang</LI> <LI><CODE>IPP_TAG_TEXT</CODE> - Tag for values of type text</LI> <LI><CODE>IPP_TAG_NAME</CODE> - Tag for values of type name</LI> <LI><CODE>IPP_TAG_KEYWORD</CODE> - Tag for values of type keyword</LI> <LI><CODE>IPP_TAG_URI</CODE> - Tag for values of type uri</LI> <LI><CODE>IPP_TAG_URISCHEME</CODE> - Tag for values of type urischeme</LI> <LI><CODE>IPP_TAG_CHARSET</CODE> - Tag for values of type charset</LI> <LI><CODE>IPP_TAG_LANGUAGE</CODE> - Tag for values of type language</LI> <LI><CODE>IPP_TAG_MIMETYPE</CODE> - Tag for values of type mimetype</LI> </UL> <H3><A NAME="8_3_3">Resolution Units</A></H3> <P>The <CODE>IPP_RES_PER_INCH</CODE> and <CODE>IPP_RES_PER_CM</CODE> constants specify dots per inch and dots per centimeter, respectively.</P> <H3><A NAME="8_3_4">Finishings</A></H3> <P>The finishing values specify special finishing operations to be performed on the job.</P> <UL> <LI><CODE>IPP_FINISH_NONE</CODE> - Do no finishing</LI> <LI><CODE>IPP_FINISH_STAPLE</CODE> - Staple the job</LI> <LI><CODE>IPP_FINISH_PUNCH</CODE> - Punch the job</LI> <LI><CODE>IPP_FINISH_COVER</CODE> - Cover the job</LI> <LI><CODE>IPP_FINISH_BIND</CODE> - Bind the job</LI> </UL> <H3><A NAME="8_3_5">Orientations</A></H3> <P>The orientation values specify the orientation of the job.</P> <UL> <LI><CODE>IPP_PORTRAIT</CODE> - No rotation</LI> <LI><CODE>IPP_LANDSCAPE</CODE> - 90 degrees counter-clockwise</LI> <LI><CODE>IPP_REVERSE_LANDSCAPE</CODE> - 90 degrees clockwise</LI> <LI><CODE>IPP_REVERSE_PORTRAIT</CODE> - 180 degrees</LI> </UL> <H3><A NAME="8_3_6">Qualities</A></H3> <P>The quality values specify the desired quality of the print.</P> <UL> <LI><CODE>IPP_QUALITY_DRAFT</CODE> - Draft quality</LI> <LI><CODE>IPP_QUALITY_NORMAL</CODE> - Normal quality</LI> <LI><CODE>IPP_QUALITY_HIGH</CODE> - High quality</LI> </UL> <H3><A NAME="8_3_7">Job States</A></H3> <P>The job state values are used to represent the current job state.</P> <UL> <LI><CODE>IPP_JOB_PENDING</CODE> - Job is pending</LI> <LI><CODE>IPP_JOB_HELD</CODE> - Job is held</LI> <LI><CODE>IPP_JOB_PROCESSING</CODE> - Job is processing</LI> <LI><CODE>IPP_JOB_STOPPED</CODE> - Job is stopped</LI> <LI><CODE>IPP_JOB_CANCELLED</CODE> - Job is cancelled</LI> <LI><CODE>IPP_JOB_ABORTED</CODE> - Job is aborted</LI> <LI><CODE>IPP_JOB_COMPLETED</CODE> - Job is completed</LI> </UL> <H3><A NAME="8_3_8">Printer States</A></H3> <P>The printer state values are used to represent the current printer state.</P> <UL> <LI><CODE>IPP_PRINTER_IDLE</CODE> - Printer is idle</LI> <LI><CODE>IPP_PRINTER_PROCESSING</CODE> - Printer is processing</LI> <LI><CODE>IPP_PRINTER_STOPPED</CODE> - Printer is stopped</LI> </UL> <H3><A NAME="8_3_9">Operations</A></H3> <P>The operation values represent the available IPP operations.</P> <UL> <LI><CODE>IPP_PRINT_JOB</CODE> - Print a file</LI> <LI><CODE>IPP_PRINT_URI</CODE> - Print a URI</LI> <LI><CODE>IPP_VALIDATE_JOB</CODE> - Validate job attributes</LI> <LI><CODE>IPP_CREATE_JOB</CODE> - Create a new job</LI> <LI><CODE>IPP_SEND_DOCUMENT</CODE> - Send a document to a job</LI> <LI><CODE>IPP_SEND_URI</CODE> - Send a URI to a job</LI> <LI><CODE>IPP_CANCEL_JOB</CODE> - Cancel a job</LI> <LI><CODE>IPP_GET_JOB_ATTRIBUTES</CODE> - Get job attributes</LI> <LI><CODE>IPP_GET_JOBS</CODE> - Get a list of all jobs</LI> <LI><CODE>IPP_GET_PRINTER_ATTRIBUTES</CODE> - Get printer attributes</LI> <LI><CODE>IPP_HOLD_JOB</CODE> - Hold a pending job</LI> <LI><CODE>IPP_RELEASE_JOB</CODE> - Release a held job</LI> <LI><CODE>IPP_RESTART_JOB</CODE> - Restart a completed job</LI> <LI><CODE>IPP_PAUSE_PRINTER</CODE> - Pause a printer</LI> <LI><CODE>IPP_RESUME_PRINTER</CODE> - Restart a paused printer</LI> <LI><CODE>IPP_PURGE_JOBS</CODE> - Purge jobs from the queue</LI> <LI><CODE>IPP_SET_PRINTER_ATTRIBUTES</CODE> - Set printer attributes</LI> <LI><CODE>IPP_SET_JOB_ATTRIBUTES</CODE> - Set job attributes</LI> <LI><CODE>IPP_GET_PRINTER_SUPPORTED_VALUES</CODE> - Get printer supported values</LI> <LI><CODE>CUPS_GET_DEFAULT</CODE> - Get the default destination</LI> <LI><CODE>CUPS_GET_PRINTERS</CODE> - Get a list of all printers</LI> <LI><CODE>CUPS_ADD_PRINTER</CODE> - Add or modify a printer</LI> <LI><CODE>CUPS_DELETE_PRINTER</CODE> - Delete a printer</LI> <LI><CODE>CUPS_GET_CLASSES</CODE> - Get a list of all classes</LI> <LI><CODE>CUPS_ADD_CLASS</CODE> - Add or modify a class</LI> <LI><CODE>CUPS_DELETE_CLASS</CODE> - Delete a class</LI> <LI><CODE>CUPS_ACCEPT_JOBS</CODE> - Accept jobs on a printer or class</LI> <LI><CODE>CUPS_REJECT_JOBS</CODE> - Reject jobs on a printer or class</LI> <LI><CODE>CUPS_SET_DEFAULT</CODE> - Set the default destination</LI> <LI><CODE>CUPS_GET_DEVICES</CODE> - Get a list of all devices</LI> <LI><CODE>CUPS_GET_PPDS</CODE> - Get a list of all PPDs</LI> <LI><CODE>CUPS_MOVE_JOB</CODE> - Move a job to a new destination</LI> </UL> <H3><A NAME="8_3_10">Status Codes</A></H3> <P>Status codes are returned by all IPP requests.</P> <UL> <LI><CODE>IPP_OK</CODE> - Request completed with no errors</LI> <LI><CODE>IPP_OK_SUBST</CODE> - Request completed but some attribute values were substituted</LI> <LI><CODE>IPP_OK_CONFLICT</CODE> - Request completed but some attributes conflicted</LI> <LI><CODE>IPP_BAD_REQUEST</CODE> - The request was bad</LI> <LI><CODE>IPP_FORBIDDEN</CODE> - You don't have access to the resource</LI> <LI><CODE>IPP_NOT_AUTHENTICATED</CODE> - You are not authenticated for the resource</LI> <LI><CODE>IPP_NOT_AUTHORIZED</CODE> - You not authorized to access the resource</LI> <LI><CODE>IPP_NOT_POSSIBLE</CODE> - The requested operation cannot be completed</LI> <LI><CODE>IPP_TIMEOUT</CODE> - A timeout occurred</LI> <LI><CODE>IPP_NOT_FOUND</CODE> - The resource was not found</LI> <LI><CODE>IPP_GONE</CODE> - The resource has gone away</LI> <LI><CODE>IPP_REQUEST_ENTITY</CODE> - The request was too large</LI> <LI><CODE>IPP_REQUEST_VALUE</CODE> - The request contained a value that was unknown to the server</LI> <LI><CODE>IPP_DOCUMENT_FORMAT</CODE> - The document format is not supported by the server</LI> <LI><CODE>IPP_ATTRIBUTES</CODE> - Required attributes are missing</LI> <LI><CODE>IPP_URI_SCHEME</CODE> - The URI scheme is not supported</LI> <LI><CODE>IPP_CHARSET</CODE> - The charset is not supported</LI> <LI><CODE>IPP_CONFLICT</CODE> - One or more attributes conflict</LI> <LI><CODE>IPP_COMPRESSION_NOT_SUPPORTED</CODE> - The specified compression is not supported</LI> <LI><CODE>IPP_COMPRESSION_ERROR</CODE> - The compressed data contained an error</LI> <LI><CODE>IPP_DOCUMENT_FORMAT_ERROR</CODE> - The document data contained an error in it</LI> <LI><CODE>IPP_DOCUMENT_ACCESS_ERROR</CODE> - The remote document could not be accessed</LI> <LI><CODE>IPP_INTERNAL_ERROR</CODE> - The server encountered an internal error</LI> <LI><CODE>IPP_OPERATION_NOT_SUPPORTED</CODE> - The requested operation is not supported</LI> <LI><CODE>IPP_SERVICE_UNAVAILABLE</CODE> - The requested service is unavailable</LI> <LI><CODE>IPP_VERSION_NOT_SUPPORTED</CODE> - The IPP request version is not supported</LI> <LI><CODE>IPP_DEVICE_ERROR</CODE> - The output device encountered an error</LI> <LI><CODE>IPP_TEMPORARY_ERROR</CODE> - A temporary error occurred</LI> <LI><CODE>IPP_NOT_ACCEPTING</CODE> - The destination is not accepting jobs</LI> <LI><CODE>IPP_PRINTER_BUSY</CODE> - The destination is busy</LI> <LI><CODE>IPP_ERROR_JOB_CANCELLED</CODE> - The requested job has been cancelled</LI> <LI><CODE>IPP_MULTIPLE_JOBS_NOT_SUPPORTED</CODE> - The server does not support multiple jobs</LI> </UL> <H2><A NAME="8_4">PPD Constants</A></H2> <H3><A NAME="8_4_1">PPD Format Version</A></H3> <P>The <CODE>PPD_VERSION</CODE> constant defines a floating point number representing the newest format version that is supported by CUPS, currently 4.3.</P> <H3><A NAME="8_4_2">PPD User-Interface Types</A></H3> <P>Each printer option has a type associated with it:</P> <UL> <LI><CODE>PPD_UI_BOOLEAN</CODE> - The user can turn this option on or off</LI> <LI><CODE>PPD_UI_PICKONE</CODE> - The user can choose one option value to use.</LI> <LI><CODE>PPD_UI_PICKMANY</CODE> - The user can choose zero or more option values.</LI> </UL> <H3><A NAME="8_4_3">PPD Sections</A></H3> <P>Some options must be output before others, or in different sections of the output document. The <CODE>ppd_section_t</CODE> enumeration defines which section the option must be output in:</P> <UL> <LI><CODE>PPD_ORDER_ANY</CODE> - The option can be output in any of the document, page, or prolog sections of the document</LI> <LI><CODE>PPD_ORDER_DOCUMENT</CODE> - The option must be output in the DocumentSetup section of the document</LI> <LI><CODE>PPD_ORDER_EXIT</CODE> - The option must be output before the document</LI> <LI><CODE>PPD_ORDER_JCL</CODE> - The option must be output in the job control section of the document</LI> <LI><CODE>PPD_ORDER_PAGE</CODE> - The option must be output in the PageSetup section of the document</LI> <LI><CODE>PPD_ORDER_PROLOG</CODE> - The option must be output in the Prolog section of the document</LI> </UL> <H3><A NAME="8_4_4">PPD Colorspaces</A></H3> <P>Each printer has a default colorspace:</P> <UL> <LI><CODE>PPD_CS_CMYK</CODE> - The printer uses CMYK colors by default</LI> <LI><CODE>PPD_CS_CMY</CODE> - The printer uses CMY colors by default</LI> <LI><CODE>PPD_CS_GRAY</CODE> - The printer uses grayscale by default</LI> <LI><CODE>PPD_CS_RGB</CODE> - The printer uses RGB colors by default</LI> <LI><CODE>PPD_CS_RGBK</CODE> - The printer uses RGBK colors by default</LI> <LI><CODE>PPD_CS_N</CODE> - The printer uses a DeviceN colorspace by default</LI> </UL> <H2><A NAME="8_5">Raster Constants</A></H2> <H3><A NAME="8_5_1">Raster Sync Words</A></H3> <P>The <CODE>CUPS_RASTER_SYNC</CODE> and <CODE>CUPS_RASTER_REVSYNC</CODE> constants define the standard sync words at the beginning of each CUPS raster file.</P> <H3><A NAME="8_5_2">Raster Stream Modes</A></H3> <P>The <CODE>CUPS_RASTER_READ</CODE> and <CODE>CUPS_RASTER_WRITE</CODE> constants are used with the <A HREF="#cupsRasterOpen"><CODE> cupsRasterOpen()</CODE></A> function to specify a stream for reading or writing.</P> <H3><A NAME="8_5_3">Raster Boolean Constants</A></H3> <P>The <CODE>CUPS_FALSE</CODE> and <CODE>CUPS_TRUE</CODE> constants represent boolean values in the page header.</P> <H3><A NAME="8_5_4">Raster Jog Values</A></H3> <P>The <CODE>cups_jog_t</CODE> enumeration defines constants for the Jog page device dictionary variable:</P> <UL> <LI><CODE>CUPS_JOG_NONE</CODE> - Do no jogging</LI> <LI><CODE>CUPS_JOG_FILE</CODE> - Jog pages after each file</LI> <LI><CODE>CUPS_JOG_JOB</CODE> - Jog pages after each job</LI> <LI><CODE>CUPS_JOG_SET</CODE> - Jog pages after each set of jobs</LI> </UL> <H3><A NAME="8_5_5">Raster Orientation Values</A></H3> <P>The <CODE>cups_orient_t</CODE> enumeration defines constants for the Orientation page device dictionary variable:</P> <UL> <LI><CODE>CUPS_ORIENT_0</CODE> - Portrait orientation</LI> <LI><CODE>CUPS_ORIENT_90</CODE> - Landscape orientation</LI> <LI><CODE>CUPS_ORIENT_180</CODE> - Reverse-portrait orientation</LI> <LI><CODE>CUPS_ORIENT_270</CODE> - Reverse-landscape orientation</LI> </UL> <H3><A NAME="8_5_6">Raster CutMedia Values</A></H3> <P>The <CODE>cups_cut_t</CODE> enumeration defines constants for the CutMedia page device dictionary variable:</P> <UL> <LI><CODE>CUPS_CUT_NONE</CODE> - Do no jogging</LI> <LI><CODE>CUPS_CUT_FILE</CODE> - Cut pages after each file</LI> <LI><CODE>CUPS_CUT_JOB</CODE> - Cut pages after each job</LI> <LI><CODE>CUPS_CUT_SET</CODE> - Cut pages after each set of jobs</LI> <LI><CODE>CUPS_CUT_PAGE</CODE> - Cut each page</LI> </UL> <H3><A NAME="8_5_7">Raster AdvanceMedia Values</A></H3> <P>The <CODE>cups_advance_t</CODE> enumeration defines constants for the AdvanceMedia page device dictionary variable:</P> <UL> <LI><CODE>CUPS_ADVANCE_NONE</CODE> - Do no jogging</LI> <LI><CODE>CUPS_ADVANCE_FILE</CODE> - Advance media after each file</LI> <LI><CODE>CUPS_ADVANCE_JOB</CODE> - Advance media after each job</LI> <LI><CODE>CUPS_ADVANCE_SET</CODE> - Advance media after each set of jobs</LI> <LI><CODE>CUPS_ADVANCE_PAGE</CODE> - Advance media for each page</LI> </UL> <H3><A NAME="8_5_8">Raster LeadingEdge Values</A></H3> <P>The <CODE>cups_edge_t</CODE> enumeration defines constants for the LeadingEdge page device dictionary variable:</P> <UL> <LI><CODE>CUPS_EDGE_TOP</CODE> - The top of the media is the leading edge</LI> <LI><CODE>CUPS_EDGE_RIGHT</CODE> - The right of the media is the leading edge</LI> <LI><CODE>CUPS_EDGE_BOTTOM</CODE> - The bottom of the media is the leading edge</LI> <LI><CODE>CUPS_EDGE_LEFT</CODE> - The left of the media is the leading edge</LI> </UL> <H3><A NAME="8_5_9">Raster Color Order Values</A></H3> <P>The <CODE>cups_order_t</CODE> enumeration defines the possible color value orderings:</P> <UL> <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK CMYK CMYK</LI> <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC MMM YYY KKK</LI> <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC ... MMM ... YYY ... KKK ...</LI> </UL> <H3><A NAME="8_5_10">Raster Colorspace Values</A></H3> <P>The <CODE>cups_cspace_t</CODE> enumeration defines the possible colorspaces:</P> <UL> <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)</LI> <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue</LI> <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha</LI> <LI><CODE>CUPS_CSPACE_K</CODE> - Black</LI> <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow</LI> <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan</LI> <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black</LI> <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black</LI> <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow</LI> <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow, light cyan, light magenta</LI> <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic magenta, metallic cyan, black</LI> <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic magenta, metallic cyan, metallic grey (silver)</LI> <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white pigment)</LI> <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)</LI> <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)</LI> </UL> <H1 ALIGN="RIGHT"><A NAME="STRUCTURES">C - Structures</A></H1> <P>This appendix describes all of the structures that are defined by the CUPS API.</P> <H2><A NAME="9_1">CUPS Structures</A></H2> <H3><A NAME="cups_dest_t">CUPS Destinations</A></H3> <P>The CUPS destination structure (<CODE>cups_dest_t</CODE>) contains information on a specific destination or instance: <CENTER> <TABLE BORDER="1" WIDTH="90%"> <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR> <TR><TD>name</TD><TD>char *</TD><TD>The name of the printer or class.</TD> </TR> <TR><TD>instance</TD><TD>char *</TD><TD>The instance of the printer or class; NULL for the primary instance.</TD></TR> <TR><TD>is_default</TD><TD>int</TD><TD>1 if the destination is set as the default, 0 otherwise.</TD></TR> <TR><TD>num_options</TD><TD>int</TD><TD>The number of options associated with this destination.</TD></TR> <TR><TD>options</TD><TD><A HREF="#cups_option_t">cups_option_t *</A></TD><TD> The options associated with this destination.</TD></TR> </TABLE> </CENTER> </P> <H3><A NAME="cups_job_t">CUPS Jobs</A></H3> <P>The CUPS job structure (<CODE>cups_job_t</CODE>) contains information on a specific job: <CENTER> <TABLE BORDER="1" WIDTH="90%"> <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR> <TR><TD>id</TD><TD>int</TD><TD>The job ID for this job.</TD></TR> <TR><TD>dest</TD><TD>char *</TD><TD>The destination for this job (printer or class name).</TD></TR> <TR><TD>title</TD><TD>char *</TD><TD>The job-name for this job (title).</TD> </TR> <TR><TD>user</TD><TD>char *</TD><TD>The job-originating-user-name for this job (username).</TD></TR> <TR><TD>format</TD><TD>char *</TD><TD>The document-format for this job (MIME type string).</TD></TR> <TR><TD>state</TD><TD>ipp_jstate</TD><TD>The current state of the job.</TD> </TR> <TR><TD>size</TD><TD>int</TD><TD>The size of this job in kilobytes.</TD></TR> <TR><TD>priority</TD><TD>int</TD><TD>The priority of this job from 1 to 100 (50 is normal).</TD></TR> <TR><TD>completed_time</TD><TD>time_t</TD><TD>The time the job was completed, or 0 if not yet completed.</TD></TR> <TR><TD>creation_time</TD><TD>time_t</TD><TD>The time the job was queued.</TD></TR> <TR><TD>processing_time</TD><TD>time_t</TD><TD>The time the job started printing.</TD></TR> </TABLE> </CENTER> </P> <H3><A NAME="cups_lang_t">CUPS Messages</A></H3> <P>The CUPS messages structure (<CODE>cups_lang_t</CODE>) contains the character set, locale name, and messages array: <CENTER> <TABLE BORDER="1" WIDTH="90%"> <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR> <TR><TD>next</TD><TD>cups_lang_t *</TD><TD>Pointer to the next messages structure in memory.</TD></TR> <TR><TD>used</TD><TD>int</TD><TD>The number of active users of this messages structure.</TD></TR> <TR><TD>encoding</TD><TD>cups_encoding_t</TD><TD>The character encoding of the message strings.</TD></TR> <TR><TD>language</TD><TD>char [16]</TD><TD>The language/locale name.</TD> </TR> <TR><TD>messages</TD><TD>char *[]</TD><TD>The array of message strings.</TD> </TR> </TABLE> </CENTER> </P> <H3><A NAME="cups_option_t">CUPS Options</A></H3> <P>The CUPS option structure (<CODE>cups_option_t</CODE>) contains the option name and string value: <CENTER> <TABLE BORDER="1" WIDTH="90%"> <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR> <TR><TD>name</TD><TD>char *</TD><TD>The name of the option.</TD></TR> <TR><TD>value</TD><TD>char *</TD><TD>The string value of the option.</TD> </TR> </TABLE> </CENTER> </P> <H2><A NAME="9_2">Networking Structures</A></H2> <H3><A NAME="http_t">HTTP State</A></H3> <P>The HTTP state structure (<CODE>http_t</CODE>) contains the current state of a HTTP request or response: <CENTER> <TABLE BORDER="1" WIDTH="90%"> <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR> <TR><TD>fd</TD><TD>int</TD><TD>The socket for the HTTP connection.</TD></TR> <TR><TD>blocking</TD><TD>int</TD><TD>1 if the HTTP functions should block, 0 if not.</TD></TR> <TR><TD>error</TD><TD>int</TD><TD>The last OS error that occurred on the socket.</TD></TR> <TR><TD>activity</TD><TD>time_t</TD><TD>The last time the HTTP connection was used.</TD></TR> <TR><TD>state</TD><TD>http_state_t</TD><TD>The current HTTP request/response state.</TD></TR> <TR><TD>status</TD><TD>int</TD><TD>The last HTTP status seen.</TD></TR> <TR><TD>version</TD><TD>http_version_t</TD><TD>The HTTP protocol version in use.</TD></TR> <TR><TD>keep_alive</TD><TD>http_keep_alive_t</TD><TD>Whether or not to use Keep-Alive</TD></TR> <TR><TD>hostaddr</TD><TD>struct sockaddr_in</TD><TD>The IPv4 address of the HTTP server.</TD></TR> <TR><TD>hostname</TD><TD>char []</TD><TD>The hostname of the HTTP server.</TD></TR> <TR><TD>fields</TD><TD>char [][]</TD><TD>The string values of all HTTP request/response fields.</TD></TR> <TR><TD>data</TD><TD>char *</TD><TD>Current byte in data buffer.</TD></TR> <TR><TD>data_encoding</TD><TD>http_encoding_t</TD><TD>The transfer encoding for the request/response.</TD></TR> <TR><TD>data_remaining</TD><TD>off_t</TD><TD>The number of bytes remaining in the current request, response, or chunk.</TD></TR> <TR><TD>used</TD><TD>int</TD><TD>The number of bytes that are used in the buffer.</TD></TR> <TR><TD>buffer</TD><TD>char []</TD><TD>The read/write buffer.</TD></TR> <TR><TD>auth_type</TD><TD>int</TD><TD>The type of authentication in use.</TD> </TR> <TR><TD>md5_state</TD><TD>md5_state_t</TD><TD>The current MD5 digest state.</TD></TR> <TR><TD>nonce</TD><TD>char []</TD><TD>The nonce value for Digest authentication.</TD></TR> <TR><TD>nonce_count</TD><TD>int</TD><TD>The nonce count value.</TD></TR> <TR><TD>tls</TD><TD>void *</TD><TD>A pointer to private encryption data.</TD> </TR> <TR><TD>encryption</TD><TD>http_encryption_t</TD><TD>The current encryption mode.</TD></TR> </TABLE> </CENTER> </P> <H3><A NAME="ipp_t">IPP State</A></H3> <P>The IPP state structure (<CODE>ipp_t</CODE>) contains the current state of a IPP request or response: <CENTER> <TABLE BORDER="1" WIDTH="90%"> <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR> <TR><TD></TD><TD></TD><TD></TD></TR> </TABLE> </CENTER> </P> <H3><A NAME="ipp_attribute_t">IPP Attribute</A></H3> <P>TODO</P> <H2><A NAME="9_3">PPD Structures</A></H2> <H3><A NAME="ppd_file_t">PPD File</A></H3> <P>TODO</P> <H3><A NAME="ppd_choice_t">PPD Choice</A></H3> <P>TODO</P> <H2><A NAME="9_4">Raster Structures</A></H2> <H3><A NAME="cups_raster_t">Raster Stream</A></H3> <P>TODO</P> <H3><A NAME="cups_raster_header_t">Raster Page Header</A></H3> <P>The raster page header (<CODE>cups_raster_header_t</CODE>) consists of the PostScript page device dictionary for the page: <CENTER> <TABLE BORDER="1" WIDTH="90%"> <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR> <TR><TD>MediaClass</TD><TD>char[64]</TD><TD>The media class name</TD></TR> <TR><TD>MediaColor</TD><TD>char[64]</TD><TD>The media color name</TD></TR> <TR><TD>MediaType</TD><TD>char[64]</TD><TD>The media type name</TD></TR> <TR><TD>OutputType</TD><TD>char[64]</TD><TD>The output type name</TD></TR> <TR><TD>AdvanceDistance</TD><TD>unsigned</TD><TD>The distance to advance the media in points</TD></TR> <TR><TD>AdvanceMedia</TD><TD>cups_adv_t</TD><TD>When to advance the media</TD></TR> <TR><TD>Collate</TD><TD>cups_bool_t</TD><TD>Whether or not to produce collated copies</TD></TR> <TR><TD>CutMedia</TD><TD>cups_cut_t</TD><TD>When to cut the media</TD></TR> <TR><TD>Duplex</TD><TD>cups_bool_t</TD><TD>Whether or not to print on both sides of the paper</TD></TR> <TR><TD>HWResolution</TD><TD>unsigned[2]</TD><TD>The resolution of the page image in pixels per inch; the HWResolution[0] represents the horizontal resolution and HWResolution[1] represents the vertical resolution</TD></TR> <TR><TD>ImagingBoundingBox</TD><TD>unsigned[4]</TD><TD>The bounding box for the page in points; the elements represent the left, bottom, right, and top coordinates of the imaged area (if 0 then the whole page is imaged)</TD></TR> <TR><TD>InsertSheet</TD><TD>cups_bool_t</TD><TD>Whether or not to insert a sheet before this page</TD></TR> <TR><TD>Jog</TD><TD>cups_jog_t</TD><TD>When to jog copies of the page</TD> </TR> <TR><TD>LeadingEdge</TD><TD>cups_edge_t</TD><TD>The leading edge of the page</TD></TR> <TR><TD>Margins</TD><TD>unsigned[2]</TD><TD>The lower-lefthand margin of the page in points</TD></TR> <TR><TD>ManualFeed</TD><TD>cups_bool_t</TD><TD>Whether or not to manually feed the page</TD></TR> <TR><TD>MediaPosition</TD><TD>unsigned</TD><TD>The input slot number to use</TD></TR> <TR><TD>MediaWeight</TD><TD>unsigned</TD><TD>The weight of the output media in grams/m<SUP>2</SUP></TD></TR> <TR><TD>MirrorPrint</TD><TD>cups_bool_t</TD><TD>Whether or not to mirror the print</TD></TR> <TR><TD>NegativePrint</TD><TD>cups_bool_t</TD><TD>Whether or not to invert the print</TD></TR> <TR><TD>NumCopies</TD><TD>unsigned</TD><TD>The number of copies to produce</TD></TR> <TR><TD>Orientation</TD><TD>cups_orient_t</TD><TD>The orientation of the page image</TD></TR> <TR><TD>OutputFaceUp</TD><TD>cups_bool_t</TD><TD>Whether or not to output the page face up</TD></TR> <TR><TD>PageSize</TD><TD>unsigned[2]</TD><TD>The width and height of the page in points</TD></TR> <TR><TD>Separations</TD><TD>cups_bool_t</TD><TD>Whether or not to output separations</TD></TR> <TR><TD>TraySwitch</TD><TD>cups_bool_t</TD><TD>Whether or not to automatically switch trays for the requested media size/type</TD></TR> <TR><TD>Tumble</TD><TD>cups_bool_t</TD><TD>Whether or not to rotate the back side of the page</TD></TR> <TR><TD>cupsWidth</TD><TD>unsigned</TD><TD>The width of the page image in pixels</TD></TR> <TR><TD>cupsHeight</TD><TD>unsigned</TD><TD>The height of the page image in pixels</TD></TR> <TR><TD>cupsMediaType</TD><TD>unsigned</TD><TD>The device-specific media type code</TD></TR> <TR><TD>cupsBitsPerColor</TD><TD>unsigned</TD><TD>The number of bits per color</TD></TR> <TR><TD>cupsBitsPerPixel</TD><TD>unsigned</TD><TD>The number of bits per pixel</TD></TR> <TR><TD>cupsBytesPerLine</TD><TD>unsigned</TD><TD>The number of bytes per line of image data</TD></TR> <TR><TD>cupsColorOrder</TD><TD>cups_order_t</TD><TD>The order of color values</TD></TR> <TR><TD>cupsColorSpace</TD><TD>cups_cspace_t</TD><TD>The type of color values</TD></TR> <TR><TD>cupsCompression</TD><TD>unsigned</TD><TD>The device-specific compression code</TD></TR> <TR><TD>cupsRowCount</TD><TD>unsigned</TD><TD>The device-specific row count</TD></TR> <TR><TD>cupsRowFeed</TD><TD>unsigned</TD><TD>The device-specific row feed</TD></TR> <TR><TD>cupsRowStep</TD><TD>unsigned</TD><TD>The device-specific row step</TD></TR> </TABLE> </CENTER> </P> <H1 ALIGN="RIGHT"><A NAME="FUNCTIONS">D - Functions</A></H1> <P>This appendix provides a reference for all of the CUPS API functions. <!-- NEW PAGE --> </P> <H2><A NAME="cupsAddDest">cupsAddDest()</A></H2> <H3><A NAME="10_1_1">Usage</A></H3> <PRE> int cupsAddDest(const char *name, const char *instance, int num_dests, cups_dest_t **dests); </PRE> <H3><A NAME="10_1_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>name</TD><TD>The name of the destination.</TD></TR> <TR><TD>instance</TD><TD>The instance of the destination, or NULL for the primary instance.</TD></TR> <TR><TD>num_dests</TD><TD>The number of destinations in the array.</TD></TR> <TR><TD>dest</TD><TD>A pointer to the destination array pointer.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_1_3">Returns</A></H3> <P>The new number of destinations in the array.</P> <H3><A NAME="10_1_4">Description</A></H3> <P><CODE>cupsAddDest()</CODE> adds the named destination to the destination array if it does not already exist.</P> <H3><A NAME="10_1_5">Example</A></H3> <PRE> #include <cups/cups.h> int num_dests; <A HREF="#cups_dest_t">cups_dest_t</A> *dests; num_dests = cupsAddDests("foo", "bar", num_dests, &dests); </PRE> <H3><A NAME="10_1_6">See Also</A></H3> <P> <A HREF="#cupsFreeDests"><CODE>cupsFreeDests()</CODE></A>, <A HREF="#cupsGetDest"> <CODE>cupsGetDest()</CODE></A>, <A HREF="#cupsGetDests"><CODE> cupsGetDests()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsAddOption">cupsAddOption()</A></H2> <H3><A NAME="10_2_1">Usage</A></H3> <PRE> int cupsAddOption(const char *name, const char *value, int num_options, cups_option_t **options); </PRE> <H3><A NAME="10_2_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>name</TD><TD>The name of the option.</TD></TR> <TR><TD>value</TD><TD>The value of the option.</TD></TR> <TR><TD>num_options</TD><TD>Number of options currently in the array.</TD> </TR> <TR><TD>options</TD><TD>Pointer to the options array.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_2_3">Returns</A></H3> <P>The new number of options.</P> <H3><A NAME="10_2_4">Description</A></H3> <P><CODE>cupsAddOption()</CODE> adds an option to the specified array.</P> <H3><A NAME="10_2_5">Example</A></H3> <PRE> #include <cups.h> ... /* Declare the options array */ int num_options; <A HREF="#cups_option_t">cups_option_t</A> *options; /* Initialize the options array */ num_options = 0; options = (cups_option_t *)0; /* Add options using cupsAddOption() */ num_options = cupsAddOption("media", "letter", num_options, &options); num_options = cupsAddOption("resolution", "300dpi", num_options, &options); </PRE> <H3><A NAME="10_2_6">See Also</A></H3> <A HREF="#cupsEncodeOptions"><CODE>cupsEncodeOptions()</CODE></A>, <A HREF="#cupsFreeOptions"> <CODE>cupsFreeOptions()</CODE></A>, <A HREF="#cupsGetOption"><CODE> cupsGetOption()</CODE></A>, <A HREF="#cupsParseOptions"><CODE> cupsParseOptions()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="cupsCancelJob">cupsCancelJob()</A></H2> <H3><A NAME="10_3_1">Usage</A></H3> <PRE> int cupsCancelJob(const char *dest, int job); </PRE> <H3><A NAME="10_3_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>dest</TD><TD>Printer or class name</TD></TR> <TR><TD>job</TD><TD>Job ID</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_3_3">Returns</A></H3> <P>1 on success, 0 on failure. On failure the error can be found by calling <A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.</P> <H3><A NAME="10_3_4">Description</A></H3> <P><CODE>cupsCancelJob()</CODE> cancels the specifies job.</P> <H3><A NAME="10_3_5">Example</A></H3> <PRE> #include <cups.h> cupsCancelJob("LaserJet", 1); </PRE> <H3><A NAME="10_3_6">See Also</A></H3> <P> <A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>, <A HREF="#cupsPrintFile"> <CODE>cupsPrintFile()</CODE></A>, <A HREF="#cupsPrintFiles"><CODE> cupsPrintFiles()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsDoAuthentication">cupsDoAuthentication()</A></H2> <H3><A NAME="10_4_1">Usage</A></H3> <PRE> int cupsDoAuthentication(http_t *http, const char *method, const char *resource); </PRE> <H3><A NAME="10_4_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>HTTP connection to server.</TD></TR> <TR><TD>method</TD><TD>HTTP method name ("GET", "POST", "PUT", etc.)</TD> </TR> <TR><TD>resource</TD><TD>HTTP resource name.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_4_3">Returns</A></H3> <P>0 if the authentication string was successfully generated, -1 otherwise.</P> <H3><A NAME="10_4_4">Description</A></H3> <P><CODE>cupsDoAuthentication()</CODE> generates an authentication string for the given method and request. It supports Basic, Digest, and CUPS local certificate authentication methods and uses the current user and password callback to collect authentication information as needed.</P> <P>Applications using this function should set the <CODE> HTTP_FIELD_AUTHORIZATION</CODE> field to the <CODE>authstring</CODE> value in the <CODE>http_t</CODE> structure prior to issuing a new request.</P> <H3><A NAME="10_4_5">Example</A></H3> <PRE> #include <cups.h> http_t *http; char resource[HTTP_MAX_URI]; http_status_t status; ... do { httpClearFields(http); httpSetField(http, HTTP_FIELD_AUTHORIZATION, http->authstring); if (httpGet(http, resource)) { if (httpReconnect(http)) { status = HTTP_ERROR; break; } continue; } while ((status = httpUpdate(http)) == HTTP_CONTINUE); if (status == HTTP_UNAUTHORIZED) { httpFlush(http); if (cupsDoAuthentication(http, "GET", resource)) break; httpReconnect(http); continue; } } while (status == HTTP_UNAUTHORIZED); </PRE> <H3><A NAME="10_4_6">See Also</A></H3> <P> <A HREF="#cupsDoAuthentication"><CODE>cupsDoAuthentication()</CODE></A> , <A HREF="#cupsGetPassword"><CODE>cupsGetPassword()</CODE></A>, <A HREF="#cupsSetPasswordCB"> <CODE>cupsSetPasswordCB()</CODE></A>, <A HREF="#cupsSetUser"><CODE> cupsSetUser()</CODE></A>, <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsDoFileRequest">cupsDoFileRequest()</A></H2> <H3><A NAME="10_5_1">Usage</A></H3> <PRE> ipp_t * cupsDoFileRequest(http_t *http, ipp_t *request, const char *resource, const char *filename); </PRE> <H3><A NAME="10_5_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>HTTP connection to server.</TD></TR> <TR><TD>request</TD><TD>IPP request data.</TD></TR> <TR><TD>resource</TD><TD>HTTP resource name for POST.</TD></TR> <TR><TD>filename</TD><TD>File to send with POST request (<CODE>NULL</CODE> pointer if none.)</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_5_3">Returns</A></H3> <P>IPP response data or <CODE>NULL</CODE> if the request fails. On failure the error can be found by calling <A HREF="#cupsLastError"><CODE> cupsLastError()</CODE></A>.</P> <H3><A NAME="10_5_4">Description</A></H3> <P><CODE>cupsDoFileRequest()</CODE> does a HTTP POST request and provides the IPP request and optionally the contents of a file to the IPP server. It also handles resubmitting the request and performing password authentication as needed.</P> <H3><A NAME="10_5_5">Example</A></H3> <PRE> #include <cups.h> <A HREF="#http_t">http_t</A> *http; <A HREF="#cups_lang_t">cups_lang_t</A> *language; <A HREF="#ipp_t">ipp_t</A> *request; ipp_t *response; ... /* Get the default language */ language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>; /* Create a new IPP request */ request = <A HREF="#ippNew">ippNew()</A>; request->request.op.operation_id = IPP_PRINT_FILE; request->request.op.request_id = 1; /* Add required attributes */ <A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET, "attributes-charset", NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language)); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE, "attributes-natural-language", NULL, language != NULL ? language->language : "C"); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, "ipp://hostname/resource"); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", NULL, <A HREF="#cupsUser">cupsUser()</A>); /* Do the request... */ response = cupsDoFileRequest(http, request, "/resource", "filename.txt"); </PRE> <H3><A NAME="10_5_6">See Also</A></H3> <P> <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>, <A HREF="#cupsLangEncoding"> <CODE>cupsLangEncoding()</CODE></A>, <A HREF="#cupsUser"><CODE> cupsUser()</CODE></A>, <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A> , <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>, <A HREF="#ippNew"> <CODE>ippNew()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsDoRequest">cupsDoRequest()</A></H2> <H3><A NAME="10_6_1">Usage</A></H3> <PRE> ipp_t * cupsDoRequest(http_t *http, ipp_t *request, const char *resource); </PRE> <H3><A NAME="10_6_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>HTTP connection to server.</TD></TR> <TR><TD>request</TD><TD>IPP request data.</TD></TR> <TR><TD>resource</TD><TD>HTTP resource name for POST.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_6_3">Returns</A></H3> <P>IPP response data or <CODE>NULL</CODE> if the request fails. On failure the error can be found by calling <A HREF="#cupsLastError"><CODE> cupsLastError()</CODE></A>.</P> <H3><A NAME="10_6_4">Description</A></H3> <P><CODE>cupsDoRequest()</CODE> does a HTTP POST request and provides the IPP request to the IPP server. It also handles resubmitting the request and performing password authentication as needed.</P> <H3><A NAME="10_6_5">Example</A></H3> <PRE> #include <cups.h> <A HREF="#http_t">http_t</A> *http; <A HREF="#cups_lang_t">cups_lang_t</A> *language; <A HREF="#ipp_t">ipp_t</A> *request; ipp_t *response; ... /* Get the default language */ language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>; /* Create a new IPP request */ request = <A HREF="#ippNew">ippNew()</A>; request->request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES; request->request.op.request_id = 1; /* Add required attributes */ <A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET, "attributes-charset", NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language)); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE, "attributes-natural-language", NULL, language != NULL ? language->language : "C"); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, "ipp://hostname/resource"); /* Do the request... */ response = cupsDoRequest(http, request, "/resource"); </PRE> <H3><A NAME="10_6_6">See Also</A></H3> <P> <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>, <A HREF="#cupsLangEncoding"> <CODE>cupsLangEncoding()</CODE></A>, <A HREF="#cupsUser"><CODE> cupsUser()</CODE></A>, <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A> , <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>, <A HREF="#ippNew"> <CODE>ippNew()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsEncodeOptions">cupsEncodeOptions()</A></H2> <H3><A NAME="10_7_1">Usage</A></H3> <PRE> void cupsEncodeOptions(ipp_t *ipp, int num_options, cups_option_t *options); </PRE> <H3><A NAME="10_7_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request.</TD></TR> <TR><TD>num_options</TD><TD>The number of options.</TD></TR> <TR><TD>options</TD><TD>The options.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_7_3">Description</A></H3> <P><CODE>cupsEncodeOptions()</CODE> encodes all of the options in the specified array as IPP attributes and adds them to the IPP request.</P> <H3><A NAME="10_7_4">Example</A></H3> <PRE> #include <cups/cups.h> <A HREF="#ipp_t">ipp_t</A> *ipp; int num_options; <A HREF="#cups_option_t">cups_option_t</A> *options; cupsEncodeOptions(ipp, num_options, options); </PRE> <H3><A NAME="10_7_5">See Also</A></H3> <P> <A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>, <A HREF="#cupsParseOptions"> <CODE>cupsParseOptions()</CODE></A>, <A HREF="#ippNew"><CODE>ippNew()</CODE> </A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsEncryption">cupsEncryption()</A></H2> <H3><A NAME="10_8_1">Usage</A></H3> <PRE> http_encryption_t cupsEncryption(void); </PRE> <H3><A NAME="10_8_2">Returns</A></H3> <P>The current encryption setting.</P> <H3><A NAME="10_8_3">Description</A></H3> <P><CODE>cupsEncryption()</CODE> returns the current encryption setting for IPP requests such as printing.</P> <H3><A NAME="10_8_4">Example</A></H3> <PRE> #include <cups/cups.h> <A HREF="#http_t">http_t</A> *http; printf("The current encryption setting is %d.\n", cupsEncryption()); http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption()); </PRE> <H3><A NAME="10_8_5">See Also</A></H3> <P> <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>, <A HREF="#httpConnectEncrypt"> <CODE>httpConnectEncrypt()</CODE></A>, <A HREF="#ippPort"><CODE> ippPort()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsFreeDests">cupsFreeDests()</A></H2> <H3><A NAME="10_9_1">Usage</A></H3> <PRE> void cupsFreeDests(int num_dests, cups_dest_t *dests); </PRE> <H3><A NAME="10_9_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>num_dests</TD><TD>The number of destinations in the array.</TD></TR> <TR><TD>dests</TD><TD>The destination array.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_9_3">Description</A></H3> <P><CODE>cupsFreeDests()</CODE> frees a destination array that was created using <CODE>cupsGetDests()</CODE>.</P> <H3><A NAME="10_9_4">Example</A></H3> <PRE> #include <cups/cups.h> int num_dests; <A HREF="#cups_dest_t">cups_dest_t</A> *dests; cups_dest_t *dest; num_dests = cupsGetDests(&dests); dest = cupsGetDest(NULL, NULL, num_dests, dests); if (dest) printf("The default destination is %s\n", dest->name); else puts("No default destination."); cupsFreeDests(num_dests, dests); </PRE> <H3><A NAME="10_9_5">See Also</A></H3> <P> <A HREF="#cupsGetDest"><CODE>cupsGetDest()</CODE></A>, <A HREF="#cupsGetDests"> <CODE>cupsGetDests()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsFreeJobs">cupsFreeJobs()</A></H2> <H3><A NAME="10_10_1">Usage</A></H3> <PRE> void cupsFreeJobs(int num_jobs, cups_job_t *jobs); </PRE> <H3><A NAME="10_10_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>num_jobs</TD><TD>The number of jobs.</TD></TR> <TR><TD>jobs</TD><TD>The job array.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_10_3">Description</A></H3> <P><CODE>cupsFreeJobs()</CODE> frees an array of print jobs created by the <CODE>cupsGetJobs()</CODE> function.</P> <H3><A NAME="10_10_4">Example</A></H3> <PRE> #include <cups/cups.h> int i; int num_jobs; <A HREF="#cups_job_t">cups_job_t</A> *jobs; num_jobs = cupsGetJobs(&jobs, NULL, 0, 0); printf("%d active job(s):\n", num_jobs); for (i = 0; i < num_jobs; i ++) printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id, jobs[i].user, jobs[i].title, jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending"); cupsFreeJobs(num_jobs, jobs); </PRE> <H3><A NAME="10_10_5">See Also</A></H3> <P> <A HREF="#cupsGetJobs"><CODE>cupsGetJobs()</CODE></A>, <A HREF="#cupsGetDests"> <CODE>cupsGetDests()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsFreeOptions">cupsFreeOptions()</A></H2> <H3><A NAME="10_11_1">Usage</A></H3> <PRE> void cupsFreeOptions(int num_options, cups_option_t *options); </PRE> <H3><A NAME="10_11_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>num_options</TD><TD>Number of options in array.</TD></TR> <TR><TD>options</TD><TD>Pointer to options array.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_11_3">Description</A></H3> <P><CODE>cupsFreeOptions()</CODE> frees all memory associated with the option array specified.</P> <H3><A NAME="10_11_4">Example</A></H3> <PRE> #include <cups/cups.h> int num_options; <A HREF="#cups_option_t">cups_option_t</A> *options; ... cupsFreeOptions(num_options, options); </PRE> <H3><A NAME="10_11_5">See Also</A></H3> <P> <A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>, <A HREF="#cupsEncodeOptions"> <CODE>cupsEncodeOptions()</CODE></A>, <A HREF="#cupsGetOption"><CODE> cupsGetOption()</CODE></A>, <A HREF="#cupsMarkOptions"><CODE> cupsMarkOptions()</CODE></A>, <A HREF="#cupsParseOptions"><CODE> cupsParseOptions()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsGetClasses">cupsGetClasses()</A></H2> <H3><A NAME="10_12_1">Usage</A></H3> <PRE> int cupsGetClasses(char ***classes); </PRE> <H3><A NAME="10_12_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>classes</TD><TD>Pointer to character pointer array.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_12_3">Returns</A></H3> <P>The number of printer classes available.</P> <H3><A NAME="10_12_4">Description</A></H3> <P><CODE>cupsGetClasses()</CODE> gets a list of the available printer classes. The returned array should be freed using the <CODE>free()</CODE> when it is no longer needed.</P> <H3><A NAME="10_12_5">Example</A></H3> <PRE> #include <cups/cups.h> int i; int num_classes; char **classes; ... num_classes = cupsGetClasses(&classes); ... if (num_classes > 0) { for (i = 0; i < num_classes; i ++) free(classes[i]); free(classes); } </PRE> <H3><A NAME="10_12_6">See Also</A></H3> <P> <A HREF="#cupsGetDefault"><CODE>cupsGetDefault()</CODE></A>, <A HREF="#cupsGetPrinters"> <CODE>cupsGetPrinters()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsGetDefault">cupsGetDefault()</A></H2> <H3><A NAME="10_13_1">Usage</A></H3> <PRE> const char * cupsGetDefault(void); </PRE> <H3><A NAME="10_13_2">Returns</A></H3> <P>A pointer to the default destination.</P> <H3><A NAME="10_13_3">Description</A></H3> <P><CODE>cupsGetDefault()</CODE> gets the default destination printer or class. The default destination is stored in a static string and will be overwritten (usually with the same value) after each call.</P> <H3><A NAME="10_13_4">Example</A></H3> <PRE> #include <cups/cups.h> printf("The default destination is %s\n", cupsGetDefault()); </PRE> <H3><A NAME="10_13_5">See Also</A></H3> <P> <A HREF="#cupsGetClasses"><CODE>cupsGetClasses()</CODE></A>, <A HREF="#cupsGetPrinters"> <CODE>cupsGetPrinters()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsGetDest">cupsGetDest()</A></H2> <H3><A NAME="10_14_1">Usage</A></H3> <PRE> cups_dest_t * cupsGetDest(const char *name, const char *instance, int num_dests, cups_dest_t *dests); </PRE> <H3><A NAME="10_14_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>name</TD><TD>The name of the destination, or NULL for the default destination.</TD></TR> <TR><TD>instance</TD><TD>The instance of the destination, or NULL for the primary instance.</TD></TR> <TR><TD>num_dests</TD><TD>The number of destinations.</TD></TR> <TR><TD>dests</TD><TD>The destination array.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_14_3">Returns</A></H3> <P>A pointer to the specified destination, or NULL if none exists.</P> <H3><A NAME="10_14_4">Description</A></H3> <P><CODE>cupsGetDest()</CODE> finds the specified destination in the array of destinations created by the <CODE>cupsGetDests()</CODE> function.</P> <H3><A NAME="10_14_5">Example</A></H3> <PRE> #include <cups/cups.h> int num_dests; <A HREF="#cups_dest_t">cups_dest_t</A> *dests; cups_dest_t *dest; num_dests = cupsGetDests(&dests); dest = cupsGetDest(NULL, NULL, num_dests, dests); if (dest) printf("The default destination is %s\n", dest->name); else puts("No default destination."); cupsFreeDests(num_dests, dests); </PRE> <H3><A NAME="10_14_6">See Also</A></H3> <P> <A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>, <A HREF="#cupsGetJobs"> <CODE>cupsGetJobs()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsGetDests">cupsGetDests()</A></H2> <H3><A NAME="10_15_1">Usage</A></H3> <PRE> int cupsGetDests(cups_dest_t **dests); </PRE> <H3><A NAME="10_15_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>dests</TD><TD>A pointer to a destination array pointer.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_15_3">Returns</A></H3> <P>The number of available destinations.</P> <H3><A NAME="10_15_4">Description</A></H3> <P><CODE>cupsGetDests()</CODE> creates an array of available destinations that the user can print to. The array should be freed using the <CODE>cupsFreeDests()</CODE> function.</P> <H3><A NAME="10_15_5">Example</A></H3> <PRE> #include <cups/cups.h> int num_dests; <A HREF="#cups_dest_t">cups_dest_t</A> *dests; cups_dest_t *dest; num_dests = cupsGetDests(&dests); dest = cupsGetDest(NULL, NULL, num_dests, dests); if (dest) printf("The default destination is %s\n", dest->name); else puts("No default destination."); cupsFreeDests(num_dests, dests); </PRE> <H3><A NAME="10_15_6">See Also</A></H3> <P> <A HREF="#cupsFreeDests"><CODE>cupsFreeDests()</CODE></A>, <A HREF="#cupsGetDest"> <CODE>cupsGetDest()</CODE></A>, <A HREF="#cupsGetJobs"><CODE> cupsGetJobs()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsGetFd">cupsGetFd()</A></H2> <H3><A NAME="10_16_1">Usage</A></H3> <PRE> http_status_t cupsGetFd(http_t *http, const char *resource, int fd); </PRE> <H3><A NAME="10_16_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection to the server.</TD></TR> <TR><TD>resource</TD><TD>The resource name on the server.</TD></TR> <TR><TD>fd</TD><TD>The file descriptor to write to.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_16_3">Returns</A></H3> <P>The HTTP status code associated with the request.</P> <H3><A NAME="10_16_4">Description</A></H3> <P><CODE>cupsGetFd()</CODE> gets a file from the given HTTP server and writes it to the specified file descriptor, performing any authentication or encryption as required.</P> <H3><A NAME="10_16_5">Example</A></H3> <PRE> #include <cups/cups.h> http_t *http; int fd; char filename[1024]; http_status_t status; ... http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption()); fd = cupsTempFd(filename, sizeof(filename)); status = cupsGetFd(http, "/admin/cupsd.conf", fd); ... close(fd); unlink(filename); httpClose(http); </PRE> <H3><A NAME="10_16_6">See Also</A></H3> <P> <A HREF="#cupsGetFile"><CODE>cupsGetFile()</CODE></A>, <A HREF="#cupsPutFd"> <CODE>cupsPutFd()</CODE></A>, <A HREF="#cupsPutFile"><CODE>cupsPutFile()</CODE> </A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsGetFile">cupsGetFile()</A></H2> <H3><A NAME="10_17_1">Usage</A></H3> <PRE> http_status_t cupsGetFile(http_t *http, const char *resource, const char *filename); </PRE> <H3><A NAME="10_17_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection to the server.</TD></TR> <TR><TD>resource</TD><TD>The resource name on the server.</TD></TR> <TR><TD>filename</TD><TD>The filename to write to.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_17_3">Returns</A></H3> <P>The HTTP status code associated with the request.</P> <H3><A NAME="10_17_4">Description</A></H3> <P><CODE>cupsGetFile()</CODE> gets a file from the given HTTP server and writes it to the specified filename, performing any authentication or encryption as required.</P> <H3><A NAME="10_17_5">Example</A></H3> <PRE> #include <cups/cups.h> http_t *http; char filename[1024]; http_status_t status; ... http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption()); cupsTempFile(filename, sizeof(filename)); status = cupsGetFile(http, "/admin/cupsd.conf", filename); ... unlink(filename); httpClose(http); </PRE> <H3><A NAME="10_17_6">See Also</A></H3> <P> <A HREF="#cupsGetFd"><CODE>cupsGetFd()</CODE></A>, <A HREF="#cupsPutFd"> <CODE>cupsPutFd()</CODE></A>, <A HREF="#cupsPutFile"><CODE>cupsPutFile()</CODE> </A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsGetJobs">cupsGetJobs()</A></H2> <H3><A NAME="10_18_1">Usage</A></H3> <PRE> int cupsGetJobs(cups_job_t **jobs, const char *dest, int myjobs, int completed); </PRE> <H3><A NAME="10_18_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>jobs</TD><TD>A pointer to the job array pointer.</TD></TR> <TR><TD>dest</TD><TD>The destination name, or NULL if jobs for all destinations are requested.</TD></TR> <TR><TD>myjobs</TD><TD>1 if only those jobs submitted by the current <CODE> cupsUser()</CODE> should be returned, 0 for jobs submitted by all users.</TD> </TR> <TR><TD>completed</TD><TD>1 if only completed jobs should be returned, 0 if only pending/processing jobs should be returned.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_18_3">Returns</A></H3> <P>The number of jobs.</P> <H3><A NAME="10_18_4">Description</A></H3> <P><CODE>cupsGetJobs()</CODE> creates an array of print jobs based on the arguments supplied in the function call. The returned array should be freed using the <CODE>cupsFreeJobs()</CODE> function.</P> <H3><A NAME="10_18_5">Example</A></H3> <PRE> #include <cups/cups.h> int i; int num_jobs; <A HREF="#cups_job_t">cups_job_t</A> *jobs; num_jobs = cupsGetJobs(&jobs, NULL, 0, 0); printf("%d active job(s):\n", num_jobs); for (i = 0; i < num_jobs; i ++) printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id, jobs[i].user, jobs[i].title, jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending"); cupsFreeJobs(num_jobs, jobs); </PRE> <H3><A NAME="10_18_6">See Also</A></H3> <P> <A HREF="#cupsFreeJobs"><CODE>cupsFreeJobs()</CODE></A>, <A HREF="#cupsGetDests"> <CODE>cupsGetDests()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsGetOption">cupsGetOption()</A></H2> <H3><A NAME="10_19_1">Usage</A></H3> <PRE> const char * cupsGetOption(const char *name, int num_options, cups_option_t *options); </PRE> <H3><A NAME="10_19_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>name</TD><TD>The name of the option.</TD></TR> <TR><TD>num_options</TD><TD>The number of options in the array.</TD></TR> <TR><TD>options</TD><TD>The options array.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_19_3">Returns</A></H3> <P>A pointer to the option values or <CODE>NULL</CODE> if the option is not defined.</P> <H3><A NAME="10_19_4">Description</A></H3> <P><CODE>cupsGetOption()</CODE> returns the first occurrence of the named option. If the option is not included in the options array then a <CODE>NULL</CODE> pointer is returned.</P> <PRE> #include <cups/cups.h> int num_options; cups_option_t *options; const char *media; ... media = cupsGetOption("media", num_options, options); </PRE> <H3><A NAME="10_19_5">See Also</A></H3> <P> <A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>, <A HREF="#cupsEncodeOptions"> <CODE>cupsEncodeOptions()</CODE></A>, <A HREF="#cupsFreeOptions"><CODE> cupsFreeOptions()</CODE></A>, <A HREF="#cupsMarkOptions"><CODE> cupsMarkOptions()</CODE></A>, <A HREF="#cupsParseOptions"><CODE> cupsParseOptions()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsGetPassword">cupsGetPassword()</A></H2> <H3><A NAME="10_20_1">Usage</A></H3> <PRE> const char * cupsGetPassword(const char *prompt); </PRE> <H3><A NAME="10_20_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>prompt</TD><TD>The prompt to display to the user.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_20_3">Returns</A></H3> <P>A pointer to the password that was entered or <CODE>NULL</CODE> if no password was entered.</P> <H3><A NAME="10_20_4">Description</A></H3> <P><CODE>cupsGetPassword()</CODE> displays the prompt string and asks the user for a password. The password text is not echoed to the user.</P> <H3><A NAME="10_20_5">Example</A></H3> <PRE> #include <cups/cups.h> char *password; ... password = cupsGetPassword("Please enter a password:"); </PRE> <H3><A NAME="10_20_6">See Also</A></H3> <P> <A HREF="#cupsDoAuthentication"><CODE>cupsDoAuthentication()</CODE></A> , <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>, <A HREF="#cupsSetPasswordCB"> <CODE>cupsSetPasswordCB()</CODE></A>, <A HREF="#cupsSetServer"><CODE> cupsSetServer()</CODE></A>, <A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE> </A>, <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsGetPPD">cupsGetPPD()</A></H2> <H3><A NAME="10_21_1">Usage</A></H3> <PRE> const char * cupsGetPPD(const char *printer); </PRE> <H3><A NAME="10_21_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>printer</TD><TD>The name of the printer.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_21_3">Returns</A></H3> <P>The name of a temporary file containing the PPD file or <CODE>NULL</CODE> if the printer cannot be located or does not have a PPD file.</P> <H3><A NAME="10_21_4">Description</A></H3> <P><CODE>cupsGetPPD()</CODE> gets a copy of the PPD file for the named printer. The printer name can be of the form "printer" or "printer@hostname".</P> <P>You should remove (unlink) the PPD file after you are done using it. The filename is stored in a static buffer and will be overwritten with each call to <CODE>cupsGetPPD()</CODE>.</P> <H3><A NAME="10_21_5">Example</A></H3> <PRE> #include <cups/cups.h> char *ppd; ... ppd = cupsGetPPD("printer@hostname"); ... unlink(ppd); </PRE> <!-- NEW PAGE --> <H2><A NAME="cupsGetPrinters">cupsGetPrinters()</A></H2> <H3><A NAME="10_22_1">Usage</A></H3> <PRE> int cupsGetPrinters(char ***printers); </PRE> <H3><A NAME="10_22_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>printers</TD><TD>Pointer to character pointer array.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_22_3">Returns</A></H3> <P>The number of printer printers available.</P> <H3><A NAME="10_22_4">Description</A></H3> <P><CODE>cupsGetPrinters()</CODE> gets a list of the available printers. The returned array should be freed using the <CODE>free()</CODE> when it is no longer needed.</P> <H3><A NAME="10_22_5">Example</A></H3> <PRE> #include <cups/cups.h> int i; int num_printers; char **printers; ... num_printers = cupsGetPrinters(&printers); ... if (num_printers > 0) { for (i = 0; i < num_printers; i ++) free(printers[i]); free(printers); } </PRE> <H3><A NAME="10_22_6">See Also</A></H3> <P> <A HREF="#cupsGetClasses"><CODE>cupsGetClasses()</CODE></A> <A HREF="#cupsGetDefault"> <CODE>cupsGetDefault()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsLangDefault">cupsLangDefault()</A></H2> <H3><A NAME="10_23_1">Usage</A></H3> <PRE> const char * cupsLangDefault(void); </PRE> <H3><A NAME="10_23_2">Returns</A></H3> <P>A pointer to the default language structure.</P> <H3><A NAME="10_23_3">Description</A></H3> <P><CODE>cupsLangDefault()</CODE> returns a language structure for the default language. The default language is defined by the <CODE>LANG</CODE> environment variable. If the specified language cannot be located then the POSIX (English) locale is used.</P> <P>Call <CODE>cupsLangFree()</CODE> to free any memory associated with the language structure when you are done.</P> <H3><A NAME="10_23_4">Example</A></H3> <PRE> #include <cups/language.h> <A HREF="#cups_lang_t">cups_lang_t</A> *language; ... language = cupsLangDefault(); ... cupsLangFree(language); </PRE> <H3><A NAME="10_23_5">See Also</A></H3> <P> <A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>, <A HREF="#cupsLangFlush"> <CODE>cupsLangFlush()</CODE></A>, <A HREF="#cupsLangFree"><CODE> cupsLangFree()</CODE></A>, <A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE> </A>, <A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsLangEncoding">cupsLangEncoding()</A></H2> <H3><A NAME="10_24_1">Usage</A></H3> <PRE> char * cupsLangEncoding(cups_lang_t *language); </PRE> <H3><A NAME="10_24_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>language</TD><TD>The language structure.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_24_3">Returns</A></H3> <P>A pointer to the encoding string.</P> <H3><A NAME="10_24_4">Description</A></H3> <P><CODE>cupsLangEncoding()</CODE> returns the language encoding used for the specified language, e.g. "iso-8859-1", "utf-8", etc.</P> <H3><A NAME="10_24_5">Example</A></H3> <PRE> #include <cups/language.h> <A HREF="#cups_lang_t">cups_lang_t</A> *language; char *encoding; ... language = cupsLangDefault(); encoding = cupsLangEncoding(language); ... cupsLangFree(language); </PRE> <H3><A NAME="10_24_6">See Also</A></H3> <P> <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>, <A HREF="#cupsLangFlush"> <CODE>cupsLangFlush()</CODE></A>, <A HREF="#cupsLangFree"><CODE> cupsLangFree()</CODE></A>, <A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE> </A>, <A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsLangFlush">cupsLangFlush()</A></H2> <H3><A NAME="10_25_1">Usage</A></H3> <PRE> void cupsLangFlush(void); </PRE> <H3><A NAME="10_25_2">Description</A></H3> <P><CODE>cupsLangFlush()</CODE> frees all language structures that have been allocated.</P> <H3><A NAME="10_25_3">Example</A></H3> <PRE> #include <cups/language.h> ... cupsLangFlush(); </PRE> <H3><A NAME="10_25_4">See Also</A></H3> <P> <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>, <A HREF="#cupsLangEncoding"> <CODE>cupsLangEncoding()</CODE></A>, <A HREF="#cupsLangFree"><CODE> cupsLangFree()</CODE></A>, <A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE> </A>, <A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsLangFree">cupsLangFree()</A></H2> <H3><A NAME="10_26_1">Usage</A></H3> <PRE> void cupsLangFree(cups_lang_t *language); </PRE> <H3><A NAME="10_26_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>language</TD><TD>The language structure to free.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_26_3">Description</A></H3> <P><CODE>cupsLangFree()</CODE> frees the specified language structure.</P> <H3><A NAME="10_26_4">Example</A></H3> <PRE> #include <cups/language.h> <A HREF="#cups_lang_t">cups_lang_t</A> *language; ... cupsLangFree(language); </PRE> <H3><A NAME="10_26_5">See Also</A></H3> <P> <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>, <A HREF="#cupsLangEncoding"> <CODE>cupsLangEncoding()</CODE></A>, <A HREF="#cupsLangFlush"><CODE> cupsLangFlush()</CODE></A>, <A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE> </A>, <A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsLangGet">cupsLangGet()</A></H2> <H3><A NAME="10_27_1">Usage</A></H3> <PRE> cups_lang_t * cupsLangGet(const char *name); </PRE> <H3><A NAME="10_27_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>name</TD><TD>The name of the locale.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_27_3">Returns</A></H3> <P>A pointer to a language structure.</P> <H3><A NAME="10_27_4">Description</A></H3> <P><CODE>cupsLangGet()</CODE> returns a language structure for the specified locale. If the locale is not defined then the POSIX (English) locale is substituted.</P> <H3><A NAME="10_27_5">Example</A></H3> <PRE> #include <cups/language.h> <A HREF="#cups_lang_t">cups_lang_t</A> *language; ... language = cupsLangGet("fr"); ... cupsLangFree(language); </PRE> <H3><A NAME="10_27_6">See Also</A></H3> <P> <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>, <A HREF="#cupsLangEncoding"> <CODE>cupsLangEncoding()</CODE></A>, <A HREF="#cupsLangFlush"><CODE> cupsLangFlush()</CODE></A>, <A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE> </A>, <A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsLangString">cupsLangString()</A></H2> <H3><A NAME="10_28_1">Usage</A></H3> <PRE> char * cupsLangString(cups_lang_t *language, int message); </PRE> <H3><A NAME="10_28_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>language</TD><TD>The language to query.</TD></TR> <TR><TD>message</TD><TD>The message number.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_28_3">Returns</A></H3> <P>A pointer to the message string or <CODE>NULL</CODE> if the message is not defined.</P> <H3><A NAME="10_28_4">Description</A></H3> <P><CODE>cupsLangString()</CODE> returns a pointer to the specified message string in the specified language.</P> <H3><A NAME="10_28_5">Example</A></H3> <PRE> #include <cups/language.h> <A HREF="#cups_lang_t">cups_lang_t</A> *language; char *s; ... language = cupsLangGet("fr"); s = cupsLangString(language, CUPS_MSG_YES); ... cupsLangFree(language); </PRE> <H3><A NAME="10_28_6">See Also</A></H3> <P> <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>, <A HREF="#cupsLangEncoding"> <CODE>cupsLangEncoding()</CODE></A>, <A HREF="#cupsLangFlush"><CODE> cupsLangFlush()</CODE></A>, <A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE> </A>, <A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsLastError">cupsLastError()</A></H2> <H3><A NAME="10_29_1">Usage</A></H3> <PRE> ipp_status_t cupsLastError(void); </PRE> <H3><A NAME="10_29_2">Returns</A></H3> <P>An enumeration containing the last IPP error.</P> <H3><A NAME="10_29_3">Description</A></H3> <P><CODE>cupsLastError()</CODE> returns the last IPP error that occurred. If no error occurred then it will return <CODE>IPP_OK</CODE> or <CODE>IPP_OK_CONFLICT</CODE>.</P> <H3><A NAME="10_29_4">Example</A></H3> <PRE> #include <cups/cups.h> ipp_status_t status; ... status = cupsLastError(); </PRE> <H3><A NAME="10_29_5">See Also</A></H3> <P> <A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>, <A HREF="#cupsPrintFile"> <CODE>cupsPrintFile()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsMarkOptions">cupsMarkOptions()</A></H2> <H3><A NAME="10_30_1">Usage</A></H3> <PRE> int cupsMarkOptions(ppd_file_t *ppd, int num_options, cups_option_t *options); </PRE> <H3><A NAME="10_30_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file to mark.</TD></TR> <TR><TD>num_options</TD><TD>The number of options in the options array.</TD> </TR> <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_30_3">Returns</A></H3> <P>The number of conflicts found.</P> <H3><A NAME="10_30_4">Description</A></H3> <P><CODE>cupsMarkOptions()</CODE> marks options in the PPD file. It also handles mapping of IPP option names and values to PPD option names.</P> <H3><A NAME="10_30_5">Example</A></H3> <PRE> #include <cups/cups.h> int num_options; <A HREF="#cups_option_t">cups_option_t</A> *options; <A HREF="#ppd_file_t">ppd_file_t</A> *ppd; ... cupsMarkOptions(ppd, num_options, options); </PRE> <H3><A NAME="10_30_6">See Also</A></H3> <P> <A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>, <A HREF="#cupsFreeOptions"> <CODE>cupsFreeOptions()</CODE></A>, <A HREF="#cupsGetOption"><CODE> cupsGetOption()</CODE></A>, <A HREF="#cupsParseOptions"><CODE> cupsParseOptions()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsParseOptions">cupsParseOptions()</A></H2> <H3><A NAME="10_31_1">Usage</A></H3> <PRE> int cupsParseOptions(const char *arg, int num_options, cups_option_t **options); </PRE> <H3><A NAME="10_31_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>arg</TD><TD>The string containing one or more options.</TD></TR> <TR><TD>num_options</TD><TD>The number of options in the options array.</TD> </TR> <TR><TD>options</TD><TD>A pointer to the options array pointer.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_31_3">Returns</A></H3> <P>The new number of options in the array.</P> <H3><A NAME="10_31_4">Description</A></H3> <P><CODE>cupsParseOptions()</CODE> parses the specifies string for one or more options of the form "name=value", "name", or "noname". It can be called multiple times to combine the options from several strings.</P> <H3><A NAME="10_31_5">Example</A></H3> <PRE> #include <cups/cups.h> int num_options; <A HREF="#cups_option_t">cups_option_t</A> *options; ... num_options = 0; options = (cups_option_t *)0; num_options = cupsParseOptions(argv[5], num_options, &options); </PRE> <H3><A NAME="10_31_6">See Also</A></H3> <P> <A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>, <A HREF="#cupsFreeOptions"> <CODE>cupsFreeOptions()</CODE></A>, <A HREF="#cupsGetOption"><CODE> cupsGetOption()</CODE></A>, <A HREF="#cupsMarkOptions"><CODE> cupsMarkOptions()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsPrintFile">cupsPrintFile()</A></H2> <H3><A NAME="10_32_1">Usage</A></H3> <PRE> int cupsPrintFile(const char *printer, const char *filename, const char *title, int num_options, cups_option_t *options); </PRE> <H3><A NAME="10_32_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>printer</TD><TD>The printer or class to print to.</TD></TR> <TR><TD>filename</TD><TD>The file to print.</TD></TR> <TR><TD>title</TD><TD>The job title.</TD></TR> <TR><TD>num_options</TD><TD>The number of options in the options array.</TD> </TR> <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_32_3">Returns</A></H3> <P>The new job ID number or 0 on error.</P> <H3><A NAME="10_32_4">Description</A></H3> <P><CODE>cupsPrintFile()</CODE> sends a file to the specified printer or class for printing. If the job cannot be printed the error code can be found by calling <CODE>cupsLastError()</CODE>.</P> <H3><A NAME="10_32_5">Example</A></H3> <PRE> #include <cups/cups.h> int num_options; <A HREF="#cups_option_t">cups_option_t</A> *options; int jobid; ... jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title", num_options, options); </PRE> <H3><A NAME="10_32_6">See Also</A></H3> <P> <A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>, <A HREF="#cupsLastError"> <CODE>cupsLastError()</CODE></A>, <A HREF="#cupsPrintFiles"><CODE> cupsPrintFiles()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsPrintFiles">cupsPrintFiles()</A></H2> <H3><A NAME="10_33_1">Usage</A></H3> <PRE> int cupsPrintFiles(const char *printer, int num_files, const char **files, const char *title, int num_options, cups_option_t *options); </PRE> <H3><A NAME="10_33_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>printer</TD><TD>The printer or class to print to.</TD></TR> <TR><TD>num_files</TD><TD>The number of files to print.</TD></TR> <TR><TD>files</TD><TD>The files to print.</TD></TR> <TR><TD>title</TD><TD>The job title.</TD></TR> <TR><TD>num_options</TD><TD>The number of options in the options array.</TD> </TR> <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_33_3">Returns</A></H3> <P>The new job ID number or 0 on error.</P> <H3><A NAME="10_33_4">Description</A></H3> <P><CODE>cupsPrintFiles()</CODE> sends multiple files to the specified printer or class for printing. If the job cannot be printed the error code can be found by calling <CODE>cupsLastError()</CODE>.</P> <H3><A NAME="10_33_5">Example</A></H3> <PRE> #include <cups/cups.h> int num_files; const char *files[100]; int num_options; <A HREF="#cups_option_t">cups_option_t</A> *options; int jobid; ... jobid = cupsPrintFiles("printer@hostname", num_files, files, "Job Title", num_options, options); </PRE> <H3><A NAME="10_33_6">See Also</A></H3> <P> <A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>, <A HREF="#cupsLastError"> <CODE>cupsLastError()</CODE></A>, <A HREF="#cupsPrintFile"><CODE> cupsPrintFile()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsPutFd">cupsPutFd()</A></H2> <H3><A NAME="10_34_1">Usage</A></H3> <PRE> http_status_t cupsPutFd(http_t *http, const char *resource, int fd); </PRE> <H3><A NAME="10_34_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection to the server.</TD></TR> <TR><TD>resource</TD><TD>The resource name on the server.</TD></TR> <TR><TD>fd</TD><TD>The file descriptor to read from.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_34_3">Returns</A></H3> <P>The HTTP status code associated with the request.</P> <H3><A NAME="10_34_4">Description</A></H3> <P><CODE>cupsPutFd()</CODE> puts a file to the given HTTP server, reading it from the specified file descriptor and performing any authentication or encryption as required.</P> <H3><A NAME="10_34_5">Example</A></H3> <PRE> #include <cups/cups.h> http_t *http; int fd; http_status_t status; ... http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption()); status = cupsPutFd(http, "/admin/cupsd.conf", fd); httpClose(http); </PRE> <H3><A NAME="10_34_6">See Also</A></H3> <P> <A HREF="#cupsGetFd"><CODE>cupsGetFd()</CODE></A>, <A HREF="#cupsGetFile"> <CODE>cupsGetFile()</CODE></A>, <A HREF="#cupsPutFile"><CODE> cupsPutFile()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsPutFile">cupsPutFile()</A></H2> <H3><A NAME="10_35_1">Usage</A></H3> <PRE> http_status_t cupsPutFile(http_t *http, const char *resource, const char *filename); </PRE> <H3><A NAME="10_35_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection to the server.</TD></TR> <TR><TD>resource</TD><TD>The resource name on the server.</TD></TR> <TR><TD>filename</TD><TD>The filename to read from.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_35_3">Returns</A></H3> <P>The HTTP status code associated with the request.</P> <H3><A NAME="10_35_4">Description</A></H3> <P><CODE>cupsPutFile()</CODE> puts a file on the given HTTP server, reading it from the specified filename and performing any authentication or encryption as required.</P> <H3><A NAME="10_35_5">Example</A></H3> <PRE> #include <cups/cups.h> http_t *http; char filename[1024]; http_status_t status; ... http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption()); status = cupsPutFile(http, "/admin/cupsd.conf", filename); httpClose(http); </PRE> <H3><A NAME="10_35_6">See Also</A></H3> <P> <A HREF="#cupsGetFd"><CODE>cupsGetFd()</CODE></A>, <A HREF="#cupsGetFile"> <CODE>cupsGetFile()</CODE></A>, <A HREF="#cupsPutFd"><CODE>cupsPutFd()</CODE> </A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsRasterClose">cupsRasterClose()</A></H2> <H3><A NAME="10_36_1">Usage</A></H3> <PRE> void cupsRasterClose(cups_raster_t *ras); </PRE> <H3><A NAME="10_36_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ras</TD><TD>The raster stream to close.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_36_3">Description</A></H3> <P><CODE>cupsRasterClose()</CODE> closes the specified raster stream.</P> <H3><A NAME="10_36_4">Example</A></H3> <PRE> #include <cups/raster.h> <A HREF="#cups_raster_t">cups_raster_t</A> *ras; ... cupsRasterClose(ras); </PRE> <H3><A NAME="10_36_5">See Also</A></H3> <P> <A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>, <A HREF="#cupsRasterReadHeader"> <CODE>cupsRasterReadHeader()</CODE></A>, <A HREF="#cupsRasterReadPixels"> <CODE>cupsRasterReadPixels()</CODE></A>, <A HREF="#cupsRasterWriteHeader"> <CODE>cupsRasterWriteHeader()</CODE></A>, <A HREF="#cupsRasterWritePixels"> <CODE>cupsRasterWritePixels()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsRasterOpen">cupsRasterOpen()</A></H2> <H3><A NAME="10_37_1">Usage</A></H3> <PRE> cups_raster_t * cupsRasterOpen(int fd, cups_mode_t mode); </PRE> <H3><A NAME="10_37_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>fd</TD><TD>The file descriptor to use.</TD></TR> <TR><TD>mode</TD><TD>The mode to use; <CODE>CUPS_RASTER_READ</CODE> or <CODE> CUPS_RASTER_WRITE</CODE>.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_37_3">Returns</A></H3> <P>A pointer to a raster stream or <CODE>NULL</CODE> if there was an error.</P> <H3><A NAME="10_37_4">Description</A></H3> <P><CODE>cupsRasterOpen()</CODE> opens a raster stream for reading or writing.</P> <H3><A NAME="10_37_5">Example</A></H3> <PRE> #include <cups/raster.h> <A HREF="#cups_raster_t">cups_raster_t</A> *ras; ... ras = cupsRasterOpen(0, CUPS_RASTER_READ); </PRE> <H3><A NAME="10_37_6">See Also</A></H3> <P> <A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>, <A HREF="#cupsRasterReadHeader"> <CODE>cupsRasterReadHeader()</CODE></A>, <A HREF="#cupsRasterReadPixels"> <CODE>cupsRasterReadPixels()</CODE></A>, <A HREF="#cupsRasterWriteHeader"> <CODE>cupsRasterWriteHeader()</CODE></A>, <A HREF="#cupsRasterWritePixels"> <CODE>cupsRasterWritePixels()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsRasterReadHeader">cupsRasterReadHeader()</A></H2> <H3><A NAME="10_38_1">Usage</A></H3> <PRE> unsigned cupsRasterReadHeader(cups_raster_t *ras, cups_page_header_t *header); </PRE> <H3><A NAME="10_38_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ras</TD><TD>The raster stream to read from.</TD></TR> <TR><TD>header</TD><TD>A pointer to a page header structure to read into.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_38_3">Returns</A></H3> <P>1 on success, 0 on EOF or error.</P> <H3><A NAME="10_38_4">Description</A></H3> <P><CODE>cupsRasterReadHeader()</CODE> reads a page header from the specified raster stream.</P> <H3><A NAME="10_38_5">Example</A></H3> <PRE> #include <cups/raster.h> int line; <A HREF="#cups_raster_t">cups_raster_t</A> *ras; <A HREF="#cups_raster_header_t">cups_raster_header_t</A> header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } </PRE> <H3><A NAME="10_38_6">See Also</A></H3> <P> <A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>, <A HREF="#cupsRasterOpen"> <CODE>cupsRasterOpen()</CODE></A>, <A HREF="#cupsRasterReadPixels"><CODE> cupsRasterReadPixels()</CODE></A>, <A HREF="#cupsRasterWriteHeader"><CODE> cupsRasterWriteHeader()</CODE></A>, <A HREF="#cupsRasterWritePixels"><CODE> cupsRasterWritePixels()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsRasterReadPixels">cupsRasterReadPixels()</A></H2> <H3><A NAME="10_39_1">Usage</A></H3> <PRE> unsigned cupsRasterReadPixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); </PRE> <H3><A NAME="10_39_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ras</TD><TD>The raster stream to read from.</TD></TR> <TR><TD>pixels</TD><TD>The pointer to a pixel buffer.</TD></TR> <TR><TD>length</TD><TD>The number of bytes of pixel data to read.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_39_3">Returns</A></H3> <P>The number of bytes read or 0 on EOF or error.</P> <H3><A NAME="10_39_4">Description</A></H3> <P><CODE>cupsRasterReadPixels()</CODE> reads pixel data from the specified raster stream.</P> <H3><A NAME="10_39_5">Example</A></H3> <PRE> #include <cups/raster.h> int line; <A HREF="#cups_raster_t">cups_raster_t</A> *ras; <A HREF="#cups_raster_header_t">cups_raster_header_t</A> header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } </PRE> <H3><A NAME="10_39_6">See Also</A></H3> <P> <A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>, <A HREF="#cupsRasterOpen"> <CODE>cupsRasterOpen()</CODE></A>, <A HREF="#cupsRasterReadHeader"><CODE> cupsRasterReadHeader()</CODE></A>, <A HREF="#cupsRasterWriteHeader"><CODE> cupsRasterWriteHeader()</CODE></A>, <A HREF="#cupsRasterWritePixels"><CODE> cupsRasterWritePixels()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsRasterWriteHeader">cupsRasterWriteHeader()</A></H2> <H3><A NAME="10_40_1">Usage</A></H3> <PRE> unsigned cupsRasterWriteHeader(cups_raster_t *ras, cups_page_header_t *header); </PRE> <H3><A NAME="10_40_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ras</TD><TD>The raster stream to write to.</TD></TR> <TR><TD>header</TD><TD>A pointer to the page header to write.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_40_3">Returns</A></H3> <P>1 on success, 0 on error.</P> <H3><A NAME="10_40_4">Description</A></H3> <P><CODE>cupsRasterWriteHeader()</CODE> writes the specified page header to a raster stream.</P> <H3><A NAME="10_40_5">Example</A></H3> <PRE> #include <cups/raster.h> int line; <A HREF="#cups_raster_t">cups_raster_t</A> *ras; <A HREF="#cups_raster_header_t">cups_raster_header_t</A> header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } </PRE> <H3><A NAME="10_40_6">See Also</A></H3> <P> <A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>, <A HREF="#cupsRasterOpen"> <CODE>cupsRasterOpen()</CODE></A>, <A HREF="#cupsRasterReadHeader"><CODE> cupsRasterReadHeader()</CODE></A>, <A HREF="#cupsRasterReadPixels"><CODE> cupsRasterReadPixels()</CODE></A>, <A HREF="#cupsRasterWritePixels"><CODE> cupsRasterWritePixels()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsRasterWritePixels">cupsRasterWritePixels()</A></H2> <H3><A NAME="10_41_1">Usage</A></H3> <PRE> unsigned cupsRasterWritePixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); </PRE> <H3><A NAME="10_41_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ras</TD><TD>The raster stream to write to.</TD></TR> <TR><TD>pixels</TD><TD>The pixel data to write.</TD></TR> <TR><TD>length</TD><TD>The number of bytes to write.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_41_3">Returns</A></H3> <P>The number of bytes written.</P> <H3><A NAME="10_41_4">Description</A></H3> <P><CODE>cupsRasterWritePixels()</CODE> writes the specified pixel data to a raster stream.</P> <H3><A NAME="10_41_5">Example</A></H3> <PRE> #include <cups/raster.h> int line; <A HREF="#cups_raster_t">cups_raster_t</A> *ras; <A HREF="#cups_raster_header_t">cups_raster_header_t</A> header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } </PRE> <H3><A NAME="10_41_6">See Also</A></H3> <P> <A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>, <A HREF="#cupsRasterOpen"> <CODE>cupsRasterOpen()</CODE></A>, <A HREF="#cupsRasterReadHeader"><CODE> cupsRasterReadHeader()</CODE></A>, <A HREF="#cupsRasterReadPixels"><CODE> cupsRasterReadPixels()</CODE></A>, <A HREF="#cupsRasterWriteHeader"><CODE> cupsRasterWriteHeader()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsServer">cupsServer()</A></H2> <H3><A NAME="10_42_1">Usage</A></H3> <PRE> const char * cupsServer(void); </PRE> <H3><A NAME="10_42_2">Returns</A></H3> <P>A pointer to the default server name.</P> <H3><A NAME="10_42_3">Description</A></H3> <P><CODE>cupsServer()</CODE> returns a pointer to the default server name. The server name is stored in a static location and will be overwritten with every call to <CODE>cupsServer()</CODE>.</P> <P>The default server is determined from the following locations:</P> <OL> <LI>The <CODE>CUPS_SERVER</CODE> environment variable,</LI> <LI>The <CODE>ServerName</CODE> directive in the<VAR> client.conf</VAR> file,</LI> <LI>The default host, "localhost".</LI> </OL> <H3><A NAME="10_42_4">Example</A></H3> <PRE> #include <cups/cups.h> const char *server; server = cupsServer(); </PRE> <H3><A NAME="10_42_5">See Also</A></H3> <P> <A HREF="#cupsGetPassword"><CODE>cupsGetPassword()</CODE></A>, <A HREF="#cupsSetPasswordCB"> <CODE>cupsSetPasswordCB()</CODE></A>, <A HREF="#cupsSetServer"><CODE> cupsSetServer()</CODE></A>, <A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE> </A>, <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsSetDests">cupsSetDests()</A></H2> <H3><A NAME="10_43_1">Usage</A></H3> <PRE> void cupsSetDests(int num_dests, cups_dest_t *dests); </PRE> <H3><A NAME="10_43_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>num_dests</TD><TD>Number of destinations.</TD></TR> <TR><TD>dests</TD><TD>Array of destinations.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_43_3">Description</A></H3> <P><CODE>cupsSetDests()</CODE> saves the destination array to disk. If the current UID is 0, the destinations are saved in the<VAR> /etc/cups/lpoptions</VAR> file, otherwise they are saved in the<VAR> ~/.lpoptions</VAR> file. This function is typically used to save the default options and instances that are set by the user.</P> <H3><A NAME="10_43_4">Example</A></H3> <PRE> #include <cups/cups.h> int num_dests; <A HREF="#cups_dest_t">cups_dest_t</A> *dests; ... cupsSetDests(num_dests, dests); </PRE> <H3><A NAME="10_43_5">See Also</A></H3> <P> <A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsSetEncryption">cupsSetEncryption()</A></H2> <H3><A NAME="10_44_1">Usage</A></H3> <PRE> void cupsSetEncryption(http_encryption_t encryption); </PRE> <H3><A NAME="10_44_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>encryption</TD><TD>The type of encryption to use.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_44_3">Description</A></H3> <P><CODE>cupsSetEncryption()</CODE> sets the default type of encryption to use when connecting with the print server.</P> <H3><A NAME="10_44_4">Example</A></H3> <PRE> #include <cups/cups.h> cupsSetEncryption(HTTP_ENCRYPT_REQUIRED); </PRE> <H3><A NAME="10_44_5">See Also</A></H3> <P> <A HREF="#cupsEncryption"><CODE>cupsEncryption()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsSetPasswordCB">cupsSetPasswordCB()</A></H2> <H3><A NAME="10_45_1">Usage</A></H3> <PRE> void cupsSetPasswordCB(const char *(*cb)(const char *prompt)); </PRE> <H3><A NAME="10_45_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>cb</TD><TD>The password callback function.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_45_3">Description</A></H3> <P><CODE>cupsSetPasswordCB()</CODE> sets the callback function to use when asking the user for a password. The callback function must accept a single character string pointer (the prompt string) and return <CODE> NULL</CODE> if the user did not enter a password string or a pointer to the password string otherwise.</P> <H3><A NAME="10_45_4">Example</A></H3> <PRE> #include <cups/cups.h> const char * my_password_cb(const char *prompt) { return (getpass(prompt)); } ... char *password; ... cupsSetPasswordCB(my_password_cb); password = cupsGetPassword("Please enter a password:"); </PRE> <H3><A NAME="10_45_5">See Also</A></H3> <P> <A HREF="#cupsDoAuthentication"><CODE>cupsDoAuthentication()</CODE></A> , <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>, <A HREF="#cupsSetServer"> <CODE>cupsSetServer()</CODE></A>, <A HREF="#cupsSetUser"><CODE> cupsSetUser()</CODE></A>, <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsSetServer">cupsSetServer()</A></H2> <H3><A NAME="10_46_1">Usage</A></H3> <PRE> void cupsSetServer(const char *server); </PRE> <H3><A NAME="10_46_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>server</TD><TD>The default server to use.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_46_3">Description</A></H3> <P><CODE>cupsSetServer()</CODE> sets the default server to use for the CUPS API. If the <CODE>server</CODE> argument is <CODE>NULL</CODE>, the default server is used.</P> <H3><A NAME="10_46_4">Example</A></H3> <PRE> #include <cups/cups.h> cupsSetServer("foo.bar.com"); </PRE> <H3><A NAME="10_46_5">See Also</A></H3> <P> <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>, <A HREF="#cupsSetPasswordCB"> <CODE>cupsSetPasswordCB()</CODE></A>, <A HREF="#cupsSetUser"><CODE> cupsSetUser()</CODE></A>, <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsSetUser">cupsSetUser()</A></H2> <H3><A NAME="10_47_1">Usage</A></H3> <PRE> void cupsSetUser(const char *user); </PRE> <H3><A NAME="10_47_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>user</TD><TD>The user name string to use.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_47_3">Description</A></H3> <P><CODE>cupsSetUser()</CODE> sets the default user name for authentication. If the <CODE>user</CODE> argument is <CODE>NULL</CODE> then the current login user is used.</P> <H3><A NAME="10_47_4">Example</A></H3> <PRE> #include <cups/cups.h> ... cupsSetUser("root"); </PRE> <H3><A NAME="10_47_5">See Also</A></H3> <P> <A HREF="#cupsDoAuthentication"><CODE>cupsDoAuthentication()</CODE></A> , <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>, <A HREF="#cupsSetPasswordCB"> <CODE>cupsSetPasswordCB()</CODE></A>, <A HREF="#cupsSetServer"><CODE> cupsSetServer()</CODE></A>, <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsTempFd">cupsTempFd()</A></H2> <H3><A NAME="10_48_1">Usage</A></H3> <PRE> int cupsTempFd(char *filename, int length); </PRE> <H3><A NAME="10_48_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>filename</TD><TD>The character string to hold the temporary filename.</TD></TR> <TR><TD>length</TD><TD>The size of the filename string in bytes.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_48_3">Returns</A></H3> <P>A file descriptor open for reading and writing.</P> <H3><A NAME="10_48_4">Description</A></H3> <P><CODE>cupsTempFd()</CODE> create a temporary filename in the<VAR> /var/tmp</VAR> directory or the directory specified by the <CODE>TMPDIR</CODE> environment variable.</P> <H3><A NAME="10_48_5">Example</A></H3> <PRE> #include <cups/cups.h> int fd; char filename[256]; fd = cupsTempFd(filename, sizeof(filename)); </PRE> <H3><A NAME="10_48_6">See Also</A></H3> <P> <A HREF="#cupsTempFile"><CODE>cupsTempFile()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsTempFile">cupsTempFile()</A></H2> <H3><A NAME="10_49_1">Usage</A></H3> <PRE> char * cupsTempFile(char *filename, int length); </PRE> <H3><A NAME="10_49_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>filename</TD><TD>The character string to hold the temporary filename.</TD></TR> <TR><TD>length</TD><TD>The size of the filename string in bytes.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_49_3">Returns</A></H3> <P>A pointer to <CODE>filename</CODE>.</P> <H3><A NAME="10_49_4">Description</A></H3> <P><CODE>cupsTempFile()</CODE> creates a temporary filename in the<VAR> /var/tmp</VAR> directory or the directory specified by the <CODE>TMPDIR</CODE> environment variable.</P> <H3><A NAME="10_49_5">Example</A></H3> <PRE> #include <cups/cups.h> char filename[256]; cupsTempFile(filename, sizeof(filename)); </PRE> <H3><A NAME="10_49_6">See Also</A></H3> <P> <A HREF="#cupsTempFd"><CODE>cupsTempFd()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="cupsUser">cupsUser()</A></H2> <H3><A NAME="10_50_1">Usage</A></H3> <PRE> const char * cupsUser(void); </PRE> <H3><A NAME="10_50_2">Returns</A></H3> <P>A pointer to the current username or <CODE>NULL</CODE> if the user ID is undefined.</P> <H3><A NAME="10_50_3">Description</A></H3> <P><CODE>cupsUser()</CODE> returns the name associated with the current user ID as reported by the <CODE>getuid()</CODE> system call.</P> <H3><A NAME="10_50_4">Example</A></H3> <PRE> #include <cups/cups.h> const char *user; user = cupsUser(); </PRE> <H3><A NAME="10_50_5">See Also</A></H3> <P> <A HREF="#cupsDoAuthentication"><CODE>cupsDoAuthentication()</CODE></A> , <A HREF="#cupsGetPassword"><CODE>cupsGetPassword()</CODE></A>, <A HREF="#cupsServer"> <CODE>cupsServer()</CODE></A>, <A HREF="#cupsSetServer"><CODE> cupsSetServer()</CODE></A>, <A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE> </A> <!-- NEW PAGE --> </P> <H2><A NAME="httpBlocking">httpBlocking()</A></H2> <H3><A NAME="10_51_1">Usage</A></H3> <PRE> void httpBlocking(http_t *http, int blocking) </PRE> <H3><A NAME="10_51_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>blocking</TD><TD>0 if the connection should be non-blocking, 1 if it should be blocking</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_51_3">Description</A></H3> <P>The <CODE>httpBlocking()</CODE> function sets the blocking mode for the HTTP connection. By default HTTP connections will block (stop) the client program until data is available or can be sent to the server.</P> <H3><A NAME="10_51_4">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; http = httpConnect("server", port); httpBlocking(http, 0); </PRE> <H3><A NAME="10_51_5">See Also</A></H3> <A HREF="#httpCheck"><CODE>httpCheck()</CODE></A>, <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpCheck">httpCheck()</A></H2> <H3><A NAME="10_52_1">Usage</A></H3> <PRE> int httpCheck(http_t *http); </PRE> <H3><A NAME="10_52_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_52_3">Returns</A></H3> <P>0 if there is no data pending, 1 otherwise.</P> <H3><A NAME="10_52_4">Description</A></H3> <P>The <CODE>httpCheck()</CODE> function checks to see if there is any data pending on an HTTP connection.</P> <H3><A NAME="10_52_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; if (httpCheck(http)) { ... do something ... } </PRE> <H3><A NAME="10_52_6">See Also</A></H3> <A HREF="#httpBlocking"><CODE>httpBlocking()</CODE></A>, <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>, <A HREF="#httpGets"><CODE>httpGets()</CODE> </A>, <A HREF="#httpRead"><CODE>httpRead()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpClearFields">httpClearFields()</A></H2> <H3><A NAME="10_53_1">Usage</A></H3> <PRE> void httpClearFields(http_t *http) </PRE> <H3><A NAME="10_53_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_53_3">Description</A></H3> <P>The <CODE>httpClearFields()</CODE> function clears all HTTP request fields for the HTTP connection.</P> <H3><A NAME="10_53_4">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpClearFields(http); </PRE> <H3><A NAME="10_53_5">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpGetField"> <CODE>httpGetField()</CODE></A>, <A HREF="#httpSetField"><CODE> httpSetField()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpClose">httpClose()</A></H2> <H3><A NAME="10_54_1">Usage</A></H3> <PRE> void httpClose(http_t *http); </PRE> <H3><A NAME="10_54_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_54_3">Description</A></H3> <P>The <CODE>httpClose()</CODE> function closes an active HTTP connection.</P> <H3><A NAME="10_54_4">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpClose(http); </PRE> <H3><A NAME="10_54_5">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpConnect">httpConnect()</A></H2> <H3><A NAME="10_55_1">Usage</A></H3> <PRE> http_t * httpConnect(const char *hostname, int port); </PRE> <H3><A NAME="10_55_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>hostname</TD><TD>The name or IP address of the server to connect to</TD></TR> <TR><TD>port</TD><TD>The port number to use</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_55_3">Returns</A></H3> <P>A pointer to a HTTP connection structure or NULL if the connection could not be made.</P> <H3><A NAME="10_55_4">Description</A></H3> <P>The <CODE>httpConnect()</CODE> function opens a HTTP connection to the specified server and port.</P> <H3><A NAME="10_55_5">Example</A></H3> <PRE> #include <cups/http.h> <A HREF="#http_t">http_t</A> *http; http = httpConnect(cupsServer(), ippPort()); </PRE> <H3><A NAME="10_55_6">See Also</A></H3> <A HREF="#httpClose"><CODE>httpClose()</CODE></A>, <A HREF="#httpConnectEncrypt"> <CODE>httpConnectEncrypt()</CODE></A>, <A HREF="#httpGet"><CODE> httpGet()</CODE></A>, <A HREF="#httpGets"><CODE>httpGets()</CODE></A>, <A HREF="#httpPost"><CODE>httpPost()</CODE></A>, <A HREF="#httpRead"><CODE> httpRead()</CODE></A>, <A HREF="#httpWrite"><CODE>httpWrite()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpConnectEncrypt">httpConnectEncrypt()</A></H2> <H3><A NAME="10_56_1">Usage</A></H3> <PRE> http_t * httpConnectEncrypt(const char *hostname, int port, http_encryption_t encryption); </PRE> <H3><A NAME="10_56_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>hostname</TD><TD>The name or IP address of the server to connect to</TD></TR> <TR><TD>port</TD><TD>The port number to use</TD></TR> <TR><TD>encryption</TD><TD>The level of encryption to use</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_56_3">Returns</A></H3> <P>A pointer to a HTTP connection structure or NULL if the connection could not be made.</P> <H3><A NAME="10_56_4">Description</A></H3> <P>The <CODE>httpConnectEncrypt()</CODE> function opens a HTTP connection to the specified server, port, and encryption.</P> <H3><A NAME="10_56_5">Example</A></H3> <PRE> #include <cups/http.h> <A HREF="#http_t">http_t</A> *http; http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption()); </PRE> <H3><A NAME="10_56_6">See Also</A></H3> <A HREF="#httpClose"><CODE>httpClose()</CODE></A>, <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>, <A HREF="#httpGet"><CODE>httpGet()</CODE> </A>, <A HREF="#httpGets"><CODE>httpGets()</CODE></A>, <A HREF="#httpPost"> <CODE>httpPost()</CODE></A>, <A HREF="#httpRead"><CODE>httpRead()</CODE></A> , <A HREF="#httpWrite"><CODE>httpWrite()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpDecode64">httpDecode64()</A></H2> <H3><A NAME="10_57_1">Usage</A></H3> <PRE> char * httpDecode64(char *out, const char *in); </PRE> <H3><A NAME="10_57_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>out</TD><TD>The output string</TD></TR> <TR><TD>in</TD><TD>The input string</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_57_3">Returns</A></H3> <P>A pointer to the decoded string.</P> <H3><A NAME="10_57_4">Description</A></H3> <P>The <CODE>httpDecode64()</CODE> function decodes a base-64 encoded string to the original string.</P> <H3><A NAME="10_57_5">Example</A></H3> <PRE> #include <cups/http.h> char encoded_string[255]; char original_string[255]; httpDecode64(original_string, encoded_string); </PRE> <H3><A NAME="10_57_6">See Also</A></H3> <A HREF="#httpEncode64"><CODE>httpEncode64()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpDelete">httpDelete()</A></H2> <H3><A NAME="10_58_1">Usage</A></H3> <PRE> int httpDelete(http_t *http, const char *uri); </PRE> <H3><A NAME="10_58_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>uri</TD><TD>The URI to delete</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_58_3">Returns</A></H3> <P>0 on success, non-zero on failure.</P> <H3><A NAME="10_58_4">Description</A></H3> <P>The <CODE>httpDelete()</CODE> function sends a HTTP DELETE request to the server.</P> <H3><A NAME="10_58_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpDelete(http, "/some/uri"); </PRE> <H3><A NAME="10_58_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpSetField"> <CODE>httpSetField()</CODE></A>, <A HREF="#httpUpdate"><CODE> httpUpdate()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpEncode64">httpEncode64()</A></H2> <H3><A NAME="10_59_1">Usage</A></H3> <PRE> char * httpEncode64(char *out, const char *in); </PRE> <H3><A NAME="10_59_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>out</TD><TD>The output string</TD></TR> <TR><TD>in</TD><TD>The input string</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_59_3">Returns</A></H3> <P>A pointer to the encoded string.</P> <H3><A NAME="10_59_4">Description</A></H3> <P>The <CODE>httpEncode64()</CODE> function decodes a base-64 encoded string to the original string.</P> <H3><A NAME="10_59_5">Example</A></H3> <PRE> #include <cups/http.h> char encoded_string[255]; char original_string[255]; httpEncode64(encoded_string, original_string); </PRE> <H3><A NAME="10_59_6">See Also</A></H3> <A HREF="#httpDecode64"><CODE>httpDecode64()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpEncryption">httpEncryption()</A></H2> <H3><A NAME="10_60_1">Usage</A></H3> <PRE> int httpEncryption(http_t *http, http_encryption_t encryption); </PRE> <H3><A NAME="10_60_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection.</TD></TR> <TR><TD>encryption</TD><TD>The desired level of encryption.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_60_3">Returns</A></H3> <P>0 on success, -1 on error.</P> <H3><A NAME="10_60_4">Description</A></H3> <P><CODE>httpEncryption()</CODE> sets the encryption level for the HTTP connection.</P> <H3><A NAME="10_60_5">Example</A></H3> <PRE> #include <cups/http.h> <A HREF="#http_t">http_t</A> *http; ... httpEncryption(http, HTTP_ENCRYPT_REQUIRED); </PRE> <H3><A NAME="10_60_6">See Also</A></H3> <P> <A HREF="#httpConnectEncrypt"><CODE>httpConnectEncrypt()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="httpError">httpError()</A></H2> <H3><A NAME="10_61_1">Usage</A></H3> <PRE> int httpError(http_t *http); </PRE> <H3><A NAME="10_61_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_61_3">Returns</A></H3> <P>The last error that occurred or 0 if no error has occurred.</P> <H3><A NAME="10_61_4">Description</A></H3> <P>The <CODE>httpError()</CODE> function returns the last error that occurred on the HTTP connection.</P> <H3><A NAME="10_61_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; if (httpError(http)) { ... show an error message ... } </PRE> <H3><A NAME="10_61_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpFlush">httpFlush()</A></H2> <H3><A NAME="10_62_1">Usage</A></H3> <PRE> void httpFlush(http_t *http); </PRE> <H3><A NAME="10_62_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_62_3">Description</A></H3> <P>The <CODE>httpFlush()</CODE> function flushes any remaining data left from a GET or POST operation.</P> <H3><A NAME="10_62_4">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpFlush(http); </PRE> <H3><A NAME="10_62_5">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <!-- NEW PAGE --> <H2><A NAME="httpGet">httpGet()</A></H2> <H3><A NAME="10_63_1">Usage</A></H3> <PRE> int httpGet(http_t *http, const char *uri); </PRE> <H3><A NAME="10_63_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>uri</TD><TD>The URI to get</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_63_3">Returns</A></H3> <P>0 on success, non-zero on failure.</P> <H3><A NAME="10_63_4">Description</A></H3> <P>The <CODE>httpGet()</CODE> function sends a HTTP GET request to the server.</P> <H3><A NAME="10_63_5">Example</A></H3> <PRE> #include <cups/http.h> <A HREF="#http_t">http_t</A> *http; httpGet(http, "/some/uri"); </PRE> <H3><A NAME="10_63_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpSetField"> <CODE>httpSetField()</CODE></A>, <A HREF="#httpUpdate"><CODE> httpUpdate()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpGets">httpGets()</A></H2> <H3><A NAME="10_64_1">Usage</A></H3> <PRE> char * httpGets(char *line, int length, http_t *http) </PRE> <H3><A NAME="10_64_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>line</TD><TD>The string to fill with a line from the HTTP connection</TD></TR> <TR><TD>length</TD><TD>The maximum length of the string</TD></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_64_3">Returns</A></H3> <P>A pointer to the string or NULL if no line could be retrieved.</P> <H3><A NAME="10_64_4">Description</A></H3> <P>The <CODE>httpGets()</CODE> function is used to read a request line from the HTTP connection. It is not normally used by a client program.</P> <H3><A NAME="10_64_5">Example</A></H3> <PRE> #include <cups/http.h> <A HREF="#http_t">http_t</A> *http; char line[1024]; if (httpGets(line, sizeof(line), http)) { ... process the line ... } </PRE> <H3><A NAME="10_64_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpUpdate"> <CODE>httpUpdate()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpGetDateString">httpGetDateString()</A></H2> <H3><A NAME="10_65_1">Usage</A></H3> <PRE> const char * httpGetDateString(time_t time) </PRE> <H3><A NAME="10_65_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>time</TD><TD>The UNIX date/time value</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_65_3">Returns</A></H3> <P>A pointer to a static string containing the HTTP date/time string for the specified UNIX time value.</P> <H3><A NAME="10_65_4">Description</A></H3> <P>The <CODE>httpGetDateString()</CODE> function generates a date/time string suitable for HTTP requests from a UNIX time value.</P> <H3><A NAME="10_65_5">Example</A></H3> <PRE> #include <cups/http.h> puts(httpGetDateString(time(NULL))); </PRE> <H3><A NAME="10_65_6">See Also</A></H3> <A HREF="#httpGetDateTime"><CODE>httpGetDateTime()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpGetDateTime">httpGetDateTime()</A></H2> <H3><A NAME="10_66_1">Usage</A></H3> <PRE> time_t httpGetDateTime(const char *date) </PRE> <H3><A NAME="10_66_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>date</TD><TD>The HTTP date/time string</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_66_3">Returns</A></H3> <P>A UNIX time value.</P> <H3><A NAME="10_66_4">Description</A></H3> <P>The <CODE>httpGetDateTime()</CODE> function converts a HTTP date/time string to a UNIX time value.</P> <H3><A NAME="10_66_5">Example</A></H3> <PRE> #include <cups/http.h> printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT")); </PRE> <H3><A NAME="10_66_6">See Also</A></H3> <A HREF="#httpGetDateString"><CODE>httpGetDateString()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpGetField">httpGetField()</A></H2> <H3><A NAME="10_67_1">Usage</A></H3> <PRE> const char * httpGetField(http_t *http, http_field_t field); </PRE> <H3><A NAME="10_67_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>field</TD><TD>The HTTP field</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_67_3">Returns</A></H3> <P>A pointer to the field value string.</P> <H3><A NAME="10_67_4">Description</A></H3> <P>The <CODE>httpGetField()</CODE> function returns the current value for the specified HTTP field.</P> <H3><A NAME="10_67_5">Example</A></H3> <PRE> #include <cups/http.h> <A HREF="#http_t">http_t</A> *http; httpGet(http, "/some/uri"); while (httpUpdate(http) == HTTP_CONTINUE); puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE)); </PRE> <H3><A NAME="10_67_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpGetSubField"> <CODE>httpGetSubField()</CODE></A>, <A HREF="#httpSetField"><CODE> httpSetField()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpGetHostByName">httpGetHostByName()</A></H2> <H3><A NAME="10_68_1">Usage</A></H3> <PRE> struct hostent * httpGetHostByName(const char *name); </PRE> <H3><A NAME="10_68_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>name</TD><TD>Name or IP address to lookup.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_68_3">Returns</A></H3> <P>NULL if the host could not be found or a pointer to a host entry containing one or more addresses.</P> <H3><A NAME="10_68_4">Description</A></H3> <P><CODE>httpGetHostByName()</CODE> is a portable wrapper around the <CODE> gethostbyname()</CODE> function which handles both hostnames and IP addresses.</P> <H3><A NAME="10_68_5">Example</A></H3> <PRE> #include <cups/http.h> struct hostent *hostaddr; hostaddr = httpGetHostByName("foo.bar.com"); </PRE> <!-- NEW PAGE --> <H2><A NAME="httpGetLength">httpGetLength()</A></H2> <H3><A NAME="10_69_1">Usage</A></H3> <PRE> int httpGetLength(http_t *http); </PRE> <H3><A NAME="10_69_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_69_3">Returns</A></H3> <P>The content length of the response or MAX_INT if chunking is used.</P> <H3><A NAME="10_69_4">Description</A></H3> <P><CODE>httpGetLength()</CODE> returns the content length of a response.</P> <H3><A NAME="10_69_5">Example</A></H3> <PRE> #include <cups/http.h> <A HREF="#http_t">http_t</A> *http; ... printf("The length of the response is %d bytes.\n", httpGetLength(http)); </PRE> <H3><A NAME="10_69_6">See Also</A></H3> <P> <A HREF="#httpGet"><CODE>httpGet()</CODE></A>, <A HREF="#httpPost"><CODE> httpPost()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="httpGetSubField">httpGetSubField()</A></H2> <H3><A NAME="10_70_1">Usage</A></H3> <PRE> const char * httpGetSubField(http_t *http, http_field_t field, const char *name, char *value); </PRE> <H3><A NAME="10_70_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection.</TD></TR> <TR><TD>field</TD><TD>The HTTP field.</TD></TR> <TR><TD>name</TD><TD>The name of the subfield.</TD></TR> <TR><TD>value</TD><TD>The string to hold the subfield value.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_70_3">Returns</A></H3> <P>A pointer to the subfield value string or NULL if it does not exist.</P> <H3><A NAME="10_70_4">Description</A></H3> <P>The <CODE>httpGetSubField()</CODE> function returns a subfield value from the specified HTTP field. The destination string buffer must be at least <CODE>HTTP_MAX_VALUE</CODE> bytes in length.</P> <H3><A NAME="10_70_5">Example</A></H3> <PRE> #include <cups/http.h> <A HREF="#http_t">http_t</A> *http; char value[HTTP_MAX_VALUE]; httpGet(http, "/some/uri"); while (httpUpdate(http) == HTTP_CONTINUE); puts(httpGetSubField(http, HTTP_FIELD_CONTENT_TYPE, "charset", value)); </PRE> <H3><A NAME="10_70_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpGetField"> <CODE>httpGetField()</CODE></A>, <A HREF="#httpSetField"><CODE> httpSetField()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpHead">httpHead()</A></H2> <H3><A NAME="10_71_1">Usage</A></H3> <PRE> int httpHead(http_t *http, const char *uri); </PRE> <H3><A NAME="10_71_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>uri</TD><TD>The URI to head</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_71_3">Returns</A></H3> <P>0 on success, non-zero on failure.</P> <H3><A NAME="10_71_4">Description</A></H3> <P>The <CODE>httpHead()</CODE> function sends a HTTP HEAD request to the server.</P> <H3><A NAME="10_71_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpHead(http, "/some/uri"); </PRE> <H3><A NAME="10_71_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpSetField"> <CODE>httpSetField()</CODE></A>, <A HREF="#httpUpdate"><CODE> httpUpdate()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpInitialize">httpInitialize()</A></H2> <H3><A NAME="10_72_1">Usage</A></H3> <PRE> void httpInitialize(void); </PRE> <H3><A NAME="10_72_2">Description</A></H3> <P>The <CODE>httpInitialize()</CODE> function initializes the networking code as needed by the underlying platform. It is called automatically by the <CODE>httpConnect()</CODE> function.</P> <H3><A NAME="10_72_3">Example</A></H3> <PRE> #include <cups/http.h> httpInitialize(); </PRE> <H3><A NAME="10_72_4">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpMD5">httpMD5()</A></H2> <H3><A NAME="10_73_1">Usage</A></H3> <PRE> char * httpMD5(const char *username, const char *realm, const char *passwd, char md5[33]); </PRE> <H3><A NAME="10_73_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>username</TD><TD>The authenticating user name.</TD></TR> <TR><TD>realm</TD><TD>The authenticating realm name.</TD></TR> <TR><TD>passwd</TD><TD>The authenticating password.</TD></TR> <TR><TD>md5</TD><TD>The MD5 sum string.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_73_3">Returns</A></H3> <P>A pointer to the MD5 sum string.</P> <H3><A NAME="10_73_4">Description</A></H3> <P><CODE>httpMD5()</CODE> computes the MD5 hash of the username, realm, and password as required by the HTTP Digest specification.</P> <H3><A NAME="10_73_5">Example</A></H3> <PRE> #include <cups/http.h> char md5[33]; ... httpMD5("user", "realm", "password", md5); </PRE> <H3><A NAME="10_73_6">See Also</A></H3> <P> <A HREF="#httpMD5Final"><CODE>httpMD5Final()</CODE></A>, <A HREF="#httpMD5String"> <CODE>httpMD5String()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="httpMD5Final">httpMD5Final()</A></H2> <H3><A NAME="10_74_1">Usage</A></H3> <PRE> char * httpMD5Final(const char *nonce, const char *method, const char *resource, char md5[33]); </PRE> <H3><A NAME="10_74_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>nonce</TD><TD>The server nonce value.</TD></TR> <TR><TD>method</TD><TD>The HTTP method (GET, POST, etc.)</TD></TR> <TR><TD>resource</TD><TD>The resource path.</TD></TR> <TR><TD>md5</TD><TD>The MD5 sum string.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_74_3">Returns</A></H3> <P>The MD5 sum string.</P> <H3><A NAME="10_74_4">Description</A></H3> <P><CODE>httpMD5Final()</CODE> appends the nonce, method, and resource to the specified MD5 sum.</P> <H3><A NAME="10_74_5">Example</A></H3> <PRE> #include <cups/http.h> char md5[33]; ... httpMD5Final("nonce", "GET", "/jobs", md5); </PRE> <H3><A NAME="10_74_6">See Also</A></H3> <P> <A HREF="#httpMD5"><CODE>httpMD5()</CODE></A>, <A HREF="#httpMD5String"> <CODE>httpMD5String()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="httpMD5String">httpMD5String()</A></H2> <H3><A NAME="10_75_1">Usage</A></H3> <PRE> char * httpMD5String(const md5_byte_t *sum, char md5[33]); </PRE> <H3><A NAME="10_75_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>sum</TD><TD>The raw MD5 sum data.</TD></TR> <TR><TD>md5</TD><TD>The MD5 sum string.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_75_3">Returns</A></H3> <P>The MD5 sum string.</P> <H3><A NAME="10_75_4">Description</A></H3> <P><CODE>httpMD5String()</CODE> converts the raw MD5 sum value to a string.</P> <H3><A NAME="10_75_5">Example</A></H3> <PRE> #include <cups/http.h> md5_byte_t sum[16]; char md5[33]; ... httpMD5String(sum, md5); </PRE> <H3><A NAME="10_75_6">See Also</A></H3> <P> <A HREF="#httpMD5"><CODE>httpMD5()</CODE></A>, <A HREF="#httpMD5Final"> <CODE>httpMD5Final()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="httpOptions">httpOptions()</A></H2> <H3><A NAME="10_76_1">Usage</A></H3> <PRE> int httpOptions(http_t *http, const char *uri); </PRE> <H3><A NAME="10_76_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>uri</TD><TD>The URI to check for options</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_76_3">Returns</A></H3> <P>0 on success, non-zero on failure.</P> <H3><A NAME="10_76_4">Description</A></H3> <P>The <CODE>httpOptions()</CODE> function sends a HTTP OPTIONS request to the server.</P> <H3><A NAME="10_76_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpOptions(http, "/some/uri"); </PRE> <H3><A NAME="10_76_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpSetField"> <CODE>httpSetField()</CODE></A>, <A HREF="#httpUpdate"><CODE> httpUpdate()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpPost">httpPost()</A></H2> <H3><A NAME="10_77_1">Usage</A></H3> <PRE> int httpPost(http_t *http, const char *uri); </PRE> <H3><A NAME="10_77_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>uri</TD><TD>The URI to post to</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_77_3">Returns</A></H3> <P>0 on success, non-zero on failure.</P> <H3><A NAME="10_77_4">Description</A></H3> <P>The <CODE>httpPost()</CODE> function sends a HTTP POST request to the server.</P> <H3><A NAME="10_77_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpPost(http, "/some/uri"); </PRE> <H3><A NAME="10_77_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpSetField"> <CODE>httpSetField()</CODE></A>, <A HREF="#httpUpdate"><CODE> httpUpdate()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpPrintf">httpPrintf()</A></H2> <H3><A NAME="10_78_1">Usage</A></H3> <PRE> int httpPrintf(http_t *http, const char *format, ...); </PRE> <H3><A NAME="10_78_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>format</TD><TD>A printf-style format string</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_78_3">Returns</A></H3> <P>The number of bytes written.</P> <H3><A NAME="10_78_4">Description</A></H3> <P>The <CODE>httpPrintf()</CODE> function sends a formatted string to the HTTP connection. It is normally only used by the CUPS API and scheduler.</P> <H3><A NAME="10_78_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpPrintf(http, "GET / HTTP/1.1 \r\n"); </PRE> <H3><A NAME="10_78_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpPut">httpPut()</A></H2> <H3><A NAME="10_79_1">Usage</A></H3> <PRE> int httpPut(http_t *http, const char *uri); </PRE> <H3><A NAME="10_79_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>uri</TD><TD>The URI to put</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_79_3">Returns</A></H3> <P>0 on success, non-zero on failure.</P> <H3><A NAME="10_79_4">Description</A></H3> <P>The <CODE>httpPut()</CODE> function sends a HTTP PUT request to the server.</P> <H3><A NAME="10_79_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpDelete(http, "/some/uri"); </PRE> <H3><A NAME="10_79_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpSetField"> <CODE>httpSetField()</CODE></A>, <A HREF="#httpUpdate"><CODE> httpUpdate()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpRead">httpRead()</A></H2> <H3><A NAME="10_80_1">Usage</A></H3> <PRE> int httpRead(http_t *http, char *buffer, int length); </PRE> <H3><A NAME="10_80_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>buffer</TD><TD>The buffer to read into</TD></TR> <TR><TD>length</TD><TD>The number of bytes to read</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_80_3">Returns</A></H3> <P>The number of bytes read or -1 on error.</P> <H3><A NAME="10_80_4">Description</A></H3> <P>The <CODE>httpRead()</CODE> function reads data from the HTTP connection, possibly the result of a GET or POST request.</P> <H3><A NAME="10_80_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; char buffer[1024]; int bytes; httpGet(http, "/"); while (httpUpdate(http) != HTTP_CONTINUE); while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0) { buffer[bytes] = '\0'; fputs(buffer, stdout); } </PRE> <H3><A NAME="10_80_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpWrite"> <CODE>httpWrite()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpReconnect">httpReconnect()</A></H2> <H3><A NAME="10_81_1">Usage</A></H3> <PRE> int httpReconnect(http_t *http); </PRE> <H3><A NAME="10_81_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_81_3">Returns</A></H3> <P>0 on success, non-zero on failure.</P> <H3><A NAME="10_81_4">Description</A></H3> <P>The <CODE>httpReconnect()</CODE> function reconnects to the HTTP server. This is usually done automatically if the HTTP functions detect that the server connection has terminated.</P> <H3><A NAME="10_81_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpReconnect(http); </PRE> <H3><A NAME="10_81_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpSeparate">httpSeparate()</A></H2> <H3><A NAME="10_82_1">Usage</A></H3> <PRE> void httpSeparate(const char *uri, char *method, char *username, char *host, int *port, char *resource); </PRE> <H3><A NAME="10_82_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>uri</TD><TD>The URI to separate</TD></TR> <TR><TD>method</TD><TD>The method (scheme) of the URI</TD></TR> <TR><TD>username</TD><TD>The username (and password) portion of the URI, if any</TD></TR> <TR><TD>host</TD><TD>The hostname portion of the URI, if any</TD></TR> <TR><TD>port</TD><TD>The port number for the URI, either as specified or as default for the method/scheme</TD></TR> <TR><TD>resource</TD><TD>The resource string, usually a filename on the server</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_82_3">Description</A></H3> <P>The <CODE>httpSeparate()</CODE> function separates the specified URI into its component parts. The method, username, hostname, and resource strings should be at least <CODE>HTTP_MAX_URI</CODE> characters long to avoid potential buffer overflow problems.</P> <H3><A NAME="10_82_4">Example</A></H3> <PRE> char uri[HTTP_MAX_URI]; char method[HTTP_MAX_URI]; char username[HTTP_MAX_URI]; char host[HTTP_MAX_URI]; char resource[HTTP_MAX_URI]; int port; ... httpSeparate(uri, method, username, host, &port, resource); </PRE> <H3><A NAME="10_82_5">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpSetField">httpSetField()</A></H2> <H3><A NAME="10_83_1">Usage</A></H3> <PRE> void httpSetField(http_t *http, http_field_t field, const char *value); </PRE> <H3><A NAME="10_83_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>field</TD><TD>The HTTP field</TD></TR> <TR><TD>value</TD><TD>The string value for the field</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_83_3">Description</A></H3> <P>The <CODE>httpSetField()</CODE> function sets the current value for the specified HTTP field.</P> <H3><A NAME="10_83_4">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325")); httpGet(http, "/some/uri"); while (httpUpdate(http) == HTTP_CONTINUE); </PRE> <H3><A NAME="10_83_5">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpGetField"> <CODE>httpGetField()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpStatus">httpStatus()</A></H2> <H3><A NAME="10_84_1">Usage</A></H3> <PRE> const char * httpStatus(http_status_t status); </PRE> <H3><A NAME="10_84_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>status</TD><TD>The HTTP status code from the server.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_84_3">Returns</A></H3> <P>The standard HTTP status text associated with the status code.</P> <H3><A NAME="10_84_4">Description</A></H3> <P><CODE>httpStatus()</CODE> returns the standard HTTP status text associated with the status code.</P> <H3><A NAME="10_84_5">Example</A></H3> <PRE> #include <cups/http.h> <A HREF="#http_t">http_t</A> *http; ... puts(httpStatus(http->status)); </PRE> <!-- NEW PAGE --> <H2><A NAME="httpTrace">httpTrace()</A></H2> <H3><A NAME="10_85_1">Usage</A></H3> <PRE> int httpTrace(http_t *http, const char *uri); </PRE> <H3><A NAME="10_85_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>uri</TD><TD>The URI to trace</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_85_3">Returns</A></H3> <P>0 on success, non-zero on failure.</P> <H3><A NAME="10_85_4">Description</A></H3> <P>The <CODE>httpTrace()</CODE> function sends a HTTP TRACE request to the server.</P> <H3><A NAME="10_85_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; httpTrace(http, "/some/uri"); </PRE> <H3><A NAME="10_85_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpSetField"> <CODE>httpSetField()</CODE></A>, <A HREF="#httpUpdate"><CODE> httpUpdate()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpUpdate">httpUpdate()</A></H2> <H3><A NAME="10_86_1">Usage</A></H3> <PRE> http_status_t httpUpdate(http_t *http); </PRE> <H3><A NAME="10_86_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_86_3">Returns</A></H3> <P>The HTTP status of the current request.</P> <H3><A NAME="10_86_4">Description</A></H3> <P>The <CODE>httpUpdate()</CODE> function updates the current request status. It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or TRACE request to finalize the HTTP request and retrieve the request status.</P> <P>Since proxies and the current blocking mode can cause the request to take longer, programs should continue calling <CODE>httpUpdate() <CODE> until the return status is not the constant value <CODE>HTTP_CONTINUE</CODE> .</CODE></CODE></P> <H3><A NAME="10_86_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; http_status_t status; httpGet(http, "/some/uri"); while ((status = httpUpdate(http)) == HTTP_CONTINUE); printf("Request status is %d\n", status); </PRE> <H3><A NAME="10_86_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpDelete"> <CODE>httpDelete()</CODE></A>, <A HREF="#httpGet"><CODE>httpGet()</CODE></A> , <A HREF="#httpHead"><CODE>httpHead()</CODE></A>, <A HREF="#httpOptions"> <CODE>httpOptions()</CODE></A>, <A HREF="#httpPost"><CODE>httpPost()</CODE> </A>, <A HREF="#httpPut"><CODE>httpPut()</CODE></A>, <A HREF="#httpTrace"> <CODE>httpTrace()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="httpWrite">httpWrite()</A></H2> <H3><A NAME="10_87_1">Usage</A></H3> <PRE> int httpWrite(http_t *http, char *buffer, int length); </PRE> <H3><A NAME="10_87_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>buffer</TD><TD>The buffer to read into</TD></TR> <TR><TD>length</TD><TD>The number of bytes to read</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_87_3">Returns</A></H3> <P>The number of bytes read or -1 on error.</P> <H3><A NAME="10_87_4">Description</A></H3> <P>The <CODE>httpWrite()</CODE> function reads data from the HTTP connection, possibly the result of a GET or POST request.</P> <H3><A NAME="10_87_5">Example</A></H3> <PRE> #include <cups/http.h> http_t *http; FILE *fp; char buffer[1024]; int bytes; httpPost(http, "/"); while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) httpWrite(http, buffer, bytes); while (httpUpdate(http) != HTTP_CONTINUE); while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0) { buffer[bytes] = '\0'; fputs(buffer, stdout); } </PRE> <H3><A NAME="10_87_6">See Also</A></H3> <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>, <A HREF="#httpRead"> <CODE>httpRead()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddBoolean">ippAddBoolean()</A></H2> <H3><A NAME="10_88_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddBoolean(ipp_t *ipp, ipp_tag_t group, const char *name, char value); </PRE> <H3><A NAME="10_88_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> <TR><TD>group</TD><TD>The IPP group</TD></TR> <TR><TD>name</TD><TD>The name of attribute</TD></TR> <TR><TD>value</TD><TD>The boolean value</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_88_3">Returns</A></H3> <P>A pointer to the new attribute or NULL if the attribute could not be created.</P> <H3><A NAME="10_88_4">Description</A></H3> <P>The <CODE>ippAddBoolean()</CODE> function adds a single boolean attribute value to the specified IPP request.</P> <H3><A NAME="10_88_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1); </PRE> <H3><A NAME="10_88_6">See Also</A></H3> <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>, <A HREF="#ippAddDate"> <CODE>ippAddDate()</CODE></A>, <A HREF="#ippAddInteger"><CODE> ippAddInteger()</CODE></A>, <A HREF="#ippAddIntegers"><CODE> ippAddIntegers()</CODE></A>, <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE> </A>, <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>, <A HREF="#ippAddResolution"> <CODE>ippAddResolution()</CODE></A>, <A HREF="#ippAddResolutions"><CODE> ippAddResolutions()</CODE></A>, <A HREF="#ippAddSeparator"><CODE> ippAddSeparator()</CODE></A>, <A HREF="#ippAddString"><CODE> ippAddString()</CODE></A>, <A HREF="#ippAddStrings"><CODE> ippAddStrings()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddBooleans">ippAddBooleans()</A></H2> <H3><A NAME="10_89_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddBooleans(ipp_t *ipp, ipp_tag_t group, const char *name, int num_values, const char *values); </PRE> <H3><A NAME="10_89_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> <TR><TD>group</TD><TD>The IPP group</TD></TR> <TR><TD>name</TD><TD>The name of attribute</TD></TR> <TR><TD>num_values</TD><TD>The number of values</TD></TR> <TR><TD>values</TD><TD>The boolean values</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_89_3">Returns</A></H3> <P>A pointer to the new attribute or NULL if the attribute could not be created.</P> <H3><A NAME="10_89_4">Description</A></H3> <P>The <CODE>ippAddBooleans()</CODE> function adds one or more boolean attribute values to the specified IPP request. If the <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE> false values is created.</P> <H3><A NAME="10_89_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; char values[10]; ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values); </PRE> <H3><A NAME="10_89_6">See Also</A></H3> <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>, <A HREF="#ippAddDate"> <CODE>ippAddDate()</CODE></A>, <A HREF="#ippAddInteger"><CODE> ippAddInteger()</CODE></A>, <A HREF="#ippAddIntegers"><CODE> ippAddIntegers()</CODE></A>, <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE> </A>, <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>, <A HREF="#ippAddResolution"> <CODE>ippAddResolution()</CODE></A>, <A HREF="#ippAddResolutions"><CODE> ippAddResolutions()</CODE></A>, <A HREF="#ippAddSeparator"><CODE> ippAddSeparator()</CODE></A>, <A HREF="#ippAddString"><CODE> ippAddString()</CODE></A>, <A HREF="#ippAddStrings"><CODE> ippAddStrings()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddDate">ippAddDate()</A></H2> <H3><A NAME="10_90_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddDate(ipp_t *ipp, ipp_tag_t group, const char *name, ipp_uchar_t *value); </PRE> <H3><A NAME="10_90_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> <TR><TD>group</TD><TD>The IPP group</TD></TR> <TR><TD>name</TD><TD>The name of attribute</TD></TR> <TR><TD>value</TD><TD>The date value</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_90_3">Returns</A></H3> <P>A pointer to the new attribute or NULL if the attribute could not be created.</P> <H3><A NAME="10_90_4">Description</A></H3> <P>The <CODE>ippAddDate()</CODE> function adds a single date-time attribute value to the specified IPP request.</P> <H3><A NAME="10_90_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute", ippTimeToDate(time(NULL)); </PRE> <H3><A NAME="10_90_6">See Also</A></H3> <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>, <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>, <A HREF="#ippAddInteger"><CODE> ippAddInteger()</CODE></A>, <A HREF="#ippAddIntegers"><CODE> ippAddIntegers()</CODE></A>, <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE> </A>, <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>, <A HREF="#ippAddResolution"> <CODE>ippAddResolution()</CODE></A>, <A HREF="#ippAddResolutions"><CODE> ippAddResolutions()</CODE></A>, <A HREF="#ippAddSeparator"><CODE> ippAddSeparator()</CODE></A>, <A HREF="#ippAddString"><CODE> ippAddString()</CODE></A>, <A HREF="#ippAddStrings"><CODE> ippAddStrings()</CODE></A>, <A HREF="#ippTimeToDate"><CODE> ippTimeToDate()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddInteger">ippAddInteger()</A></H2> <H3><A NAME="10_91_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddInteger(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, int value); </PRE> <H3><A NAME="10_91_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> <TR><TD>group</TD><TD>The IPP group</TD></TR> <TR><TD>tag</TD><TD>The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)</TD></TR> <TR><TD>name</TD><TD>The name of attribute</TD></TR> <TR><TD>value</TD><TD>The integer value</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_91_3">Returns</A></H3> <P>A pointer to the new attribute or NULL if the attribute could not be created.</P> <H3><A NAME="10_91_4">Description</A></H3> <P>The <CODE>ippAddInteger()</CODE> function adds a single integer attribute value to the specified IPP request.</P> <H3><A NAME="10_91_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100); </PRE> <H3><A NAME="10_91_6">See Also</A></H3> <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>, <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>, <A HREF="#ippAddDate"><CODE> ippAddDate()</CODE></A>, <A HREF="#ippAddIntegers"><CODE> ippAddIntegers()</CODE></A>, <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE> </A>, <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>, <A HREF="#ippAddResolution"> <CODE>ippAddResolution()</CODE></A>, <A HREF="#ippAddResolutions"><CODE> ippAddResolutions()</CODE></A>, <A HREF="#ippAddSeparator"><CODE> ippAddSeparator()</CODE></A>, <A HREF="#ippAddString"><CODE> ippAddString()</CODE></A>, <A HREF="#ippAddStrings"><CODE> ippAddStrings()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddIntegers">ippAddIntegers()</A></H2> <H3><A NAME="10_92_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddIntegers(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, int num_values, const int *values); </PRE> <H3><A NAME="10_92_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> <TR><TD>group</TD><TD>The IPP group</TD></TR> <TR><TD>tag</TD><TD>The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)</TD></TR> <TR><TD>name</TD><TD>The name of attribute</TD></TR> <TR><TD>num_values</TD><TD>The number of values</TD></TR> <TR><TD>values</TD><TD>The integer values</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_92_3">Returns</A></H3> <P>A pointer to the new attribute or NULL if the attribute could not be created.</P> <H3><A NAME="10_92_4">Description</A></H3> <P>The <CODE>ippAddIntegers()</CODE> function adds one or more integer attribute values to the specified IPP request. If the <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE> 0 values is created.</P> <H3><A NAME="10_92_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; int values[100]; ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values); </PRE> <H3><A NAME="10_92_6">See Also</A></H3> <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>, <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>, <A HREF="#ippAddDate"><CODE> ippAddDate()</CODE></A>, <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE> </A>, <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>, <A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>, <A HREF="#ippAddResolution"><CODE> ippAddResolution()</CODE></A>, <A HREF="#ippAddResolutions"><CODE> ippAddResolutions()</CODE></A>, <A HREF="#ippAddSeparator"><CODE> ippAddSeparator()</CODE></A>, <A HREF="#ippAddString"><CODE> ippAddString()</CODE></A>, <A HREF="#ippAddStrings"><CODE> ippAddStrings()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddRange">ippAddRange()</A></H2> <H3><A NAME="10_93_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddRange(ipp_t *ipp, ipp_tag_t group, const char *name, int low, int high); </PRE> <H3><A NAME="10_93_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> <TR><TD>group</TD><TD>The IPP group</TD></TR> <TR><TD>name</TD><TD>The name of attribute</TD></TR> <TR><TD>low</TD><TD>The lower value</TD></TR> <TR><TD>high</TD><TD>The higher value</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_93_3">Returns</A></H3> <P>A pointer to the new attribute or NULL if the attribute could not be created.</P> <H3><A NAME="10_93_4">Description</A></H3> <P>The <CODE>ippAddRange()</CODE> function adds a single range attribute value to the specified IPP request.</P> <H3><A NAME="10_93_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10); </PRE> <H3><A NAME="10_93_6">See Also</A></H3> <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>, <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>, <A HREF="#ippAddDate"><CODE> ippAddDate()</CODE></A>, <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE> </A>, <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>, <A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>, <A HREF="#ippAddResolution"><CODE> ippAddResolution()</CODE></A>, <A HREF="#ippAddResolutions"><CODE> ippAddResolutions()</CODE></A>, <A HREF="#ippAddSeparator"><CODE> ippAddSeparator()</CODE></A>, <A HREF="#ippAddString"><CODE> ippAddString()</CODE></A>, <A HREF="#ippAddStrings"><CODE> ippAddStrings()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddRanges">ippAddRanges()</A></H2> <H3><A NAME="10_94_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddRanges(ipp_t *ipp, ipp_tag_t group, const char *name, int num_values, const int *lows, const int *highs); </PRE> <H3><A NAME="10_94_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> <TR><TD>group</TD><TD>The IPP group</TD></TR> <TR><TD>name</TD><TD>The name of attribute</TD></TR> <TR><TD>num_values</TD><TD>The number of range values</TD></TR> <TR><TD>lows</TD><TD>The lower values</TD></TR> <TR><TD>highs</TD><TD>The higher values</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_94_3">Returns</A></H3> <P>A pointer to the new attribute or NULL if the attribute could not be created.</P> <H3><A NAME="10_94_4">Description</A></H3> <P>The <CODE>ippAddRanges()</CODE> function adds one or more range attribute values to the specified IPP request. If the <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE> 0,0 ranges is created.</P> <H3><A NAME="10_94_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; int lows[2]; int highs[2]; ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs); </PRE> <H3><A NAME="10_94_6">See Also</A></H3> <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>, <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>, <A HREF="#ippAddDate"><CODE> ippAddDate()</CODE></A>, <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE> </A>, <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>, <A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE></A>, <A HREF="#ippAddResolution"><CODE> ippAddResolution()</CODE></A>, <A HREF="#ippAddResolutions"><CODE> ippAddResolutions()</CODE></A>, <A HREF="#ippAddSeparator"><CODE> ippAddSeparator()</CODE></A>, <A HREF="#ippAddString"><CODE> ippAddString()</CODE></A>, <A HREF="#ippAddStrings"><CODE> ippAddStrings()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddResolution">ippAddResolution()</A></H2> <H3><A NAME="10_95_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddResolution(ipp_t *ipp, ipp_tag_t group, const char *name, int xres, int yres, ipp_res_t units); </PRE> <H3><A NAME="10_95_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> <TR><TD>group</TD><TD>The IPP group</TD></TR> <TR><TD>name</TD><TD>The name of attribute</TD></TR> <TR><TD>xres</TD><TD>The horizontal resolution</TD></TR> <TR><TD>yres</TD><TD>The vertical resolution</TD></TR> <TR><TD>units</TD><TD>The resolution units</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_95_3">Returns</A></H3> <P>A pointer to the new attribute or NULL if the attribute could not be created.</P> <H3><A NAME="10_95_4">Description</A></H3> <P>The <CODE>ippAddResolution()</CODE> function adds a single resolution attribute value to the specified IPP request.</P> <H3><A NAME="10_95_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution", 720, 720, IPP_RES_PER_INCH); </PRE> <H3><A NAME="10_95_6">See Also</A></H3> <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>, <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>, <A HREF="#ippAddDate"><CODE> ippAddDate()</CODE></A>, <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE> </A>, <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>, <A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE></A>, <A HREF="#ippAddRanges"><CODE> ippAddRanges()</CODE></A>, <A HREF="#ippAddResolutions"><CODE> ippAddResolutions()</CODE></A>, <A HREF="#ippAddSeparator"><CODE> ippAddSeparator()</CODE></A>, <A HREF="#ippAddString"><CODE> ippAddString()</CODE></A>, <A HREF="#ippAddStrings"><CODE> ippAddStrings()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddResolutions">ippAddResolutions()</A></H2> <H3><A NAME="10_96_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddResolutions(ipp_t *ipp, ipp_tag_t group, const char *name, int num_values, const int *xres, const int *yres, const ipp_res_t *units); </PRE> <H3><A NAME="10_96_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> <TR><TD>group</TD><TD>The IPP group</TD></TR> <TR><TD>name</TD><TD>The name of attribute</TD></TR> <TR><TD>num_values</TD><TD>The number of resolution values</TD></TR> <TR><TD>xres</TD><TD>The horizontal resolutions</TD></TR> <TR><TD>yres</TD><TD>The vertical resolutions</TD></TR> <TR><TD>units</TD><TD>The resolution units</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_96_3">Returns</A></H3> <P>A pointer to the new attribute or NULL if the attribute could not be created.</P> <H3><A NAME="10_96_4">Description</A></H3> <P>The <CODE>ippAddResolutions()</CODE> function adds one or more resolution attribute values to the specified IPP request. If the <CODE> values</CODE> pointer is <CODE>NULL</CODE> then an array of <CODE> num_values</CODE> 0,0 resolutions is created.</P> <H3><A NAME="10_96_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; int xres[5]; int yres[5]; ipp_res_t units[5]; ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolutions-supported", 5, xres, yres, units); </PRE> <H3><A NAME="10_96_6">See Also</A></H3> <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>, <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>, <A HREF="#ippAddDate"><CODE> ippAddDate()</CODE></A>, <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE> </A>, <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>, <A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE></A>, <A HREF="#ippAddRanges"><CODE> ippAddRanges()</CODE></A>, <A HREF="#ippAddResolution"><CODE> ippAddResolution()</CODE></A>, <A HREF="#ippAddSeparator"><CODE> ippAddSeparator()</CODE></A>, <A HREF="#ippAddString"><CODE> ippAddString()</CODE></A>, <A HREF="#ippAddStrings"><CODE> ippAddStrings()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddSeparator">ippAddSeparator()</A></H2> <H3><A NAME="10_97_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddSeparator(ipp_t *ipp); </PRE> <H3><A NAME="10_97_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_97_3">Returns</A></H3> <P>A pointer to the new separator or NULL if the separator could not be created.</P> <H3><A NAME="10_97_4">Description</A></H3> <P>The <CODE>ippAddSeparator()</CODE> function adds a group separator to the specified IPP request.</P> <H3><A NAME="10_97_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; ippAddSeparator(ipp); </PRE> <H3><A NAME="10_97_6">See Also</A></H3> <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>, <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>, <A HREF="#ippAddDate"><CODE> ippAddDate()</CODE></A>, <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE> </A>, <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>, <A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE></A>, <A HREF="#ippAddRanges"><CODE> ippAddRanges()</CODE></A>, <A HREF="#ippAddResolution"><CODE> ippAddResolution()</CODE></A>, <A HREF="#ippAddResolutions"><CODE> ippAddResolutions()</CODE></A>, <A HREF="#ippAddString"><CODE> ippAddString()</CODE></A>, <A HREF="#ippAddStrings"><CODE> ippAddStrings()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddString">ippAddString()</A></H2> <H3><A NAME="10_98_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddString(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, const char *charset, const char *value); </PRE> <H3><A NAME="10_98_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> <TR><TD>group</TD><TD>The IPP group</TD></TR> <TR><TD>tag</TD><TD>The type of string value</TD></TR> <TR><TD>name</TD><TD>The name of attribute</TD></TR> <TR><TD>charset</TD><TD>The character set for the string</TD></TR> <TR><TD>value</TD><TD>The string value</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_98_3">Returns</A></H3> <P>A pointer to the new attribute or NULL if the attribute could not be created.</P> <H3><A NAME="10_98_4">Description</A></H3> <P>The <CODE>ippAddString()</CODE> function adds a single string attribute value to the specified IPP request. For <CODE> IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE> strings, the charset value is provided with the string to identify the string encoding used. Otherwise the charset value is ignored.</P> <H3><A NAME="10_98_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name", NULL, "abc123"); </PRE> <H3><A NAME="10_98_6">See Also</A></H3> <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>, <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>, <A HREF="#ippAddDate"><CODE> ippAddDate()</CODE></A>, <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE> </A>, <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>, <A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE></A>, <A HREF="#ippAddRanges"><CODE> ippAddRanges()</CODE></A>, <A HREF="#ippAddResolution"><CODE> ippAddResolution()</CODE></A>, <A HREF="#ippAddResolutions"><CODE> ippAddResolutions()</CODE></A>, <A HREF="#ippAddSeparator"><CODE> ippAddSeparator()</CODE></A>, <A HREF="#ippAddStrings"><CODE> ippAddStrings()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippAddStrings">ippAddStrings()</A></H2> <H3><A NAME="10_99_1">Usage</A></H3> <PRE> ipp_attribute_t * ippAddStrings(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, int num_values, const char *charset, const char **values); </PRE> <H3><A NAME="10_99_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request</TD></TR> <TR><TD>group</TD><TD>The IPP group</TD></TR> <TR><TD>tag</TD><TD>The type of string value</TD></TR> <TR><TD>name</TD><TD>The name of attribute</TD></TR> <TR><TD>num_values</TD><TD>The number of strings</TD></TR> <TR><TD>charset</TD><TD>The character set for the strings</TD></TR> <TR><TD>values</TD><TD>The string values</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_99_3">Returns</A></H3> <P>A pointer to the new attribute or NULL if the attribute could not be created.</P> <H3><A NAME="10_99_4">Description</A></H3> <P>The <CODE>ippAddStrings()</CODE> function adds one or more string attribute values to the specified IPP request. For <CODE> IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE> strings, the charset value is provided with the strings to identify the string encoding used. Otherwise the charset value is ignored. If the <CODE> values</CODE> pointer is <CODE>NULL</CODE> then an array of <CODE> num_values</CODE> NULL strings is created.</P> <H3><A NAME="10_99_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; char *values[2] = { "one", "two" }; ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, "attr-name", 2, NULL, values); </PRE> <H3><A NAME="10_99_6">See Also</A></H3> <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>, <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>, <A HREF="#ippAddDate"><CODE> ippAddDate()</CODE></A>, <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE> </A>, <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>, <A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE></A>, <A HREF="#ippAddRanges"><CODE> ippAddRanges()</CODE></A>, <A HREF="#ippAddResolution"><CODE> ippAddResolution()</CODE></A>, <A HREF="#ippAddResolutions"><CODE> ippAddResolutions()</CODE></A>, <A HREF="#ippAddSeparator"><CODE> ippAddSeparator()</CODE></A>, <A HREF="#ippAddString"><CODE> ippAddString()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippDateToTime">ippDateToTime()</A></H2> <H3><A NAME="10_100_1">Usage</A></H3> <PRE> time_t ippDateToTime(const ipp_uchar_t date[11]); </PRE> <H3><A NAME="10_100_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>date</TD><TD>The IPP date-time value</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_100_3">Returns</A></H3> <P>A UNIX time value.</P> <H3><A NAME="10_100_4">Description</A></H3> <P>The <CODE>ippDateToTime()</CODE> function converts an IPP date-time value to a UNIX time value.</P> <H3><A NAME="10_100_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_uchar_t date[11]; printf("UNIX time is %d\n", ippDateToTime(date)); </PRE> <H3><A NAME="10_100_6">See Also</A></H3> <A HREF="#ippTimeToDate"><CODE>ippTimeToDate()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippDelete">ippDelete()</A></H2> <H3><A NAME="10_101_1">Usage</A></H3> <PRE> void ippDelete(ipp_t *ipp); </PRE> <H3><A NAME="10_101_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_101_3">Description</A></H3> <P>The <CODE>ippDelete()</CODE> function deletes all memory used by an IPP request or response.</P> <H3><A NAME="10_101_4">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; ippDelete(ipp); </PRE> <H3><A NAME="10_101_5">See Also</A></H3> <A HREF="#ippNew"><CODE>ippNew()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippErrorString">ippErrorString()</A></H2> <H3><A NAME="10_102_1">Usage</A></H3> <PRE> const char * ippErrorString(ipp_status_t error); </PRE> <H3><A NAME="10_102_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>error</TD><TD>IPP error code.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_102_3">Returns</A></H3> <P>The standard text representation of the IPP error code.</P> <H3><A NAME="10_102_4">Description</A></H3> <P><CODE>ippErrorString()</CODE> returns the standard text representation of the IPP error code.</P> <H3><A NAME="10_102_5">Example</A></H3> <PRE> #include <cups/ipp.h> puts(ippErrorString(IPP_OK)); </PRE> <H3><A NAME="10_102_6">See Also</A></H3> <P> <A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="ippFindAttribute">ippFindAttribute()</A></H2> <H3><A NAME="10_103_1">Usage</A></H3> <PRE> ipp_attribute_t * ippFindAttribute(ipp_t *ipp, const char *name, ipp_tag_t tag); </PRE> <H3><A NAME="10_103_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR> <TR><TD>name</TD><TD>The name of the attribute</TD></TR> <TR><TD>tag</TD><TD>The required value tag for the attribute or <CODE> IPP_TAG_ZERO</CODE> for any type of value.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_103_3">Returns</A></H3> <P>A pointer to the first occurrence of the requested attribute, or <CODE> NULL</CODE> if it was not found.</P> <H3><A NAME="10_103_4">Description</A></H3> <P><CODE>ippFindAttribute()</CODE> finds the first occurrence of the named attribute. The <CODE>tag</CODE> parameter restricts the search to a specific value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value with the name.</P> <P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE> match the name/text values with or without the language code.</P> <H3><A NAME="10_103_5">Example</A></H3> <PRE> <A HREF="#ipp_attribute_t">ipp_attribute_t</A> *attr; attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT); while (attr != NULL) { puts(attr->values[0].string.text); attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT); } </PRE> <H3><A NAME="10_103_6">See Also</A></H3> <A HREF="#cupsDoFileRequest"><CODE>cupsDoFileRequest()</CODE></A>, <A HREF="#cupsDoRequest"> <CODE>cupsDoRequest()</CODE></A>, <A HREF="#ippDelete"><CODE>ippDelete()</CODE> </A>, <A HREF="#ippFindNextAttribute"><CODE>ippFindNextAttribute()</CODE> </A>, <A HREF="#ippNew"><CODE>ippNew()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippFindNextAttribute">ippFindNextAttribute()</A></H2> <H3><A NAME="10_104_1">Usage</A></H3> <PRE> ipp_attribute_t * ippFindNextAttribute(ipp_t *ipp, const char *name, ipp_tag_t tag); </PRE> <H3><A NAME="10_104_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR> <TR><TD>name</TD><TD>The name of the attribute</TD></TR> <TR><TD>tag</TD><TD>The required value tag for the attribute or <CODE> IPP_TAG_ZERO</CODE> for any type of value.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_104_3">Returns</A></H3> <P>A pointer to the next occurrence of the requested attribute, or <CODE> NULL</CODE> if it was not found.</P> <H3><A NAME="10_104_4">Description</A></H3> <P><CODE>ippFindNextAttribute()</CODE> finds the next occurrence of the named attribute. The <CODE>tag</CODE> parameter restricts the search to a specific value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value with the name.</P> <P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE> match the name/text values with or without the language code.</P> <H3><A NAME="10_104_5">Example</A></H3> <PRE> <A HREF="#ipp_attribute_t">ipp_attribute_t</A> *attr; attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT); while (attr != NULL) { puts(attr->values[0].string.text); attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT); } </PRE> <H3><A NAME="10_104_6">See Also</A></H3> <A HREF="#cupsDoFileRequest"><CODE>cupsDoFileRequest()</CODE></A>, <A HREF="#cupsDoRequest"> <CODE>cupsDoRequest()</CODE></A>, <A HREF="#ippDelete"><CODE>ippDelete()</CODE> </A>, <A HREF="#ippFindNextAttribute"><CODE>ippFindNextAttribute()</CODE> </A>, <A HREF="#ippNew"><CODE>ippNew()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippLength">ippLength()</A></H2> <H3><A NAME="10_105_1">Usage</A></H3> <PRE> int ippLength(ipp_t *ipp); </PRE> <H3><A NAME="10_105_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_105_3">Returns</A></H3> <P>The total encoded length of the IPP request or response in bytes.</P> <H3><A NAME="10_105_4">Description</A></H3> <P><CODE>ippLength()</CODE> returns the length of the IPP request or response in bytes.</P> <H3><A NAME="10_105_5">Example</A></H3> <PRE> printf("The length of the response is %d bytes.\n", ippLength(response)); </PRE> <H3><A NAME="10_105_6">See Also</A></H3> <A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>, <A HREF="#ippNew"><CODE> ippNew()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippNew">ippNew()</A></H2> <H3><A NAME="10_106_1">Usage</A></H3> <PRE> ipp_t * ippNew(void); </PRE> <H3><A NAME="10_106_2">Returns</A></H3> <P>A pointer to a new IPP request or response.</P> <H3><A NAME="10_106_3">Description</A></H3> <P>The <CODE>ippNew()</CODE> function creates a new IPP request or response.</P> <H3><A NAME="10_106_4">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_t *ipp; ipp = ippNew(); </PRE> <H3><A NAME="10_106_5">See Also</A></H3> <A HREF="#ippDelete"><CODE>ippDelete()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippPort">ippPort()</A></H2> <H3><A NAME="10_107_1">Usage</A></H3> <PRE> int ippPort(void); </PRE> <H3><A NAME="10_107_2">Returns</A></H3> <P>The default TCP/IP port number for IPP requests.</P> <H3><A NAME="10_107_3">Description</A></H3> <P>The <CODE>ippPort()</CODE> function returns the default IPP port number for requests.</P> <H3><A NAME="10_107_4">Example</A></H3> <PRE> #include <cups/http.h> #include <cups/ipp.h> http_t *http; http = httpConnect(cupsServer(), ippPort()); </PRE> <H3><A NAME="10_107_5">See Also</A></H3> <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>, <A HREF="#ippSetPort"> <CODE>ippSetPort()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippRead">ippRead()</A></H2> <H3><A NAME="10_108_1">Usage</A></H3> <PRE> ipp_state_t ippRead(http_t *http, ipp_t *ipp); </PRE> <H3><A NAME="10_108_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_108_3">Returns</A></H3> <P>The current read state.</P> <H3><A NAME="10_108_4">Description</A></H3> <P>The <CODE>ippRead()</CODE> function reads IPP attributes from the specified HTTP connection. Programs should continue calling <CODE> ippRead()</CODE> until <CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE> is returned.</P> <H3><A NAME="10_108_5">Example</A></H3> <PRE> #include <cups/http.h> #include <cups/ipp.h> http_t *http; ipp_t *ipp; ipp_state_t status; ipp = ippNew(); while ((status = ippRead(http, ipp)) != IPP_ERROR) if (status == IPP_DATA) break; if (status == IPP_DATA) { ... read additional non-IPP data using httpRead() ... } </PRE> <H3><A NAME="10_108_6">See Also</A></H3> <A HREF="#ippWrite"><CODE>ippWrite()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippSetPort">ippSetPort()</A></H2> <H3><A NAME="10_109_1">Usage</A></H3> <PRE> void ippSetPort(int port); </PRE> <H3><A NAME="10_109_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>port</TD><TD>The port number to use</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_109_3">Description</A></H3> <P>The <CODE>ippSetPort()</CODE> function sets the default IPP port number for requests.</P> <H3><A NAME="10_109_4">Example</A></H3> <PRE> #include <cups/http.h> #include <cups/ipp.h> ... ippSetPort(8631); </PRE> <H3><A NAME="10_109_5">See Also</A></H3> <A HREF="#ippPort"><CODE>ippPort()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippTimeToDate">ippTimeToDate()</A></H2> <H3><A NAME="10_110_1">Usage</A></H3> <PRE> ipp_uchar_t * ippTimeToDate(time_t time); </PRE> <H3><A NAME="10_110_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>time</TD><TD>The UNIX time value</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_110_3">Returns</A></H3> <P>A static pointer to an IPP date-time value.</P> <H3><A NAME="10_110_4">Description</A></H3> <P>The <CODE>ippTimeToDate()</CODE> function converts a UNIX time to an IPP date-time value.</P> <H3><A NAME="10_110_5">Example</A></H3> <PRE> #include <cups/ipp.h> ipp_uchar_t *date; date = ippTimeToDate(time(NULL)); </PRE> <H3><A NAME="10_110_6">See Also</A></H3> <A HREF="#ippDateToTime"><CODE>ippDateToTime()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ippWrite">ippWrite()</A></H2> <H3><A NAME="10_111_1">Usage</A></H3> <PRE> ipp_state_t ippWrite(http_t *http, ipp_t *ipp); </PRE> <H3><A NAME="10_111_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>http</TD><TD>The HTTP connection</TD></TR> <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_111_3">Returns</A></H3> <P>The current write state.</P> <H3><A NAME="10_111_4">Description</A></H3> <P>The <CODE>ippWrite()</CODE> function writes IPP attributes to the specified HTTP connection. Programs should continue calling <CODE> ippWrite()</CODE> until <CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE> is returned.</P> <H3><A NAME="10_111_5">Example</A></H3> <PRE> #include <cups/http.h> #include <cups/ipp.h> http_t *http; ipp_t *ipp; ipp_state_t status; ipp = ippNew(); ... add attributes ... while ((status = ippWrite(http, ipp)) != IPP_ERROR) if (status == IPP_DATA) break; if (status == IPP_DATA) { ... read additional non-IPP data using httpWrite() ... } </PRE> <H3><A NAME="10_111_6">See Also</A></H3> <A HREF="#ippRead"><CODE>ippRead()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdClose">ppdClose()</A></H2> <H3><A NAME="10_112_1">Usage</A></H3> <PRE> void ppdClose(ppd_file_t *ppd); </PRE> <H3><A NAME="10_112_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_112_3">Description</A></H3> <P>The <CODE>ppdClose()</CODE> function frees all memory associated with the PPD file.</P> <H3><A NAME="10_112_4">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppdClose(ppd); </PRE> <H3><A NAME="10_112_5">See Also</A></H3> <A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>, <A HREF="#ppdOpenFd"><CODE> ppdOpenFd()</CODE></A>, <A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE> </A> <!-- NEW PAGE --> <H2><A NAME="ppdCollect">ppdCollect()</A></H2> <H3><A NAME="10_113_1">Usage</A></H3> <PRE> int ppdCollect(ppd_file_t *ppd, ppd_section_t section, ppd_choice_t ***choices); </PRE> <H3><A NAME="10_113_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file.</TD></TR> <TR><TD>section</TD><TD>The document section to collect.</TD></TR> <TR><TD>choices</TD><TD>The array of option choices that are marked.</TD> </TR> </TABLE> </CENTER> <H3><A NAME="10_113_3">Returns</A></H3> <P>The number of options collected.</P> <H3><A NAME="10_113_4">Description</A></H3> <P><CODE>ppdCollect()</CODE> collects all of the marked options in the specified section, sorts them by their order dependency values, and returns an array that can be used to emit option commands in the proper order. It is normally used by the <CODE>ppdEmit*()</CODE> functions.</P> <H3><A NAME="10_113_5">Example</A></H3> <PRE> #include <cups/ppd.h> <A HREF="#ppd_file_t">ppd_file_t</A> *ppd; int num_choices; <A HREF="#ppd_choice_t">ppd_choice_t</A> **choices; ... num_choices = ppdCollect(ppd, PPD_ORDER_JCL, &choices); </PRE> <H3><A NAME="10_113_6">See Also</A></H3> <P> <A HREF="#ppdEmit"><CODE>ppdEmit()</CODE></A>, <A HREF="#ppdEmitFd"><CODE> ppdEmitFd()</CODE></A>, <A HREF="#ppdEmitJCL"><CODE>ppdEmitJCL()</CODE></A> <!-- NEW PAGE --> </P> <H2><A NAME="ppdConflicts">ppdConflicts()</A></H2> <H3><A NAME="10_114_1">Usage</A></H3> <PRE> int ppdConflicts(ppd_file_t *ppd); </PRE> <H3><A NAME="10_114_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_114_3">Returns</A></H3> <P>The number of option conflicts in the file.</P> <H3><A NAME="10_114_4">Description</A></H3> <P>The <CODE>ppdConflicts()</CODE> function returns the number of conflicts with the currently selected options.</P> <H3><A NAME="10_114_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; printf("%d conflicts\n", ppdConflicts(ppd)); </PRE> <H3><A NAME="10_114_6">See Also</A></H3> <A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>, <A HREF="#ppdIsMarked"> <CODE>ppdIsMarked()</CODE></A>, <A HREF="#ppdMarkDefaults"><CODE> ppdMarkDefaults()</CODE></A>, <A HREF="#ppdMarkOption"><CODE> ppdMarkOption()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdEmit">ppdEmit()</A></H2> <H3><A NAME="10_115_1">Usage</A></H3> <PRE> int ppdEmit(ppd_file_t *ppd, FILE *file, ppd_section_t section); </PRE> <H3><A NAME="10_115_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> <TR><TD>file</TD><TD>The file to write to</TD></TR> <TR><TD>section</TD><TD>The option section to write</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_115_3">Returns</A></H3> <P>0 on success, -1 on error.</P> <H3><A NAME="10_115_4">Description</A></H3> <P>The <CODE>ppdEmit()</CODE> function sends printer-specific option commands to the specified file.</P> <H3><A NAME="10_115_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppdEmit(ppd, stdout, PPD_ORDER_PAGE); </PRE> <H3><A NAME="10_115_6">See Also</A></H3> <A HREF="#ppdEmitFd"><CODE>ppdEmitFd()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdEmitFd">ppdEmitFd()</A></H2> <H3><A NAME="10_116_1">Usage</A></H3> <PRE> int ppdEmitFd(ppd_file_t *ppd, int fd, ppd_section_t section); </PRE> <H3><A NAME="10_116_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> <TR><TD>fd</TD><TD>The file descriptor to write to</TD></TR> <TR><TD>section</TD><TD>The option section to write</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_116_3">Returns</A></H3> <P>0 on success, -1 on error.</P> <H3><A NAME="10_116_4">Description</A></H3> <P>The <CODE>ppdEmitFd()</CODE> function sends printer-specific option commands to the specified file descriptor.</P> <H3><A NAME="10_116_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppdEmitFd(ppd, 1, PPD_ORDER_PAGE); </PRE> <H3><A NAME="10_116_6">See Also</A></H3> <A HREF="#ppdEmit"><CODE>ppdEmit()</CODE></A>, <A HREF="#ppdEmitJCL"><CODE> ppdEmitJCL()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdEmitJCL">ppdEmitJCL()</A></H2> <H3><A NAME="10_117_1">Usage</A></H3> <PRE> int ppdEmitJCL(ppd_file_t *ppd, FILE *file, int job_id, const char *user, const char *title); </PRE> <H3><A NAME="10_117_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> <TR><TD>file</TD><TD>The file to write to</TD></TR> <TR><TD>job_id</TD><TD>The job ID number</TD></TR> <TR><TD>user</TD><TD>The job user</TD></TR> <TR><TD>title</TD><TD>The job name</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_117_3">Returns</A></H3> <P>0 on success, -1 on error.</P> <H3><A NAME="10_117_4">Description</A></H3> <P>The <CODE>ppdEmitJCL()</CODE> function sends printer-specific job control commands to the specified file. For printers that support the HP Printer Job Language (PJL) job control language, the output also contains a display string that usually appears on the printer's LCD.</P> <H3><A NAME="10_117_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppdEmitJCL(ppd, stdout, job_id, user, title); </PRE> <H3><A NAME="10_117_6">See Also</A></H3> <A HREF="#ppdEmit"><CODE>ppdEmit()</CODE></A>, <A HREF="#ppdEmitFd"><CODE> ppdEmitFd()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdFindAttr">ppdFindAttr()</A></H2> <H3><A NAME="10_118_1">Usage</A></H3> <PRE> ppd_attr_t * ppdFindAttr(ppd_file_t *ppd, const char *keyword, const char *spec); </PRE> <H3><A NAME="10_118_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> <TR><TD>keyword</TD><TD>The name of the attribute</TD></TR> <TR><TD>spec</TD><TD>The option keyword associated with the attribute or NULL if you don't care.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_118_3">Returns</A></H3> <P>A pointer to the attribute data or NULL if the attribute does not exist.</P> <H3><A NAME="10_118_4">Description</A></H3> <P>The <CODE>ppdFindAttr()</CODE> function returns a pointer to the first occurrence of the attribute in the PPD file.</P> <H3><A NAME="10_118_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppd_attr_t *attr; attr = ppdFindAttr(ppd, "RequiresPageRegion", "Upper"); </PRE> <H3><A NAME="10_118_6">See Also</A></H3> <A HREF="#ppdFindNextAttr"><CODE>ppdFindNextAttr()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdFindChoice">ppdFindChoice()</A></H2> <H3><A NAME="10_119_1">Usage</A></H3> <PRE> ppd_choice_t * ppdFindChoice(ppd_option_t *option, const char *choice); </PRE> <H3><A NAME="10_119_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>option</TD><TD>A pointer to the option</TD></TR> <TR><TD>choice</TD><TD>The name of the choice</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_119_3">Returns</A></H3> <P>A pointer to the choice data or NULL if the choice does not exist.</P> <H3><A NAME="10_119_4">Description</A></H3> <P>The <CODE>ppdFindChoice()</CODE> function returns a pointer to the choice data for the specified option.</P> <H3><A NAME="10_119_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppd_option_t *option; ppd_choice_t *choice; option = ppdFindOption(ppd, "PageSize"); choice = ppdFindChoice(option, "Letter"); </PRE> <H3><A NAME="10_119_6">See Also</A></H3> <A HREF="#ppdFindMarkedChoice"><CODE>ppdFindMarkedChoice()</CODE></A>, <A HREF="#ppdFindOption"><CODE>ppdFindOption()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdFindMarkedChoice">ppdFindMarkedChoice()</A></H2> <H3><A NAME="10_120_1">Usage</A></H3> <PRE> ppd_choice_t * ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword); </PRE> <H3><A NAME="10_120_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> <TR><TD>keyword</TD><TD>The name of the option</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_120_3">Returns</A></H3> <P>A pointer to the choice data or NULL if the choice does not exist or is not marked.</P> <H3><A NAME="10_120_4">Description</A></H3> <P>The <CODE>ppdFindMarkedChoice()</CODE> function returns a pointer to the marked choice data for the specified option.</P> <H3><A NAME="10_120_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppd_choice_t *choice; choice = ppdFindMarkedChoice(ppd, "PageSize"); </PRE> <H3><A NAME="10_120_6">See Also</A></H3> <A HREF="#ppdFindChoice"><CODE>ppdFindChoice()</CODE></A>, <A HREF="#ppdFindOption"> <CODE>ppdFindOption()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdFindNextAttr">ppdFindNextAttr()</A></H2> <H3><A NAME="10_121_1">Usage</A></H3> <PRE> ppd_attr_t * ppdFindNextAttr(ppd_file_t *ppd, const char *keyword, const char *spec); </PRE> <H3><A NAME="10_121_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>A pointer to the PPD file</TD></TR> <TR><TD>keyword</TD><TD>The name of the attribute</TD></TR> <TR><TD>spec</TD><TD>The option keyword associated with the attribute or NULL if you don't care.</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_121_3">Returns</A></H3> <P>A pointer to the attribute data or NULL if the attribute does not exist.</P> <H3><A NAME="10_121_4">Description</A></H3> <P>The <CODE>ppdFindNextAttr()</CODE> function returns a pointer to the next occurrence of the attribute in the PPD file.</P> <H3><A NAME="10_121_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppd_attr_t *attr; for (attr = ppdFindAttr(ppd, "cupsICCProfile", NULL); attr != NULL; attr = ppdFindNextAttr(ppd, "cupsICCProfile", NULL)) { printf("*%s %s/%s: \"%s\"\n", attr->name, attr->spec, attr->text, attr->value ? attr->value : "(none)"); } </PRE> <H3><A NAME="10_121_6">See Also</A></H3> <A HREF="#ppdFindAttr"><CODE>ppdFindAttr()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdFindOption">ppdFindOption()</A></H2> <H3><A NAME="10_122_1">Usage</A></H3> <PRE> ppd_option_t * ppdFindOption(ppd_file_t *ppd, const char *keyword); </PRE> <H3><A NAME="10_122_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> <TR><TD>keyword</TD><TD>The name of the option</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_122_3">Returns</A></H3> <P>A pointer to the option data or NULL if the option does not exist.</P> <H3><A NAME="10_122_4">Description</A></H3> <P>The <CODE>ppdFindOption()</CODE> function returns a pointer to the option data for the specified option.</P> <H3><A NAME="10_122_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppd_option_t *option; option = ppdFindOption(ppd, "PageSize"); </PRE> <H3><A NAME="10_122_6">See Also</A></H3> <A HREF="#ppdFindChoice"><CODE>ppdFindChoice()</CODE></A>, <A HREF="#ppdFindMarkedChoice"> <CODE>ppdFindMarkedChoice()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdIsMarked">ppdIsMarked()</A></H2> <H3><A NAME="10_123_1">Usage</A></H3> <PRE> int ppdIsMarked(ppd_file_t *ppd, const char *keyword, const char *choice); </PRE> <H3><A NAME="10_123_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> <TR><TD>keyword</TD><TD>The name of the option</TD></TR> <TR><TD>choice</TD><TD>The name of the option choice</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_123_3">Returns</A></H3> <P>1 if the choice is marked, 0 otherwise.</P> <H3><A NAME="10_123_4">Description</A></H3> <P>The <CODE>ppdIsMarked()</CODE> function returns whether or not the specified option choice is marked.</P> <H3><A NAME="10_123_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; printf("Letter size %s selected.\n", ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not"); </PRE> <H3><A NAME="10_123_6">See Also</A></H3> <A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>, <A HREF="#ppdConflicts"> <CODE>ppdConflicts()</CODE></A>, <A HREF="#ppdIsMarked"><CODE> ppdIsMarked()</CODE></A>, <A HREF="#ppdMarkDefaults"><CODE> ppdMarkDefaults()</CODE></A>, <A HREF="#ppdMarkOption"><CODE> ppdMarkOption()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdMarkDefaults">ppdMarkDefaults()</A></H2> <H3><A NAME="10_124_1">Usage</A></H3> <PRE> void ppdMarkDefaults(ppd_file_t *ppd); </PRE> <H3><A NAME="10_124_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_124_3">Description</A></H3> <P>The <CODE>ppdMarkDefaults()</CODE> function marks all of the default choices in the PPD file.</P> <H3><A NAME="10_124_4">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppdMarkDefaults(ppd); </PRE> <H3><A NAME="10_124_5">See Also</A></H3> <A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>, <A HREF="#ppdConflicts"> <CODE>ppdConflicts()</CODE></A>, <A HREF="#ppdIsMarked"><CODE> ppdIsMarked()</CODE></A>, <A HREF="#ppdMarkDefaults"><CODE> ppdMarkDefaults()</CODE></A>, <A HREF="#ppdMarkOption"><CODE> ppdMarkOption()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdMarkOption">ppdMarkOption()</A></H2> <H3><A NAME="10_125_1">Usage</A></H3> <PRE> int ppdMarkOption(ppd_file_t *ppd, const char *keyword, const char *choice); </PRE> <H3><A NAME="10_125_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> <TR><TD>keyword</TD><TD>The name of the option</TD></TR> <TR><TD>choice</TD><TD>The name of the choice</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_125_3">Returns</A></H3> <P>The number of conflicts in the PPD file.</P> <H3><A NAME="10_125_4">Description</A></H3> <P>The <CODE>ppdMarkOption()</CODE> function marks the specified option choice.</P> <H3><A NAME="10_125_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppdMarkOption(ppd, "PageSize", "Letter"); </PRE> <H3><A NAME="10_125_6">See Also</A></H3> <A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>, <A HREF="#ppdConflicts"> <CODE>ppdConflicts()</CODE></A>, <A HREF="#ppdIsMarked"><CODE> ppdIsMarked()</CODE></A>, <A HREF="#ppdMarkDefaults"><CODE> ppdMarkDefaults()</CODE></A>, <A HREF="#ppdMarkOption"><CODE> ppdMarkOption()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdOpen">ppdOpen()</A></H2> <H3><A NAME="10_126_1">Usage</A></H3> <PRE> ppd_file_t * ppdOpen(FILE *file); </PRE> <H3><A NAME="10_126_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>file</TD><TD>The file to read from</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_126_3">Returns</A></H3> <P>A pointer to a PPD file structure or NULL if the PPD file could not be read.</P> <H3><A NAME="10_126_4">Description</A></H3> <P>The <CODE>ppdOpen()</CODE> function reads a PPD file from the specified file into memory.</P> <H3><A NAME="10_126_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; FILE *file; file = fopen("filename.ppd", "rb"); ppd = ppdOpen(file); fclose(file); </PRE> <H3><A NAME="10_126_6">See Also</A></H3> <A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>, <A HREF="#ppdOpenFd"><CODE> ppdOpenFd()</CODE></A>, <A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE> </A> <!-- NEW PAGE --> <H2><A NAME="ppdOpenFd">ppdOpenFd()</A></H2> <H3><A NAME="10_127_1">Usage</A></H3> <PRE> ppd_file_t * ppdOpenFd(int fd); </PRE> <H3><A NAME="10_127_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>fd</TD><TD>The file descriptor to read from</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_127_3">Returns</A></H3> <P>A pointer to a PPD file structure or NULL if the PPD file could not be read.</P> <H3><A NAME="10_127_4">Description</A></H3> <P>The <CODE>ppdOpenFd()</CODE> function reads a PPD file from the specified file descriptor into memory.</P> <H3><A NAME="10_127_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; int fd; fd = open("filename.ppd", O_RDONLY); ppd = ppdOpenFd(fd); close(fd); </PRE> <H3><A NAME="10_127_6">See Also</A></H3> <A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>, <A HREF="#ppdOpen"><CODE> ppdOpen()</CODE></A>, <A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdOpenFile">ppdOpenFile()</A></H2> <H3><A NAME="10_128_1">Usage</A></H3> <PRE> ppd_file_t * ppdOpenFile(const char *filename); </PRE> <H3><A NAME="10_128_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>filename</TD><TD>The name of the file to read from</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_128_3">Returns</A></H3> <P>A pointer to a PPD file structure or NULL if the PPD file could not be read.</P> <H3><A NAME="10_128_4">Description</A></H3> <P>The <CODE>ppdOpenFile()</CODE> function reads a PPD file from the named file into memory.</P> <H3><A NAME="10_128_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppd = ppdOpenFile("filename.ppd"); </PRE> <H3><A NAME="10_128_6">See Also</A></H3> <A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>, <A HREF="#ppdOpen"><CODE> ppdOpen()</CODE></A>, <A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdPageLength">ppdPageLength()</A></H2> <H3><A NAME="10_129_1">Usage</A></H3> <PRE> float ppdPageLength(ppd_file_t *ppd, const char *name); </PRE> <H3><A NAME="10_129_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> <TR><TD>name</TD><TD>The name of the page size</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_129_3">Returns</A></H3> <P>The length of the specified page size in points or 0 if the page size does not exist.</P> <H3><A NAME="10_129_4">Description</A></H3> <P>The <CODE>ppdPageLength()</CODE> function returns the page length of the specified page size.</P> <H3><A NAME="10_129_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; printf("Length = %.0f\n", ppdPageLength(ppd, "Letter")); </PRE> <H3><A NAME="10_129_6">See Also</A></H3> <A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>, <A HREF="#ppdPageSize"> <CODE>ppdPageSize()</CODE></A>, <A HREF="#ppdPageWidth"><CODE> ppdPageWidth()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdPageSize">ppdPageSize()</A></H2> <H3><A NAME="10_130_1">Usage</A></H3> <PRE> ppd_size_t * ppdPageSize(ppd_file_t *ppd, const char *name); </PRE> <H3><A NAME="10_130_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> <TR><TD>name</TD><TD>The name of the page size</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_130_3">Returns</A></H3> <P>A pointer to the page size record of the specified page size in points or NULL if the page size does not exist.</P> <H3><A NAME="10_130_4">Description</A></H3> <P>The <CODE>ppdPageSize()</CODE> function returns the page size record for the specified page size.</P> <H3><A NAME="10_130_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; ppd_size_t *size; size = ppdPageSize(ppd, "Letter"); if (size != NULL) { printf(" Width = %.0f\n", size->width); printf("Length = %.0f\n", size->length); printf(" Left = %.0f\n", size->left); printf(" Right = %.0f\n", size->right); printf("Bottom = %.0f\n", size->bottom); printf(" Top = %.0f\n", size->top); } </PRE> <H3><A NAME="10_130_6">See Also</A></H3> <A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>, <A HREF="#ppdPageWidth"> <CODE>ppdPageWidth()</CODE></A> <!-- NEW PAGE --> <H2><A NAME="ppdPageWidth">ppdPageWidth()</A></H2> <H3><A NAME="10_131_1">Usage</A></H3> <PRE> float ppdPageWidth(ppd_file_t *ppd, const char *name); </PRE> <H3><A NAME="10_131_2">Arguments</A></H3> <CENTER> <TABLE BORDER WIDTH="80%"> <TR><TH>Argument</TH><TH>Description</TH></TR> <TR><TD>ppd</TD><TD>The PPD file</TD></TR> <TR><TD>name</TD><TD>The name of the page size</TD></TR> </TABLE> </CENTER> <H3><A NAME="10_131_3">Returns</A></H3> <P>The width of the specified page size in points or 0 if the page size does not exist.</P> <H3><A NAME="10_131_4">Description</A></H3> <P>The <CODE>ppdPageWidth()</CODE> function returns the page width of the specified page size.</P> <H3><A NAME="10_131_5">Example</A></H3> <PRE> #include <cups/ppd.h> ppd_file_t *ppd; printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter")); </PRE> <H3><A NAME="10_131_6">See Also</A></H3> <A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>, <A HREF="#ppdPageSize"> <CODE>ppdPageSize()</CODE></A></BODY> </HTML>