This software programmers manual provides software programming information for the Common UNIX Printing System ("CUPS") Version 1.1.15. Document Overview This software programmers manual is organized into the following sections: 1 - Printing System Overview 2 - The CUPS API 3 - Writing Filters 4 - Writing Printer Drivers 5 - Writing Backends A - Software License Agreement B - Constants C - Structures D - Functions Notation Conventions Various font and syntax conventions are used in this guide. Examples and their meanings and uses are explained below: Example Description lpstat lpstat(1) The names of commands; the first mention of a command or function in a chapter is followed by a manual page section number. /var /usr/share/cups/data/testprint.ps File and directory names. Request ID is Printer-123 Screen output. lp -d printer filename ENTER Literal user input; special keys like ENTER are in ALL CAPS. 12.3 Numbers in the text are written using the period (.) to indicate the decimal point. Abbreviations The following abbreviations are used throughout this manual: kb Kilobytes, or 1024 bytes Mb Megabytes, or 1048576 bytes Gb Gigabytes, or 1073741824 bytes Other References CUPS Software Administrators Manual An administration guide for the CUPS software. CUPS Software Users Manual An end-user guide for using the CUPS software. 2 - The CUPS API This chapter describes the CUPS Application Programmers Interface ("API"). The CUPS API Library 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. 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. Programs that use the CUPS API library typically will include the <cups/cups.h> header file: #include <cups/cups.h> ... jobid = cupsPrintFile("myprinter", "filename.ps", "title", num_options, options); Use the -lcups compiler option when linking to the CUPS API library: cc -o program program.c -lcups ENTER Additional options and libraries may be required depending on the operating system and the location of the CUPS API library. Detecting the CUPS API Library in GNU Autoconf GNU autoconf is a popular configuration tool used by many programs. Add the following lines to your configure.in file to check for the CUPS API library in your configuration script: 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) Printing Services The CUPS API library provides some basic printing services for applications that need to print files. Include Files The include file used by all of these functions is <cups/cups.h>: #include <cups/cups.h> Printing a File The CUPS API provides two functions for printing files. The first is cupsPrintFile which prints a single named file: #include <cups/cups.h> ... int jobid; ... jobid = cupsPrintFile("name", "filename", "title", 0, NULL); The name string is the name of the printer or class to print to. The filename string is the name of the file to print. The title string is the name of the print job, e.g. "Acme Word Document". The return value is a unique ID number for the print job or 0 if there was an error. Printing Multiple Files The second printing function is cupsPrintFiles: #include <cups/cups.h> ... int jobid; int num_files; const char *files[100]; ... jobid = cupsPrintFiles("name", num_files, files, "title", 0, NULL); Instead of passing a filename string as with cupsPrintFile(), you pass a file count (num_files) and filename pointer array (files) for each file that you want to print. As with cupsPrintFile(), the return value is a unique ID for the print job. Cancelling Jobs The cupsCancelJob() function cancels a queued print job: #include <cups/cups.h> ... int jobid; int status; ... status = cupsCancelJob("name", jobid); The name string specifies the destination and is used to determine the server to send the request to. The jobid value is the integer returned from a previous cupsPrintFile() or cupsPrintFiles() call. cupsCancelJob() returns 1 if the job was successfully cancelled and 0 if there was an error. Getting the Available Printers and Classes The cupsGetDests() function can be used to get a list of the available printers, classes, and instances that a user has defined: #include <cups/cups.h> ... int num_dests; cups_dest_t *dests; ... num_dests = cupsGetDests(&dests); Each destination is stored in a cups_dest_t 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: 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; 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 cupsGetDest() function: #include <cups/cups.h> ... int num_dests; cups_dest_t *dests; cups_dest_t *mydest; ... mydest = cupsGetDest("name", "instance", num_dests, dests); The name string is the printer or class name. You can pass a value of NULL to get the default destination. The instance string is the user-defined instance name. Pass NULL to select the default instance, e.g. "name" instead of "name/instance". Printing with Options All of the previous printing examples have passed 0 and NULL for the last two arguments to the cupsPrintFile() and cupsPrintFiles() functions. These last two arguments are the number of options and a pointer to the option array: 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); The cups_option_t structure holds each option and its value. These are converted as needed and passed to the CUPS server when printing a file. The simplest way of handling options is to use the num_options and options members of the cups_dest_t structure described earlier: #include <cups/cups.h> ... int jobid; int num_dests; cups_dest_t *dests; cups_dest_t *mydest; ... mydest = cupsGetDest("name", "instance", num_dests, dests); jobid = cupsPrintFile(mydest->name, "filename", "title", mydest->num_options, mydest->options); This effectively uses the options a user has previous selected without a lot of code. Setting Printer Options Options can also be set by your program using the cupsAddOption() function: #include <cups/cups.h> ... int num_options; cups_option_t *options; ... num_options = 0; options = NULL; ... num_options = cupsAddOption("name", "value", num_options, &options); num_options = cupsAddOption("name", "value", num_options, &options); num_options = cupsAddOption("name", "value", num_options, &options); num_options = cupsAddOption("name", "value", num_options, &options); The name string is the name of the option, and the value string is the value for that option. Each call to cupsAddOption() 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 cupsAddOptions() 20 times will result in 20 options. Call cupsFreeOptions once you are done using the options: #include <cups/cups.h> ... int num_options; cups_option_t *options; ... cupsFreeOptions(num_options, options); Getting Errors If any of the CUPS API printing functions returns an error, the reason for that error can be found by calling cupsLastError() and cupsErrorString(). cupsLastError() returns the last IPP error code that was encountered. cupsErrorString() converts the error code to a localized message string suitable for presentation to the user: #include <cups/cups.h> ... int jobid; ... if (jobid == 0) puts(cupsErrorString(cupsLastError())); Passwords and Authentication 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. 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. The cupsSetPasswordCB() function is used to set a password callback in your program. Only one function can be used at any time. The cupsSetUser() function sets the current username for authentication. This function can be called by your password callback function to change the current username as needed. The following example shows a simple password callback that gets a username and password from the user: #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); 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 cupsUser() to make things easier on the user. PPD Services CUPS includes functions to access and manipulate PostScript Printer Description ("PPD") files that are used with the printer drivers in CUPS. 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.) Include Files Include the <cups/ppd.h> header file to use the PPD functions: #include <cups/ppd.h> This header file is also included by the <cups/cups.h> header file. Getting a PPD File for a Printer The cupsGetPPD() function retrieves the PPD file for the named printer or class: #include <cups/cups.h> ... const char *filename; filename = cupsGetPPD("name"); The name string is the name of the printer or class, including the remote server name as appropriate (e.g. "printer@server".) The return value is a pointer to a filename in static storage; this value is overwritten with each call to cupsGetPPD(). If the printer or class does not exist, a NULL pointer will be returned. Loading a PPD File The ppdOpenFile() function "opens" a PPD file and loads it into memory: #include <cups/ppd.h> ... ppd_file_t *ppd; ppd = ppdOpenFile("filename"); The filename string is the name of the file to load, such as the value returned by the cupsGetPPD() function. 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. Freeing PPD File Information Once you are done using a PPD file, call the ppdClose() function to free all memory that has been used: #include <cups/ppd.h> ... ppd_file_t *ppd; ... ppdClose(ppd); The PPD File Structure 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 ppd_file_t structure. Capabilities Each PPD file contains a number of informational attributes that describe the capabilities of the printer. These are provided in the ppd_file_t structure in the following members: Member Type Description accurate_screens int 1 = supports accurate screens color_device int 1 = color device colorspace ppd_cs_t Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB, PPD_CS_RGBK, PPD_CS_N contone_only int 1 = printer is continuous tone only num_emulations emulations int ppd_emul_t * Emulations supported by the printer flip_duplex int 1 = need to flip odd pages when duplexing num_fonts fonts int char ** The fonts available on the printer. jcl_begin jcl_ps jcl_end char * Job Control Language commands for PostScript output landscape int Landscape orientation, -90 or 90 degrees lang_encoding char * The character used for the option strings lang_version char * The language used for the options strings (English, French, etc.) language_level int PostScript language level, 1 to 3 manual_copies int 1 = Copies are done manually model_number int Driver-specific model number. patches char * Patch commands to send to the printer manufacturer char * The Manufacturer attribute from the PPD file, if any modelname char * The ModelName attribute from the PPD file nickname char * The NickName attribute from the PPD file, if any product char * The Product attribute from the PPD file, if any shortnickname char * The ShortNickName attribute from the PPD file, if any throughput int Number of pages per minute ttrasterizer char * The TruType font rasterizer (Type42) variable_sizes int 1 = supports variable sizes Options and Groups PPD files support multiple options, which are stored in ppd_option_t and ppd_choice_t structures by the PPD functions. Each option in turn is associated with a group stored in the ppd_group_t 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. Groups can also have sub-groups; CUPS currently limits the depth of sub-groups to 1 level to reduce programming complexity. Conflicts PPD files support specification of conflict conditions between different options. Conflicts are stored in ppd_conflict_t structures which specify the options that conflict with each other. Page Sizes PPD files specify all of the available pages sizes and the physical margins associated with them. These sizes are stored in ppd_size_t structures and are available in the num_sizes and sizes members of the ppd_file_t structure. You can lookup a particular page size with the ppdPageWidth(), ppdPageLength(), and ppdPageSize() functions: #include <cups/ppd.h> ... ppd_file_t *ppd; ppd_size_t *size; float width; float length; ... size = ppdPageSize(ppd, "size"); width = ppdPageWidth(ppd, "size"); length = ppdPageLength(ppd, "size"); The size string is the named page size option. The width and length are in points; there are 72 points per inch. The ppd_size_t structure contains the width, length, and margin information: 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; Custom Page Sizes Besides the standard page sizes listed in a PPD file, some printers support variable or custom page sizes. If variables_sizes is non-zero, the custom_min, custom_max, and custom_margins members of the ppd_file_t structure define the limits of the variable sizes. To get the resulting media size, use a page size string of Custom.widthxlength, where width and length are integer values in points: Custom.612x792 [8.5 inches wide, 11 inches long] Custom.1224x792 [17 inches wide, 11 inches long] Marking Options Before marking any user-defined options, call the ppdMarkDefaults() function to mark the default options from the PPD file: #include <cups/ppd.h> ... ppd_file_t *ppd; ... ppdMarkDefaults(ppd); Then call the ppdMarkOption() function to mark individual options: #include <cups/ppd.h> ... ppd_file_t *ppd; int conflicts; ... conflicts = ppdMarkOption(ppd, "name", "value"); The name and value strings choose a particular option and choice, respectively. The return value is 0 if there are not conflicts created by the selection. CUPS also provides a convenience function for marking all options in the cups_option_t structure: #include <cups/cups.h> ... ppd_file_t *ppd; int num_options; cups_option_t *options; int conflicts; ... conflicts = cupsMarkOptions(ppd, num_options, options); The cupsMarkOptions() function also handles mapping the IPP job template attributes to PPD options. The return value is the number of conflicts present. Checking for Conflicts The ppdMarkOption() and cupsMarkOptions() functions return the number of conflicts with the currently marked options. Call the ppdConflicts() function to get the number of conflicts after you have marked all of the options: #include <cups/cups.h> ... ppd_file_t *ppd; int conflicts; ... conflicts = ppdConflicts(ppd); The return value is the number of conflicting options, or 0 if there are no conflicts. 3 - Writing Filters This chapter describes how to write a file filter for CUPS. Overview 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. Security Considerations 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. Users and Groups The default CUPS configuration runs filters as user "lp" and group "other". Temporary Files Temporary files should be created in the directory specified by the "TMPDIR" environment variable. The cupsTempFile() function can be used to safely choose temporary files in this directory. Sending Messages to the User 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 LogLevel directive. The type of message is determined by an initial prefix sent on each line: DEBUG: - a debug message INFO: - an informational message WARNING: - a warning message ERROR: - an error message PAGE: - a page accounting message 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 printer-state-message attribute for the printer, and also added to the error_log unless it is an informational or page accounting message. Page Accounting Page accounting messages are used to inform the server when one or more pages are printed. Each line has the form: PAGE: page-number copy-count The page-number field is the current page number, starting at 1. The copy-count field specifies the number of copies of that page that was produced. Page account messages are added to the page_log file and cause the job-sheets-completed attribute to be updated for the job. Command-Line Arguments Every filter accepts exactly 6 or 7 command-line arguments: printer job user title copies options [filename] printer - The name of the printer queue (normally this is the name of the program being run) job - The numeric job ID for the job being printed user - The string from the originating-user-name attribute title - The string from the job-name attribute copies - The numeric value from the number-copies attribute options - 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 filename - The request file The filename argument is only provided to the first filter in the chain; all filters must be prepared to read the print file from the standard input if the filename argument is omitted. Copy Generation The copies argument specifies the number of copies to produce of the input file. In general, you should only generate copies if the filename 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 pstops is responsible for copy generation. Environment Variables Every filter receives a fixed set of environment variables that can be used by the filter: CHARSET - The character set used by the client for this print file CONTENT_TYPE - The original document type, such as "application/postscript" CUPS_DATADIR - The location of CUPS data files CUPS_SERVERROOT - The location of CUPS configuration files DEVICE_URI - The output device URI LANG - The language used by the client for this print file PATH - The execution path exported to the filter PPD - The full filename of the printer's PPD file PRINTER - The name of the printer queue RIP_CACHE - The maximum amount of memory each filter should use SOFTWARE - The name of the CUPS software, typically "CUPS/1.1" TZ - The local timezone USER - The name of the current user Dissecting the HP-GL/2 Filter The HP-GL/2 filter (hpgltops) 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. Initializing the Filter The first task of any filter is to ensure that the correct number of command-line arguments are present: if (argc < 6 || argc > 7) { fputs("ERROR: hpgltops job-id user title copies options [file]\n", stderr); return (1); } After this you open the print file or read from the standard input as needed: 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); } } Once the print file has been opened, options can be processed using the cupsParseOptions() and cupsGetOption() functions: 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; 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. PostScript Output 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: %!PS-Adobe-3.0 %%BoundingBox: left bottom right top %%Pages: (atend) %%EndComments The left, bottom, right, and top values are integers in points from the lower-lefthand corner of the page. Pages must be surrounded by: %%Page: number number gsave ... grestore showpage And the end of each file must contain: %%Trailer %%Pages: number-pages %%EOF These comments allow the PostScript filter to correctly perform page accounting, copy generation, N-up printing, and so forth. 4 - Writing Printer Drivers 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. Overview 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. CUPS Raster Data CUPS raster data (application/vnd.cups-raster) consists of a stream of raster page descriptions produced by one of the RIP filters, such as pstoraster or imagetoraster. Each page of data begins with a page dictionary structure called cups_raster_header_t. This structure contains the colorspace, bits per color, media size, media type, hardware resolution, and so forth. After the page dictionary comes the page data which is a full-resolution, uncompressed bitmap representing the page in the printer's output colorspace. Page Accounting 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. Color Management Printer drivers can implement their color management via the cupsColorProfile 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. For example, the pstoraster 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. Device and Bitmap Variables 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: Variable Type Description cupsWidth read-only integer Width of bitmap in pixels cupsHeight read-only integer Height of bitmap in pixels cupsMediaType read-write integer Device-specific media type code cupsBitsPerColor read-write integer Number of bits per color; 1, 2, 4, and 8 are currently supported cupsBitsPerPixel read-only integer Number of bits per pixel; 1 to 32 cupsBytesPerLine read-only integer Number of bytes per line of raster graphics cupsColorOrder read-write enum The order of color values in the bitmap: CUPS_ORDER_CHUNKED - CMYK CMYK CMYK CUPS_ORDER_BANDED - CCC MMM YYY KKK CUPS_ORDER_PLANAR - CCC ... MMM ... YYY ... KKK ... cupsColorSpace read-write enum The colorspace of the bitmap: CUPS_CSPACE_W - White (luminance) CUPS_CSPACE_RGB - Red, green, blue CUPS_CSPACE_RGBA - Red, green, blue, alpha CUPS_CSPACE_K - Black CUPS_CSPACE_CMY - Cyan, magenta, yellow CUPS_CSPACE_YMC - Yellow, magenta, cyan CUPS_CSPACE_CMYK - Cyan, magenta, yellow, black CUPS_CSPACE_YMCK - Yellow, magenta, cyan, black CUPS_CSPACE_KCMY - Black, cyan, magenta, yellow CUPS_CSPACE_KCMYcm - Black, cyan, magenta, yellow, light cyan, light magenta CUPS_CSPACE_GMCK - Metallic yellow (gold), metallic magenta, metallic cyan, black CUPS_CSPACE_GMCS - Metallic yellow (gold), metallic magenta, metallic cyan, metallic grey (silver) CUPS_CSPACE_WHITE - White pigment (black as white pigment) CUPS_CSPACE_GOLD - Gold foil (black as gold foil) CUPS_CSPACE_SILVER - Silver foil (black as silver foil) cupsCompression read-write integer Device-specific compression type code cupsRowCount read-write integer Device-specific row count value cupsRowFeed read-write integer Device-specific row feed value cupsRowStep read-write integer Device-specific row step value 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. Dissecting the HP-PCL Driver The HP-PCL driver provided with CUPS (rastertohp) 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 - deskjet.ppd or laserjet.ppd. PPD Files 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. A typical CUPS printer driver will include ColorModel, InputSlot, PageSize, PageRegion, and Resolution options. Each option is shown using the standard PPD format: *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 The OpenUI 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. Every option must have a default value, specified using the DefaultOption keyword. 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: *PageSize A4/A4: "<</PageSize[595 842]/ImagingBBox null>> setpagedevice" or broken down on separate lines using the End keyword to terminate them: *PageSize A4/A4: "<< /PageSize [595 842] /ImagingBBox null >> setpagedevice" *End 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. Reading Raster Data 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 cupsRasterOpen() function opens a raster stream for printing: 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); Once you have opened the raster stream you just need to read each page and print it: 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 ... } } After you have processed all pages, close the raster stream and return: cupsRasterClose(ras); return (0); 5 - Writing Backends 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. Overview Backends are special filters that communicate with printers directly. They are treated slightly differently than filters, however, and have some unique requirements. Security Considerations 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. Command-Line Arguments 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. Copy Generation 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. Page Accounting 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. Exclusive Access Backends that talk to local character or block devices should open the device file in exclusive mode (O_EXCL) to cooperate with other printers defined for the same device. Retries All backends must 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. 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. Dissecting the Serial Port Backend 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. Supporting Device Discovery 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...) The serial backend lists devices by looking at serial port files in the /dev directory, by consulting a hardware inventory (IRIX), and in some cases by trying to open the ports to see if they actually exist. Once it finds a serial port it writes a single line for each port to the standard error file. Each line looks like this: serial serial:/dev/ttyS0?baud=115200 "Unknown" "Serial Port 1" The first word "serial" is the device class; this identifies the class of device which can be used to categorize it in user interfaces. CUPS currently recognizes the following classes: "file" - a disk file. "direct" - a parallel or fixed-rate serial data port, currently used for Centronics, IEEE-1284, and USB printer ports. "serial" - a variable-rate serial port. "network" - a network connection, typically via AppSocket, HTTP, IPP, LPD, or SMB/CIFS protocols. After the device class is the device URI, 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. 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. Opening the Serial Port 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 do-while loop: 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); 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. Writing Data to the Port 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: 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; } The check for the ENOTTY error is needed on some platforms to clear an error from a previous ioctl() call. Finishing Up 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. A - Software License Agreement B - Constants This appendix lists all of the constants that are defined by the CUPS API. CUPS Constants Version Number The CUPS_VERSION 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. Printer Capabilities The CUPS_PRINTER constants represent capability bits for printers and classes: CUPS_PRINTER_LOCAL - Is a local printer or class. CUPS_PRINTER_REMOTE - Is a remote printer or class. CUPS_PRINTER_CLASS - Is a class. CUPS_PRINTER_BW - Printer prints in black and white. CUPS_PRINTER_COLOR - Printer prints in color. CUPS_PRINTER_DUPLEX - Printer can print double-sided. CUPS_PRINTER_STAPLE - Printer can staple output. CUPS_PRINTER_COPIES - Printer can produce multiple copies on its own. CUPS_PRINTER_COLLATE - Printer can collate copies. CUPS_PRINTER_PUNCH - Printer can punch holes in output. CUPS_PRINTER_COVER - Printer can put covers on output. CUPS_PRINTER_BIND - Printer can bind output. CUPS_PRINTER_SORT - Printer can sort output. CUPS_PRINTER_SMALL - Printer can print on media up to 9x14 inches. CUPS_PRINTER_MEDIUM - Printer can print on media from 9x14 to 18x24 inches. CUPS_PRINTER_LARGE - Printer can print on media larger than 18x24 inches. CUPS_PRINTER_VARIABLE - Printer can print on variable or custom media sizes. CUPS_PRINTER_IMPLICIT - Is an implicit class. CUPS_PRINTER_OPTIONS - All of the printer capability and option bits. Encodings CUPS defines the following character set encoding constants: CUPS_US_ASCII - US ASCII character set. CUPS_UTF_8 - UTF-8 encoding of Unicode. CUPS_ISO8859_1 - ISO-8859-1 character set. CUPS_ISO8859_2 - ISO-8859-2 character set. CUPS_ISO8859_3 - ISO-8859-3 character set. CUPS_ISO8859_4 - ISO-8859-4 character set. CUPS_ISO8859_5 - ISO-8859-5 character set. CUPS_ISO8859_6 - ISO-8859-6 character set. CUPS_ISO8859_7 - ISO-8859-7 character set. CUPS_ISO8859_8 - ISO-8859-8 character set. CUPS_ISO8859_9 - ISO-8859-9 character set. CUPS_ISO8859_10 - ISO-8859-10 character set. CUPS_ISO8859_13 - ISO-8859-13 character set. CUPS_ISO8859_14 - ISO-8859-14 character set. CUPS_ISO8859_15 - ISO-8859-15 character set. CUPS_WINDOWS_874 - Windows code page 874. CUPS_WINDOWS_1250 - Windows code page 1250. CUPS_WINDOWS_1251 - Windows code page 1251. CUPS_WINDOWS_1252 - Windows code page 1252. CUPS_WINDOWS_1253 - Windows code page 1253. CUPS_WINDOWS_1254 - Windows code page 1254. CUPS_WINDOWS_1255 - Windows code page 1255. CUPS_WINDOWS_1256 - Windows code page 1256. CUPS_WINDOWS_1257 - Windows code page 1257. CUPS_WINDOWS_1258 - Windows code page 1258. CUPS_KOI8_R - Russian code page koi8-r. CUPS_KOI8_U - Ukrainian code page koi8-r. HTTP Constants Limits The following constants define the limits for strings: HTTP_MAX_BUFFER - Size of socket buffer. HTTP_MAX_HOST - Maximum length of hostname. HTTP_MAX_URI - Maximum length of URI. HTTP_MAX_VALUE - Maximum length of field values. Status Codes The following status codes can be returned by httpUpdate(): HTTP_ERROR - A network error occurred HTTP_CONTINUE - Continue response from HTTP proxy HTTP_OK - OPTIONS/GET/HEAD/POST/TRACE command was successful HTTP_CREATED - PUT command was successful HTTP_ACCEPTED - DELETE command was successful HTTP_NOT_AUTHORITATIVE - Information isn't authoritative HTTP_NO_CONTENT - Successful command HTTP_RESET_CONTENT - Content was reset/recreated HTTP_PARTIAL_CONTENT - Only a partial file was recieved/sent HTTP_MULTIPLE_CHOICES - Multiple files match request HTTP_MOVED_PERMANENTLY - Document has moved permanently HTTP_MOVED_TEMPORARILY - Document has moved temporarily HTTP_SEE_OTHER - See this other link... HTTP_NOT_MODIFIED - File not modified HTTP_USE_PROXY - Must use a proxy to access this URI HTTP_BAD_REQUEST - Bad request HTTP_UNAUTHORIZED - Unauthorized to access host HTTP_PAYMENT_REQUIRED - Payment required HTTP_FORBIDDEN - Forbidden to access this URI HTTP_NOT_FOUND - URI was not found HTTP_METHOD_NOT_ALLOWED - Method is not allowed HTTP_NOT_ACCEPTABLE - Not Acceptable HTTP_PROXY_AUTHENTICATION - Proxy Authentication is Required HTTP_REQUEST_TIMEOUT - Request timed out HTTP_CONFLICT - Request is self-conflicting HTTP_GONE - Server has gone away HTTP_LENGTH_REQUIRED - A content length or encoding is required HTTP_PRECONDITION - Precondition failed HTTP_REQUEST_TOO_LARGE - Request entity too large HTTP_URI_TOO_LONG - URI too long HTTP_UNSUPPORTED_MEDIATYPE - The requested media type is unsupported HTTP_SERVER_ERROR - Internal server error HTTP_NOT_IMPLEMENTED - Feature not implemented HTTP_BAD_GATEWAY - Bad gateway HTTP_SERVICE_UNAVAILABLE - Service is unavailable HTTP_GATEWAY_TIMEOUT - Gateway connection timed out HTTP_NOT_SUPPORTED - HTTP version not supported Fields The following fields are indices for each of the standard HTTP fields in HTTP 1/1: HTTP_FIELD_ACCEPT_LANGUAGE - Accept-Language HTTP_FIELD_ACCEPT_RANGES - Accept-Ranges HTTP_FIELD_AUTHORIZATION - Authorization HTTP_FIELD_CONNECTION - Connection HTTP_FIELD_CONTENT_ENCODING - Content-Encoding HTTP_FIELD_CONTENT_LANGUAGE - Content-Language HTTP_FIELD_CONTENT_LENGTH - Content-Length HTTP_FIELD_CONTENT_LOCATION - Content-Location HTTP_FIELD_CONTENT_MD5 - Content-MD5 HTTP_FIELD_CONTENT_RANGE - Content-Range HTTP_FIELD_CONTENT_TYPE - Content-Type HTTP_FIELD_CONTENT_VERSION - Content-Version HTTP_FIELD_DATE - Date HTTP_FIELD_HOST - Host HTTP_FIELD_IF_MODIFIED_SINCE - If-Modified-Since HTTP_FIELD_IF_UNMODIFIED_SINCE - If-Unmodified-Since HTTP_FIELD_KEEP_ALIVE - Keep-Alive HTTP_FIELD_LAST_MODIFIED - Last-Modified HTTP_FIELD_LINK - Link HTTP_FIELD_LOCATION - Location HTTP_FIELD_RANGE - Range HTTP_FIELD_REFERER - Referer HTTP_FIELD_RETRY_AFTER - Retry-After HTTP_FIELD_TRANSFER_ENCODING - Transfer-Encoding HTTP_FIELD_UPGRADE - Upgrade HTTP_FIELD_USER_AGENT - User-Agent HTTP_FIELD_WWW_AUTHENTICATE - WWW-Authenticate IPP Constants Limits The following constants define array limits for IPP data: IPP_MAX_NAME - Maximum length of an attribute name IPP_MAX_VALUES - Maximum number of set-of values that can be read in a request. Tags IPP_TAG_ZERO - Wildcard tag value for searches; also used to separate groups of attributes IPP_TAG_OPERATION - Tag for values of type operation IPP_TAG_JOB - Tag for values of type job IPP_TAG_END - Tag for values of type end IPP_TAG_PRINTER - Tag for values of type printer IPP_TAG_UNSUPPORTED_GROUP - Tag for values of type unsupported_group IPP_TAG_UNSUPPORTED_VALUE - Tag for values of type unsupported_value IPP_TAG_DEFAULT - Tag for values of type default IPP_TAG_UNKNOWN - Tag for values of type unknown IPP_TAG_NOVALUE - Tag for values of type novalue IPP_TAG_NOTSETTABLE - Tag for values of type notsettable IPP_TAG_DELETEATTR - Tag for values of type deleteattr IPP_TAG_ANYVALUE - Tag for values of type anyvalue IPP_TAG_INTEGER - Tag for values of type integer IPP_TAG_BOOLEAN - Tag for values of type boolean IPP_TAG_ENUM - Tag for values of type enum IPP_TAG_STRING - Tag for values of type string IPP_TAG_DATE - Tag for values of type date IPP_TAG_RESOLUTION - Tag for values of type resolution IPP_TAG_RANGE - Tag for values of type range IPP_TAG_COLLECTION - Tag for values of type collection IPP_TAG_TEXTLANG - Tag for values of type textlang IPP_TAG_NAMELANG - Tag for values of type namelang IPP_TAG_TEXT - Tag for values of type text IPP_TAG_NAME - Tag for values of type name IPP_TAG_KEYWORD - Tag for values of type keyword IPP_TAG_URI - Tag for values of type uri IPP_TAG_URISCHEME - Tag for values of type urischeme IPP_TAG_CHARSET - Tag for values of type charset IPP_TAG_LANGUAGE - Tag for values of type language IPP_TAG_MIMETYPE - Tag for values of type mimetype Resolution Units The IPP_RES_PER_INCH and IPP_RES_PER_CM constants specify dots per inch and dots per centimeter, respectively. Finishings The finishing values specify special finishing operations to be performed on the job. IPP_FINISH_NONE - Do no finishing IPP_FINISH_STAPLE - Staple the job IPP_FINISH_PUNCH - Punch the job IPP_FINISH_COVER - Cover the job IPP_FINISH_BIND - Bind the job Orientations The orientation values specify the orientation of the job. IPP_PORTRAIT - No rotation IPP_LANDSCAPE - 90 degrees counter-clockwise IPP_REVERSE_LANDSCAPE - 90 degrees clockwise IPP_REVERSE_PORTRAIT - 180 degrees Qualities The quality values specify the desired quality of the print. IPP_QUALITY_DRAFT - Draft quality IPP_QUALITY_NORMAL - Normal quality IPP_QUALITY_HIGH - High quality Job States The job state values are used to represent the current job state. IPP_JOB_PENDING - Job is pending IPP_JOB_HELD - Job is held IPP_JOB_PROCESSING - Job is processing IPP_JOB_STOPPED - Job is stopped IPP_JOB_CANCELLED - Job is cancelled IPP_JOB_ABORTED - Job is aborted IPP_JOB_COMPLETED - Job is completed Printer States The printer state values are used to represent the current printer state. IPP_PRINTER_IDLE - Printer is idle IPP_PRINTER_PROCESSING - Printer is processing IPP_PRINTER_STOPPED - Printer is stopped Operations The operation values represent the available IPP operations. IPP_PRINT_JOB - Print a file IPP_PRINT_URI - Print a URI IPP_VALIDATE_JOB - Validate job attributes IPP_CREATE_JOB - Create a new job IPP_SEND_DOCUMENT - Send a document to a job IPP_SEND_URI - Send a URI to a job IPP_CANCEL_JOB - Cancel a job IPP_GET_JOB_ATTRIBUTES - Get job attributes IPP_GET_JOBS - Get a list of all jobs IPP_GET_PRINTER_ATTRIBUTES - Get printer attributes IPP_HOLD_JOB - Hold a pending job IPP_RELEASE_JOB - Release a held job IPP_RESTART_JOB - Restart a completed job IPP_PAUSE_PRINTER - Pause a printer IPP_RESUME_PRINTER - Restart a paused printer IPP_PURGE_JOBS - Purge jobs from the queue IPP_SET_PRINTER_ATTRIBUTES - Set printer attributes IPP_SET_JOB_ATTRIBUTES - Set job attributes IPP_GET_PRINTER_SUPPORTED_VALUES - Get printer supported values CUPS_GET_DEFAULT - Get the default destination CUPS_GET_PRINTERS - Get a list of all printers CUPS_ADD_PRINTER - Add or modify a printer CUPS_DELETE_PRINTER - Delete a printer CUPS_GET_CLASSES - Get a list of all classes CUPS_ADD_CLASS - Add or modify a class CUPS_DELETE_CLASS - Delete a class CUPS_ACCEPT_JOBS - Accept jobs on a printer or class CUPS_REJECT_JOBS - Reject jobs on a printer or class CUPS_SET_DEFAULT - Set the default destination CUPS_GET_DEVICES - Get a list of all devices CUPS_GET_PPDS - Get a list of all PPDs CUPS_MOVE_JOB - Move a job to a new destination Status Codes Status codes are returned by all IPP requests. IPP_OK - Request completed with no errors IPP_OK_SUBST - Request completed but some attribute values were substituted IPP_OK_CONFLICT - Request completed but some attributes conflicted IPP_BAD_REQUEST - The request was bad IPP_FORBIDDEN - You don't have access to the resource IPP_NOT_AUTHENTICATED - You are not authenticated for the resource IPP_NOT_AUTHORIZED - You not authorized to access the resource IPP_NOT_POSSIBLE - The requested operation cannot be completed IPP_TIMEOUT - A timeout occurred IPP_NOT_FOUND - The resource was not found IPP_GONE - The resource has gone away IPP_REQUEST_ENTITY - The request was too large IPP_REQUEST_VALUE - The request contained a value that was unknown to the server IPP_DOCUMENT_FORMAT - The document format is not supported by the server IPP_ATTRIBUTES - Required attributes are missing IPP_URI_SCHEME - The URI scheme is not supported IPP_CHARSET - The charset is not supported IPP_CONFLICT - One or more attributes conflict IPP_COMPRESSION_NOT_SUPPORTED - The specified compression is not supported IPP_COMPRESSION_ERROR - The compressed data contained an error IPP_DOCUMENT_FORMAT_ERROR - The document data contained an error in it IPP_DOCUMENT_ACCESS_ERROR - The remote document could not be accessed IPP_INTERNAL_ERROR - The server encountered an internal error IPP_OPERATION_NOT_SUPPORTED - The requested operation is not supported IPP_SERVICE_UNAVAILABLE - The requested service is unavailable IPP_VERSION_NOT_SUPPORTED - The IPP request version is not supported IPP_DEVICE_ERROR - The output device encountered an error IPP_TEMPORARY_ERROR - A temporary error occurred IPP_NOT_ACCEPTING - The destination is not accepting jobs IPP_PRINTER_BUSY - The destination is busy IPP_ERROR_JOB_CANCELLED - The requested job has been cancelled IPP_MULTIPLE_JOBS_NOT_SUPPORTED - The server does not support multiple jobs PPD Constants PPD Format Version The PPD_VERSION constant defines a floating point number representing the newest format version that is supported by CUPS, currently 4.3. PPD User-Interface Types Each printer option has a type associated with it: PPD_UI_BOOLEAN - The user can turn this option on or off PPD_UI_PICKONE - The user can choose one option value to use. PPD_UI_PICKMANY - The user can choose zero or more option values. PPD Sections Some options must be output before others, or in different sections of the output document. The ppd_section_t enumeration defines which section the option must be output in: PPD_ORDER_ANY - The option can be output in any of the document, page, or prolog sections of the document PPD_ORDER_DOCUMENT - The option must be output in the DocumentSetup section of the document PPD_ORDER_EXIT - The option must be output before the document PPD_ORDER_JCL - The option must be output in the job control section of the document PPD_ORDER_PAGE - The option must be output in the PageSetup section of the document PPD_ORDER_PROLOG - The option must be output in the Prolog section of the document PPD Colorspaces Each printer has a default colorspace: PPD_CS_CMYK - The printer uses CMYK colors by default PPD_CS_CMY - The printer uses CMY colors by default PPD_CS_GRAY - The printer uses grayscale by default PPD_CS_RGB - The printer uses RGB colors by default PPD_CS_RGBK - The printer uses RGBK colors by default PPD_CS_N - The printer uses a DeviceN colorspace by default Raster Constants Raster Sync Words The CUPS_RASTER_SYNC and CUPS_RASTER_REVSYNC constants define the standard sync words at the beginning of each CUPS raster file. Raster Stream Modes The CUPS_RASTER_READ and CUPS_RASTER_WRITE constants are used with the cupsRasterOpen() function to specify a stream for reading or writing. Raster Boolean Constants The CUPS_FALSE and CUPS_TRUE constants represent boolean values in the page header. Raster Jog Values The cups_jog_t enumeration defines constants for the Jog page device dictionary variable: CUPS_JOG_NONE - Do no jogging CUPS_JOG_FILE - Jog pages after each file CUPS_JOG_JOB - Jog pages after each job CUPS_JOG_SET - Jog pages after each set of jobs Raster Orientation Values The cups_orient_t enumeration defines constants for the Orientation page device dictionary variable: CUPS_ORIENT_0 - Portrait orientation CUPS_ORIENT_90 - Landscape orientation CUPS_ORIENT_180 - Reverse-portrait orientation CUPS_ORIENT_270 - Reverse-landscape orientation Raster CutMedia Values The cups_cut_t enumeration defines constants for the CutMedia page device dictionary variable: CUPS_CUT_NONE - Do no jogging CUPS_CUT_FILE - Cut pages after each file CUPS_CUT_JOB - Cut pages after each job CUPS_CUT_SET - Cut pages after each set of jobs CUPS_CUT_PAGE - Cut each page Raster AdvanceMedia Values The cups_advance_t enumeration defines constants for the AdvanceMedia page device dictionary variable: CUPS_ADVANCE_NONE - Do no jogging CUPS_ADVANCE_FILE - Advance media after each file CUPS_ADVANCE_JOB - Advance media after each job CUPS_ADVANCE_SET - Advance media after each set of jobs CUPS_ADVANCE_PAGE - Advance media for each page Raster LeadingEdge Values The cups_edge_t enumeration defines constants for the LeadingEdge page device dictionary variable: CUPS_EDGE_TOP - The top of the media is the leading edge CUPS_EDGE_RIGHT - The right of the media is the leading edge CUPS_EDGE_BOTTOM - The bottom of the media is the leading edge CUPS_EDGE_LEFT - The left of the media is the leading edge Raster Color Order Values The cups_order_t enumeration defines the possible color value orderings: CUPS_ORDER_CHUNKED - CMYK CMYK CMYK CUPS_ORDER_BANDED - CCC MMM YYY KKK CUPS_ORDER_PLANAR - CCC ... MMM ... YYY ... KKK ... Raster Colorspace Values The cups_cspace_t enumeration defines the possible colorspaces: CUPS_CSPACE_W - White (luminance) CUPS_CSPACE_RGB - Red, green, blue CUPS_CSPACE_RGBA - Red, green, blue, alpha CUPS_CSPACE_K - Black CUPS_CSPACE_CMY - Cyan, magenta, yellow CUPS_CSPACE_YMC - Yellow, magenta, cyan CUPS_CSPACE_CMYK - Cyan, magenta, yellow, black CUPS_CSPACE_YMCK - Yellow, magenta, cyan, black CUPS_CSPACE_KCMY - Black, cyan, magenta, yellow CUPS_CSPACE_KCMYcm - Black, cyan, magenta, yellow, light cyan, light magenta CUPS_CSPACE_GMCK - Metallic yellow (gold), metallic magenta, metallic cyan, black CUPS_CSPACE_GMCS - Metallic yellow (gold), metallic magenta, metallic cyan, metallic grey (silver) CUPS_CSPACE_WHITE - White pigment (black as white pigment) CUPS_CSPACE_GOLD - Gold foil (black as gold foil) CUPS_CSPACE_SILVER - Silver foil (black as silver foil) C - Structures This appendix describes all of the structures that are defined by the CUPS API. CUPS Structures CUPS Destinations The CUPS destination structure (cups_dest_t) contains information on a specific destination or instance: Member Type Description name char * The name of the printer or class. instance char * The instance of the printer or class; NULL for the primary instance. is_default int 1 if the destination is set as the default, 0 otherwise. num_options int The number of options associated with this destination. options cups_option_t * The options associated with this destination. CUPS Jobs The CUPS job structure (cups_job_t) contains information on a specific job: Member Type Description id int The job ID for this job. dest char * The destination for this job (printer or class name). title char * The job-name for this job (title). user char * The job-originating-user-name for this job (username). format char * The document-format for this job (MIME type string). state ipp_jstate The current state of the job. size int The size of this job in kilobytes. priority int The priority of this job from 1 to 100 (50 is normal). completed_time time_t The time the job was completed, or 0 if not yet completed. creation_time time_t The time the job was queued. processing_time time_t The time the job started printing. CUPS Messages The CUPS messages structure (cups_lang_t) contains the character set, locale name, and messages array: Member Type Description next cups_lang_t * Pointer to the next messages structure in memory. used int The number of active users of this messages structure. encoding cups_encoding_t The character encoding of the message strings. language char [16] The language/locale name. messages char *[] The array of message strings. CUPS Options The CUPS option structure (cups_option_t) contains the option name and string value: Member Type Description name char * The name of the option. value char * The string value of the option. Networking Structures HTTP State The HTTP state structure (http_t) contains the current state of a HTTP request or response: Member Type Description fd int The socket for the HTTP connection. blocking int 1 if the HTTP functions should block, 0 if not. error int The last OS error that occurred on the socket. activity time_t The last time the HTTP connection was used. state http_state_t The current HTTP request/response state. status int The last HTTP status seen. version http_version_t The HTTP protocol version in use. keep_alive http_keep_alive_t Whether or not to use Keep-Alive hostaddr struct sockaddr_in The IPv4 address of the HTTP server. hostname char [] The hostname of the HTTP server. fields char [][] The string values of all HTTP request/response fields. data char * Current byte in data buffer. data_encoding http_encoding_t The transfer encoding for the request/response. data_remaining int The number of bytes remaining in the current request, response, or chunk. used int The number of bytes that are used in the buffer. buffer char [] The read/write buffer. auth_type int The type of authentication in use. md5_state md5_state_t The current MD5 digest state. nonce char [] The nonce value for Digest authentication. nonce_count int The nonce count value. tls void * A pointer to private encryption data. encryption http_encryption_t The current encryption mode. IPP State The IPP state structure (ipp_t) contains the current state of a IPP request or response: Member Type Description Raster Structures Raster Page Header The raster page header (cups_raster_header_t) consists of the PostScript page device dictionary for the page: Member Type Description MediaClass char[64] The media class name MediaColor char[64] The media color name MediaType char[64] The media type name OutputType char[64] The output type name AdvanceDistance unsigned The distance to advance the media in points AdvanceMedia cups_adv_t When to advance the media Collate cups_bool_t Whether or not to produce collated copies CutMedia cups_cut_t When to cut the media Duplex cups_bool_t Whether or not to print on both sides of the paper HWResolution unsigned[2] The resolution of the page image in pixels per inch; the HWResolution[0] represents the horizontal resolution and HWResolution[1] represents the vertical resolution ImagingBoundingBox unsigned[4] 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) InsertSheet cups_bool_t Whether or not to insert a sheet before this page Jog cups_jog_t When to jog copies of the page LeadingEdge cups_edge_t The leading edge of the page Margins unsigned[2] The lower-lefthand margin of the page in points ManualFeed cups_bool_t Whether or not to manually feed the page MediaPosition unsigned The input slot number to use MediaWeight unsigned The weight of the output media in grams/m2 MirrorPrint cups_bool_t Whether or not to mirror the print NegativePrint cups_bool_t Whether or not to invert the print NumCopies unsigned The number of copies to produce Orientation cups_orient_t The orientation of the page image OutputFaceUp cups_bool_t Whether or not to output the page face up PageSize unsigned[2] The width and height of the page in points Separations cups_bool_t Whether or not to output separations TraySwitch cups_bool_t Whether or not to automatically switch trays for the requested media size/type Tumble cups_bool_t Whether or not to rotate the back side of the page cupsWidth unsigned The width of the page image in pixels cupsHeight unsigned The height of the page image in pixels cupsMediaType unsigned The device-specific media type code cupsBitsPerColor unsigned The number of bits per color cupsBitsPerPixel unsigned The number of bits per pixel cupsBytesPerLine unsigned The number of bytes per line of image data cupsColorOrder cups_order_t The order of color values cupsColorSpace cups_cspace_t The type of color values cupsCompression unsigned The device-specific compression code cupsRowCount unsigned The device-specific row count cupsRowFeed unsigned The device-specific row feed cupsRowStep unsigned The device-specific row step D - Functions This appendix provides a reference for all of the CUPS API functions. cupsAddOption() Usage int cupsAddOption(const char *name, const char *value, int num_options, cups_option_t **options); Arguments Argument Description name The name of the option. value The value of the option. num_options Number of options currently in the array. options Pointer to the options array. Returns The new number of options. Description cupsAddOption() adds an option to the specified array. Example #include <cups.h> ... /* Declare the options array */ int num_options; cups_option_t *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); See Also cupsFreeOptions(), cupsGetOption(), cupsParseOptions() cupsCancelJob() Usage int cupsCancelJob(const char *dest, int job); Arguments Argument Description dest Printer or class name job Job ID Returns 1 on success, 0 on failure. On failure the error can be found by calling cupsLastError(). Description cupsCancelJob() cancels the specifies job. Example #include <cups.h> cupsCancelJob("LaserJet", 1); See Also cupsLastError(), cupsPrintFile() cupsDoFileRequest() Usage ipp_t * cupsDoFileRequest(http_t *http, ipp_t *request, const char *resource, const char *filename); Arguments Argument Description http HTTP connection to server. request IPP request data. resource HTTP resource name for POST. filename File to send with POST request (NULL pointer if none.) Returns IPP response data or NULL if the request fails. On failure the error can be found by calling cupsLastError(). Description cupsDoFileRequest() 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. Example #include <cups.h> http_t *http; cups_lang_t *language; ipp_t *request; ipp_t *response; ... /* Get the default language */ language = cupsLangDefault(); /* Create a new IPP request */ request = ippNew(); request->request.op.operation_id = IPP_PRINT_FILE; request->request.op.request_id = 1; /* Add required attributes */ ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET, "attributes-charset", NULL, cupsLangEncoding(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, cupsUser()); /* Do the request... */ response = cupsDoFileRequest(http, request, "/resource", "filename.txt"); See Also cupsLangDefault(), cupsLangEncoding(), cupsUser(), httpConnect(), ippAddString(), ippNew() cupsDoRequest() Usage ipp_t * cupsDoRequest(http_t *http, ipp_t *request, const char *resource); Arguments Argument Description http HTTP connection to server. request IPP request data. resource HTTP resource name for POST. Returns IPP response data or NULL if the request fails. On failure the error can be found by calling cupsLastError(). Description cupsDoRequest() 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. Example #include <cups.h> http_t *http; cups_lang_t *language; ipp_t *request; ipp_t *response; ... /* Get the default language */ language = cupsLangDefault(); /* Create a new IPP request */ request = ippNew(); request->request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES; request->request.op.request_id = 1; /* Add required attributes */ ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET, "attributes-charset", NULL, cupsLangEncoding(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"); See Also cupsLangDefault(), cupsLangEncoding(), cupsUser(), httpConnect(), ippAddString(), ippNew() cupsFreeOptions() Usage void cupsFreeOptions(int num_options, cups_option_t *options); Arguments Argument Description num_options Number of options in array. options Pointer to options array. Description cupsFreeOptions() frees all memory associated with the option array specified. Example #include <cups/cups.h> int num_options; cups_option_t *options; ... cupsFreeOptions(num_options, options); See Also cupsAddOption(), cupsGetOption(), cupsMarkOptions(), cupsParseOptions() cupsGetClasses() Usage int cupsGetClasses(char ***classes); Arguments Argument Description classes Pointer to character pointer array. Returns The number of printer classes available. Description cupsGetClasses() gets a list of the available printer classes. The returned array should be freed using the free() when it is no longer needed. Example #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); } See Also cupsGetDefault(), cupsGetPrinters() cupsGetDefault() Usage const char * cupsGetDefault(void); Returns A pointer to the default destination. Description cupsGetDefault() 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. Example #include <cups/cups.h> printf("The default destination is %s\n", cupsGetDefault()); See Also cupsGetClasses(), cupsGetPrinters() cupsGetOption() Usage const char * cupsGetOption(const char *name, int num_options, cups_option_t *options); Arguments Argument Description name The name of the option. num_options The number of options in the array. options The options array. Returns A pointer to the option values or NULL if the option is not defined. Description cupsGetOption() returns the first occurrence of the named option. If the option is not included in the options array then a NULL pointer is returned. #include <cups/cups.h> int num_options; cups_option_t *options; const char *media; ... media = cupsGetOption("media", num_options, options); See Also cupsAddOption(), cupsFreeOptions(), cupsMarkOptions(), cupsParseOptions() cupsGetPassword() Usage const char * cupsGetPassword(const char *prompt); Arguments Argument Description prompt The prompt to display to the user. Returns A pointer to the password that was entered or NULL if no password was entered. Description cupsGetPassword() displays the prompt string and asks the user for a password. The password text is not echoed to the user. Example #include <cups/cups.h> char *password; ... password = cupsGetPassword("Please enter a password:"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser() cupsGetPPD() Usage const char * cupsGetPPD(const char *printer); Arguments Argument Description printer The name of the printer. Returns The name of a temporary file containing the PPD file or NULL if the printer cannot be located or does not have a PPD file. Description cupsGetPPD() gets a copy of the PPD file for the named printer. The printer name can be of the form "printer" or "printer@hostname". 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 cupsGetPPD(). Example #include <cups/cups.h> char *ppd; ... ppd = cupsGetPPD("printer@hostname"); ... unlink(ppd); cupsGetPrinters() Usage int cupsGetPrinters(char ***printers); Arguments Argument Description printers Pointer to character pointer array. Returns The number of printer printers available. Description cupsGetPrinters() gets a list of the available printers. The returned array should be freed using the free() when it is no longer needed. Example #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); } See Also cupsGetClasses(), cupsGetDefault() cupsLangDefault() Usage const char * cupsLangDefault(void); Returns A pointer to the default language structure. Description cupsLangDefault() returns a language structure for the default language. The default language is defined by the LANG environment variable. If the specified language cannot be located then the POSIX (English) locale is used. Call cupsLangFree() to free any memory associated with the language structure when you are done. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangDefault(); ... cupsLangFree(language); See Also cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangEncoding() Usage char * cupsLangEncoding(cups_lang_t *language); Arguments Argument Description language The language structure. Returns A pointer to the encoding string. Description cupsLangEncoding() returns the language encoding used for the specified language, e.g. "iso-8859-1", "utf-8", etc. Example #include <cups/language.h> cups_lang_t *language; char *encoding; ... language = cupsLangDefault(); encoding = cupsLangEncoding(language); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFlush() Usage void cupsLangFlush(void); Description cupsLangFlush() frees all language structures that have been allocated. Example #include <cups/language.h> ... cupsLangFlush(); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFree() Usage void cupsLangFree(cups_lang_t *language); Arguments Argument Description language The language structure to free. Description cupsLangFree() frees the specified language structure. Example #include <cups/language.h> cups_lang_t *language; ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangGet(), cupsLangString() cupsLangGet() Usage cups_lang_t * cupsLangGet(const char *name); Arguments Argument Description name The name of the locale. Returns A pointer to a language structure. Description cupsLangGet() returns a language structure for the specified locale. If the locale is not defined then the POSIX (English) locale is substituted. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangGet("fr"); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangString() cupsLangString() Usage char * cupsLangString(cups_lang_t *language, int message); Arguments Argument Description language The language to query. message The message number. Returns A pointer to the message string or NULL if the message is not defined. Description cupsLangString() returns a pointer to the specified message string in the specified language. Example #include <cups/language.h> cups_lang_t *language; char *s; ... language = cupsLangGet("fr"); s = cupsLangString(language, CUPS_MSG_YES); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet() cupsLastError() Usage ipp_status_t cupsLastError(void); Returns An enumeration containing the last IPP error. Description cupsLastError() returns the last IPP error that occurred. If no error occurred then it will return IPP_OK or IPP_OK_CONFLICT. Example #include <cups/cups.h> ipp_status_t status; ... status = cupsLastError(); See Also cupsCancelJob(), cupsPrintFile() cupsMarkOptions() Usage int cupsMarkOptions(ppd_file_t *ppd, int num_options, cups_option_t *options); Arguments Argument Description ppd The PPD file to mark. num_options The number of options in the options array. options A pointer to the options array. Returns The number of conflicts found. Description cupsMarkOptions() marks options in the PPD file. It also handles mapping of IPP option names and values to PPD option names. Example #include <cups/cups.h> int num_options; cups_option_t *options; ppd_file_t *ppd; ... cupsMarkOptions(ppd, num_options, options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsParseOptions() cupsParseOptions() Usage int cupsParseOptions(const char *arg, int num_options, cups_option_t **options); Arguments Argument Description arg The string containing one or more options. num_options The number of options in the options array. options A pointer to the options array pointer. Returns The new number of options in the array. Description cupsParseOptions() 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. Example #include <cups/cups.h> int num_options; cups_option_t *options; ... num_options = 0; options = (cups_option_t *)0; num_options = cupsParseOptions(argv[5], num_options, &options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsMarkOptions() cupsPrintFile() Usage int cupsPrintFile(const char *printer, const char *filename, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. filename The file to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFile() 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 cupsLastError(). Example #include <cups/cups.h> int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFiles() cupsPrintFiles() Usage int cupsPrintFiles(const char *printer, int num_files, const char **files, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. num_files The number of files to print. files The files to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFiles() 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 cupsLastError(). Example #include <cups/cups.h> int num_files; const char *files[100]; int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFiles("printer@hostname", num_files, files, "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFile() cupsRasterClose() Usage void cupsRasterClose(cups_raster_t *ras); Arguments Argument Description ras The raster stream to close. Description cupsRasterClose() closes the specified raster stream. Example #include <cups/raster.h> cups_raster_t *ras; ... cupsRasterClose(ras); See Also cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterOpen() Usage cups_raster_t * cupsRasterOpen(int fd, cups_mode_t mode); Arguments Argument Description fd The file descriptor to use. mode The mode to use; CUPS_RASTER_READ or CUPS_RASTER_WRITE. Returns A pointer to a raster stream or NULL if there was an error. Description cupsRasterOpen() opens a raster stream for reading or writing. Example #include <cups/raster.h> cups_raster_t *ras; ... ras = cupsRasterOpen(0, CUPS_RASTER_READ); See Also cupsRasterClose(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadHeader() Usage unsigned cupsRasterReadHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to read from. header A pointer to a page header structure to read into. Returns 1 on success, 0 on EOF or error. Description cupsRasterReadHeader() reads a page header from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadPixels() Usage unsigned cupsRasterReadPixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to read from. pixels The pointer to a pixel buffer. length The number of bytes of pixel data to read. Returns The number of bytes read or 0 on EOF or error. Description cupsRasterReadPixels() reads pixel data from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterWriteHeader() Usage unsigned cupsRasterWriteHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to write to. header A pointer to the page header to write. Returns 1 on success, 0 on error. Description cupsRasterWriteHeader() writes the specified page header to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWritePixels() cupsRasterWritePixels() Usage unsigned cupsRasterWritePixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to write to. pixels The pixel data to write. length The number of bytes to write. Returns The number of bytes written. Description cupsRasterWritePixels() writes the specified pixel data to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader() cupsServer() Usage const char * cupsServer(void); Returns A pointer to the default server name. Description cupsServer() 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 cupsServer() The default server is determined from the following locations: The CUPS_SERVER environment variable, The ServerName directive in the client.conf file, The default host, "localhost". Example #include <cups/cups.h> const char *server; server = cupsServer(); See Also cupsGetPassword(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetPasswordCB() Usage void cupsSetPasswordCB(const char *(*cb)(const char *prompt)); Arguments Argument Description cb The password callback function. Description cupsSetPasswordCB() 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 NULL if the user did not enter a password string or a pointer to the password string otherwise. Example #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:"); See Also cupsServer(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetServer() Usage void cupsSetServer(const char *server); Arguments Argument Description server The default server to use. Description cupsSetServer() sets the default server to use for the CUPS API. If the server argument is NULL, the default server is used. Example #include <cups/cups.h> cupsSetServer("foo.bar.com"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetUser(), cupsUser() cupsSetUser() Usage void cupsSetUser(const char *user); Arguments Argument Description user The user name string to use. Description cupsSetUser() sets the default user name for authentication. If the user argument is NULL then the current login user is used. Example #include <cups/cups.h> ... cupsSetUser("root"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsUser() cupsTempFile() Usage char * cupsTempFile(char *filename, int length); Arguments Argument Description filename The character string to hold the temporary filename. length The size of the filename string in bytes. Returns A pointer to filename. Description cupsTempFile() generates a temporary filename for the /var/tmp directory or the directory specified by the TMPDIR environment variable. Example #include <cups/cups.h> char filename[256]; cupsTempFile(filename, sizeof(filename)); cupsUser() Usage const char * cupsUser(void); Returns A pointer to the current username or NULL if the user ID is undefined. Description cupsUser() returns the name associated with the current user ID as reported by the getuid() system call. Example #include <cups/cups.h> const char *user; user = cupsUser(); See Also cupsGetPassword(), cupsServer() httpBlocking() Usage void httpBlocking(http_t *http, int blocking) Arguments Argument Description http The HTTP connection blocking 0 if the connection should be non-blocking, 1 if it should be blocking Description The httpBlocking() 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. Example #include <cups/http.h> http_t *http; http = httpConnect("server", port); httpBlocking(http, 0); See Also httpCheck(), httpConnect() httpCheck() Usage int httpCheck(http_t *http); Arguments Argument Description http The HTTP connection Returns 0 if there is no data pending, 1 otherwise. Description The httpCheck() function checks to see if there is any data pending on an HTTP connection. Example #include <cups/http.h> http_t *http; if (httpCheck(http)) { ... do something ... } See Also httpBlocking(), httpConnect(), httpGets(), httpRead() httpClearFields() Usage void httpClearFields(http_t *http) Arguments Argument Description http The HTTP connection Description The httpClearFields() function clears all HTTP request fields for the HTTP connection. Example #include <cups/http.h> http_t *http; httpClearFields(http); See Also httpConnect(), httpGetField(), httpSetField() httpClose() Usage void httpClose(http_t *http); Arguments Argument Description http The HTTP connection Description The httpClose() function closes an active HTTP connection. Example #include <cups/http.h> http_t *http; httpClose(http); See Also httpConnect() httpConnect() Usage http_t *httpConnect(const char *hostname, int port); Arguments Argument Description hostname The name or IP address of the server to connect to port The port number to use Returns A pointer to a HTTP connection structure or NULL if the connection could not be made. Description The httpConnect() function opens a HTTP connection to the specified server and port. Example #include <cups/http.h> http_t *http; http = httpConnect(cupsServer(), ippPort()); See Also httpClose(), httpGet(), httpGets(), httpPost(), httpRead(), httpWrite() httpDecode64() Usage char *httpDecode64(char *out, const char *in); Arguments Argument Description out The output string in The input string Returns A pointer to the decoded string. Description The httpDecode64() function decodes a base-64 encoded string to the original string. Example #include <cups/http.h> char encoded_string[255]; char original_string[255]; httpDecode64(original_string, encoded_string); See Also httpEncode64() httpDelete() Usage int httpDelete(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to delete Returns 0 on success, non-zero on failure. Description The httpDelete() function sends a HTTP DELETE request to the server. Example #include <cups/http.h> http_t *http; httpDelete(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpEncode64() Usage char *httpEncode64(char *out, const char *in); Arguments Argument Description out The output string in The input string Returns A pointer to the encoded string. Description The httpEncode64() function decodes a base-64 encoded string to the original string. Example #include <cups/http.h> char encoded_string[255]; char original_string[255]; httpEncode64(encoded_string, original_string); See Also httpDecode64() httpError() Usage int httpError(http_t *http); Arguments Argument Description http The HTTP connection Returns The last error that occurred or 0 if no error has occurred. Description The httpError() function returns the last error that occurred on the HTTP connection. Example #include <cups/http.h> http_t *http; if (httpError(http)) { ... show an error message ... } See Also httpConnect() httpFlush() Usage void httpFlush(http_t *http); Arguments Argument Description http The HTTP connection Description The httpFlush() function flushes any remaining data left from a GET or POST operation. Example #include <cups/http.h> http_t *http; httpFlush(http); See Also httpConnect(), httpGet() Usage int httpGet(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to get Returns 0 on success, non-zero on failure. Description The httpGet() function sends a HTTP GET request to the server. Example #include <cups/http.h> http_t *http; httpGet(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpGets() Usage char *httpGets(char *line, int length, http_t *http) Arguments Argument Description line The string to fill with a line from the HTTP connection length The maximum length of the string http The HTTP connection Returns A pointer to the string or NULL if no line could be retrieved. Description The httpGets() function is used to read a request line from the HTTP connection. It is not normally used by a client program. Example #include <cups/http.h> http_t *http; char line[1024]; if (httpGets(line, sizeof(line), http)) { ... process the line ... } See Also httpConnect(), httpUpdate() httpGetDateString() Usage const char *httpGetDateString(time_t time) Arguments Argument Description time The UNIX date/time value Returns A pointer to a static string containing the HTTP date/time string for the specified UNIX time value. Description The httpGetDateString() function generates a date/time string suitable for HTTP requests from a UNIX time value. Example #include <cups/http.h> puts(httpGetDateString(time(NULL))); See Also httpGetDateTime() httpGetDateTime() Usage time_t httpGetDateTime(const char *date) Arguments Argument Description date The HTTP date/time string Returns A UNIX time value. Description The httpGetDateTime() function converts a HTTP date/time string to a UNIX time value. Example #include <cups/http.h> printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT")); See Also httpGetDateString() httpGetField() Usage const char *httpGetField(http_t *http, http_field_t field); Arguments Argument Description http The HTTP connection field The HTTP field Returns A pointer to the field value string. Description The httpGetField() function returns the current value for the specified HTTP field. Example #include <cups/http.h> http_t *http; httpGet(http, "/some/uri"); while (httpUpdate(http) == HTTP_CONTINUE); puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE)); See Also httpConnect(), httpSetField() httpHead() Usage int httpHead(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to head Returns 0 on success, non-zero on failure. Description The httpHead() function sends a HTTP HEAD request to the server. Example #include <cups/http.h> http_t *http; httpHead(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpInitialize() Usage void httpInitialize(void); Description The httpInitialize() function initializes the networking code as needed by the underlying platform. It is called automatically by the httpConnect() function. Example #include <cups/http.h> httpInitialize(); See Also httpConnect() httpOptions() Usage int httpOptions(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to check for options Returns 0 on success, non-zero on failure. Description The httpOptions() function sends a HTTP OPTIONS request to the server. Example #include <cups/http.h> http_t *http; httpOptions(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpPost() Usage int httpPost(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to post to Returns 0 on success, non-zero on failure. Description The httpPost() function sends a HTTP POST request to the server. Example #include <cups/http.h> http_t *http; httpPost(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpPrintf() Usage int httpPrintf(http_t *http, const char *format, ...); Arguments Argument Description http The HTTP connection format A printf-style format string Returns The number of bytes written. Description The httpPrintf() function sends a formatted string to the HTTP connection. It is normally only used by the CUPS API and scheduler. Example #include <cups/http.h> http_t *http; httpPrintf(http, "GET / HTTP/1.1 \r\n"); See Also httpConnect() httpPut() Usage int httpPut(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to put Returns 0 on success, non-zero on failure. Description The httpPut() function sends a HTTP PUT request to the server. Example #include <cups/http.h> http_t *http; httpDelete(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpRead() Usage int httpRead(http_t *http, char *buffer, int length); Arguments Argument Description http The HTTP connection buffer The buffer to read into length The number of bytes to read Returns The number of bytes read or -1 on error. Description The httpRead() function reads data from the HTTP connection, possibly the result of a GET or POST request. Example #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); } See Also httpConnect(), httpWrite() httpReconnect() Usage int httpReconnect(http_t *http); Arguments Argument Description http The HTTP connection Returns 0 on success, non-zero on failure. Description The httpReconnect() function reconnects to the HTTP server. This is usually done automatically if the HTTP functions detect that the server connection has terminated. Example #include <cups/http.h> http_t *http; httpReconnect(http); See Also httpConnect() httpSeparate() Usage void httpSeparate(const char *uri, char *method, char *username, char *host, int *port, char *resource); Arguments Argument Description uri The URI to separate method The method (scheme) of the URI username The username (and password) portion of the URI, if any host The hostname portion of the URI, if any port The port number for the URI, either as specified or as default for the method/scheme resource The resource string, usually a filename on the server Description The httpSeparate() function separates the specified URI into its component parts. The method, username, hostname, and resource strings should be at least HTTP_MAX_URI characters long to avoid potential buffer overflow problems. Example 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); See Also httpConnect() httpSetField() Usage void httpSetField(http_t *http, http_field_t field, const char *value); Arguments Argument Description http The HTTP connection field The HTTP field value The string value for the field Description The httpSetField() function sets the current value for the specified HTTP field. Example #include <cups/http.h> http_t *http; httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325")); httpGet(http, "/some/uri"); while (httpUpdate(http) == HTTP_CONTINUE); See Also httpConnect(), httpGetField() httpTrace() Usage int httpTrace(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to trace Returns 0 on success, non-zero on failure. Description The httpTrace() function sends a HTTP TRACE request to the server. Example #include <cups/http.h> http_t *http; httpTrace(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpUpdate() Usage http_status_t httpUpdate(http_t *http); Arguments Argument Description http The HTTP connection Returns The HTTP status of the current request. Description The httpUpdate() 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. Since proxies and the current blocking mode can cause the request to take longer, programs should continue calling httpUpdate() until the return status is not the constant value HTTP_CONTINUE. Example #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); See Also httpConnect(), httpDelete(), httpGet(), httpHead(), httpOptions(), httpPost(), httpPut(), httpTrace() httpWrite() Usage int httpWrite(http_t *http, char *buffer, int length); Arguments Argument Description http The HTTP connection buffer The buffer to read into length The number of bytes to read Returns The number of bytes read or -1 on error. Description The httpWrite() function reads data from the HTTP connection, possibly the result of a GET or POST request. Example #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); } See Also httpConnect(), httpRead() ippAddBoolean() Usage ipp_attribute_t *ippAddBoolean(ipp_t *ipp, ipp_tag_t group, const char *name, char value); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute value The boolean value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddBoolean() function adds a single boolean attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1); See Also ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddBooleans() Usage ipp_attribute_t *ippAddBooleans(ipp_t *ipp, ipp_tag_t group, const char *name, int num_values, const char *values); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute num_values The number of values values The boolean values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddBooleans() function adds one or more boolean attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values false values is created. Example #include <cups/ipp.h> ipp_t *ipp; char values[10]; ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values); See Also ippAddBoolean(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddDate() Usage ipp_attribute_t *ippAddDate(ipp_t *ipp, ipp_tag_t group, const char *name, ipp_uchar_t *value); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute value The date value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddDate() function adds a single date-time attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute", ippTimeToDate(time(NULL)); See Also ippAddBoolean(), ippAddBooleans(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings(), ippTimeToDate() ippAddInteger() Usage ipp_attribute_t *ippAddInteger(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, int value); Arguments Argument Description ipp The IPP request group The IPP group tag The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM) name The name of attribute value The integer value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddInteger() function adds a single integer attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddIntegers() Usage ipp_attribute_t *ippAddIntegers(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, int num_values, const int *values); Arguments Argument Description ipp The IPP request group The IPP group tag The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM) name The name of attribute num_values The number of values values The integer values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddIntegers() function adds one or more integer attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0 values is created. Example #include <cups/ipp.h> ipp_t *ipp; int values[100]; ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddRange() Usage ipp_attribute_t *ippAddRange(ipp_t *ipp, ipp_tag_t group, const char *name, int low, int high); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute low The lower value high The higher value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddRange() function adds a single range attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddRanges() Usage ipp_attribute_t *ippAddRanges(ipp_t *ipp, ipp_tag_t group, const char *name, int num_values, const int *lows, const int *highs); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute num_values The number of range values lows The lower values highs The higher values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddRanges() function adds one or more range attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0,0 ranges is created. Example #include <cups/ipp.h> ipp_t *ipp; int lows[2]; int highs[2]; ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddResolution() Usage ipp_attribute_t *ippAddResolution(ipp_t *ipp, ipp_tag_t group, const char *name, int xres, int yres, ipp_res_t units); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute xres The horizontal resolution yres The vertical resolution units The resolution units Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddResolution() function adds a single resolution attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution", 720, 720, IPP_RES_PER_INCH); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddResolutions() Usage 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); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute num_values The number of resolution values xres The horizontal resolutions yres The vertical resolutions units The resolution units Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddResolutions() function adds one or more resolution attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0,0 resolutions is created. Example #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); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddSeparator() Usage ipp_attribute_t *ippAddSeparator(ipp_t *ipp); Arguments Argument Description ipp The IPP request Returns A pointer to the new separator or NULL if the separator could not be created. Description The ippAddSeparator() function adds a group separator to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddSeparator(ipp); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddString(), ippAddStrings() ippAddString() Usage ipp_attribute_t *ippAddString(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, const char *charset, const char *value); Arguments Argument Description ipp The IPP request group The IPP group tag The type of string value name The name of attribute charset The character set for the string value The string value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddString() function adds a single string attribute value to the specified IPP request. For IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the charset value is provided with the string to identify the string encoding used. Otherwise the charset value is ignored. Example #include <cups/ipp.h> ipp_t *ipp; ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name", NULL, "abc123"); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddStrings() ippAddStrings() Usage 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); Arguments Argument Description ipp The IPP request group The IPP group tag The type of string value name The name of attribute num_values The number of strings charset The character set for the strings values The string values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddStrings() function adds one or more string attribute values to the specified IPP request. For IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the charset value is provided with the strings to identify the string encoding used. Otherwise the charset value is ignored. If the values pointer is NULL then an array of num_values NULL strings is created. Example #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); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString() ippDateToTime() Usage time_t ippDateToTime(const ipp_uchar_t date[11]); Arguments Argument Description date The IPP date-time value Returns A UNIX time value. Description The ippDateToTime() function converts an IPP date-time value to a UNIX time value. Example #include <cups/ipp.h> ipp_uchar_t date[11]; printf("UNIX time is %d\n", ippDateToTime(date)); See Also ippTimeToDate() ippDelete() Usage void ippDelete(ipp_t *ipp); Arguments Argument Description ipp The IPP request or response Description The ippDelete() function deletes all memory used by an IPP request or response. Example #include <cups/ipp.h> ipp_t *ipp; ippDelete(ipp); See Also ippNew() ippFindAttribute() Usage ipp_attribute_t *ippFindAttribute(ipp_t *ipp, const char *name, ipp_tag_t tag); Arguments Argument Description ipp The IPP request or response name The name of the attribute tag The required value tag for the attribute or IPP_TAG_ZERO for any type of value. Returns A pointer to the first occurrence of the requested attribute, or NULL if it was not found. Description ippFindAttribute() finds the first occurrence of the named attribute. The tag parameter restricts the search to a specific value type - use IPP_TAG_ZERO to find any value with the name. The value tags IPP_TAG_NAME and IPP_TAG_TEXT match the name/text values with or without the language code. Example ipp_attribute_t *attr; attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT); See Also cupsDoFileRequest(), cupsDoRequest(), ippDelete(), ippNew() ippLength() Usage int ippLength(ipp_t *ipp); Arguments Argument Description ipp The IPP request or response Returns The total encoded length of the IPP request or response in bytes. Description ippLength() returns the length of the IPP request or response in bytes. Example printf("The length of the response is %d bytes.\n", ippLength(response)); See Also ippDelete(), ippNew() ippNew() Usage ipp_t *ippNew(void); Returns A pointer to a new IPP request or response. Description The ippNew() function creates a new IPP request or response. Example #include <cups/ipp.h> ipp_t *ipp; ipp = ippNew(); See Also ippDelete() ippPort() Usage int ippPort(void); Returns The default TCP/IP port number for IPP requests. Description The ippPort() function returns the default IPP port number for requests. Example #include <cups/http.h> #include <cups/ipp.h> http_t *http; http = httpConnect(cupsServer(), ippPort()); See Also cupsServer(), ippSetPort() ippRead() Usage ipp_state_t ippRead(http_t *http, ipp_t *ipp); Arguments Argument Description http The HTTP connection ipp The IPP request or response Returns The current read state. Description The ippRead() function reads IPP attributes from the specified HTTP connection. Programs should continue calling ippRead() until IPP_ERROR or IPP_DATA is returned. Example #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() ... } See Also ippWrite() ippSetPort() Usage void ippSetPort(int port); Arguments Argument Description port The port number to use Description The ippSetPort() function sets the default IPP port number for requests. Example #include <cups/http.h> #include <cups/ipp.h> ... ippSetPort(8631); See Also ippPort() ippTimeToDate() Usage ipp_uchar_t *ippTimeToDate(time_t time); Arguments Argument Description time The UNIX time value Returns A static pointer to an IPP date-time value. Description The ippTimeToDate() function converts a UNIX time to an IPP date-time value. Example #include <cups/ipp.h> ipp_uchar_t *date; date = ippTimeToDate(time(NULL)); See Also ippDateToTime() ippWrite() Usage ipp_state_t ippWrite(http_t *http, ipp_t *ipp); Arguments Argument Description http The HTTP connection ipp The IPP request or response Returns The current write state. Description The ippWrite() function writes IPP attributes to the specified HTTP connection. Programs should continue calling ippWrite() until IPP_ERROR or IPP_DATA is returned. Example #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() ... } See Also ippRead() ppdClose() Usage void ppdClose(ppd_file_t *ppd); Arguments Argument Description ppd The PPD file Description The ppdClose() function frees all memory associated with the PPD file. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdClose(ppd); See Also ppdOpen(), ppdOpenFd(), ppdOpenFile() ppdConflicts() Usage int ppdConflicts(ppd_file_t *ppd); Arguments Argument Description ppd The PPD file Returns The number of option conflicts in the file. Description The ppdConflicts() function returns the number of conflicts with the currently selected options. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("%d conflicts\n", ppdConflicts(ppd)); See Also cupsMarkOptions(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdEmit() Usage int ppdEmit(ppd_file_t *ppd, FILE *file, ppd_section_t section); Arguments Argument Description ppd The PPD file file The file to write to section The option section to write Returns 0 on success, -1 on error. Description The ppdEmit() function sends printer-specific option commands to the specified file. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdEmit(ppd, stdout, PPD_ORDER_PAGE); See Also ppdEmitFd() ppdEmitFd() Usage int ppdEmitFd(ppd_file_t *ppd, int fd, ppd_section_t section); Arguments Argument Description ppd The PPD file fd The file descriptor to write to section The option section to write Returns 0 on success, -1 on error. Description The ppdEmitFd() function sends printer-specific option commands to the specified file descriptor. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdEmitFd(ppd, 1, PPD_ORDER_PAGE); See Also ppdEmit() ppdFindChoice() Usage ppd_choice_t *ppdFindChoice(ppd_option_t *option, const char *choice); Arguments Argument Description option A pointer to the option choice The name of the choice Returns A pointer to the choice data or NULL if the choice does not exist. Description The ppdFindChoice() function returns a pointer to the choice data for the specified option. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd_option_t *option; ppd_choice_t *choice; option = ppdFindOption(ppd, "PageSize"); choice = ppdFindChoice(option, "Letter"); See Also ppdFindMarkedChoice(), ppdFindOption() ppdFindMarkedChoice() Usage ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword); Arguments Argument Description ppd The PPD file keyword The name of the option Returns A pointer to the choice data or NULL if the choice does not exist or is not marked. Description The ppdFindMarkedChoice() function returns a pointer to the marked choice data for the specified option. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd_choice_t *choice; choice = ppdFindMarkedChoice(ppd, "PageSize"); See Also ppdFindChoice(), ppdFindOption() ppdFindOption() Usage ppd_option_t *ppdFindOption(ppd_file_t *ppd, const char *keyword); Arguments Argument Description ppd The PPD file keyword The name of the option Returns A pointer to the option data or NULL if the option does not exist. Description The ppdFindOption() function returns a pointer to the option data for the specified option. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd_option_t *option; option = ppdFindOption(ppd, "PageSize"); See Also ppdFindChoice(), ppdFindMarkedChoice() ppdIsMarked() Usage int ppdIsMarked(ppd_file_t *ppd, const char *keyword, char char *choice); Arguments Argument Description ppd The PPD file keyword The name of the option choice The name of the option choice Returns 1 if the choice is marked, 0 otherwise. Description The ppdIsMarked() function returns whether or not the specified option choice is marked. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("Letter size %s selected.\n", ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not"); See Also cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdMarkDefaults() Usage void ppdMarkDefaults(ppd_file_t *ppd); Arguments Argument Description ppd The PPD file Description The ppdMarkDefaults() function marks all of the default choices in the PPD file. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdMarkDefaults(ppd); See Also cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdMarkOption() Usage int ppdMarkOption(ppd_file_t *ppd, const char *keyword, const char *choice); Arguments Argument Description ppd The PPD file keyword The name of the option choice The name of the choice Returns The number of conflicts in the PPD file. Description The ppdMarkOption() function marks the specified option choice. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdMarkOption(ppd, "PageSize", "Letter"); See Also cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdOpen() Usage ppd_file_t *ppdOpen(FILE *file); Arguments Argument Description file The file to read from Returns A pointer to a PPD file structure or NULL if the PPD file could not be read. Description The ppdOpen() function reads a PPD file from the specified file into memory. Example #include <cups/ppd.h> ppd_file_t *ppd; FILE *file; file = fopen("filename.ppd", "rb"); ppd = ppdOpen(file); fclose(file); See Also ppdClose(), ppdOpenFd(), ppdOpenFile() ppdOpenFd() Usage ppd_file_t *ppdOpenFd(int fd); Arguments Argument Description fd The file descriptor to read from Returns A pointer to a PPD file structure or NULL if the PPD file could not be read. Description The ppdOpenFd() function reads a PPD file from the specified file descriptor into memory. Example #include <cups/ppd.h> ppd_file_t *ppd; int fd; fd = open("filename.ppd", O_RDONLY); ppd = ppdOpenFd(fd); close(fd); See Also ppdClose(), ppdOpen(), ppdOpenFile() ppdOpenFile() Usage ppd_file_t *ppdOpenFile(const char *filename); Arguments Argument Description filename The name of the file to read from Returns A pointer to a PPD file structure or NULL if the PPD file could not be read. Description The ppdOpenFile() function reads a PPD file from the named file into memory. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd = ppdOpenFile("filename.ppd"); See Also ppdClose(), ppdOpen(), ppdOpenFd() ppdPageLength() Usage float ppdPageLength(ppd_file_t *ppd, const char *name); Arguments Argument Description ppd The PPD file name The name of the page size Returns The length of the specified page size in points or 0 if the page size does not exist. Description The ppdPageLength() function returns the page length of the specified page size. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("Length = %.0f\n", ppdPageLength(ppd, "Letter")); See Also ppdPageLength(), ppdPageSize(), ppdPageWidth() ppdPageSize() Usage ppd_size_t *ppdPageSize(ppd_file_t *ppd, const char *name); Arguments Argument Description ppd The PPD file name The name of the page size Returns A pointer to the page size record of the specified page size in points or NULL if the page size does not exist. Description The ppdPageSize() function returns the page size record for the specified page size. Example #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); } See Also ppdPageLength(), ppdPageWidth() ppdPageWidth() Usage float ppdPageWidth(ppd_file_t *ppd, const char *name); Arguments Argument Description ppd The PPD file name The name of the page size Returns The width of the specified page size in points or 0 if the page size does not exist. Description The ppdPageWidth() function returns the page width of the specified page size. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter")); See Also ppdPageLength(), ppdPageSize()
This software programmers manual is organized into the following sections:
Various font and syntax conventions are used in this guide. Examples and their meanings and uses are explained below:
lpstat
lpstat(1)
This chapter describes the CUPS Application Programmers Interface ("API").
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.
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.
Programs that use the CUPS API library typically will include the <cups/cups.h> header file:
<cups/cups.h>
#include <cups/cups.h> ... jobid = cupsPrintFile("myprinter", "filename.ps", "title", num_options, options);
Use the -lcups compiler option when linking to the CUPS API library:
-lcups
cc -o program program.c -lcups ENTER
Additional options and libraries may be required depending on the operating system and the location of the CUPS API library.
GNU autoconf is a popular configuration tool used by many programs. Add the following lines to your configure.in file to check for the CUPS API library in your configuration script: 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) Printing Services The CUPS API library provides some basic printing services for applications that need to print files. Include Files The include file used by all of these functions is <cups/cups.h>: #include <cups/cups.h> Printing a File The CUPS API provides two functions for printing files. The first is cupsPrintFile which prints a single named file: #include <cups/cups.h> ... int jobid; ... jobid = cupsPrintFile("name", "filename", "title", 0, NULL); The name string is the name of the printer or class to print to. The filename string is the name of the file to print. The title string is the name of the print job, e.g. "Acme Word Document". The return value is a unique ID number for the print job or 0 if there was an error. Printing Multiple Files The second printing function is cupsPrintFiles: #include <cups/cups.h> ... int jobid; int num_files; const char *files[100]; ... jobid = cupsPrintFiles("name", num_files, files, "title", 0, NULL); Instead of passing a filename string as with cupsPrintFile(), you pass a file count (num_files) and filename pointer array (files) for each file that you want to print. As with cupsPrintFile(), the return value is a unique ID for the print job. Cancelling Jobs The cupsCancelJob() function cancels a queued print job: #include <cups/cups.h> ... int jobid; int status; ... status = cupsCancelJob("name", jobid); The name string specifies the destination and is used to determine the server to send the request to. The jobid value is the integer returned from a previous cupsPrintFile() or cupsPrintFiles() call. cupsCancelJob() returns 1 if the job was successfully cancelled and 0 if there was an error. Getting the Available Printers and Classes The cupsGetDests() function can be used to get a list of the available printers, classes, and instances that a user has defined: #include <cups/cups.h> ... int num_dests; cups_dest_t *dests; ... num_dests = cupsGetDests(&dests); Each destination is stored in a cups_dest_t 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: 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; 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 cupsGetDest() function: #include <cups/cups.h> ... int num_dests; cups_dest_t *dests; cups_dest_t *mydest; ... mydest = cupsGetDest("name", "instance", num_dests, dests); The name string is the printer or class name. You can pass a value of NULL to get the default destination. The instance string is the user-defined instance name. Pass NULL to select the default instance, e.g. "name" instead of "name/instance". Printing with Options All of the previous printing examples have passed 0 and NULL for the last two arguments to the cupsPrintFile() and cupsPrintFiles() functions. These last two arguments are the number of options and a pointer to the option array: 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); The cups_option_t structure holds each option and its value. These are converted as needed and passed to the CUPS server when printing a file. The simplest way of handling options is to use the num_options and options members of the cups_dest_t structure described earlier: #include <cups/cups.h> ... int jobid; int num_dests; cups_dest_t *dests; cups_dest_t *mydest; ... mydest = cupsGetDest("name", "instance", num_dests, dests); jobid = cupsPrintFile(mydest->name, "filename", "title", mydest->num_options, mydest->options); This effectively uses the options a user has previous selected without a lot of code. Setting Printer Options Options can also be set by your program using the cupsAddOption() function: #include <cups/cups.h> ... int num_options; cups_option_t *options; ... num_options = 0; options = NULL; ... num_options = cupsAddOption("name", "value", num_options, &options); num_options = cupsAddOption("name", "value", num_options, &options); num_options = cupsAddOption("name", "value", num_options, &options); num_options = cupsAddOption("name", "value", num_options, &options); The name string is the name of the option, and the value string is the value for that option. Each call to cupsAddOption() 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 cupsAddOptions() 20 times will result in 20 options. Call cupsFreeOptions once you are done using the options: #include <cups/cups.h> ... int num_options; cups_option_t *options; ... cupsFreeOptions(num_options, options); Getting Errors If any of the CUPS API printing functions returns an error, the reason for that error can be found by calling cupsLastError() and cupsErrorString(). cupsLastError() returns the last IPP error code that was encountered. cupsErrorString() converts the error code to a localized message string suitable for presentation to the user: #include <cups/cups.h> ... int jobid; ... if (jobid == 0) puts(cupsErrorString(cupsLastError())); Passwords and Authentication 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. 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. The cupsSetPasswordCB() function is used to set a password callback in your program. Only one function can be used at any time. The cupsSetUser() function sets the current username for authentication. This function can be called by your password callback function to change the current username as needed. The following example shows a simple password callback that gets a username and password from the user: #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); 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 cupsUser() to make things easier on the user. PPD Services CUPS includes functions to access and manipulate PostScript Printer Description ("PPD") files that are used with the printer drivers in CUPS. 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.) Include Files Include the <cups/ppd.h> header file to use the PPD functions: #include <cups/ppd.h> This header file is also included by the <cups/cups.h> header file. Getting a PPD File for a Printer The cupsGetPPD() function retrieves the PPD file for the named printer or class: #include <cups/cups.h> ... const char *filename; filename = cupsGetPPD("name"); The name string is the name of the printer or class, including the remote server name as appropriate (e.g. "printer@server".) The return value is a pointer to a filename in static storage; this value is overwritten with each call to cupsGetPPD(). If the printer or class does not exist, a NULL pointer will be returned. Loading a PPD File The ppdOpenFile() function "opens" a PPD file and loads it into memory: #include <cups/ppd.h> ... ppd_file_t *ppd; ppd = ppdOpenFile("filename"); The filename string is the name of the file to load, such as the value returned by the cupsGetPPD() function. 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. Freeing PPD File Information Once you are done using a PPD file, call the ppdClose() function to free all memory that has been used: #include <cups/ppd.h> ... ppd_file_t *ppd; ... ppdClose(ppd); The PPD File Structure 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 ppd_file_t structure. Capabilities Each PPD file contains a number of informational attributes that describe the capabilities of the printer. These are provided in the ppd_file_t structure in the following members: Member Type Description accurate_screens int 1 = supports accurate screens color_device int 1 = color device colorspace ppd_cs_t Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB, PPD_CS_RGBK, PPD_CS_N contone_only int 1 = printer is continuous tone only num_emulations emulations int ppd_emul_t * Emulations supported by the printer flip_duplex int 1 = need to flip odd pages when duplexing num_fonts fonts int char ** The fonts available on the printer. jcl_begin jcl_ps jcl_end char * Job Control Language commands for PostScript output landscape int Landscape orientation, -90 or 90 degrees lang_encoding char * The character used for the option strings lang_version char * The language used for the options strings (English, French, etc.) language_level int PostScript language level, 1 to 3 manual_copies int 1 = Copies are done manually model_number int Driver-specific model number. patches char * Patch commands to send to the printer manufacturer char * The Manufacturer attribute from the PPD file, if any modelname char * The ModelName attribute from the PPD file nickname char * The NickName attribute from the PPD file, if any product char * The Product attribute from the PPD file, if any shortnickname char * The ShortNickName attribute from the PPD file, if any throughput int Number of pages per minute ttrasterizer char * The TruType font rasterizer (Type42) variable_sizes int 1 = supports variable sizes Options and Groups PPD files support multiple options, which are stored in ppd_option_t and ppd_choice_t structures by the PPD functions. Each option in turn is associated with a group stored in the ppd_group_t 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. Groups can also have sub-groups; CUPS currently limits the depth of sub-groups to 1 level to reduce programming complexity. Conflicts PPD files support specification of conflict conditions between different options. Conflicts are stored in ppd_conflict_t structures which specify the options that conflict with each other. Page Sizes PPD files specify all of the available pages sizes and the physical margins associated with them. These sizes are stored in ppd_size_t structures and are available in the num_sizes and sizes members of the ppd_file_t structure. You can lookup a particular page size with the ppdPageWidth(), ppdPageLength(), and ppdPageSize() functions: #include <cups/ppd.h> ... ppd_file_t *ppd; ppd_size_t *size; float width; float length; ... size = ppdPageSize(ppd, "size"); width = ppdPageWidth(ppd, "size"); length = ppdPageLength(ppd, "size"); The size string is the named page size option. The width and length are in points; there are 72 points per inch. The ppd_size_t structure contains the width, length, and margin information: 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; Custom Page Sizes Besides the standard page sizes listed in a PPD file, some printers support variable or custom page sizes. If variables_sizes is non-zero, the custom_min, custom_max, and custom_margins members of the ppd_file_t structure define the limits of the variable sizes. To get the resulting media size, use a page size string of Custom.widthxlength, where width and length are integer values in points: Custom.612x792 [8.5 inches wide, 11 inches long] Custom.1224x792 [17 inches wide, 11 inches long] Marking Options Before marking any user-defined options, call the ppdMarkDefaults() function to mark the default options from the PPD file: #include <cups/ppd.h> ... ppd_file_t *ppd; ... ppdMarkDefaults(ppd); Then call the ppdMarkOption() function to mark individual options: #include <cups/ppd.h> ... ppd_file_t *ppd; int conflicts; ... conflicts = ppdMarkOption(ppd, "name", "value"); The name and value strings choose a particular option and choice, respectively. The return value is 0 if there are not conflicts created by the selection. CUPS also provides a convenience function for marking all options in the cups_option_t structure: #include <cups/cups.h> ... ppd_file_t *ppd; int num_options; cups_option_t *options; int conflicts; ... conflicts = cupsMarkOptions(ppd, num_options, options); The cupsMarkOptions() function also handles mapping the IPP job template attributes to PPD options. The return value is the number of conflicts present. Checking for Conflicts The ppdMarkOption() and cupsMarkOptions() functions return the number of conflicts with the currently marked options. Call the ppdConflicts() function to get the number of conflicts after you have marked all of the options: #include <cups/cups.h> ... ppd_file_t *ppd; int conflicts; ... conflicts = ppdConflicts(ppd); The return value is the number of conflicting options, or 0 if there are no conflicts. 3 - Writing Filters This chapter describes how to write a file filter for CUPS. Overview 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. Security Considerations 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. Users and Groups The default CUPS configuration runs filters as user "lp" and group "other". Temporary Files Temporary files should be created in the directory specified by the "TMPDIR" environment variable. The cupsTempFile() function can be used to safely choose temporary files in this directory. Sending Messages to the User 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 LogLevel directive. The type of message is determined by an initial prefix sent on each line: DEBUG: - a debug message INFO: - an informational message WARNING: - a warning message ERROR: - an error message PAGE: - a page accounting message 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 printer-state-message attribute for the printer, and also added to the error_log unless it is an informational or page accounting message. Page Accounting Page accounting messages are used to inform the server when one or more pages are printed. Each line has the form: PAGE: page-number copy-count The page-number field is the current page number, starting at 1. The copy-count field specifies the number of copies of that page that was produced. Page account messages are added to the page_log file and cause the job-sheets-completed attribute to be updated for the job. Command-Line Arguments Every filter accepts exactly 6 or 7 command-line arguments: printer job user title copies options [filename] printer - The name of the printer queue (normally this is the name of the program being run) job - The numeric job ID for the job being printed user - The string from the originating-user-name attribute title - The string from the job-name attribute copies - The numeric value from the number-copies attribute options - 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 filename - The request file The filename argument is only provided to the first filter in the chain; all filters must be prepared to read the print file from the standard input if the filename argument is omitted. Copy Generation The copies argument specifies the number of copies to produce of the input file. In general, you should only generate copies if the filename 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 pstops is responsible for copy generation. Environment Variables Every filter receives a fixed set of environment variables that can be used by the filter: CHARSET - The character set used by the client for this print file CONTENT_TYPE - The original document type, such as "application/postscript" CUPS_DATADIR - The location of CUPS data files CUPS_SERVERROOT - The location of CUPS configuration files DEVICE_URI - The output device URI LANG - The language used by the client for this print file PATH - The execution path exported to the filter PPD - The full filename of the printer's PPD file PRINTER - The name of the printer queue RIP_CACHE - The maximum amount of memory each filter should use SOFTWARE - The name of the CUPS software, typically "CUPS/1.1" TZ - The local timezone USER - The name of the current user Dissecting the HP-GL/2 Filter The HP-GL/2 filter (hpgltops) 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. Initializing the Filter The first task of any filter is to ensure that the correct number of command-line arguments are present: if (argc < 6 || argc > 7) { fputs("ERROR: hpgltops job-id user title copies options [file]\n", stderr); return (1); } After this you open the print file or read from the standard input as needed: 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); } } Once the print file has been opened, options can be processed using the cupsParseOptions() and cupsGetOption() functions: 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; 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. PostScript Output 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: %!PS-Adobe-3.0 %%BoundingBox: left bottom right top %%Pages: (atend) %%EndComments The left, bottom, right, and top values are integers in points from the lower-lefthand corner of the page. Pages must be surrounded by: %%Page: number number gsave ... grestore showpage And the end of each file must contain: %%Trailer %%Pages: number-pages %%EOF These comments allow the PostScript filter to correctly perform page accounting, copy generation, N-up printing, and so forth. 4 - Writing Printer Drivers 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. Overview 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. CUPS Raster Data CUPS raster data (application/vnd.cups-raster) consists of a stream of raster page descriptions produced by one of the RIP filters, such as pstoraster or imagetoraster. Each page of data begins with a page dictionary structure called cups_raster_header_t. This structure contains the colorspace, bits per color, media size, media type, hardware resolution, and so forth. After the page dictionary comes the page data which is a full-resolution, uncompressed bitmap representing the page in the printer's output colorspace. Page Accounting 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. Color Management Printer drivers can implement their color management via the cupsColorProfile 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. For example, the pstoraster 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. Device and Bitmap Variables 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: Variable Type Description cupsWidth read-only integer Width of bitmap in pixels cupsHeight read-only integer Height of bitmap in pixels cupsMediaType read-write integer Device-specific media type code cupsBitsPerColor read-write integer Number of bits per color; 1, 2, 4, and 8 are currently supported cupsBitsPerPixel read-only integer Number of bits per pixel; 1 to 32 cupsBytesPerLine read-only integer Number of bytes per line of raster graphics cupsColorOrder read-write enum The order of color values in the bitmap: CUPS_ORDER_CHUNKED - CMYK CMYK CMYK CUPS_ORDER_BANDED - CCC MMM YYY KKK CUPS_ORDER_PLANAR - CCC ... MMM ... YYY ... KKK ... cupsColorSpace read-write enum The colorspace of the bitmap: CUPS_CSPACE_W - White (luminance) CUPS_CSPACE_RGB - Red, green, blue CUPS_CSPACE_RGBA - Red, green, blue, alpha CUPS_CSPACE_K - Black CUPS_CSPACE_CMY - Cyan, magenta, yellow CUPS_CSPACE_YMC - Yellow, magenta, cyan CUPS_CSPACE_CMYK - Cyan, magenta, yellow, black CUPS_CSPACE_YMCK - Yellow, magenta, cyan, black CUPS_CSPACE_KCMY - Black, cyan, magenta, yellow CUPS_CSPACE_KCMYcm - Black, cyan, magenta, yellow, light cyan, light magenta CUPS_CSPACE_GMCK - Metallic yellow (gold), metallic magenta, metallic cyan, black CUPS_CSPACE_GMCS - Metallic yellow (gold), metallic magenta, metallic cyan, metallic grey (silver) CUPS_CSPACE_WHITE - White pigment (black as white pigment) CUPS_CSPACE_GOLD - Gold foil (black as gold foil) CUPS_CSPACE_SILVER - Silver foil (black as silver foil) cupsCompression read-write integer Device-specific compression type code cupsRowCount read-write integer Device-specific row count value cupsRowFeed read-write integer Device-specific row feed value cupsRowStep read-write integer Device-specific row step value 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. Dissecting the HP-PCL Driver The HP-PCL driver provided with CUPS (rastertohp) 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 - deskjet.ppd or laserjet.ppd. PPD Files 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. A typical CUPS printer driver will include ColorModel, InputSlot, PageSize, PageRegion, and Resolution options. Each option is shown using the standard PPD format: *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 The OpenUI 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. Every option must have a default value, specified using the DefaultOption keyword. 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: *PageSize A4/A4: "<</PageSize[595 842]/ImagingBBox null>> setpagedevice" or broken down on separate lines using the End keyword to terminate them: *PageSize A4/A4: "<< /PageSize [595 842] /ImagingBBox null >> setpagedevice" *End 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. Reading Raster Data 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 cupsRasterOpen() function opens a raster stream for printing: 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); Once you have opened the raster stream you just need to read each page and print it: 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 ... } } After you have processed all pages, close the raster stream and return: cupsRasterClose(ras); return (0); 5 - Writing Backends 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. Overview Backends are special filters that communicate with printers directly. They are treated slightly differently than filters, however, and have some unique requirements. Security Considerations 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. Command-Line Arguments 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. Copy Generation 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. Page Accounting 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. Exclusive Access Backends that talk to local character or block devices should open the device file in exclusive mode (O_EXCL) to cooperate with other printers defined for the same device. Retries All backends must 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. 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. Dissecting the Serial Port Backend 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. Supporting Device Discovery 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...) The serial backend lists devices by looking at serial port files in the /dev directory, by consulting a hardware inventory (IRIX), and in some cases by trying to open the ports to see if they actually exist. Once it finds a serial port it writes a single line for each port to the standard error file. Each line looks like this: serial serial:/dev/ttyS0?baud=115200 "Unknown" "Serial Port 1" The first word "serial" is the device class; this identifies the class of device which can be used to categorize it in user interfaces. CUPS currently recognizes the following classes: "file" - a disk file. "direct" - a parallel or fixed-rate serial data port, currently used for Centronics, IEEE-1284, and USB printer ports. "serial" - a variable-rate serial port. "network" - a network connection, typically via AppSocket, HTTP, IPP, LPD, or SMB/CIFS protocols. After the device class is the device URI, 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. 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. Opening the Serial Port 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 do-while loop: 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); 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. Writing Data to the Port 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: 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; } The check for the ENOTTY error is needed on some platforms to clear an error from a previous ioctl() call. Finishing Up 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. A - Software License Agreement B - Constants This appendix lists all of the constants that are defined by the CUPS API. CUPS Constants Version Number The CUPS_VERSION 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. Printer Capabilities The CUPS_PRINTER constants represent capability bits for printers and classes: CUPS_PRINTER_LOCAL - Is a local printer or class. CUPS_PRINTER_REMOTE - Is a remote printer or class. CUPS_PRINTER_CLASS - Is a class. CUPS_PRINTER_BW - Printer prints in black and white. CUPS_PRINTER_COLOR - Printer prints in color. CUPS_PRINTER_DUPLEX - Printer can print double-sided. CUPS_PRINTER_STAPLE - Printer can staple output. CUPS_PRINTER_COPIES - Printer can produce multiple copies on its own. CUPS_PRINTER_COLLATE - Printer can collate copies. CUPS_PRINTER_PUNCH - Printer can punch holes in output. CUPS_PRINTER_COVER - Printer can put covers on output. CUPS_PRINTER_BIND - Printer can bind output. CUPS_PRINTER_SORT - Printer can sort output. CUPS_PRINTER_SMALL - Printer can print on media up to 9x14 inches. CUPS_PRINTER_MEDIUM - Printer can print on media from 9x14 to 18x24 inches. CUPS_PRINTER_LARGE - Printer can print on media larger than 18x24 inches. CUPS_PRINTER_VARIABLE - Printer can print on variable or custom media sizes. CUPS_PRINTER_IMPLICIT - Is an implicit class. CUPS_PRINTER_OPTIONS - All of the printer capability and option bits. Encodings CUPS defines the following character set encoding constants: CUPS_US_ASCII - US ASCII character set. CUPS_UTF_8 - UTF-8 encoding of Unicode. CUPS_ISO8859_1 - ISO-8859-1 character set. CUPS_ISO8859_2 - ISO-8859-2 character set. CUPS_ISO8859_3 - ISO-8859-3 character set. CUPS_ISO8859_4 - ISO-8859-4 character set. CUPS_ISO8859_5 - ISO-8859-5 character set. CUPS_ISO8859_6 - ISO-8859-6 character set. CUPS_ISO8859_7 - ISO-8859-7 character set. CUPS_ISO8859_8 - ISO-8859-8 character set. CUPS_ISO8859_9 - ISO-8859-9 character set. CUPS_ISO8859_10 - ISO-8859-10 character set. CUPS_ISO8859_13 - ISO-8859-13 character set. CUPS_ISO8859_14 - ISO-8859-14 character set. CUPS_ISO8859_15 - ISO-8859-15 character set. CUPS_WINDOWS_874 - Windows code page 874. CUPS_WINDOWS_1250 - Windows code page 1250. CUPS_WINDOWS_1251 - Windows code page 1251. CUPS_WINDOWS_1252 - Windows code page 1252. CUPS_WINDOWS_1253 - Windows code page 1253. CUPS_WINDOWS_1254 - Windows code page 1254. CUPS_WINDOWS_1255 - Windows code page 1255. CUPS_WINDOWS_1256 - Windows code page 1256. CUPS_WINDOWS_1257 - Windows code page 1257. CUPS_WINDOWS_1258 - Windows code page 1258. CUPS_KOI8_R - Russian code page koi8-r. CUPS_KOI8_U - Ukrainian code page koi8-r. HTTP Constants Limits The following constants define the limits for strings: HTTP_MAX_BUFFER - Size of socket buffer. HTTP_MAX_HOST - Maximum length of hostname. HTTP_MAX_URI - Maximum length of URI. HTTP_MAX_VALUE - Maximum length of field values. Status Codes The following status codes can be returned by httpUpdate(): HTTP_ERROR - A network error occurred HTTP_CONTINUE - Continue response from HTTP proxy HTTP_OK - OPTIONS/GET/HEAD/POST/TRACE command was successful HTTP_CREATED - PUT command was successful HTTP_ACCEPTED - DELETE command was successful HTTP_NOT_AUTHORITATIVE - Information isn't authoritative HTTP_NO_CONTENT - Successful command HTTP_RESET_CONTENT - Content was reset/recreated HTTP_PARTIAL_CONTENT - Only a partial file was recieved/sent HTTP_MULTIPLE_CHOICES - Multiple files match request HTTP_MOVED_PERMANENTLY - Document has moved permanently HTTP_MOVED_TEMPORARILY - Document has moved temporarily HTTP_SEE_OTHER - See this other link... HTTP_NOT_MODIFIED - File not modified HTTP_USE_PROXY - Must use a proxy to access this URI HTTP_BAD_REQUEST - Bad request HTTP_UNAUTHORIZED - Unauthorized to access host HTTP_PAYMENT_REQUIRED - Payment required HTTP_FORBIDDEN - Forbidden to access this URI HTTP_NOT_FOUND - URI was not found HTTP_METHOD_NOT_ALLOWED - Method is not allowed HTTP_NOT_ACCEPTABLE - Not Acceptable HTTP_PROXY_AUTHENTICATION - Proxy Authentication is Required HTTP_REQUEST_TIMEOUT - Request timed out HTTP_CONFLICT - Request is self-conflicting HTTP_GONE - Server has gone away HTTP_LENGTH_REQUIRED - A content length or encoding is required HTTP_PRECONDITION - Precondition failed HTTP_REQUEST_TOO_LARGE - Request entity too large HTTP_URI_TOO_LONG - URI too long HTTP_UNSUPPORTED_MEDIATYPE - The requested media type is unsupported HTTP_SERVER_ERROR - Internal server error HTTP_NOT_IMPLEMENTED - Feature not implemented HTTP_BAD_GATEWAY - Bad gateway HTTP_SERVICE_UNAVAILABLE - Service is unavailable HTTP_GATEWAY_TIMEOUT - Gateway connection timed out HTTP_NOT_SUPPORTED - HTTP version not supported Fields The following fields are indices for each of the standard HTTP fields in HTTP 1/1: HTTP_FIELD_ACCEPT_LANGUAGE - Accept-Language HTTP_FIELD_ACCEPT_RANGES - Accept-Ranges HTTP_FIELD_AUTHORIZATION - Authorization HTTP_FIELD_CONNECTION - Connection HTTP_FIELD_CONTENT_ENCODING - Content-Encoding HTTP_FIELD_CONTENT_LANGUAGE - Content-Language HTTP_FIELD_CONTENT_LENGTH - Content-Length HTTP_FIELD_CONTENT_LOCATION - Content-Location HTTP_FIELD_CONTENT_MD5 - Content-MD5 HTTP_FIELD_CONTENT_RANGE - Content-Range HTTP_FIELD_CONTENT_TYPE - Content-Type HTTP_FIELD_CONTENT_VERSION - Content-Version HTTP_FIELD_DATE - Date HTTP_FIELD_HOST - Host HTTP_FIELD_IF_MODIFIED_SINCE - If-Modified-Since HTTP_FIELD_IF_UNMODIFIED_SINCE - If-Unmodified-Since HTTP_FIELD_KEEP_ALIVE - Keep-Alive HTTP_FIELD_LAST_MODIFIED - Last-Modified HTTP_FIELD_LINK - Link HTTP_FIELD_LOCATION - Location HTTP_FIELD_RANGE - Range HTTP_FIELD_REFERER - Referer HTTP_FIELD_RETRY_AFTER - Retry-After HTTP_FIELD_TRANSFER_ENCODING - Transfer-Encoding HTTP_FIELD_UPGRADE - Upgrade HTTP_FIELD_USER_AGENT - User-Agent HTTP_FIELD_WWW_AUTHENTICATE - WWW-Authenticate IPP Constants Limits The following constants define array limits for IPP data: IPP_MAX_NAME - Maximum length of an attribute name IPP_MAX_VALUES - Maximum number of set-of values that can be read in a request. Tags IPP_TAG_ZERO - Wildcard tag value for searches; also used to separate groups of attributes IPP_TAG_OPERATION - Tag for values of type operation IPP_TAG_JOB - Tag for values of type job IPP_TAG_END - Tag for values of type end IPP_TAG_PRINTER - Tag for values of type printer IPP_TAG_UNSUPPORTED_GROUP - Tag for values of type unsupported_group IPP_TAG_UNSUPPORTED_VALUE - Tag for values of type unsupported_value IPP_TAG_DEFAULT - Tag for values of type default IPP_TAG_UNKNOWN - Tag for values of type unknown IPP_TAG_NOVALUE - Tag for values of type novalue IPP_TAG_NOTSETTABLE - Tag for values of type notsettable IPP_TAG_DELETEATTR - Tag for values of type deleteattr IPP_TAG_ANYVALUE - Tag for values of type anyvalue IPP_TAG_INTEGER - Tag for values of type integer IPP_TAG_BOOLEAN - Tag for values of type boolean IPP_TAG_ENUM - Tag for values of type enum IPP_TAG_STRING - Tag for values of type string IPP_TAG_DATE - Tag for values of type date IPP_TAG_RESOLUTION - Tag for values of type resolution IPP_TAG_RANGE - Tag for values of type range IPP_TAG_COLLECTION - Tag for values of type collection IPP_TAG_TEXTLANG - Tag for values of type textlang IPP_TAG_NAMELANG - Tag for values of type namelang IPP_TAG_TEXT - Tag for values of type text IPP_TAG_NAME - Tag for values of type name IPP_TAG_KEYWORD - Tag for values of type keyword IPP_TAG_URI - Tag for values of type uri IPP_TAG_URISCHEME - Tag for values of type urischeme IPP_TAG_CHARSET - Tag for values of type charset IPP_TAG_LANGUAGE - Tag for values of type language IPP_TAG_MIMETYPE - Tag for values of type mimetype Resolution Units The IPP_RES_PER_INCH and IPP_RES_PER_CM constants specify dots per inch and dots per centimeter, respectively. Finishings The finishing values specify special finishing operations to be performed on the job. IPP_FINISH_NONE - Do no finishing IPP_FINISH_STAPLE - Staple the job IPP_FINISH_PUNCH - Punch the job IPP_FINISH_COVER - Cover the job IPP_FINISH_BIND - Bind the job Orientations The orientation values specify the orientation of the job. IPP_PORTRAIT - No rotation IPP_LANDSCAPE - 90 degrees counter-clockwise IPP_REVERSE_LANDSCAPE - 90 degrees clockwise IPP_REVERSE_PORTRAIT - 180 degrees Qualities The quality values specify the desired quality of the print. IPP_QUALITY_DRAFT - Draft quality IPP_QUALITY_NORMAL - Normal quality IPP_QUALITY_HIGH - High quality Job States The job state values are used to represent the current job state. IPP_JOB_PENDING - Job is pending IPP_JOB_HELD - Job is held IPP_JOB_PROCESSING - Job is processing IPP_JOB_STOPPED - Job is stopped IPP_JOB_CANCELLED - Job is cancelled IPP_JOB_ABORTED - Job is aborted IPP_JOB_COMPLETED - Job is completed Printer States The printer state values are used to represent the current printer state. IPP_PRINTER_IDLE - Printer is idle IPP_PRINTER_PROCESSING - Printer is processing IPP_PRINTER_STOPPED - Printer is stopped Operations The operation values represent the available IPP operations. IPP_PRINT_JOB - Print a file IPP_PRINT_URI - Print a URI IPP_VALIDATE_JOB - Validate job attributes IPP_CREATE_JOB - Create a new job IPP_SEND_DOCUMENT - Send a document to a job IPP_SEND_URI - Send a URI to a job IPP_CANCEL_JOB - Cancel a job IPP_GET_JOB_ATTRIBUTES - Get job attributes IPP_GET_JOBS - Get a list of all jobs IPP_GET_PRINTER_ATTRIBUTES - Get printer attributes IPP_HOLD_JOB - Hold a pending job IPP_RELEASE_JOB - Release a held job IPP_RESTART_JOB - Restart a completed job IPP_PAUSE_PRINTER - Pause a printer IPP_RESUME_PRINTER - Restart a paused printer IPP_PURGE_JOBS - Purge jobs from the queue IPP_SET_PRINTER_ATTRIBUTES - Set printer attributes IPP_SET_JOB_ATTRIBUTES - Set job attributes IPP_GET_PRINTER_SUPPORTED_VALUES - Get printer supported values CUPS_GET_DEFAULT - Get the default destination CUPS_GET_PRINTERS - Get a list of all printers CUPS_ADD_PRINTER - Add or modify a printer CUPS_DELETE_PRINTER - Delete a printer CUPS_GET_CLASSES - Get a list of all classes CUPS_ADD_CLASS - Add or modify a class CUPS_DELETE_CLASS - Delete a class CUPS_ACCEPT_JOBS - Accept jobs on a printer or class CUPS_REJECT_JOBS - Reject jobs on a printer or class CUPS_SET_DEFAULT - Set the default destination CUPS_GET_DEVICES - Get a list of all devices CUPS_GET_PPDS - Get a list of all PPDs CUPS_MOVE_JOB - Move a job to a new destination Status Codes Status codes are returned by all IPP requests. IPP_OK - Request completed with no errors IPP_OK_SUBST - Request completed but some attribute values were substituted IPP_OK_CONFLICT - Request completed but some attributes conflicted IPP_BAD_REQUEST - The request was bad IPP_FORBIDDEN - You don't have access to the resource IPP_NOT_AUTHENTICATED - You are not authenticated for the resource IPP_NOT_AUTHORIZED - You not authorized to access the resource IPP_NOT_POSSIBLE - The requested operation cannot be completed IPP_TIMEOUT - A timeout occurred IPP_NOT_FOUND - The resource was not found IPP_GONE - The resource has gone away IPP_REQUEST_ENTITY - The request was too large IPP_REQUEST_VALUE - The request contained a value that was unknown to the server IPP_DOCUMENT_FORMAT - The document format is not supported by the server IPP_ATTRIBUTES - Required attributes are missing IPP_URI_SCHEME - The URI scheme is not supported IPP_CHARSET - The charset is not supported IPP_CONFLICT - One or more attributes conflict IPP_COMPRESSION_NOT_SUPPORTED - The specified compression is not supported IPP_COMPRESSION_ERROR - The compressed data contained an error IPP_DOCUMENT_FORMAT_ERROR - The document data contained an error in it IPP_DOCUMENT_ACCESS_ERROR - The remote document could not be accessed IPP_INTERNAL_ERROR - The server encountered an internal error IPP_OPERATION_NOT_SUPPORTED - The requested operation is not supported IPP_SERVICE_UNAVAILABLE - The requested service is unavailable IPP_VERSION_NOT_SUPPORTED - The IPP request version is not supported IPP_DEVICE_ERROR - The output device encountered an error IPP_TEMPORARY_ERROR - A temporary error occurred IPP_NOT_ACCEPTING - The destination is not accepting jobs IPP_PRINTER_BUSY - The destination is busy IPP_ERROR_JOB_CANCELLED - The requested job has been cancelled IPP_MULTIPLE_JOBS_NOT_SUPPORTED - The server does not support multiple jobs PPD Constants PPD Format Version The PPD_VERSION constant defines a floating point number representing the newest format version that is supported by CUPS, currently 4.3. PPD User-Interface Types Each printer option has a type associated with it: PPD_UI_BOOLEAN - The user can turn this option on or off PPD_UI_PICKONE - The user can choose one option value to use. PPD_UI_PICKMANY - The user can choose zero or more option values. PPD Sections Some options must be output before others, or in different sections of the output document. The ppd_section_t enumeration defines which section the option must be output in: PPD_ORDER_ANY - The option can be output in any of the document, page, or prolog sections of the document PPD_ORDER_DOCUMENT - The option must be output in the DocumentSetup section of the document PPD_ORDER_EXIT - The option must be output before the document PPD_ORDER_JCL - The option must be output in the job control section of the document PPD_ORDER_PAGE - The option must be output in the PageSetup section of the document PPD_ORDER_PROLOG - The option must be output in the Prolog section of the document PPD Colorspaces Each printer has a default colorspace: PPD_CS_CMYK - The printer uses CMYK colors by default PPD_CS_CMY - The printer uses CMY colors by default PPD_CS_GRAY - The printer uses grayscale by default PPD_CS_RGB - The printer uses RGB colors by default PPD_CS_RGBK - The printer uses RGBK colors by default PPD_CS_N - The printer uses a DeviceN colorspace by default Raster Constants Raster Sync Words The CUPS_RASTER_SYNC and CUPS_RASTER_REVSYNC constants define the standard sync words at the beginning of each CUPS raster file. Raster Stream Modes The CUPS_RASTER_READ and CUPS_RASTER_WRITE constants are used with the cupsRasterOpen() function to specify a stream for reading or writing. Raster Boolean Constants The CUPS_FALSE and CUPS_TRUE constants represent boolean values in the page header. Raster Jog Values The cups_jog_t enumeration defines constants for the Jog page device dictionary variable: CUPS_JOG_NONE - Do no jogging CUPS_JOG_FILE - Jog pages after each file CUPS_JOG_JOB - Jog pages after each job CUPS_JOG_SET - Jog pages after each set of jobs Raster Orientation Values The cups_orient_t enumeration defines constants for the Orientation page device dictionary variable: CUPS_ORIENT_0 - Portrait orientation CUPS_ORIENT_90 - Landscape orientation CUPS_ORIENT_180 - Reverse-portrait orientation CUPS_ORIENT_270 - Reverse-landscape orientation Raster CutMedia Values The cups_cut_t enumeration defines constants for the CutMedia page device dictionary variable: CUPS_CUT_NONE - Do no jogging CUPS_CUT_FILE - Cut pages after each file CUPS_CUT_JOB - Cut pages after each job CUPS_CUT_SET - Cut pages after each set of jobs CUPS_CUT_PAGE - Cut each page Raster AdvanceMedia Values The cups_advance_t enumeration defines constants for the AdvanceMedia page device dictionary variable: CUPS_ADVANCE_NONE - Do no jogging CUPS_ADVANCE_FILE - Advance media after each file CUPS_ADVANCE_JOB - Advance media after each job CUPS_ADVANCE_SET - Advance media after each set of jobs CUPS_ADVANCE_PAGE - Advance media for each page Raster LeadingEdge Values The cups_edge_t enumeration defines constants for the LeadingEdge page device dictionary variable: CUPS_EDGE_TOP - The top of the media is the leading edge CUPS_EDGE_RIGHT - The right of the media is the leading edge CUPS_EDGE_BOTTOM - The bottom of the media is the leading edge CUPS_EDGE_LEFT - The left of the media is the leading edge Raster Color Order Values The cups_order_t enumeration defines the possible color value orderings: CUPS_ORDER_CHUNKED - CMYK CMYK CMYK CUPS_ORDER_BANDED - CCC MMM YYY KKK CUPS_ORDER_PLANAR - CCC ... MMM ... YYY ... KKK ... Raster Colorspace Values The cups_cspace_t enumeration defines the possible colorspaces: CUPS_CSPACE_W - White (luminance) CUPS_CSPACE_RGB - Red, green, blue CUPS_CSPACE_RGBA - Red, green, blue, alpha CUPS_CSPACE_K - Black CUPS_CSPACE_CMY - Cyan, magenta, yellow CUPS_CSPACE_YMC - Yellow, magenta, cyan CUPS_CSPACE_CMYK - Cyan, magenta, yellow, black CUPS_CSPACE_YMCK - Yellow, magenta, cyan, black CUPS_CSPACE_KCMY - Black, cyan, magenta, yellow CUPS_CSPACE_KCMYcm - Black, cyan, magenta, yellow, light cyan, light magenta CUPS_CSPACE_GMCK - Metallic yellow (gold), metallic magenta, metallic cyan, black CUPS_CSPACE_GMCS - Metallic yellow (gold), metallic magenta, metallic cyan, metallic grey (silver) CUPS_CSPACE_WHITE - White pigment (black as white pigment) CUPS_CSPACE_GOLD - Gold foil (black as gold foil) CUPS_CSPACE_SILVER - Silver foil (black as silver foil) C - Structures This appendix describes all of the structures that are defined by the CUPS API. CUPS Structures CUPS Destinations The CUPS destination structure (cups_dest_t) contains information on a specific destination or instance: Member Type Description name char * The name of the printer or class. instance char * The instance of the printer or class; NULL for the primary instance. is_default int 1 if the destination is set as the default, 0 otherwise. num_options int The number of options associated with this destination. options cups_option_t * The options associated with this destination. CUPS Jobs The CUPS job structure (cups_job_t) contains information on a specific job: Member Type Description id int The job ID for this job. dest char * The destination for this job (printer or class name). title char * The job-name for this job (title). user char * The job-originating-user-name for this job (username). format char * The document-format for this job (MIME type string). state ipp_jstate The current state of the job. size int The size of this job in kilobytes. priority int The priority of this job from 1 to 100 (50 is normal). completed_time time_t The time the job was completed, or 0 if not yet completed. creation_time time_t The time the job was queued. processing_time time_t The time the job started printing. CUPS Messages The CUPS messages structure (cups_lang_t) contains the character set, locale name, and messages array: Member Type Description next cups_lang_t * Pointer to the next messages structure in memory. used int The number of active users of this messages structure. encoding cups_encoding_t The character encoding of the message strings. language char [16] The language/locale name. messages char *[] The array of message strings. CUPS Options The CUPS option structure (cups_option_t) contains the option name and string value: Member Type Description name char * The name of the option. value char * The string value of the option. Networking Structures HTTP State The HTTP state structure (http_t) contains the current state of a HTTP request or response: Member Type Description fd int The socket for the HTTP connection. blocking int 1 if the HTTP functions should block, 0 if not. error int The last OS error that occurred on the socket. activity time_t The last time the HTTP connection was used. state http_state_t The current HTTP request/response state. status int The last HTTP status seen. version http_version_t The HTTP protocol version in use. keep_alive http_keep_alive_t Whether or not to use Keep-Alive hostaddr struct sockaddr_in The IPv4 address of the HTTP server. hostname char [] The hostname of the HTTP server. fields char [][] The string values of all HTTP request/response fields. data char * Current byte in data buffer. data_encoding http_encoding_t The transfer encoding for the request/response. data_remaining int The number of bytes remaining in the current request, response, or chunk. used int The number of bytes that are used in the buffer. buffer char [] The read/write buffer. auth_type int The type of authentication in use. md5_state md5_state_t The current MD5 digest state. nonce char [] The nonce value for Digest authentication. nonce_count int The nonce count value. tls void * A pointer to private encryption data. encryption http_encryption_t The current encryption mode. IPP State The IPP state structure (ipp_t) contains the current state of a IPP request or response: Member Type Description Raster Structures Raster Page Header The raster page header (cups_raster_header_t) consists of the PostScript page device dictionary for the page: Member Type Description MediaClass char[64] The media class name MediaColor char[64] The media color name MediaType char[64] The media type name OutputType char[64] The output type name AdvanceDistance unsigned The distance to advance the media in points AdvanceMedia cups_adv_t When to advance the media Collate cups_bool_t Whether or not to produce collated copies CutMedia cups_cut_t When to cut the media Duplex cups_bool_t Whether or not to print on both sides of the paper HWResolution unsigned[2] The resolution of the page image in pixels per inch; the HWResolution[0] represents the horizontal resolution and HWResolution[1] represents the vertical resolution ImagingBoundingBox unsigned[4] 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) InsertSheet cups_bool_t Whether or not to insert a sheet before this page Jog cups_jog_t When to jog copies of the page LeadingEdge cups_edge_t The leading edge of the page Margins unsigned[2] The lower-lefthand margin of the page in points ManualFeed cups_bool_t Whether or not to manually feed the page MediaPosition unsigned The input slot number to use MediaWeight unsigned The weight of the output media in grams/m2 MirrorPrint cups_bool_t Whether or not to mirror the print NegativePrint cups_bool_t Whether or not to invert the print NumCopies unsigned The number of copies to produce Orientation cups_orient_t The orientation of the page image OutputFaceUp cups_bool_t Whether or not to output the page face up PageSize unsigned[2] The width and height of the page in points Separations cups_bool_t Whether or not to output separations TraySwitch cups_bool_t Whether or not to automatically switch trays for the requested media size/type Tumble cups_bool_t Whether or not to rotate the back side of the page cupsWidth unsigned The width of the page image in pixels cupsHeight unsigned The height of the page image in pixels cupsMediaType unsigned The device-specific media type code cupsBitsPerColor unsigned The number of bits per color cupsBitsPerPixel unsigned The number of bits per pixel cupsBytesPerLine unsigned The number of bytes per line of image data cupsColorOrder cups_order_t The order of color values cupsColorSpace cups_cspace_t The type of color values cupsCompression unsigned The device-specific compression code cupsRowCount unsigned The device-specific row count cupsRowFeed unsigned The device-specific row feed cupsRowStep unsigned The device-specific row step D - Functions This appendix provides a reference for all of the CUPS API functions. cupsAddOption() Usage int cupsAddOption(const char *name, const char *value, int num_options, cups_option_t **options); Arguments Argument Description name The name of the option. value The value of the option. num_options Number of options currently in the array. options Pointer to the options array. Returns The new number of options. Description cupsAddOption() adds an option to the specified array. Example #include <cups.h> ... /* Declare the options array */ int num_options; cups_option_t *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); See Also cupsFreeOptions(), cupsGetOption(), cupsParseOptions() cupsCancelJob() Usage int cupsCancelJob(const char *dest, int job); Arguments Argument Description dest Printer or class name job Job ID Returns 1 on success, 0 on failure. On failure the error can be found by calling cupsLastError(). Description cupsCancelJob() cancels the specifies job. Example #include <cups.h> cupsCancelJob("LaserJet", 1); See Also cupsLastError(), cupsPrintFile() cupsDoFileRequest() Usage ipp_t * cupsDoFileRequest(http_t *http, ipp_t *request, const char *resource, const char *filename); Arguments Argument Description http HTTP connection to server. request IPP request data. resource HTTP resource name for POST. filename File to send with POST request (NULL pointer if none.) Returns IPP response data or NULL if the request fails. On failure the error can be found by calling cupsLastError(). Description cupsDoFileRequest() 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. Example #include <cups.h> http_t *http; cups_lang_t *language; ipp_t *request; ipp_t *response; ... /* Get the default language */ language = cupsLangDefault(); /* Create a new IPP request */ request = ippNew(); request->request.op.operation_id = IPP_PRINT_FILE; request->request.op.request_id = 1; /* Add required attributes */ ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET, "attributes-charset", NULL, cupsLangEncoding(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, cupsUser()); /* Do the request... */ response = cupsDoFileRequest(http, request, "/resource", "filename.txt"); See Also cupsLangDefault(), cupsLangEncoding(), cupsUser(), httpConnect(), ippAddString(), ippNew() cupsDoRequest() Usage ipp_t * cupsDoRequest(http_t *http, ipp_t *request, const char *resource); Arguments Argument Description http HTTP connection to server. request IPP request data. resource HTTP resource name for POST. Returns IPP response data or NULL if the request fails. On failure the error can be found by calling cupsLastError(). Description cupsDoRequest() 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. Example #include <cups.h> http_t *http; cups_lang_t *language; ipp_t *request; ipp_t *response; ... /* Get the default language */ language = cupsLangDefault(); /* Create a new IPP request */ request = ippNew(); request->request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES; request->request.op.request_id = 1; /* Add required attributes */ ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET, "attributes-charset", NULL, cupsLangEncoding(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"); See Also cupsLangDefault(), cupsLangEncoding(), cupsUser(), httpConnect(), ippAddString(), ippNew() cupsFreeOptions() Usage void cupsFreeOptions(int num_options, cups_option_t *options); Arguments Argument Description num_options Number of options in array. options Pointer to options array. Description cupsFreeOptions() frees all memory associated with the option array specified. Example #include <cups/cups.h> int num_options; cups_option_t *options; ... cupsFreeOptions(num_options, options); See Also cupsAddOption(), cupsGetOption(), cupsMarkOptions(), cupsParseOptions() cupsGetClasses() Usage int cupsGetClasses(char ***classes); Arguments Argument Description classes Pointer to character pointer array. Returns The number of printer classes available. Description cupsGetClasses() gets a list of the available printer classes. The returned array should be freed using the free() when it is no longer needed. Example #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); } See Also cupsGetDefault(), cupsGetPrinters() cupsGetDefault() Usage const char * cupsGetDefault(void); Returns A pointer to the default destination. Description cupsGetDefault() 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. Example #include <cups/cups.h> printf("The default destination is %s\n", cupsGetDefault()); See Also cupsGetClasses(), cupsGetPrinters() cupsGetOption() Usage const char * cupsGetOption(const char *name, int num_options, cups_option_t *options); Arguments Argument Description name The name of the option. num_options The number of options in the array. options The options array. Returns A pointer to the option values or NULL if the option is not defined. Description cupsGetOption() returns the first occurrence of the named option. If the option is not included in the options array then a NULL pointer is returned. #include <cups/cups.h> int num_options; cups_option_t *options; const char *media; ... media = cupsGetOption("media", num_options, options); See Also cupsAddOption(), cupsFreeOptions(), cupsMarkOptions(), cupsParseOptions() cupsGetPassword() Usage const char * cupsGetPassword(const char *prompt); Arguments Argument Description prompt The prompt to display to the user. Returns A pointer to the password that was entered or NULL if no password was entered. Description cupsGetPassword() displays the prompt string and asks the user for a password. The password text is not echoed to the user. Example #include <cups/cups.h> char *password; ... password = cupsGetPassword("Please enter a password:"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser() cupsGetPPD() Usage const char * cupsGetPPD(const char *printer); Arguments Argument Description printer The name of the printer. Returns The name of a temporary file containing the PPD file or NULL if the printer cannot be located or does not have a PPD file. Description cupsGetPPD() gets a copy of the PPD file for the named printer. The printer name can be of the form "printer" or "printer@hostname". 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 cupsGetPPD(). Example #include <cups/cups.h> char *ppd; ... ppd = cupsGetPPD("printer@hostname"); ... unlink(ppd); cupsGetPrinters() Usage int cupsGetPrinters(char ***printers); Arguments Argument Description printers Pointer to character pointer array. Returns The number of printer printers available. Description cupsGetPrinters() gets a list of the available printers. The returned array should be freed using the free() when it is no longer needed. Example #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); } See Also cupsGetClasses(), cupsGetDefault() cupsLangDefault() Usage const char * cupsLangDefault(void); Returns A pointer to the default language structure. Description cupsLangDefault() returns a language structure for the default language. The default language is defined by the LANG environment variable. If the specified language cannot be located then the POSIX (English) locale is used. Call cupsLangFree() to free any memory associated with the language structure when you are done. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangDefault(); ... cupsLangFree(language); See Also cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangEncoding() Usage char * cupsLangEncoding(cups_lang_t *language); Arguments Argument Description language The language structure. Returns A pointer to the encoding string. Description cupsLangEncoding() returns the language encoding used for the specified language, e.g. "iso-8859-1", "utf-8", etc. Example #include <cups/language.h> cups_lang_t *language; char *encoding; ... language = cupsLangDefault(); encoding = cupsLangEncoding(language); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFlush() Usage void cupsLangFlush(void); Description cupsLangFlush() frees all language structures that have been allocated. Example #include <cups/language.h> ... cupsLangFlush(); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFree() Usage void cupsLangFree(cups_lang_t *language); Arguments Argument Description language The language structure to free. Description cupsLangFree() frees the specified language structure. Example #include <cups/language.h> cups_lang_t *language; ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangGet(), cupsLangString() cupsLangGet() Usage cups_lang_t * cupsLangGet(const char *name); Arguments Argument Description name The name of the locale. Returns A pointer to a language structure. Description cupsLangGet() returns a language structure for the specified locale. If the locale is not defined then the POSIX (English) locale is substituted. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangGet("fr"); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangString() cupsLangString() Usage char * cupsLangString(cups_lang_t *language, int message); Arguments Argument Description language The language to query. message The message number. Returns A pointer to the message string or NULL if the message is not defined. Description cupsLangString() returns a pointer to the specified message string in the specified language. Example #include <cups/language.h> cups_lang_t *language; char *s; ... language = cupsLangGet("fr"); s = cupsLangString(language, CUPS_MSG_YES); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet() cupsLastError() Usage ipp_status_t cupsLastError(void); Returns An enumeration containing the last IPP error. Description cupsLastError() returns the last IPP error that occurred. If no error occurred then it will return IPP_OK or IPP_OK_CONFLICT. Example #include <cups/cups.h> ipp_status_t status; ... status = cupsLastError(); See Also cupsCancelJob(), cupsPrintFile() cupsMarkOptions() Usage int cupsMarkOptions(ppd_file_t *ppd, int num_options, cups_option_t *options); Arguments Argument Description ppd The PPD file to mark. num_options The number of options in the options array. options A pointer to the options array. Returns The number of conflicts found. Description cupsMarkOptions() marks options in the PPD file. It also handles mapping of IPP option names and values to PPD option names. Example #include <cups/cups.h> int num_options; cups_option_t *options; ppd_file_t *ppd; ... cupsMarkOptions(ppd, num_options, options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsParseOptions() cupsParseOptions() Usage int cupsParseOptions(const char *arg, int num_options, cups_option_t **options); Arguments Argument Description arg The string containing one or more options. num_options The number of options in the options array. options A pointer to the options array pointer. Returns The new number of options in the array. Description cupsParseOptions() 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. Example #include <cups/cups.h> int num_options; cups_option_t *options; ... num_options = 0; options = (cups_option_t *)0; num_options = cupsParseOptions(argv[5], num_options, &options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsMarkOptions() cupsPrintFile() Usage int cupsPrintFile(const char *printer, const char *filename, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. filename The file to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFile() 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 cupsLastError(). Example #include <cups/cups.h> int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFiles() cupsPrintFiles() Usage int cupsPrintFiles(const char *printer, int num_files, const char **files, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. num_files The number of files to print. files The files to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFiles() 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 cupsLastError(). Example #include <cups/cups.h> int num_files; const char *files[100]; int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFiles("printer@hostname", num_files, files, "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFile() cupsRasterClose() Usage void cupsRasterClose(cups_raster_t *ras); Arguments Argument Description ras The raster stream to close. Description cupsRasterClose() closes the specified raster stream. Example #include <cups/raster.h> cups_raster_t *ras; ... cupsRasterClose(ras); See Also cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterOpen() Usage cups_raster_t * cupsRasterOpen(int fd, cups_mode_t mode); Arguments Argument Description fd The file descriptor to use. mode The mode to use; CUPS_RASTER_READ or CUPS_RASTER_WRITE. Returns A pointer to a raster stream or NULL if there was an error. Description cupsRasterOpen() opens a raster stream for reading or writing. Example #include <cups/raster.h> cups_raster_t *ras; ... ras = cupsRasterOpen(0, CUPS_RASTER_READ); See Also cupsRasterClose(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadHeader() Usage unsigned cupsRasterReadHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to read from. header A pointer to a page header structure to read into. Returns 1 on success, 0 on EOF or error. Description cupsRasterReadHeader() reads a page header from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadPixels() Usage unsigned cupsRasterReadPixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to read from. pixels The pointer to a pixel buffer. length The number of bytes of pixel data to read. Returns The number of bytes read or 0 on EOF or error. Description cupsRasterReadPixels() reads pixel data from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterWriteHeader() Usage unsigned cupsRasterWriteHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to write to. header A pointer to the page header to write. Returns 1 on success, 0 on error. Description cupsRasterWriteHeader() writes the specified page header to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWritePixels() cupsRasterWritePixels() Usage unsigned cupsRasterWritePixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to write to. pixels The pixel data to write. length The number of bytes to write. Returns The number of bytes written. Description cupsRasterWritePixels() writes the specified pixel data to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader() cupsServer() Usage const char * cupsServer(void); Returns A pointer to the default server name. Description cupsServer() 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 cupsServer() The default server is determined from the following locations: The CUPS_SERVER environment variable, The ServerName directive in the client.conf file, The default host, "localhost". Example #include <cups/cups.h> const char *server; server = cupsServer(); See Also cupsGetPassword(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetPasswordCB() Usage void cupsSetPasswordCB(const char *(*cb)(const char *prompt)); Arguments Argument Description cb The password callback function. Description cupsSetPasswordCB() 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 NULL if the user did not enter a password string or a pointer to the password string otherwise. Example #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:"); See Also cupsServer(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetServer() Usage void cupsSetServer(const char *server); Arguments Argument Description server The default server to use. Description cupsSetServer() sets the default server to use for the CUPS API. If the server argument is NULL, the default server is used. Example #include <cups/cups.h> cupsSetServer("foo.bar.com"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetUser(), cupsUser() cupsSetUser() Usage void cupsSetUser(const char *user); Arguments Argument Description user The user name string to use. Description cupsSetUser() sets the default user name for authentication. If the user argument is NULL then the current login user is used. Example #include <cups/cups.h> ... cupsSetUser("root"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsUser() cupsTempFile() Usage char * cupsTempFile(char *filename, int length); Arguments Argument Description filename The character string to hold the temporary filename. length The size of the filename string in bytes. Returns A pointer to filename. Description cupsTempFile() generates a temporary filename for the /var/tmp directory or the directory specified by the TMPDIR environment variable. Example #include <cups/cups.h> char filename[256]; cupsTempFile(filename, sizeof(filename)); cupsUser() Usage const char * cupsUser(void); Returns A pointer to the current username or NULL if the user ID is undefined. Description cupsUser() returns the name associated with the current user ID as reported by the getuid() system call. Example #include <cups/cups.h> const char *user; user = cupsUser(); See Also cupsGetPassword(), cupsServer() httpBlocking() Usage void httpBlocking(http_t *http, int blocking) Arguments Argument Description http The HTTP connection blocking 0 if the connection should be non-blocking, 1 if it should be blocking Description The httpBlocking() 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. Example #include <cups/http.h> http_t *http; http = httpConnect("server", port); httpBlocking(http, 0); See Also httpCheck(), httpConnect() httpCheck() Usage int httpCheck(http_t *http); Arguments Argument Description http The HTTP connection Returns 0 if there is no data pending, 1 otherwise. Description The httpCheck() function checks to see if there is any data pending on an HTTP connection. Example #include <cups/http.h> http_t *http; if (httpCheck(http)) { ... do something ... } See Also httpBlocking(), httpConnect(), httpGets(), httpRead() httpClearFields() Usage void httpClearFields(http_t *http) Arguments Argument Description http The HTTP connection Description The httpClearFields() function clears all HTTP request fields for the HTTP connection. Example #include <cups/http.h> http_t *http; httpClearFields(http); See Also httpConnect(), httpGetField(), httpSetField() httpClose() Usage void httpClose(http_t *http); Arguments Argument Description http The HTTP connection Description The httpClose() function closes an active HTTP connection. Example #include <cups/http.h> http_t *http; httpClose(http); See Also httpConnect() httpConnect() Usage http_t *httpConnect(const char *hostname, int port); Arguments Argument Description hostname The name or IP address of the server to connect to port The port number to use Returns A pointer to a HTTP connection structure or NULL if the connection could not be made. Description The httpConnect() function opens a HTTP connection to the specified server and port. Example #include <cups/http.h> http_t *http; http = httpConnect(cupsServer(), ippPort()); See Also httpClose(), httpGet(), httpGets(), httpPost(), httpRead(), httpWrite() httpDecode64() Usage char *httpDecode64(char *out, const char *in); Arguments Argument Description out The output string in The input string Returns A pointer to the decoded string. Description The httpDecode64() function decodes a base-64 encoded string to the original string. Example #include <cups/http.h> char encoded_string[255]; char original_string[255]; httpDecode64(original_string, encoded_string); See Also httpEncode64() httpDelete() Usage int httpDelete(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to delete Returns 0 on success, non-zero on failure. Description The httpDelete() function sends a HTTP DELETE request to the server. Example #include <cups/http.h> http_t *http; httpDelete(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpEncode64() Usage char *httpEncode64(char *out, const char *in); Arguments Argument Description out The output string in The input string Returns A pointer to the encoded string. Description The httpEncode64() function decodes a base-64 encoded string to the original string. Example #include <cups/http.h> char encoded_string[255]; char original_string[255]; httpEncode64(encoded_string, original_string); See Also httpDecode64() httpError() Usage int httpError(http_t *http); Arguments Argument Description http The HTTP connection Returns The last error that occurred or 0 if no error has occurred. Description The httpError() function returns the last error that occurred on the HTTP connection. Example #include <cups/http.h> http_t *http; if (httpError(http)) { ... show an error message ... } See Also httpConnect() httpFlush() Usage void httpFlush(http_t *http); Arguments Argument Description http The HTTP connection Description The httpFlush() function flushes any remaining data left from a GET or POST operation. Example #include <cups/http.h> http_t *http; httpFlush(http); See Also httpConnect(), httpGet() Usage int httpGet(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to get Returns 0 on success, non-zero on failure. Description The httpGet() function sends a HTTP GET request to the server. Example #include <cups/http.h> http_t *http; httpGet(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpGets() Usage char *httpGets(char *line, int length, http_t *http) Arguments Argument Description line The string to fill with a line from the HTTP connection length The maximum length of the string http The HTTP connection Returns A pointer to the string or NULL if no line could be retrieved. Description The httpGets() function is used to read a request line from the HTTP connection. It is not normally used by a client program. Example #include <cups/http.h> http_t *http; char line[1024]; if (httpGets(line, sizeof(line), http)) { ... process the line ... } See Also httpConnect(), httpUpdate() httpGetDateString() Usage const char *httpGetDateString(time_t time) Arguments Argument Description time The UNIX date/time value Returns A pointer to a static string containing the HTTP date/time string for the specified UNIX time value. Description The httpGetDateString() function generates a date/time string suitable for HTTP requests from a UNIX time value. Example #include <cups/http.h> puts(httpGetDateString(time(NULL))); See Also httpGetDateTime() httpGetDateTime() Usage time_t httpGetDateTime(const char *date) Arguments Argument Description date The HTTP date/time string Returns A UNIX time value. Description The httpGetDateTime() function converts a HTTP date/time string to a UNIX time value. Example #include <cups/http.h> printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT")); See Also httpGetDateString() httpGetField() Usage const char *httpGetField(http_t *http, http_field_t field); Arguments Argument Description http The HTTP connection field The HTTP field Returns A pointer to the field value string. Description The httpGetField() function returns the current value for the specified HTTP field. Example #include <cups/http.h> http_t *http; httpGet(http, "/some/uri"); while (httpUpdate(http) == HTTP_CONTINUE); puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE)); See Also httpConnect(), httpSetField() httpHead() Usage int httpHead(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to head Returns 0 on success, non-zero on failure. Description The httpHead() function sends a HTTP HEAD request to the server. Example #include <cups/http.h> http_t *http; httpHead(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpInitialize() Usage void httpInitialize(void); Description The httpInitialize() function initializes the networking code as needed by the underlying platform. It is called automatically by the httpConnect() function. Example #include <cups/http.h> httpInitialize(); See Also httpConnect() httpOptions() Usage int httpOptions(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to check for options Returns 0 on success, non-zero on failure. Description The httpOptions() function sends a HTTP OPTIONS request to the server. Example #include <cups/http.h> http_t *http; httpOptions(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpPost() Usage int httpPost(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to post to Returns 0 on success, non-zero on failure. Description The httpPost() function sends a HTTP POST request to the server. Example #include <cups/http.h> http_t *http; httpPost(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpPrintf() Usage int httpPrintf(http_t *http, const char *format, ...); Arguments Argument Description http The HTTP connection format A printf-style format string Returns The number of bytes written. Description The httpPrintf() function sends a formatted string to the HTTP connection. It is normally only used by the CUPS API and scheduler. Example #include <cups/http.h> http_t *http; httpPrintf(http, "GET / HTTP/1.1 \r\n"); See Also httpConnect() httpPut() Usage int httpPut(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to put Returns 0 on success, non-zero on failure. Description The httpPut() function sends a HTTP PUT request to the server. Example #include <cups/http.h> http_t *http; httpDelete(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpRead() Usage int httpRead(http_t *http, char *buffer, int length); Arguments Argument Description http The HTTP connection buffer The buffer to read into length The number of bytes to read Returns The number of bytes read or -1 on error. Description The httpRead() function reads data from the HTTP connection, possibly the result of a GET or POST request. Example #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); } See Also httpConnect(), httpWrite() httpReconnect() Usage int httpReconnect(http_t *http); Arguments Argument Description http The HTTP connection Returns 0 on success, non-zero on failure. Description The httpReconnect() function reconnects to the HTTP server. This is usually done automatically if the HTTP functions detect that the server connection has terminated. Example #include <cups/http.h> http_t *http; httpReconnect(http); See Also httpConnect() httpSeparate() Usage void httpSeparate(const char *uri, char *method, char *username, char *host, int *port, char *resource); Arguments Argument Description uri The URI to separate method The method (scheme) of the URI username The username (and password) portion of the URI, if any host The hostname portion of the URI, if any port The port number for the URI, either as specified or as default for the method/scheme resource The resource string, usually a filename on the server Description The httpSeparate() function separates the specified URI into its component parts. The method, username, hostname, and resource strings should be at least HTTP_MAX_URI characters long to avoid potential buffer overflow problems. Example 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); See Also httpConnect() httpSetField() Usage void httpSetField(http_t *http, http_field_t field, const char *value); Arguments Argument Description http The HTTP connection field The HTTP field value The string value for the field Description The httpSetField() function sets the current value for the specified HTTP field. Example #include <cups/http.h> http_t *http; httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325")); httpGet(http, "/some/uri"); while (httpUpdate(http) == HTTP_CONTINUE); See Also httpConnect(), httpGetField() httpTrace() Usage int httpTrace(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to trace Returns 0 on success, non-zero on failure. Description The httpTrace() function sends a HTTP TRACE request to the server. Example #include <cups/http.h> http_t *http; httpTrace(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpUpdate() Usage http_status_t httpUpdate(http_t *http); Arguments Argument Description http The HTTP connection Returns The HTTP status of the current request. Description The httpUpdate() 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. Since proxies and the current blocking mode can cause the request to take longer, programs should continue calling httpUpdate() until the return status is not the constant value HTTP_CONTINUE. Example #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); See Also httpConnect(), httpDelete(), httpGet(), httpHead(), httpOptions(), httpPost(), httpPut(), httpTrace() httpWrite() Usage int httpWrite(http_t *http, char *buffer, int length); Arguments Argument Description http The HTTP connection buffer The buffer to read into length The number of bytes to read Returns The number of bytes read or -1 on error. Description The httpWrite() function reads data from the HTTP connection, possibly the result of a GET or POST request. Example #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); } See Also httpConnect(), httpRead() ippAddBoolean() Usage ipp_attribute_t *ippAddBoolean(ipp_t *ipp, ipp_tag_t group, const char *name, char value); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute value The boolean value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddBoolean() function adds a single boolean attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1); See Also ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddBooleans() Usage ipp_attribute_t *ippAddBooleans(ipp_t *ipp, ipp_tag_t group, const char *name, int num_values, const char *values); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute num_values The number of values values The boolean values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddBooleans() function adds one or more boolean attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values false values is created. Example #include <cups/ipp.h> ipp_t *ipp; char values[10]; ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values); See Also ippAddBoolean(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddDate() Usage ipp_attribute_t *ippAddDate(ipp_t *ipp, ipp_tag_t group, const char *name, ipp_uchar_t *value); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute value The date value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddDate() function adds a single date-time attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute", ippTimeToDate(time(NULL)); See Also ippAddBoolean(), ippAddBooleans(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings(), ippTimeToDate() ippAddInteger() Usage ipp_attribute_t *ippAddInteger(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, int value); Arguments Argument Description ipp The IPP request group The IPP group tag The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM) name The name of attribute value The integer value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddInteger() function adds a single integer attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddIntegers() Usage ipp_attribute_t *ippAddIntegers(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, int num_values, const int *values); Arguments Argument Description ipp The IPP request group The IPP group tag The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM) name The name of attribute num_values The number of values values The integer values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddIntegers() function adds one or more integer attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0 values is created. Example #include <cups/ipp.h> ipp_t *ipp; int values[100]; ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddRange() Usage ipp_attribute_t *ippAddRange(ipp_t *ipp, ipp_tag_t group, const char *name, int low, int high); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute low The lower value high The higher value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddRange() function adds a single range attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddRanges() Usage ipp_attribute_t *ippAddRanges(ipp_t *ipp, ipp_tag_t group, const char *name, int num_values, const int *lows, const int *highs); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute num_values The number of range values lows The lower values highs The higher values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddRanges() function adds one or more range attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0,0 ranges is created. Example #include <cups/ipp.h> ipp_t *ipp; int lows[2]; int highs[2]; ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddResolution() Usage ipp_attribute_t *ippAddResolution(ipp_t *ipp, ipp_tag_t group, const char *name, int xres, int yres, ipp_res_t units); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute xres The horizontal resolution yres The vertical resolution units The resolution units Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddResolution() function adds a single resolution attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution", 720, 720, IPP_RES_PER_INCH); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddResolutions() Usage 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); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute num_values The number of resolution values xres The horizontal resolutions yres The vertical resolutions units The resolution units Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddResolutions() function adds one or more resolution attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0,0 resolutions is created. Example #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); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddSeparator() Usage ipp_attribute_t *ippAddSeparator(ipp_t *ipp); Arguments Argument Description ipp The IPP request Returns A pointer to the new separator or NULL if the separator could not be created. Description The ippAddSeparator() function adds a group separator to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddSeparator(ipp); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddString(), ippAddStrings() ippAddString() Usage ipp_attribute_t *ippAddString(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, const char *charset, const char *value); Arguments Argument Description ipp The IPP request group The IPP group tag The type of string value name The name of attribute charset The character set for the string value The string value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddString() function adds a single string attribute value to the specified IPP request. For IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the charset value is provided with the string to identify the string encoding used. Otherwise the charset value is ignored. Example #include <cups/ipp.h> ipp_t *ipp; ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name", NULL, "abc123"); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddStrings() ippAddStrings() Usage 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); Arguments Argument Description ipp The IPP request group The IPP group tag The type of string value name The name of attribute num_values The number of strings charset The character set for the strings values The string values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddStrings() function adds one or more string attribute values to the specified IPP request. For IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the charset value is provided with the strings to identify the string encoding used. Otherwise the charset value is ignored. If the values pointer is NULL then an array of num_values NULL strings is created. Example #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); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString() ippDateToTime() Usage time_t ippDateToTime(const ipp_uchar_t date[11]); Arguments Argument Description date The IPP date-time value Returns A UNIX time value. Description The ippDateToTime() function converts an IPP date-time value to a UNIX time value. Example #include <cups/ipp.h> ipp_uchar_t date[11]; printf("UNIX time is %d\n", ippDateToTime(date)); See Also ippTimeToDate() ippDelete() Usage void ippDelete(ipp_t *ipp); Arguments Argument Description ipp The IPP request or response Description The ippDelete() function deletes all memory used by an IPP request or response. Example #include <cups/ipp.h> ipp_t *ipp; ippDelete(ipp); See Also ippNew() ippFindAttribute() Usage ipp_attribute_t *ippFindAttribute(ipp_t *ipp, const char *name, ipp_tag_t tag); Arguments Argument Description ipp The IPP request or response name The name of the attribute tag The required value tag for the attribute or IPP_TAG_ZERO for any type of value. Returns A pointer to the first occurrence of the requested attribute, or NULL if it was not found. Description ippFindAttribute() finds the first occurrence of the named attribute. The tag parameter restricts the search to a specific value type - use IPP_TAG_ZERO to find any value with the name. The value tags IPP_TAG_NAME and IPP_TAG_TEXT match the name/text values with or without the language code. Example ipp_attribute_t *attr; attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT); See Also cupsDoFileRequest(), cupsDoRequest(), ippDelete(), ippNew() ippLength() Usage int ippLength(ipp_t *ipp); Arguments Argument Description ipp The IPP request or response Returns The total encoded length of the IPP request or response in bytes. Description ippLength() returns the length of the IPP request or response in bytes. Example printf("The length of the response is %d bytes.\n", ippLength(response)); See Also ippDelete(), ippNew() ippNew() Usage ipp_t *ippNew(void); Returns A pointer to a new IPP request or response. Description The ippNew() function creates a new IPP request or response. Example #include <cups/ipp.h> ipp_t *ipp; ipp = ippNew(); See Also ippDelete() ippPort() Usage int ippPort(void); Returns The default TCP/IP port number for IPP requests. Description The ippPort() function returns the default IPP port number for requests. Example #include <cups/http.h> #include <cups/ipp.h> http_t *http; http = httpConnect(cupsServer(), ippPort()); See Also cupsServer(), ippSetPort() ippRead() Usage ipp_state_t ippRead(http_t *http, ipp_t *ipp); Arguments Argument Description http The HTTP connection ipp The IPP request or response Returns The current read state. Description The ippRead() function reads IPP attributes from the specified HTTP connection. Programs should continue calling ippRead() until IPP_ERROR or IPP_DATA is returned. Example #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() ... } See Also ippWrite() ippSetPort() Usage void ippSetPort(int port); Arguments Argument Description port The port number to use Description The ippSetPort() function sets the default IPP port number for requests. Example #include <cups/http.h> #include <cups/ipp.h> ... ippSetPort(8631); See Also ippPort() ippTimeToDate() Usage ipp_uchar_t *ippTimeToDate(time_t time); Arguments Argument Description time The UNIX time value Returns A static pointer to an IPP date-time value. Description The ippTimeToDate() function converts a UNIX time to an IPP date-time value. Example #include <cups/ipp.h> ipp_uchar_t *date; date = ippTimeToDate(time(NULL)); See Also ippDateToTime() ippWrite() Usage ipp_state_t ippWrite(http_t *http, ipp_t *ipp); Arguments Argument Description http The HTTP connection ipp The IPP request or response Returns The current write state. Description The ippWrite() function writes IPP attributes to the specified HTTP connection. Programs should continue calling ippWrite() until IPP_ERROR or IPP_DATA is returned. Example #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() ... } See Also ippRead() ppdClose() Usage void ppdClose(ppd_file_t *ppd); Arguments Argument Description ppd The PPD file Description The ppdClose() function frees all memory associated with the PPD file. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdClose(ppd); See Also ppdOpen(), ppdOpenFd(), ppdOpenFile() ppdConflicts() Usage int ppdConflicts(ppd_file_t *ppd); Arguments Argument Description ppd The PPD file Returns The number of option conflicts in the file. Description The ppdConflicts() function returns the number of conflicts with the currently selected options. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("%d conflicts\n", ppdConflicts(ppd)); See Also cupsMarkOptions(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdEmit() Usage int ppdEmit(ppd_file_t *ppd, FILE *file, ppd_section_t section); Arguments Argument Description ppd The PPD file file The file to write to section The option section to write Returns 0 on success, -1 on error. Description The ppdEmit() function sends printer-specific option commands to the specified file. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdEmit(ppd, stdout, PPD_ORDER_PAGE); See Also ppdEmitFd() ppdEmitFd() Usage int ppdEmitFd(ppd_file_t *ppd, int fd, ppd_section_t section); Arguments Argument Description ppd The PPD file fd The file descriptor to write to section The option section to write Returns 0 on success, -1 on error. Description The ppdEmitFd() function sends printer-specific option commands to the specified file descriptor. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdEmitFd(ppd, 1, PPD_ORDER_PAGE); See Also ppdEmit() ppdFindChoice() Usage ppd_choice_t *ppdFindChoice(ppd_option_t *option, const char *choice); Arguments Argument Description option A pointer to the option choice The name of the choice Returns A pointer to the choice data or NULL if the choice does not exist. Description The ppdFindChoice() function returns a pointer to the choice data for the specified option. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd_option_t *option; ppd_choice_t *choice; option = ppdFindOption(ppd, "PageSize"); choice = ppdFindChoice(option, "Letter"); See Also ppdFindMarkedChoice(), ppdFindOption() ppdFindMarkedChoice() Usage ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword); Arguments Argument Description ppd The PPD file keyword The name of the option Returns A pointer to the choice data or NULL if the choice does not exist or is not marked. Description The ppdFindMarkedChoice() function returns a pointer to the marked choice data for the specified option. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd_choice_t *choice; choice = ppdFindMarkedChoice(ppd, "PageSize"); See Also ppdFindChoice(), ppdFindOption() ppdFindOption() Usage ppd_option_t *ppdFindOption(ppd_file_t *ppd, const char *keyword); Arguments Argument Description ppd The PPD file keyword The name of the option Returns A pointer to the option data or NULL if the option does not exist. Description The ppdFindOption() function returns a pointer to the option data for the specified option. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd_option_t *option; option = ppdFindOption(ppd, "PageSize"); See Also ppdFindChoice(), ppdFindMarkedChoice() ppdIsMarked() Usage int ppdIsMarked(ppd_file_t *ppd, const char *keyword, char char *choice); Arguments Argument Description ppd The PPD file keyword The name of the option choice The name of the option choice Returns 1 if the choice is marked, 0 otherwise. Description The ppdIsMarked() function returns whether or not the specified option choice is marked. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("Letter size %s selected.\n", ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not"); See Also cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdMarkDefaults() Usage void ppdMarkDefaults(ppd_file_t *ppd); Arguments Argument Description ppd The PPD file Description The ppdMarkDefaults() function marks all of the default choices in the PPD file. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdMarkDefaults(ppd); See Also cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdMarkOption() Usage int ppdMarkOption(ppd_file_t *ppd, const char *keyword, const char *choice); Arguments Argument Description ppd The PPD file keyword The name of the option choice The name of the choice Returns The number of conflicts in the PPD file. Description The ppdMarkOption() function marks the specified option choice. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdMarkOption(ppd, "PageSize", "Letter"); See Also cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdOpen() Usage ppd_file_t *ppdOpen(FILE *file); Arguments Argument Description file The file to read from Returns A pointer to a PPD file structure or NULL if the PPD file could not be read. Description The ppdOpen() function reads a PPD file from the specified file into memory. Example #include <cups/ppd.h> ppd_file_t *ppd; FILE *file; file = fopen("filename.ppd", "rb"); ppd = ppdOpen(file); fclose(file); See Also ppdClose(), ppdOpenFd(), ppdOpenFile() ppdOpenFd() Usage ppd_file_t *ppdOpenFd(int fd); Arguments Argument Description fd The file descriptor to read from Returns A pointer to a PPD file structure or NULL if the PPD file could not be read. Description The ppdOpenFd() function reads a PPD file from the specified file descriptor into memory. Example #include <cups/ppd.h> ppd_file_t *ppd; int fd; fd = open("filename.ppd", O_RDONLY); ppd = ppdOpenFd(fd); close(fd); See Also ppdClose(), ppdOpen(), ppdOpenFile() ppdOpenFile() Usage ppd_file_t *ppdOpenFile(const char *filename); Arguments Argument Description filename The name of the file to read from Returns A pointer to a PPD file structure or NULL if the PPD file could not be read. Description The ppdOpenFile() function reads a PPD file from the named file into memory. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd = ppdOpenFile("filename.ppd"); See Also ppdClose(), ppdOpen(), ppdOpenFd() ppdPageLength() Usage float ppdPageLength(ppd_file_t *ppd, const char *name); Arguments Argument Description ppd The PPD file name The name of the page size Returns The length of the specified page size in points or 0 if the page size does not exist. Description The ppdPageLength() function returns the page length of the specified page size. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("Length = %.0f\n", ppdPageLength(ppd, "Letter")); See Also ppdPageLength(), ppdPageSize(), ppdPageWidth() ppdPageSize() Usage ppd_size_t *ppdPageSize(ppd_file_t *ppd, const char *name); Arguments Argument Description ppd The PPD file name The name of the page size Returns A pointer to the page size record of the specified page size in points or NULL if the page size does not exist. Description The ppdPageSize() function returns the page size record for the specified page size. Example #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); } See Also ppdPageLength(), ppdPageWidth() ppdPageWidth() Usage float ppdPageWidth(ppd_file_t *ppd, const char *name); Arguments Argument Description ppd The PPD file name The name of the page size Returns The width of the specified page size in points or 0 if the page size does not exist. Description The ppdPageWidth() function returns the page width of the specified page size. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter")); See Also ppdPageLength(), ppdPageSize()
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)
The CUPS API library provides some basic printing services for applications that need to print files.
The include file used by all of these functions is <cups/cups.h>:
#include <cups/cups.h>
The CUPS API provides two functions for printing files. The first is cupsPrintFile which prints a single named file:
cupsPrintFile
#include <cups/cups.h> ... int jobid; ... jobid = cupsPrintFile("name", "filename", "title", 0, NULL);
The name string is the name of the printer or class to print to. The filename string is the name of the file to print. The title string is the name of the print job, e.g. "Acme Word Document".
name
filename
title
The return value is a unique ID number for the print job or 0 if there was an error.
The second printing function is cupsPrintFiles:
cupsPrintFiles
#include <cups/cups.h> ... int jobid; int num_files; const char *files[100]; ... jobid = cupsPrintFiles("name", num_files, files, "title", 0, NULL);
Instead of passing a filename string as with cupsPrintFile(), you pass a file count (num_files) and filename pointer array (files) for each file that you want to print.
cupsPrintFile()
num_files
files
As with cupsPrintFile(), the return value is a unique ID for the print job.
The cupsCancelJob() function cancels a queued print job:
cupsCancelJob()
#include <cups/cups.h> ... int jobid; int status; ... status = cupsCancelJob("name", jobid);
The name string specifies the destination and is used to determine the server to send the request to. The jobid value is the integer returned from a previous cupsPrintFile() or cupsPrintFiles() call.
jobid
cupsPrintFiles()
cupsCancelJob() returns 1 if the job was successfully cancelled and 0 if there was an error.
1
0
The cupsGetDests() function can be used to get a list of the available printers, classes, and instances that a user has defined:
cupsGetDests()
#include <cups/cups.h> ... int num_dests; cups_dest_t *dests; ... num_dests = cupsGetDests(&dests);
Each destination is stored in a cups_dest_t 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:
cups_dest_t
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;
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 cupsGetDest() function:
cupsGetDest()
#include <cups/cups.h> ... int num_dests; cups_dest_t *dests; cups_dest_t *mydest; ... mydest = cupsGetDest("name", "instance", num_dests, dests);
The name string is the printer or class name. You can pass a value of NULL to get the default destination.
NULL
The instance string is the user-defined instance name. Pass NULL to select the default instance, e.g. "name" instead of "name/instance".
instance
All of the previous printing examples have passed 0 and NULL for the last two arguments to the cupsPrintFile() and cupsPrintFiles() functions. These last two arguments are the number of options and a pointer to the option array:
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);
The cups_option_t structure holds each option and its value. These are converted as needed and passed to the CUPS server when printing a file.
cups_option_t
The simplest way of handling options is to use the num_options and options members of the cups_dest_t structure described earlier:
num_options
options
#include <cups/cups.h> ... int jobid; int num_dests; cups_dest_t *dests; cups_dest_t *mydest; ... mydest = cupsGetDest("name", "instance", num_dests, dests); jobid = cupsPrintFile(mydest->name, "filename", "title", mydest->num_options, mydest->options);
This effectively uses the options a user has previous selected without a lot of code.
Options can also be set by your program using the cupsAddOption() function:
cupsAddOption()
#include <cups/cups.h> ... int num_options; cups_option_t *options; ... num_options = 0; options = NULL; ... num_options = cupsAddOption("name", "value", num_options, &options); num_options = cupsAddOption("name", "value", num_options, &options); num_options = cupsAddOption("name", "value", num_options, &options); num_options = cupsAddOption("name", "value", num_options, &options);
The name string is the name of the option, and the value string is the value for that option.
value
Each call to cupsAddOption() 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 cupsAddOptions() 20 times will result in 20 options.
cupsAddOptions()
Call cupsFreeOptions once you are done using the options:
cupsFreeOptions
#include <cups/cups.h> ... int num_options; cups_option_t *options; ... cupsFreeOptions(num_options, options);
If any of the CUPS API printing functions returns an error, the reason for that error can be found by calling cupsLastError() and cupsErrorString(). cupsLastError() returns the last IPP error code that was encountered. cupsErrorString() converts the error code to a localized message string suitable for presentation to the user:
cupsLastError()
cupsErrorString()
#include <cups/cups.h> ... int jobid; ... if (jobid == 0) puts(cupsErrorString(cupsLastError()));
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.
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.
The cupsSetPasswordCB() function is used to set a password callback in your program. Only one function can be used at any time.
cupsSetPasswordCB()
The cupsSetUser() function sets the current username for authentication. This function can be called by your password callback function to change the current username as needed.
cupsSetUser()
The following example shows a simple password callback that gets a username and password from the user:
#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);
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 cupsUser() to make things easier on the user.
cupsUser()
CUPS includes functions to access and manipulate PostScript Printer Description ("PPD") files that are used with the printer drivers in CUPS.
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.)
Include the <cups/ppd.h> header file to use the PPD functions:
<cups/ppd.h>
#include <cups/ppd.h>
This header file is also included by the <cups/cups.h> header file.
The cupsGetPPD() function retrieves the PPD file for the named printer or class:
cupsGetPPD()
#include <cups/cups.h> ... const char *filename; filename = cupsGetPPD("name");
The name string is the name of the printer or class, including the remote server name as appropriate (e.g. "printer@server".)
The return value is a pointer to a filename in static storage; this value is overwritten with each call to cupsGetPPD(). If the printer or class does not exist, a NULL pointer will be returned.
The ppdOpenFile() function "opens" a PPD file and loads it into memory:
ppdOpenFile()
#include <cups/ppd.h> ... ppd_file_t *ppd; ppd = ppdOpenFile("filename");
The filename string is the name of the file to load, such as the value returned by the cupsGetPPD() function.
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.
Once you are done using a PPD file, call the ppdClose() function to free all memory that has been used:
ppdClose()
#include <cups/ppd.h> ... ppd_file_t *ppd; ... ppdClose(ppd);
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 ppd_file_t structure.
ppd_file_t
Each PPD file contains a number of informational attributes that describe the capabilities of the printer. These are provided in the ppd_file_t structure in the following members:
accurate_screens
int
color_device
colorspace
ppd_cs_t
contone_only
num_emulations emulations
int ppd_emul_t *
flip_duplex
num_fonts fonts
int char **
jcl_begin jcl_ps jcl_end
char *
landscape
lang_encoding
lang_version
language_level
manual_copies
model_number
patches
manufacturer
modelname
nickname
product
shortnickname
throughput
ttrasterizer
variable_sizes
PPD files support multiple options, which are stored in ppd_option_t and ppd_choice_t structures by the PPD functions.
ppd_option_t
ppd_choice_t
Each option in turn is associated with a group stored in the ppd_group_t 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.
ppd_group_t
Groups can also have sub-groups; CUPS currently limits the depth of sub-groups to 1 level to reduce programming complexity.
PPD files support specification of conflict conditions between different options. Conflicts are stored in ppd_conflict_t structures which specify the options that conflict with each other.
ppd_conflict_t
PPD files specify all of the available pages sizes and the physical margins associated with them. These sizes are stored in ppd_size_t structures and are available in the num_sizes and sizes members of the ppd_file_t structure. You can lookup a particular page size with the ppdPageWidth(), ppdPageLength(), and ppdPageSize() functions:
ppd_size_t
num_sizes
sizes
ppdPageWidth()
ppdPageLength()
ppdPageSize()
#include <cups/ppd.h> ... ppd_file_t *ppd; ppd_size_t *size; float width; float length; ... size = ppdPageSize(ppd, "size"); width = ppdPageWidth(ppd, "size"); length = ppdPageLength(ppd, "size");
The size string is the named page size option. The width and length are in points; there are 72 points per inch. The ppd_size_t structure contains the width, length, and margin information:
size
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;
Besides the standard page sizes listed in a PPD file, some printers support variable or custom page sizes. If variables_sizes is non-zero, the custom_min, custom_max, and custom_margins members of the ppd_file_t structure define the limits of the variable sizes.
variables_sizes
custom_min
custom_max
custom_margins
To get the resulting media size, use a page size string of Custom.widthxlength, where width and length are integer values in points:
Custom.widthxlength
width
length
Custom.612x792 [8.5 inches wide, 11 inches long] Custom.1224x792 [17 inches wide, 11 inches long]
Before marking any user-defined options, call the ppdMarkDefaults() function to mark the default options from the PPD file:
ppdMarkDefaults()
#include <cups/ppd.h> ... ppd_file_t *ppd; ... ppdMarkDefaults(ppd);
Then call the ppdMarkOption() function to mark individual options:
ppdMarkOption()
#include <cups/ppd.h> ... ppd_file_t *ppd; int conflicts; ... conflicts = ppdMarkOption(ppd, "name", "value");
The name and value strings choose a particular option and choice, respectively. The return value is 0 if there are not conflicts created by the selection.
CUPS also provides a convenience function for marking all options in the cups_option_t structure:
#include <cups/cups.h> ... ppd_file_t *ppd; int num_options; cups_option_t *options; int conflicts; ... conflicts = cupsMarkOptions(ppd, num_options, options);
The cupsMarkOptions() function also handles mapping the IPP job template attributes to PPD options. The return value is the number of conflicts present.
cupsMarkOptions()
The ppdMarkOption() and cupsMarkOptions() functions return the number of conflicts with the currently marked options.
Call the ppdConflicts() function to get the number of conflicts after you have marked all of the options:
ppdConflicts()
#include <cups/cups.h> ... ppd_file_t *ppd; int conflicts; ... conflicts = ppdConflicts(ppd);
The return value is the number of conflicting options, or 0 if there are no conflicts.
This chapter describes how to write a file filter for CUPS.
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.
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.
The default CUPS configuration runs filters as user "lp" and group "other".
Temporary files should be created in the directory specified by the "TMPDIR" environment variable. The cupsTempFile() function can be used to safely choose temporary files in this directory.
cupsTempFile()
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 LogLevel directive.
LogLevel
The type of message is determined by an initial prefix sent on each line:
DEBUG:
INFO:
WARNING:
ERROR:
PAGE:
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 printer-state-message attribute for the printer, and also added to the error_log unless it is an informational or page accounting message.
printer-state-message
Page accounting messages are used to inform the server when one or more pages are printed. Each line has the form:
PAGE: page-number copy-count
The page-number field is the current page number, starting at 1. The copy-count field specifies the number of copies of that page that was produced.
Page account messages are added to the page_log file and cause the job-sheets-completed attribute to be updated for the job.
job-sheets-completed
Every filter accepts exactly 6 or 7 command-line arguments:
printer job user title copies options [filename]
printer
job
user
originating-user-name
job-name
copies
number-copies
The filename argument is only provided to the first filter in the chain; all filters must be prepared to read the print file from the standard input if the filename argument is omitted.
The copies argument specifies the number of copies to produce of the input file. In general, you should only generate copies if the filename 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 pstops is responsible for copy generation.
pstops
Every filter receives a fixed set of environment variables that can be used by the filter:
CHARSET
CONTENT_TYPE
CUPS_DATADIR
CUPS_SERVERROOT
DEVICE_URI
LANG
PATH
PPD
PRINTER
RIP_CACHE
SOFTWARE
TZ
USER
The HP-GL/2 filter (hpgltops) 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.
hpgltops
The first task of any filter is to ensure that the correct number of command-line arguments are present:
if (argc < 6 || argc > 7) { fputs("ERROR: hpgltops job-id user title copies options [file]\n", stderr); return (1); }
After this you open the print file or read from the standard input as needed:
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); } }
Once the print file has been opened, options can be processed using the cupsParseOptions() and cupsGetOption() functions:
cupsParseOptions()
cupsGetOption()
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;
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.
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:
%!PS-Adobe-3.0 %%BoundingBox: left bottom right top %%Pages: (atend) %%EndComments
The left, bottom, right, and top values are integers in points from the lower-lefthand corner of the page.
Pages must be surrounded by:
%%Page: number number gsave ... grestore showpage
And the end of each file must contain:
%%Trailer %%Pages: number-pages %%EOF
These comments allow the PostScript filter to correctly perform page accounting, copy generation, N-up printing, and so forth.
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.
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.
CUPS raster data (application/vnd.cups-raster) consists of a stream of raster page descriptions produced by one of the RIP filters, such as pstoraster or imagetoraster.
application/vnd.cups-raster
pstoraster
imagetoraster
Each page of data begins with a page dictionary structure called cups_raster_header_t. This structure contains the colorspace, bits per color, media size, media type, hardware resolution, and so forth.
cups_raster_header_t
After the page dictionary comes the page data which is a full-resolution, uncompressed bitmap representing the page in the printer's output colorspace.
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.
Printer drivers can implement their color management via the cupsColorProfile 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.
cupsColorProfile
For example, the pstoraster 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.
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:
CUPS_ORDER_CHUNKED
CUPS_ORDER_BANDED
CUPS_ORDER_PLANAR
CUPS_CSPACE_W
CUPS_CSPACE_RGB
CUPS_CSPACE_RGBA
CUPS_CSPACE_K
CUPS_CSPACE_CMY
CUPS_CSPACE_YMC
CUPS_CSPACE_CMYK
CUPS_CSPACE_YMCK
CUPS_CSPACE_KCMY
CUPS_CSPACE_KCMYcm
CUPS_CSPACE_GMCK
CUPS_CSPACE_GMCS
CUPS_CSPACE_WHITE
CUPS_CSPACE_GOLD
CUPS_CSPACE_SILVER
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.
The HP-PCL driver provided with CUPS (rastertohp) 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 - deskjet.ppd or laserjet.ppd.
rastertohp
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.
A typical CUPS printer driver will include ColorModel, InputSlot, PageSize, PageRegion, and Resolution options. Each option is shown using the standard PPD format:
ColorModel
InputSlot
PageSize
PageRegion
Resolution
*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
The OpenUI 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.
OpenUI
Every option must have a default value, specified using the DefaultOption keyword.
DefaultOption
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:
*PageSize A4/A4: "<</PageSize[595 842]/ImagingBBox null>> setpagedevice"
or broken down on separate lines using the End keyword to terminate them:
End
*PageSize A4/A4: "<< /PageSize [595 842] /ImagingBBox null >> setpagedevice" *End
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.
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 cupsRasterOpen() function opens a raster stream for printing:
cupsRasterOpen()
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);
Once you have opened the raster stream you just need to read each page and print it:
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 ... } }
After you have processed all pages, close the raster stream and return:
cupsRasterClose(ras); return (0);
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.
Backends are special filters that communicate with printers directly. They are treated slightly differently than filters, however, and have some unique requirements.
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.
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.
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.
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.
Backends that talk to local character or block devices should open the device file in exclusive mode (O_EXCL) to cooperate with other printers defined for the same device.
O_EXCL
All backends must 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.
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.
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.
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...)
The serial backend lists devices by looking at serial port files in the /dev directory, by consulting a hardware inventory (IRIX), and in some cases by trying to open the ports to see if they actually exist.
Once it finds a serial port it writes a single line for each port to the standard error file. Each line looks like this:
serial serial:/dev/ttyS0?baud=115200 "Unknown" "Serial Port 1"
The first word "serial" is the device class; this identifies the class of device which can be used to categorize it in user interfaces. CUPS currently recognizes the following classes:
After the device class is the device URI, 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.
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.
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 do-while loop:
do-while
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);
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.
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:
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; }
The check for the ENOTTY error is needed on some platforms to clear an error from a previous ioctl() call.
ENOTTY
ioctl()
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.
This appendix lists all of the constants that are defined by the CUPS API.
The CUPS_VERSION 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.
CUPS_VERSION
The CUPS_PRINTER constants represent capability bits for printers and classes:
CUPS_PRINTER
CUPS_PRINTER_LOCAL
CUPS_PRINTER_REMOTE
CUPS_PRINTER_CLASS
CUPS_PRINTER_BW
CUPS_PRINTER_COLOR
CUPS_PRINTER_DUPLEX
CUPS_PRINTER_STAPLE
CUPS_PRINTER_COPIES
CUPS_PRINTER_COLLATE
CUPS_PRINTER_PUNCH
CUPS_PRINTER_COVER
CUPS_PRINTER_BIND
CUPS_PRINTER_SORT
CUPS_PRINTER_SMALL
CUPS_PRINTER_MEDIUM
CUPS_PRINTER_LARGE
CUPS_PRINTER_VARIABLE
CUPS_PRINTER_IMPLICIT
CUPS_PRINTER_OPTIONS
CUPS defines the following character set encoding constants:
CUPS_US_ASCII
CUPS_UTF_8
CUPS_ISO8859_1
CUPS_ISO8859_2
CUPS_ISO8859_3
CUPS_ISO8859_4
CUPS_ISO8859_5
CUPS_ISO8859_6
CUPS_ISO8859_7
CUPS_ISO8859_8
CUPS_ISO8859_9
CUPS_ISO8859_10
CUPS_ISO8859_13
CUPS_ISO8859_14
CUPS_ISO8859_15
CUPS_WINDOWS_874
CUPS_WINDOWS_1250
CUPS_WINDOWS_1251
CUPS_WINDOWS_1252
CUPS_WINDOWS_1253
CUPS_WINDOWS_1254
CUPS_WINDOWS_1255
CUPS_WINDOWS_1256
CUPS_WINDOWS_1257
CUPS_WINDOWS_1258
CUPS_KOI8_R
CUPS_KOI8_U
The following constants define the limits for strings:
HTTP_MAX_BUFFER
HTTP_MAX_HOST
HTTP_MAX_URI
HTTP_MAX_VALUE
The following status codes can be returned by httpUpdate():
httpUpdate()
HTTP_ERROR
HTTP_CONTINUE
HTTP_OK
HTTP_CREATED
HTTP_ACCEPTED
HTTP_NOT_AUTHORITATIVE
HTTP_NO_CONTENT
HTTP_RESET_CONTENT
HTTP_PARTIAL_CONTENT
HTTP_MULTIPLE_CHOICES
HTTP_MOVED_PERMANENTLY
HTTP_MOVED_TEMPORARILY
HTTP_SEE_OTHER
HTTP_NOT_MODIFIED
HTTP_USE_PROXY
HTTP_BAD_REQUEST
HTTP_UNAUTHORIZED
HTTP_PAYMENT_REQUIRED
HTTP_FORBIDDEN
HTTP_NOT_FOUND
HTTP_METHOD_NOT_ALLOWED
HTTP_NOT_ACCEPTABLE
HTTP_PROXY_AUTHENTICATION
HTTP_REQUEST_TIMEOUT
HTTP_CONFLICT
HTTP_GONE
HTTP_LENGTH_REQUIRED
HTTP_PRECONDITION
HTTP_REQUEST_TOO_LARGE
HTTP_URI_TOO_LONG
HTTP_UNSUPPORTED_MEDIATYPE
HTTP_SERVER_ERROR
HTTP_NOT_IMPLEMENTED
HTTP_BAD_GATEWAY
HTTP_SERVICE_UNAVAILABLE
HTTP_GATEWAY_TIMEOUT
HTTP_NOT_SUPPORTED
The following fields are indices for each of the standard HTTP fields in HTTP 1/1:
HTTP_FIELD_ACCEPT_LANGUAGE
HTTP_FIELD_ACCEPT_RANGES
HTTP_FIELD_AUTHORIZATION
HTTP_FIELD_CONNECTION
HTTP_FIELD_CONTENT_ENCODING
HTTP_FIELD_CONTENT_LANGUAGE
HTTP_FIELD_CONTENT_LENGTH
HTTP_FIELD_CONTENT_LOCATION
HTTP_FIELD_CONTENT_MD5
HTTP_FIELD_CONTENT_RANGE
HTTP_FIELD_CONTENT_TYPE
HTTP_FIELD_CONTENT_VERSION
HTTP_FIELD_DATE
HTTP_FIELD_HOST
HTTP_FIELD_IF_MODIFIED_SINCE
HTTP_FIELD_IF_UNMODIFIED_SINCE
HTTP_FIELD_KEEP_ALIVE
HTTP_FIELD_LAST_MODIFIED
HTTP_FIELD_LINK
HTTP_FIELD_LOCATION
HTTP_FIELD_RANGE
HTTP_FIELD_REFERER
HTTP_FIELD_RETRY_AFTER
HTTP_FIELD_TRANSFER_ENCODING
HTTP_FIELD_UPGRADE
HTTP_FIELD_USER_AGENT
HTTP_FIELD_WWW_AUTHENTICATE
The following constants define array limits for IPP data:
IPP_MAX_NAME
IPP_MAX_VALUES
IPP_TAG_ZERO
IPP_TAG_OPERATION
IPP_TAG_JOB
IPP_TAG_END
IPP_TAG_PRINTER
IPP_TAG_UNSUPPORTED_GROUP
IPP_TAG_UNSUPPORTED_VALUE
IPP_TAG_DEFAULT
IPP_TAG_UNKNOWN
IPP_TAG_NOVALUE
IPP_TAG_NOTSETTABLE
IPP_TAG_DELETEATTR
IPP_TAG_ANYVALUE
IPP_TAG_INTEGER
IPP_TAG_BOOLEAN
IPP_TAG_ENUM
IPP_TAG_STRING
IPP_TAG_DATE
IPP_TAG_RESOLUTION
IPP_TAG_RANGE
IPP_TAG_COLLECTION
IPP_TAG_TEXTLANG
IPP_TAG_NAMELANG
IPP_TAG_TEXT
IPP_TAG_NAME
IPP_TAG_KEYWORD
IPP_TAG_URI
IPP_TAG_URISCHEME
IPP_TAG_CHARSET
IPP_TAG_LANGUAGE
IPP_TAG_MIMETYPE
The IPP_RES_PER_INCH and IPP_RES_PER_CM constants specify dots per inch and dots per centimeter, respectively.
IPP_RES_PER_INCH
IPP_RES_PER_CM
The finishing values specify special finishing operations to be performed on the job.
IPP_FINISH_NONE
IPP_FINISH_STAPLE
IPP_FINISH_PUNCH
IPP_FINISH_COVER
IPP_FINISH_BIND
The orientation values specify the orientation of the job.
IPP_PORTRAIT
IPP_LANDSCAPE
IPP_REVERSE_LANDSCAPE
IPP_REVERSE_PORTRAIT
The quality values specify the desired quality of the print.
IPP_QUALITY_DRAFT
IPP_QUALITY_NORMAL
IPP_QUALITY_HIGH
The job state values are used to represent the current job state.
IPP_JOB_PENDING
IPP_JOB_HELD
IPP_JOB_PROCESSING
IPP_JOB_STOPPED
IPP_JOB_CANCELLED
IPP_JOB_ABORTED
IPP_JOB_COMPLETED
The printer state values are used to represent the current printer state.
IPP_PRINTER_IDLE
IPP_PRINTER_PROCESSING
IPP_PRINTER_STOPPED
The operation values represent the available IPP operations.
IPP_PRINT_JOB
IPP_PRINT_URI
IPP_VALIDATE_JOB
IPP_CREATE_JOB
IPP_SEND_DOCUMENT
IPP_SEND_URI
IPP_CANCEL_JOB
IPP_GET_JOB_ATTRIBUTES
IPP_GET_JOBS
IPP_GET_PRINTER_ATTRIBUTES
IPP_HOLD_JOB
IPP_RELEASE_JOB
IPP_RESTART_JOB
IPP_PAUSE_PRINTER
IPP_RESUME_PRINTER
IPP_PURGE_JOBS
IPP_SET_PRINTER_ATTRIBUTES
IPP_SET_JOB_ATTRIBUTES
IPP_GET_PRINTER_SUPPORTED_VALUES
CUPS_GET_DEFAULT
CUPS_GET_PRINTERS
CUPS_ADD_PRINTER
CUPS_DELETE_PRINTER
CUPS_GET_CLASSES
CUPS_ADD_CLASS
CUPS_DELETE_CLASS
CUPS_ACCEPT_JOBS
CUPS_REJECT_JOBS
CUPS_SET_DEFAULT
CUPS_GET_DEVICES
CUPS_GET_PPDS
CUPS_MOVE_JOB
Status codes are returned by all IPP requests.
IPP_OK
IPP_OK_SUBST
IPP_OK_CONFLICT
IPP_BAD_REQUEST
IPP_FORBIDDEN
IPP_NOT_AUTHENTICATED
IPP_NOT_AUTHORIZED
IPP_NOT_POSSIBLE
IPP_TIMEOUT
IPP_NOT_FOUND
IPP_GONE
IPP_REQUEST_ENTITY
IPP_REQUEST_VALUE
IPP_DOCUMENT_FORMAT
IPP_ATTRIBUTES
IPP_URI_SCHEME
IPP_CHARSET
IPP_CONFLICT
IPP_COMPRESSION_NOT_SUPPORTED
IPP_COMPRESSION_ERROR
IPP_DOCUMENT_FORMAT_ERROR
IPP_DOCUMENT_ACCESS_ERROR
IPP_INTERNAL_ERROR
IPP_OPERATION_NOT_SUPPORTED
IPP_SERVICE_UNAVAILABLE
IPP_VERSION_NOT_SUPPORTED
IPP_DEVICE_ERROR
IPP_TEMPORARY_ERROR
IPP_NOT_ACCEPTING
IPP_PRINTER_BUSY
IPP_ERROR_JOB_CANCELLED
IPP_MULTIPLE_JOBS_NOT_SUPPORTED
The PPD_VERSION constant defines a floating point number representing the newest format version that is supported by CUPS, currently 4.3.
PPD_VERSION
Each printer option has a type associated with it:
PPD_UI_BOOLEAN
PPD_UI_PICKONE
PPD_UI_PICKMANY
Some options must be output before others, or in different sections of the output document. The ppd_section_t enumeration defines which section the option must be output in:
ppd_section_t
PPD_ORDER_ANY
PPD_ORDER_DOCUMENT
PPD_ORDER_EXIT
PPD_ORDER_JCL
PPD_ORDER_PAGE
PPD_ORDER_PROLOG
Each printer has a default colorspace:
PPD_CS_CMYK
PPD_CS_CMY
PPD_CS_GRAY
PPD_CS_RGB
PPD_CS_RGBK
PPD_CS_N
The CUPS_RASTER_SYNC and CUPS_RASTER_REVSYNC constants define the standard sync words at the beginning of each CUPS raster file.
CUPS_RASTER_SYNC
CUPS_RASTER_REVSYNC
The CUPS_RASTER_READ and CUPS_RASTER_WRITE constants are used with the cupsRasterOpen() function to specify a stream for reading or writing.
CUPS_RASTER_READ
CUPS_RASTER_WRITE
The CUPS_FALSE and CUPS_TRUE constants represent boolean values in the page header.
CUPS_FALSE
CUPS_TRUE
The cups_jog_t enumeration defines constants for the Jog page device dictionary variable:
cups_jog_t
CUPS_JOG_NONE
CUPS_JOG_FILE
CUPS_JOG_JOB
CUPS_JOG_SET
The cups_orient_t enumeration defines constants for the Orientation page device dictionary variable:
cups_orient_t
CUPS_ORIENT_0
CUPS_ORIENT_90
CUPS_ORIENT_180
CUPS_ORIENT_270
The cups_cut_t enumeration defines constants for the CutMedia page device dictionary variable:
cups_cut_t
CUPS_CUT_NONE
CUPS_CUT_FILE
CUPS_CUT_JOB
CUPS_CUT_SET
CUPS_CUT_PAGE
The cups_advance_t enumeration defines constants for the AdvanceMedia page device dictionary variable:
cups_advance_t
CUPS_ADVANCE_NONE
CUPS_ADVANCE_FILE
CUPS_ADVANCE_JOB
CUPS_ADVANCE_SET
CUPS_ADVANCE_PAGE
The cups_edge_t enumeration defines constants for the LeadingEdge page device dictionary variable:
cups_edge_t
CUPS_EDGE_TOP
CUPS_EDGE_RIGHT
CUPS_EDGE_BOTTOM
CUPS_EDGE_LEFT
The cups_order_t enumeration defines the possible color value orderings:
cups_order_t
The cups_cspace_t enumeration defines the possible colorspaces:
cups_cspace_t
This appendix describes all of the structures that are defined by the CUPS API.
The CUPS destination structure (cups_dest_t) contains information on a specific destination or instance:
The CUPS job structure (cups_job_t) contains information on a specific job:
cups_job_t
The CUPS messages structure (cups_lang_t) contains the character set, locale name, and messages array:
cups_lang_t
The CUPS option structure (cups_option_t) contains the option name and string value:
The HTTP state structure (http_t) contains the current state of a HTTP request or response:
http_t
The IPP state structure (ipp_t) contains the current state of a IPP request or response:
ipp_t
The raster page header (cups_raster_header_t) consists of the PostScript page device dictionary for the page:
This appendix provides a reference for all of the CUPS API functions.
int cupsAddOption(const char *name, const char *value, int num_options, cups_option_t **options);
The new number of options.
cupsAddOption() adds an option to the specified array.
#include <cups.h> ... /* Declare the options array */ int num_options; cups_option_t *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);
cupsFreeOptions()
int cupsCancelJob(const char *dest, int job);
1 on success, 0 on failure. On failure the error can be found by calling cupsLastError().
cupsCancelJob() cancels the specifies job.
#include <cups.h> cupsCancelJob("LaserJet", 1);
cupsLastError(), cupsPrintFile()
ipp_t * cupsDoFileRequest(http_t *http, ipp_t *request, const char *resource, const char *filename);
IPP response data or NULL if the request fails. On failure the error can be found by calling cupsLastError().
cupsDoFileRequest() 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.
cupsDoFileRequest()
#include <cups.h> http_t *http; cups_lang_t *language; ipp_t *request; ipp_t *response; ... /* Get the default language */ language = cupsLangDefault(); /* Create a new IPP request */ request = ippNew(); request->request.op.operation_id = IPP_PRINT_FILE; request->request.op.request_id = 1; /* Add required attributes */ ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET, "attributes-charset", NULL, cupsLangEncoding(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, cupsUser()); /* Do the request... */ response = cupsDoFileRequest(http, request, "/resource", "filename.txt");
cupsLangDefault(), cupsLangEncoding(), cupsUser(), httpConnect(), ippAddString(), ippNew()
cupsLangDefault()
cupsLangEncoding()
httpConnect()
ippAddString()
ippNew()
ipp_t * cupsDoRequest(http_t *http, ipp_t *request, const char *resource);
cupsDoRequest() 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.
cupsDoRequest()
#include <cups.h> http_t *http; cups_lang_t *language; ipp_t *request; ipp_t *response; ... /* Get the default language */ language = cupsLangDefault(); /* Create a new IPP request */ request = ippNew(); request->request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES; request->request.op.request_id = 1; /* Add required attributes */ ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET, "attributes-charset", NULL, cupsLangEncoding(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");
void cupsFreeOptions(int num_options, cups_option_t *options); Arguments Argument Description num_options Number of options in array. options Pointer to options array. Description cupsFreeOptions() frees all memory associated with the option array specified. Example #include <cups/cups.h> int num_options; cups_option_t *options; ... cupsFreeOptions(num_options, options); See Also cupsAddOption(), cupsGetOption(), cupsMarkOptions(), cupsParseOptions() cupsGetClasses() Usage int cupsGetClasses(char ***classes); Arguments Argument Description classes Pointer to character pointer array. Returns The number of printer classes available. Description cupsGetClasses() gets a list of the available printer classes. The returned array should be freed using the free() when it is no longer needed. Example #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); } See Also cupsGetDefault(), cupsGetPrinters() cupsGetDefault() Usage const char * cupsGetDefault(void); Returns A pointer to the default destination. Description cupsGetDefault() 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. Example #include <cups/cups.h> printf("The default destination is %s\n", cupsGetDefault()); See Also cupsGetClasses(), cupsGetPrinters() cupsGetOption() Usage const char * cupsGetOption(const char *name, int num_options, cups_option_t *options); Arguments Argument Description name The name of the option. num_options The number of options in the array. options The options array. Returns A pointer to the option values or NULL if the option is not defined. Description cupsGetOption() returns the first occurrence of the named option. If the option is not included in the options array then a NULL pointer is returned. #include <cups/cups.h> int num_options; cups_option_t *options; const char *media; ... media = cupsGetOption("media", num_options, options); See Also cupsAddOption(), cupsFreeOptions(), cupsMarkOptions(), cupsParseOptions() cupsGetPassword() Usage const char * cupsGetPassword(const char *prompt); Arguments Argument Description prompt The prompt to display to the user. Returns A pointer to the password that was entered or NULL if no password was entered. Description cupsGetPassword() displays the prompt string and asks the user for a password. The password text is not echoed to the user. Example #include <cups/cups.h> char *password; ... password = cupsGetPassword("Please enter a password:"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser() cupsGetPPD() Usage const char * cupsGetPPD(const char *printer); Arguments Argument Description printer The name of the printer. Returns The name of a temporary file containing the PPD file or NULL if the printer cannot be located or does not have a PPD file. Description cupsGetPPD() gets a copy of the PPD file for the named printer. The printer name can be of the form "printer" or "printer@hostname". 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 cupsGetPPD(). Example #include <cups/cups.h> char *ppd; ... ppd = cupsGetPPD("printer@hostname"); ... unlink(ppd); cupsGetPrinters() Usage int cupsGetPrinters(char ***printers); Arguments Argument Description printers Pointer to character pointer array. Returns The number of printer printers available. Description cupsGetPrinters() gets a list of the available printers. The returned array should be freed using the free() when it is no longer needed. Example #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); } See Also cupsGetClasses(), cupsGetDefault() cupsLangDefault() Usage const char * cupsLangDefault(void); Returns A pointer to the default language structure. Description cupsLangDefault() returns a language structure for the default language. The default language is defined by the LANG environment variable. If the specified language cannot be located then the POSIX (English) locale is used. Call cupsLangFree() to free any memory associated with the language structure when you are done. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangDefault(); ... cupsLangFree(language); See Also cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangEncoding() Usage char * cupsLangEncoding(cups_lang_t *language); Arguments Argument Description language The language structure. Returns A pointer to the encoding string. Description cupsLangEncoding() returns the language encoding used for the specified language, e.g. "iso-8859-1", "utf-8", etc. Example #include <cups/language.h> cups_lang_t *language; char *encoding; ... language = cupsLangDefault(); encoding = cupsLangEncoding(language); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFlush() Usage void cupsLangFlush(void); Description cupsLangFlush() frees all language structures that have been allocated. Example #include <cups/language.h> ... cupsLangFlush(); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFree() Usage void cupsLangFree(cups_lang_t *language); Arguments Argument Description language The language structure to free. Description cupsLangFree() frees the specified language structure. Example #include <cups/language.h> cups_lang_t *language; ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangGet(), cupsLangString() cupsLangGet() Usage cups_lang_t * cupsLangGet(const char *name); Arguments Argument Description name The name of the locale. Returns A pointer to a language structure. Description cupsLangGet() returns a language structure for the specified locale. If the locale is not defined then the POSIX (English) locale is substituted. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangGet("fr"); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangString() cupsLangString() Usage char * cupsLangString(cups_lang_t *language, int message); Arguments Argument Description language The language to query. message The message number. Returns A pointer to the message string or NULL if the message is not defined. Description cupsLangString() returns a pointer to the specified message string in the specified language. Example #include <cups/language.h> cups_lang_t *language; char *s; ... language = cupsLangGet("fr"); s = cupsLangString(language, CUPS_MSG_YES); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet() cupsLastError() Usage ipp_status_t cupsLastError(void); Returns An enumeration containing the last IPP error. Description cupsLastError() returns the last IPP error that occurred. If no error occurred then it will return IPP_OK or IPP_OK_CONFLICT. Example #include <cups/cups.h> ipp_status_t status; ... status = cupsLastError(); See Also cupsCancelJob(), cupsPrintFile() cupsMarkOptions() Usage int cupsMarkOptions(ppd_file_t *ppd, int num_options, cups_option_t *options); Arguments Argument Description ppd The PPD file to mark. num_options The number of options in the options array. options A pointer to the options array. Returns The number of conflicts found. Description cupsMarkOptions() marks options in the PPD file. It also handles mapping of IPP option names and values to PPD option names. Example #include <cups/cups.h> int num_options; cups_option_t *options; ppd_file_t *ppd; ... cupsMarkOptions(ppd, num_options, options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsParseOptions() cupsParseOptions() Usage int cupsParseOptions(const char *arg, int num_options, cups_option_t **options); Arguments Argument Description arg The string containing one or more options. num_options The number of options in the options array. options A pointer to the options array pointer. Returns The new number of options in the array. Description cupsParseOptions() 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. Example #include <cups/cups.h> int num_options; cups_option_t *options; ... num_options = 0; options = (cups_option_t *)0; num_options = cupsParseOptions(argv[5], num_options, &options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsMarkOptions() cupsPrintFile() Usage int cupsPrintFile(const char *printer, const char *filename, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. filename The file to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFile() 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 cupsLastError(). Example #include <cups/cups.h> int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFiles() cupsPrintFiles() Usage int cupsPrintFiles(const char *printer, int num_files, const char **files, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. num_files The number of files to print. files The files to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFiles() 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 cupsLastError(). Example #include <cups/cups.h> int num_files; const char *files[100]; int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFiles("printer@hostname", num_files, files, "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFile() cupsRasterClose() Usage void cupsRasterClose(cups_raster_t *ras); Arguments Argument Description ras The raster stream to close. Description cupsRasterClose() closes the specified raster stream. Example #include <cups/raster.h> cups_raster_t *ras; ... cupsRasterClose(ras); See Also cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterOpen() Usage cups_raster_t * cupsRasterOpen(int fd, cups_mode_t mode); Arguments Argument Description fd The file descriptor to use. mode The mode to use; CUPS_RASTER_READ or CUPS_RASTER_WRITE. Returns A pointer to a raster stream or NULL if there was an error. Description cupsRasterOpen() opens a raster stream for reading or writing. Example #include <cups/raster.h> cups_raster_t *ras; ... ras = cupsRasterOpen(0, CUPS_RASTER_READ); See Also cupsRasterClose(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadHeader() Usage unsigned cupsRasterReadHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to read from. header A pointer to a page header structure to read into. Returns 1 on success, 0 on EOF or error. Description cupsRasterReadHeader() reads a page header from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadPixels() Usage unsigned cupsRasterReadPixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to read from. pixels The pointer to a pixel buffer. length The number of bytes of pixel data to read. Returns The number of bytes read or 0 on EOF or error. Description cupsRasterReadPixels() reads pixel data from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterWriteHeader() Usage unsigned cupsRasterWriteHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to write to. header A pointer to the page header to write. Returns 1 on success, 0 on error. Description cupsRasterWriteHeader() writes the specified page header to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWritePixels() cupsRasterWritePixels() Usage unsigned cupsRasterWritePixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to write to. pixels The pixel data to write. length The number of bytes to write. Returns The number of bytes written. Description cupsRasterWritePixels() writes the specified pixel data to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader() cupsServer() Usage const char * cupsServer(void); Returns A pointer to the default server name. Description cupsServer() 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 cupsServer() The default server is determined from the following locations: The CUPS_SERVER environment variable, The ServerName directive in the client.conf file, The default host, "localhost". Example #include <cups/cups.h> const char *server; server = cupsServer(); See Also cupsGetPassword(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetPasswordCB() Usage void cupsSetPasswordCB(const char *(*cb)(const char *prompt)); Arguments Argument Description cb The password callback function. Description cupsSetPasswordCB() 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 NULL if the user did not enter a password string or a pointer to the password string otherwise. Example #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:"); See Also cupsServer(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetServer() Usage void cupsSetServer(const char *server); Arguments Argument Description server The default server to use. Description cupsSetServer() sets the default server to use for the CUPS API. If the server argument is NULL, the default server is used. Example #include <cups/cups.h> cupsSetServer("foo.bar.com"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetUser(), cupsUser() cupsSetUser() Usage void cupsSetUser(const char *user); Arguments Argument Description user The user name string to use. Description cupsSetUser() sets the default user name for authentication. If the user argument is NULL then the current login user is used. Example #include <cups/cups.h> ... cupsSetUser("root"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsUser() cupsTempFile() Usage char * cupsTempFile(char *filename, int length); Arguments Argument Description filename The character string to hold the temporary filename. length The size of the filename string in bytes. Returns A pointer to filename. Description cupsTempFile() generates a temporary filename for the /var/tmp directory or the directory specified by the TMPDIR environment variable. Example #include <cups/cups.h> char filename[256]; cupsTempFile(filename, sizeof(filename)); cupsUser() Usage const char * cupsUser(void); Returns A pointer to the current username or NULL if the user ID is undefined. Description cupsUser() returns the name associated with the current user ID as reported by the getuid() system call. Example #include <cups/cups.h> const char *user; user = cupsUser(); See Also cupsGetPassword(), cupsServer() httpBlocking() Usage void httpBlocking(http_t *http, int blocking) Arguments Argument Description http The HTTP connection blocking 0 if the connection should be non-blocking, 1 if it should be blocking Description The httpBlocking() 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. Example #include <cups/http.h> http_t *http; http = httpConnect("server", port); httpBlocking(http, 0); See Also httpCheck(), httpConnect() httpCheck() Usage int httpCheck(http_t *http); Arguments Argument Description http The HTTP connection Returns 0 if there is no data pending, 1 otherwise. Description The httpCheck() function checks to see if there is any data pending on an HTTP connection. Example #include <cups/http.h> http_t *http; if (httpCheck(http)) { ... do something ... } See Also httpBlocking(), httpConnect(), httpGets(), httpRead() httpClearFields() Usage void httpClearFields(http_t *http) Arguments Argument Description http The HTTP connection Description The httpClearFields() function clears all HTTP request fields for the HTTP connection. Example #include <cups/http.h> http_t *http; httpClearFields(http); See Also httpConnect(), httpGetField(), httpSetField() httpClose() Usage void httpClose(http_t *http); Arguments Argument Description http The HTTP connection Description The httpClose() function closes an active HTTP connection. Example #include <cups/http.h> http_t *http; httpClose(http); See Also httpConnect() httpConnect() Usage http_t *httpConnect(const char *hostname, int port); Arguments Argument Description hostname The name or IP address of the server to connect to port The port number to use Returns A pointer to a HTTP connection structure or NULL if the connection could not be made. Description The httpConnect() function opens a HTTP connection to the specified server and port. Example #include <cups/http.h> http_t *http; http = httpConnect(cupsServer(), ippPort()); See Also httpClose(), httpGet(), httpGets(), httpPost(), httpRead(), httpWrite() httpDecode64() Usage char *httpDecode64(char *out, const char *in); Arguments Argument Description out The output string in The input string Returns A pointer to the decoded string. Description The httpDecode64() function decodes a base-64 encoded string to the original string. Example #include <cups/http.h> char encoded_string[255]; char original_string[255]; httpDecode64(original_string, encoded_string); See Also httpEncode64() httpDelete() Usage int httpDelete(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to delete Returns 0 on success, non-zero on failure. Description The httpDelete() function sends a HTTP DELETE request to the server. Example #include <cups/http.h> http_t *http; httpDelete(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpEncode64() Usage char *httpEncode64(char *out, const char *in); Arguments Argument Description out The output string in The input string Returns A pointer to the encoded string. Description The httpEncode64() function decodes a base-64 encoded string to the original string. Example #include <cups/http.h> char encoded_string[255]; char original_string[255]; httpEncode64(encoded_string, original_string); See Also httpDecode64() httpError() Usage int httpError(http_t *http); Arguments Argument Description http The HTTP connection Returns The last error that occurred or 0 if no error has occurred. Description The httpError() function returns the last error that occurred on the HTTP connection. Example #include <cups/http.h> http_t *http; if (httpError(http)) { ... show an error message ... } See Also httpConnect() httpFlush() Usage void httpFlush(http_t *http); Arguments Argument Description http The HTTP connection Description The httpFlush() function flushes any remaining data left from a GET or POST operation. Example #include <cups/http.h> http_t *http; httpFlush(http); See Also httpConnect(), httpGet() Usage int httpGet(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to get Returns 0 on success, non-zero on failure. Description The httpGet() function sends a HTTP GET request to the server. Example #include <cups/http.h> http_t *http; httpGet(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpGets() Usage char *httpGets(char *line, int length, http_t *http) Arguments Argument Description line The string to fill with a line from the HTTP connection length The maximum length of the string http The HTTP connection Returns A pointer to the string or NULL if no line could be retrieved. Description The httpGets() function is used to read a request line from the HTTP connection. It is not normally used by a client program. Example #include <cups/http.h> http_t *http; char line[1024]; if (httpGets(line, sizeof(line), http)) { ... process the line ... } See Also httpConnect(), httpUpdate() httpGetDateString() Usage const char *httpGetDateString(time_t time) Arguments Argument Description time The UNIX date/time value Returns A pointer to a static string containing the HTTP date/time string for the specified UNIX time value. Description The httpGetDateString() function generates a date/time string suitable for HTTP requests from a UNIX time value. Example #include <cups/http.h> puts(httpGetDateString(time(NULL))); See Also httpGetDateTime() httpGetDateTime() Usage time_t httpGetDateTime(const char *date) Arguments Argument Description date The HTTP date/time string Returns A UNIX time value. Description The httpGetDateTime() function converts a HTTP date/time string to a UNIX time value. Example #include <cups/http.h> printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT")); See Also httpGetDateString() httpGetField() Usage const char *httpGetField(http_t *http, http_field_t field); Arguments Argument Description http The HTTP connection field The HTTP field Returns A pointer to the field value string. Description The httpGetField() function returns the current value for the specified HTTP field. Example #include <cups/http.h> http_t *http; httpGet(http, "/some/uri"); while (httpUpdate(http) == HTTP_CONTINUE); puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE)); See Also httpConnect(), httpSetField() httpHead() Usage int httpHead(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to head Returns 0 on success, non-zero on failure. Description The httpHead() function sends a HTTP HEAD request to the server. Example #include <cups/http.h> http_t *http; httpHead(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpInitialize() Usage void httpInitialize(void); Description The httpInitialize() function initializes the networking code as needed by the underlying platform. It is called automatically by the httpConnect() function. Example #include <cups/http.h> httpInitialize(); See Also httpConnect() httpOptions() Usage int httpOptions(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to check for options Returns 0 on success, non-zero on failure. Description The httpOptions() function sends a HTTP OPTIONS request to the server. Example #include <cups/http.h> http_t *http; httpOptions(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpPost() Usage int httpPost(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to post to Returns 0 on success, non-zero on failure. Description The httpPost() function sends a HTTP POST request to the server. Example #include <cups/http.h> http_t *http; httpPost(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpPrintf() Usage int httpPrintf(http_t *http, const char *format, ...); Arguments Argument Description http The HTTP connection format A printf-style format string Returns The number of bytes written. Description The httpPrintf() function sends a formatted string to the HTTP connection. It is normally only used by the CUPS API and scheduler. Example #include <cups/http.h> http_t *http; httpPrintf(http, "GET / HTTP/1.1 \r\n"); See Also httpConnect() httpPut() Usage int httpPut(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to put Returns 0 on success, non-zero on failure. Description The httpPut() function sends a HTTP PUT request to the server. Example #include <cups/http.h> http_t *http; httpDelete(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpRead() Usage int httpRead(http_t *http, char *buffer, int length); Arguments Argument Description http The HTTP connection buffer The buffer to read into length The number of bytes to read Returns The number of bytes read or -1 on error. Description The httpRead() function reads data from the HTTP connection, possibly the result of a GET or POST request. Example #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); } See Also httpConnect(), httpWrite() httpReconnect() Usage int httpReconnect(http_t *http); Arguments Argument Description http The HTTP connection Returns 0 on success, non-zero on failure. Description The httpReconnect() function reconnects to the HTTP server. This is usually done automatically if the HTTP functions detect that the server connection has terminated. Example #include <cups/http.h> http_t *http; httpReconnect(http); See Also httpConnect() httpSeparate() Usage void httpSeparate(const char *uri, char *method, char *username, char *host, int *port, char *resource); Arguments Argument Description uri The URI to separate method The method (scheme) of the URI username The username (and password) portion of the URI, if any host The hostname portion of the URI, if any port The port number for the URI, either as specified or as default for the method/scheme resource The resource string, usually a filename on the server Description The httpSeparate() function separates the specified URI into its component parts. The method, username, hostname, and resource strings should be at least HTTP_MAX_URI characters long to avoid potential buffer overflow problems. Example 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); See Also httpConnect() httpSetField() Usage void httpSetField(http_t *http, http_field_t field, const char *value); Arguments Argument Description http The HTTP connection field The HTTP field value The string value for the field Description The httpSetField() function sets the current value for the specified HTTP field. Example #include <cups/http.h> http_t *http; httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325")); httpGet(http, "/some/uri"); while (httpUpdate(http) == HTTP_CONTINUE); See Also httpConnect(), httpGetField() httpTrace() Usage int httpTrace(http_t *http, const char *uri); Arguments Argument Description http The HTTP connection uri The URI to trace Returns 0 on success, non-zero on failure. Description The httpTrace() function sends a HTTP TRACE request to the server. Example #include <cups/http.h> http_t *http; httpTrace(http, "/some/uri"); See Also httpConnect(), httpSetField(), httpUpdate() httpUpdate() Usage http_status_t httpUpdate(http_t *http); Arguments Argument Description http The HTTP connection Returns The HTTP status of the current request. Description The httpUpdate() 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. Since proxies and the current blocking mode can cause the request to take longer, programs should continue calling httpUpdate() until the return status is not the constant value HTTP_CONTINUE. Example #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); See Also httpConnect(), httpDelete(), httpGet(), httpHead(), httpOptions(), httpPost(), httpPut(), httpTrace() httpWrite() Usage int httpWrite(http_t *http, char *buffer, int length); Arguments Argument Description http The HTTP connection buffer The buffer to read into length The number of bytes to read Returns The number of bytes read or -1 on error. Description The httpWrite() function reads data from the HTTP connection, possibly the result of a GET or POST request. Example #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); } See Also httpConnect(), httpRead() ippAddBoolean() Usage ipp_attribute_t *ippAddBoolean(ipp_t *ipp, ipp_tag_t group, const char *name, char value); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute value The boolean value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddBoolean() function adds a single boolean attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1); See Also ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddBooleans() Usage ipp_attribute_t *ippAddBooleans(ipp_t *ipp, ipp_tag_t group, const char *name, int num_values, const char *values); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute num_values The number of values values The boolean values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddBooleans() function adds one or more boolean attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values false values is created. Example #include <cups/ipp.h> ipp_t *ipp; char values[10]; ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values); See Also ippAddBoolean(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddDate() Usage ipp_attribute_t *ippAddDate(ipp_t *ipp, ipp_tag_t group, const char *name, ipp_uchar_t *value); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute value The date value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddDate() function adds a single date-time attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute", ippTimeToDate(time(NULL)); See Also ippAddBoolean(), ippAddBooleans(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings(), ippTimeToDate() ippAddInteger() Usage ipp_attribute_t *ippAddInteger(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, int value); Arguments Argument Description ipp The IPP request group The IPP group tag The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM) name The name of attribute value The integer value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddInteger() function adds a single integer attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddIntegers() Usage ipp_attribute_t *ippAddIntegers(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, int num_values, const int *values); Arguments Argument Description ipp The IPP request group The IPP group tag The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM) name The name of attribute num_values The number of values values The integer values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddIntegers() function adds one or more integer attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0 values is created. Example #include <cups/ipp.h> ipp_t *ipp; int values[100]; ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddRange() Usage ipp_attribute_t *ippAddRange(ipp_t *ipp, ipp_tag_t group, const char *name, int low, int high); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute low The lower value high The higher value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddRange() function adds a single range attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddRanges() Usage ipp_attribute_t *ippAddRanges(ipp_t *ipp, ipp_tag_t group, const char *name, int num_values, const int *lows, const int *highs); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute num_values The number of range values lows The lower values highs The higher values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddRanges() function adds one or more range attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0,0 ranges is created. Example #include <cups/ipp.h> ipp_t *ipp; int lows[2]; int highs[2]; ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddResolution() Usage ipp_attribute_t *ippAddResolution(ipp_t *ipp, ipp_tag_t group, const char *name, int xres, int yres, ipp_res_t units); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute xres The horizontal resolution yres The vertical resolution units The resolution units Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddResolution() function adds a single resolution attribute value to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution", 720, 720, IPP_RES_PER_INCH); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddResolutions() Usage 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); Arguments Argument Description ipp The IPP request group The IPP group name The name of attribute num_values The number of resolution values xres The horizontal resolutions yres The vertical resolutions units The resolution units Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddResolutions() function adds one or more resolution attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0,0 resolutions is created. Example #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); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddSeparator(), ippAddString(), ippAddStrings() ippAddSeparator() Usage ipp_attribute_t *ippAddSeparator(ipp_t *ipp); Arguments Argument Description ipp The IPP request Returns A pointer to the new separator or NULL if the separator could not be created. Description The ippAddSeparator() function adds a group separator to the specified IPP request. Example #include <cups/ipp.h> ipp_t *ipp; ippAddSeparator(ipp); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddString(), ippAddStrings() ippAddString() Usage ipp_attribute_t *ippAddString(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, const char *charset, const char *value); Arguments Argument Description ipp The IPP request group The IPP group tag The type of string value name The name of attribute charset The character set for the string value The string value Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddString() function adds a single string attribute value to the specified IPP request. For IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the charset value is provided with the string to identify the string encoding used. Otherwise the charset value is ignored. Example #include <cups/ipp.h> ipp_t *ipp; ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name", NULL, "abc123"); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddStrings() ippAddStrings() Usage 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); Arguments Argument Description ipp The IPP request group The IPP group tag The type of string value name The name of attribute num_values The number of strings charset The character set for the strings values The string values Returns A pointer to the new attribute or NULL if the attribute could not be created. Description The ippAddStrings() function adds one or more string attribute values to the specified IPP request. For IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the charset value is provided with the strings to identify the string encoding used. Otherwise the charset value is ignored. If the values pointer is NULL then an array of num_values NULL strings is created. Example #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); See Also ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString() ippDateToTime() Usage time_t ippDateToTime(const ipp_uchar_t date[11]); Arguments Argument Description date The IPP date-time value Returns A UNIX time value. Description The ippDateToTime() function converts an IPP date-time value to a UNIX time value. Example #include <cups/ipp.h> ipp_uchar_t date[11]; printf("UNIX time is %d\n", ippDateToTime(date)); See Also ippTimeToDate() ippDelete() Usage void ippDelete(ipp_t *ipp); Arguments Argument Description ipp The IPP request or response Description The ippDelete() function deletes all memory used by an IPP request or response. Example #include <cups/ipp.h> ipp_t *ipp; ippDelete(ipp); See Also ippNew() ippFindAttribute() Usage ipp_attribute_t *ippFindAttribute(ipp_t *ipp, const char *name, ipp_tag_t tag); Arguments Argument Description ipp The IPP request or response name The name of the attribute tag The required value tag for the attribute or IPP_TAG_ZERO for any type of value. Returns A pointer to the first occurrence of the requested attribute, or NULL if it was not found. Description ippFindAttribute() finds the first occurrence of the named attribute. The tag parameter restricts the search to a specific value type - use IPP_TAG_ZERO to find any value with the name. The value tags IPP_TAG_NAME and IPP_TAG_TEXT match the name/text values with or without the language code. Example ipp_attribute_t *attr; attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT); See Also cupsDoFileRequest(), cupsDoRequest(), ippDelete(), ippNew() ippLength() Usage int ippLength(ipp_t *ipp); Arguments Argument Description ipp The IPP request or response Returns The total encoded length of the IPP request or response in bytes. Description ippLength() returns the length of the IPP request or response in bytes. Example printf("The length of the response is %d bytes.\n", ippLength(response)); See Also ippDelete(), ippNew() ippNew() Usage ipp_t *ippNew(void); Returns A pointer to a new IPP request or response. Description The ippNew() function creates a new IPP request or response. Example #include <cups/ipp.h> ipp_t *ipp; ipp = ippNew(); See Also ippDelete() ippPort() Usage int ippPort(void); Returns The default TCP/IP port number for IPP requests. Description The ippPort() function returns the default IPP port number for requests. Example #include <cups/http.h> #include <cups/ipp.h> http_t *http; http = httpConnect(cupsServer(), ippPort()); See Also cupsServer(), ippSetPort() ippRead() Usage ipp_state_t ippRead(http_t *http, ipp_t *ipp); Arguments Argument Description http The HTTP connection ipp The IPP request or response Returns The current read state. Description The ippRead() function reads IPP attributes from the specified HTTP connection. Programs should continue calling ippRead() until IPP_ERROR or IPP_DATA is returned. Example #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() ... } See Also ippWrite() ippSetPort() Usage void ippSetPort(int port); Arguments Argument Description port The port number to use Description The ippSetPort() function sets the default IPP port number for requests. Example #include <cups/http.h> #include <cups/ipp.h> ... ippSetPort(8631); See Also ippPort() ippTimeToDate() Usage ipp_uchar_t *ippTimeToDate(time_t time); Arguments Argument Description time The UNIX time value Returns A static pointer to an IPP date-time value. Description The ippTimeToDate() function converts a UNIX time to an IPP date-time value. Example #include <cups/ipp.h> ipp_uchar_t *date; date = ippTimeToDate(time(NULL)); See Also ippDateToTime() ippWrite() Usage ipp_state_t ippWrite(http_t *http, ipp_t *ipp); Arguments Argument Description http The HTTP connection ipp The IPP request or response Returns The current write state. Description The ippWrite() function writes IPP attributes to the specified HTTP connection. Programs should continue calling ippWrite() until IPP_ERROR or IPP_DATA is returned. Example #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() ... } See Also ippRead() ppdClose() Usage void ppdClose(ppd_file_t *ppd); Arguments Argument Description ppd The PPD file Description The ppdClose() function frees all memory associated with the PPD file. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdClose(ppd); See Also ppdOpen(), ppdOpenFd(), ppdOpenFile() ppdConflicts() Usage int ppdConflicts(ppd_file_t *ppd); Arguments Argument Description ppd The PPD file Returns The number of option conflicts in the file. Description The ppdConflicts() function returns the number of conflicts with the currently selected options. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("%d conflicts\n", ppdConflicts(ppd)); See Also cupsMarkOptions(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdEmit() Usage int ppdEmit(ppd_file_t *ppd, FILE *file, ppd_section_t section); Arguments Argument Description ppd The PPD file file The file to write to section The option section to write Returns 0 on success, -1 on error. Description The ppdEmit() function sends printer-specific option commands to the specified file. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdEmit(ppd, stdout, PPD_ORDER_PAGE); See Also ppdEmitFd() ppdEmitFd() Usage int ppdEmitFd(ppd_file_t *ppd, int fd, ppd_section_t section); Arguments Argument Description ppd The PPD file fd The file descriptor to write to section The option section to write Returns 0 on success, -1 on error. Description The ppdEmitFd() function sends printer-specific option commands to the specified file descriptor. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdEmitFd(ppd, 1, PPD_ORDER_PAGE); See Also ppdEmit() ppdFindChoice() Usage ppd_choice_t *ppdFindChoice(ppd_option_t *option, const char *choice); Arguments Argument Description option A pointer to the option choice The name of the choice Returns A pointer to the choice data or NULL if the choice does not exist. Description The ppdFindChoice() function returns a pointer to the choice data for the specified option. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd_option_t *option; ppd_choice_t *choice; option = ppdFindOption(ppd, "PageSize"); choice = ppdFindChoice(option, "Letter"); See Also ppdFindMarkedChoice(), ppdFindOption() ppdFindMarkedChoice() Usage ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword); Arguments Argument Description ppd The PPD file keyword The name of the option Returns A pointer to the choice data or NULL if the choice does not exist or is not marked. Description The ppdFindMarkedChoice() function returns a pointer to the marked choice data for the specified option. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd_choice_t *choice; choice = ppdFindMarkedChoice(ppd, "PageSize"); See Also ppdFindChoice(), ppdFindOption() ppdFindOption() Usage ppd_option_t *ppdFindOption(ppd_file_t *ppd, const char *keyword); Arguments Argument Description ppd The PPD file keyword The name of the option Returns A pointer to the option data or NULL if the option does not exist. Description The ppdFindOption() function returns a pointer to the option data for the specified option. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd_option_t *option; option = ppdFindOption(ppd, "PageSize"); See Also ppdFindChoice(), ppdFindMarkedChoice() ppdIsMarked() Usage int ppdIsMarked(ppd_file_t *ppd, const char *keyword, char char *choice); Arguments Argument Description ppd The PPD file keyword The name of the option choice The name of the option choice Returns 1 if the choice is marked, 0 otherwise. Description The ppdIsMarked() function returns whether or not the specified option choice is marked. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("Letter size %s selected.\n", ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not"); See Also cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdMarkDefaults() Usage void ppdMarkDefaults(ppd_file_t *ppd); Arguments Argument Description ppd The PPD file Description The ppdMarkDefaults() function marks all of the default choices in the PPD file. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdMarkDefaults(ppd); See Also cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdMarkOption() Usage int ppdMarkOption(ppd_file_t *ppd, const char *keyword, const char *choice); Arguments Argument Description ppd The PPD file keyword The name of the option choice The name of the choice Returns The number of conflicts in the PPD file. Description The ppdMarkOption() function marks the specified option choice. Example #include <cups/ppd.h> ppd_file_t *ppd; ppdMarkOption(ppd, "PageSize", "Letter"); See Also cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption() ppdOpen() Usage ppd_file_t *ppdOpen(FILE *file); Arguments Argument Description file The file to read from Returns A pointer to a PPD file structure or NULL if the PPD file could not be read. Description The ppdOpen() function reads a PPD file from the specified file into memory. Example #include <cups/ppd.h> ppd_file_t *ppd; FILE *file; file = fopen("filename.ppd", "rb"); ppd = ppdOpen(file); fclose(file); See Also ppdClose(), ppdOpenFd(), ppdOpenFile() ppdOpenFd() Usage ppd_file_t *ppdOpenFd(int fd); Arguments Argument Description fd The file descriptor to read from Returns A pointer to a PPD file structure or NULL if the PPD file could not be read. Description The ppdOpenFd() function reads a PPD file from the specified file descriptor into memory. Example #include <cups/ppd.h> ppd_file_t *ppd; int fd; fd = open("filename.ppd", O_RDONLY); ppd = ppdOpenFd(fd); close(fd); See Also ppdClose(), ppdOpen(), ppdOpenFile() ppdOpenFile() Usage ppd_file_t *ppdOpenFile(const char *filename); Arguments Argument Description filename The name of the file to read from Returns A pointer to a PPD file structure or NULL if the PPD file could not be read. Description The ppdOpenFile() function reads a PPD file from the named file into memory. Example #include <cups/ppd.h> ppd_file_t *ppd; ppd = ppdOpenFile("filename.ppd"); See Also ppdClose(), ppdOpen(), ppdOpenFd() ppdPageLength() Usage float ppdPageLength(ppd_file_t *ppd, const char *name); Arguments Argument Description ppd The PPD file name The name of the page size Returns The length of the specified page size in points or 0 if the page size does not exist. Description The ppdPageLength() function returns the page length of the specified page size. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("Length = %.0f\n", ppdPageLength(ppd, "Letter")); See Also ppdPageLength(), ppdPageSize(), ppdPageWidth() ppdPageSize() Usage ppd_size_t *ppdPageSize(ppd_file_t *ppd, const char *name); Arguments Argument Description ppd The PPD file name The name of the page size Returns A pointer to the page size record of the specified page size in points or NULL if the page size does not exist. Description The ppdPageSize() function returns the page size record for the specified page size. Example #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); } See Also ppdPageLength(), ppdPageWidth() ppdPageWidth() Usage float ppdPageWidth(ppd_file_t *ppd, const char *name); Arguments Argument Description ppd The PPD file name The name of the page size Returns The width of the specified page size in points or 0 if the page size does not exist. Description The ppdPageWidth() function returns the page width of the specified page size. Example #include <cups/ppd.h> ppd_file_t *ppd; printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter")); See Also ppdPageLength(), ppdPageSize()
cupsFreeOptions() frees all memory associated with the option array specified.
#include <cups/cups.h> int num_options; cups_option_t *options; ... cupsFreeOptions(num_options, options);
cupsAddOption(), cupsGetOption(), cupsMarkOptions(), cupsParseOptions()
int cupsGetClasses(char ***classes);
The number of printer classes available.
cupsGetClasses() gets a list of the available printer classes. The returned array should be freed using the free() when it is no longer needed.
cupsGetClasses()
free()
#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); }
cupsGetDefault(), cupsGetPrinters() cupsGetDefault() Usage const char * cupsGetDefault(void); Returns A pointer to the default destination. Description cupsGetDefault() 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. Example #include <cups/cups.h> printf("The default destination is %s\n", cupsGetDefault()); See Also cupsGetClasses(), cupsGetPrinters() cupsGetOption() Usage const char * cupsGetOption(const char *name, int num_options, cups_option_t *options); Arguments Argument Description name The name of the option. num_options The number of options in the array. options The options array. Returns A pointer to the option values or NULL if the option is not defined. Description cupsGetOption() returns the first occurrence of the named option. If the option is not included in the options array then a NULL pointer is returned. #include <cups/cups.h> int num_options; cups_option_t *options; const char *media; ... media = cupsGetOption("media", num_options, options); See Also cupsAddOption(), cupsFreeOptions(), cupsMarkOptions(), cupsParseOptions() cupsGetPassword() Usage const char * cupsGetPassword(const char *prompt); Arguments Argument Description prompt The prompt to display to the user. Returns A pointer to the password that was entered or NULL if no password was entered. Description cupsGetPassword() displays the prompt string and asks the user for a password. The password text is not echoed to the user. Example #include <cups/cups.h> char *password; ... password = cupsGetPassword("Please enter a password:"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser() cupsGetPPD() Usage const char * cupsGetPPD(const char *printer); Arguments Argument Description printer The name of the printer. Returns The name of a temporary file containing the PPD file or NULL if the printer cannot be located or does not have a PPD file. Description cupsGetPPD() gets a copy of the PPD file for the named printer. The printer name can be of the form "printer" or "printer@hostname". 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 cupsGetPPD(). Example #include <cups/cups.h> char *ppd; ... ppd = cupsGetPPD("printer@hostname"); ... unlink(ppd); cupsGetPrinters() Usage int cupsGetPrinters(char ***printers); Arguments Argument Description printers Pointer to character pointer array. Returns The number of printer printers available. Description cupsGetPrinters() gets a list of the available printers. The returned array should be freed using the free() when it is no longer needed. Example #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); } See Also cupsGetClasses(), cupsGetDefault() cupsLangDefault() Usage const char * cupsLangDefault(void); Returns A pointer to the default language structure. Description cupsLangDefault() returns a language structure for the default language. The default language is defined by the LANG environment variable. If the specified language cannot be located then the POSIX (English) locale is used. Call cupsLangFree() to free any memory associated with the language structure when you are done. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangDefault(); ... cupsLangFree(language); See Also cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangEncoding() Usage char * cupsLangEncoding(cups_lang_t *language); Arguments Argument Description language The language structure. Returns A pointer to the encoding string. Description cupsLangEncoding() returns the language encoding used for the specified language, e.g. "iso-8859-1", "utf-8", etc. Example #include <cups/language.h> cups_lang_t *language; char *encoding; ... language = cupsLangDefault(); encoding = cupsLangEncoding(language); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFlush() Usage void cupsLangFlush(void); Description cupsLangFlush() frees all language structures that have been allocated. Example #include <cups/language.h> ... cupsLangFlush(); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFree() Usage void cupsLangFree(cups_lang_t *language); Arguments Argument Description language The language structure to free. Description cupsLangFree() frees the specified language structure. Example #include <cups/language.h> cups_lang_t *language; ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangGet(), cupsLangString() cupsLangGet() Usage cups_lang_t * cupsLangGet(const char *name); Arguments Argument Description name The name of the locale. Returns A pointer to a language structure. Description cupsLangGet() returns a language structure for the specified locale. If the locale is not defined then the POSIX (English) locale is substituted. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangGet("fr"); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangString() cupsLangString() Usage char * cupsLangString(cups_lang_t *language, int message); Arguments Argument Description language The language to query. message The message number. Returns A pointer to the message string or NULL if the message is not defined. Description cupsLangString() returns a pointer to the specified message string in the specified language. Example #include <cups/language.h> cups_lang_t *language; char *s; ... language = cupsLangGet("fr"); s = cupsLangString(language, CUPS_MSG_YES); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet() cupsLastError() Usage ipp_status_t cupsLastError(void); Returns An enumeration containing the last IPP error. Description cupsLastError() returns the last IPP error that occurred. If no error occurred then it will return IPP_OK or IPP_OK_CONFLICT. Example #include <cups/cups.h> ipp_status_t status; ... status = cupsLastError(); See Also cupsCancelJob(), cupsPrintFile() cupsMarkOptions() Usage int cupsMarkOptions(ppd_file_t *ppd, int num_options, cups_option_t *options); Arguments Argument Description ppd The PPD file to mark. num_options The number of options in the options array. options A pointer to the options array. Returns The number of conflicts found. Description cupsMarkOptions() marks options in the PPD file. It also handles mapping of IPP option names and values to PPD option names. Example #include <cups/cups.h> int num_options; cups_option_t *options; ppd_file_t *ppd; ... cupsMarkOptions(ppd, num_options, options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsParseOptions() cupsParseOptions() Usage int cupsParseOptions(const char *arg, int num_options, cups_option_t **options); Arguments Argument Description arg The string containing one or more options. num_options The number of options in the options array. options A pointer to the options array pointer. Returns The new number of options in the array. Description cupsParseOptions() 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. Example #include <cups/cups.h> int num_options; cups_option_t *options; ... num_options = 0; options = (cups_option_t *)0; num_options = cupsParseOptions(argv[5], num_options, &options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsMarkOptions() cupsPrintFile() Usage int cupsPrintFile(const char *printer, const char *filename, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. filename The file to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFile() 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 cupsLastError(). Example #include <cups/cups.h> int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFiles() cupsPrintFiles() Usage int cupsPrintFiles(const char *printer, int num_files, const char **files, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. num_files The number of files to print. files The files to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFiles() 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 cupsLastError(). Example #include <cups/cups.h> int num_files; const char *files[100]; int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFiles("printer@hostname", num_files, files, "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFile() cupsRasterClose() Usage void cupsRasterClose(cups_raster_t *ras); Arguments Argument Description ras The raster stream to close. Description cupsRasterClose() closes the specified raster stream. Example #include <cups/raster.h> cups_raster_t *ras; ... cupsRasterClose(ras); See Also cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterOpen() Usage cups_raster_t * cupsRasterOpen(int fd, cups_mode_t mode); Arguments Argument Description fd The file descriptor to use. mode The mode to use; CUPS_RASTER_READ or CUPS_RASTER_WRITE. Returns A pointer to a raster stream or NULL if there was an error. Description cupsRasterOpen() opens a raster stream for reading or writing. Example #include <cups/raster.h> cups_raster_t *ras; ... ras = cupsRasterOpen(0, CUPS_RASTER_READ); See Also cupsRasterClose(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadHeader() Usage unsigned cupsRasterReadHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to read from. header A pointer to a page header structure to read into. Returns 1 on success, 0 on EOF or error. Description cupsRasterReadHeader() reads a page header from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadPixels() Usage unsigned cupsRasterReadPixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to read from. pixels The pointer to a pixel buffer. length The number of bytes of pixel data to read. Returns The number of bytes read or 0 on EOF or error. Description cupsRasterReadPixels() reads pixel data from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterWriteHeader() Usage unsigned cupsRasterWriteHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to write to. header A pointer to the page header to write. Returns 1 on success, 0 on error. Description cupsRasterWriteHeader() writes the specified page header to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWritePixels() cupsRasterWritePixels() Usage unsigned cupsRasterWritePixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to write to. pixels The pixel data to write. length The number of bytes to write. Returns The number of bytes written. Description cupsRasterWritePixels() writes the specified pixel data to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader() cupsServer() Usage const char * cupsServer(void); Returns A pointer to the default server name. Description cupsServer() 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 cupsServer() The default server is determined from the following locations: The CUPS_SERVER environment variable, The ServerName directive in the client.conf file, The default host, "localhost". Example #include <cups/cups.h> const char *server; server = cupsServer(); See Also cupsGetPassword(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetPasswordCB() Usage void cupsSetPasswordCB(const char *(*cb)(const char *prompt)); Arguments Argument Description cb The password callback function. Description cupsSetPasswordCB() 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 NULL if the user did not enter a password string or a pointer to the password string otherwise. Example #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:"); See Also cupsServer(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetServer() Usage void cupsSetServer(const char *server); Arguments Argument Description server The default server to use. Description cupsSetServer() sets the default server to use for the CUPS API. If the server argument is NULL, the default server is used. Example #include <cups/cups.h> cupsSetServer("foo.bar.com"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetUser(), cupsUser() cupsSetUser() Usage void cupsSetUser(const char *user); Arguments Argument Description user The user name string to use. Description cupsSetUser() sets the default user name for authentication. If the user argument is NULL then the current login user is used. Example #include <cups/cups.h> ... cupsSetUser("root"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsUser() cupsTempFile() Usage char * cupsTempFile(char *filename, int length); Arguments Argument Description filename The character string to hold the temporary filename. length The size of the filename string in bytes. Returns A pointer to filename. Description cupsTempFile() generates a temporary filename for the /var/tmp directory or the directory specified by the TMPDIR environment variable. Example #include <cups/cups.h> char filename[256]; cupsTempFile(filename, sizeof(filename)); cupsUser() Usage const char * cupsUser(void); Returns A pointer to the current username or NULL if the user ID is undefined. Description cupsUser() returns the name associated with the current user ID as reported by the getuid() system call. Example #include <cups/cups.h> const char *user; user = cupsUser(); See Also cupsGetPassword(), cupsServer() httpBlocking() Usage void httpBlocking(http_t *http, int blocking) Arguments Argument Description http The HTTP connection blocking 0 if the connection should be non-blocking, 1 if it should be blocking Description The httpBlocking() 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. Example #include <cups/http.h> http_t *http; http = httpConnect("server", port); httpBlocking(http, 0); See Also httpCheck(), httpConnect() httpCheck() Usage int httpCheck(http_t *http); Arguments Argument Description http The HTTP connection Returns 0 if there is no data pending, 1 otherwise. Description The httpCheck() function checks to see if there is any data pending on an HTTP connection. Example #include <cups/http.h> http_t *http; if (httpCheck(http)) { ... do something ... } See Also httpBlocking(), httpConnect(), httpGets(), httpRead() httpClearFields() Usage void httpClearFields(http_t *http) Arguments Argument Description http The HTTP connection Description The httpClearFields() function clears all HTTP request fields for the HTTP connection. Example #include <cups/http.h> http_t *http; httpClearFields(http); See Also httpConnect(), httpGetField(), httpSetField()
const char * cupsGetDefault(void);
A pointer to the default destination.
cupsGetDefault() 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.
cupsGetDefault()
#include <cups/cups.h> printf("The default destination is %s\n", cupsGetDefault());
cupsGetClasses(), cupsGetPrinters() cupsGetOption() Usage const char * cupsGetOption(const char *name, int num_options, cups_option_t *options); Arguments Argument Description name The name of the option. num_options The number of options in the array. options The options array. Returns A pointer to the option values or NULL if the option is not defined. Description cupsGetOption() returns the first occurrence of the named option. If the option is not included in the options array then a NULL pointer is returned. #include <cups/cups.h> int num_options; cups_option_t *options; const char *media; ... media = cupsGetOption("media", num_options, options); See Also cupsAddOption(), cupsFreeOptions(), cupsMarkOptions(), cupsParseOptions() cupsGetPassword() Usage const char * cupsGetPassword(const char *prompt); Arguments Argument Description prompt The prompt to display to the user. Returns A pointer to the password that was entered or NULL if no password was entered. Description cupsGetPassword() displays the prompt string and asks the user for a password. The password text is not echoed to the user. Example #include <cups/cups.h> char *password; ... password = cupsGetPassword("Please enter a password:"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser() cupsGetPPD() Usage const char * cupsGetPPD(const char *printer); Arguments Argument Description printer The name of the printer. Returns The name of a temporary file containing the PPD file or NULL if the printer cannot be located or does not have a PPD file. Description cupsGetPPD() gets a copy of the PPD file for the named printer. The printer name can be of the form "printer" or "printer@hostname". 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 cupsGetPPD(). Example #include <cups/cups.h> char *ppd; ... ppd = cupsGetPPD("printer@hostname"); ... unlink(ppd); cupsGetPrinters() Usage int cupsGetPrinters(char ***printers); Arguments Argument Description printers Pointer to character pointer array. Returns The number of printer printers available. Description cupsGetPrinters() gets a list of the available printers. The returned array should be freed using the free() when it is no longer needed. Example #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); } See Also cupsGetClasses(), cupsGetDefault() cupsLangDefault() Usage const char * cupsLangDefault(void); Returns A pointer to the default language structure. Description cupsLangDefault() returns a language structure for the default language. The default language is defined by the LANG environment variable. If the specified language cannot be located then the POSIX (English) locale is used. Call cupsLangFree() to free any memory associated with the language structure when you are done. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangDefault(); ... cupsLangFree(language); See Also cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangEncoding() Usage char * cupsLangEncoding(cups_lang_t *language); Arguments Argument Description language The language structure. Returns A pointer to the encoding string. Description cupsLangEncoding() returns the language encoding used for the specified language, e.g. "iso-8859-1", "utf-8", etc. Example #include <cups/language.h> cups_lang_t *language; char *encoding; ... language = cupsLangDefault(); encoding = cupsLangEncoding(language); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFlush() Usage void cupsLangFlush(void); Description cupsLangFlush() frees all language structures that have been allocated. Example #include <cups/language.h> ... cupsLangFlush(); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFree() Usage void cupsLangFree(cups_lang_t *language); Arguments Argument Description language The language structure to free. Description cupsLangFree() frees the specified language structure. Example #include <cups/language.h> cups_lang_t *language; ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangGet(), cupsLangString() cupsLangGet() Usage cups_lang_t * cupsLangGet(const char *name); Arguments Argument Description name The name of the locale. Returns A pointer to a language structure. Description cupsLangGet() returns a language structure for the specified locale. If the locale is not defined then the POSIX (English) locale is substituted. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangGet("fr"); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangString() cupsLangString() Usage char * cupsLangString(cups_lang_t *language, int message); Arguments Argument Description language The language to query. message The message number. Returns A pointer to the message string or NULL if the message is not defined. Description cupsLangString() returns a pointer to the specified message string in the specified language. Example #include <cups/language.h> cups_lang_t *language; char *s; ... language = cupsLangGet("fr"); s = cupsLangString(language, CUPS_MSG_YES); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet() cupsLastError() Usage ipp_status_t cupsLastError(void); Returns An enumeration containing the last IPP error. Description cupsLastError() returns the last IPP error that occurred. If no error occurred then it will return IPP_OK or IPP_OK_CONFLICT. Example #include <cups/cups.h> ipp_status_t status; ... status = cupsLastError(); See Also cupsCancelJob(), cupsPrintFile() cupsMarkOptions() Usage int cupsMarkOptions(ppd_file_t *ppd, int num_options, cups_option_t *options); Arguments Argument Description ppd The PPD file to mark. num_options The number of options in the options array. options A pointer to the options array. Returns The number of conflicts found. Description cupsMarkOptions() marks options in the PPD file. It also handles mapping of IPP option names and values to PPD option names. Example #include <cups/cups.h> int num_options; cups_option_t *options; ppd_file_t *ppd; ... cupsMarkOptions(ppd, num_options, options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsParseOptions() cupsParseOptions() Usage int cupsParseOptions(const char *arg, int num_options, cups_option_t **options); Arguments Argument Description arg The string containing one or more options. num_options The number of options in the options array. options A pointer to the options array pointer. Returns The new number of options in the array. Description cupsParseOptions() 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. Example #include <cups/cups.h> int num_options; cups_option_t *options; ... num_options = 0; options = (cups_option_t *)0; num_options = cupsParseOptions(argv[5], num_options, &options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsMarkOptions() cupsPrintFile() Usage int cupsPrintFile(const char *printer, const char *filename, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. filename The file to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFile() 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 cupsLastError(). Example #include <cups/cups.h> int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFiles() cupsPrintFiles() Usage int cupsPrintFiles(const char *printer, int num_files, const char **files, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. num_files The number of files to print. files The files to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFiles() 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 cupsLastError(). Example #include <cups/cups.h> int num_files; const char *files[100]; int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFiles("printer@hostname", num_files, files, "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFile() cupsRasterClose() Usage void cupsRasterClose(cups_raster_t *ras); Arguments Argument Description ras The raster stream to close. Description cupsRasterClose() closes the specified raster stream. Example #include <cups/raster.h> cups_raster_t *ras; ... cupsRasterClose(ras); See Also cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterOpen() Usage cups_raster_t * cupsRasterOpen(int fd, cups_mode_t mode); Arguments Argument Description fd The file descriptor to use. mode The mode to use; CUPS_RASTER_READ or CUPS_RASTER_WRITE. Returns A pointer to a raster stream or NULL if there was an error. Description cupsRasterOpen() opens a raster stream for reading or writing. Example #include <cups/raster.h> cups_raster_t *ras; ... ras = cupsRasterOpen(0, CUPS_RASTER_READ); See Also cupsRasterClose(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadHeader() Usage unsigned cupsRasterReadHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to read from. header A pointer to a page header structure to read into. Returns 1 on success, 0 on EOF or error. Description cupsRasterReadHeader() reads a page header from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadPixels() Usage unsigned cupsRasterReadPixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to read from. pixels The pointer to a pixel buffer. length The number of bytes of pixel data to read. Returns The number of bytes read or 0 on EOF or error. Description cupsRasterReadPixels() reads pixel data from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterWriteHeader() Usage unsigned cupsRasterWriteHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to write to. header A pointer to the page header to write. Returns 1 on success, 0 on error. Description cupsRasterWriteHeader() writes the specified page header to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWritePixels() cupsRasterWritePixels() Usage unsigned cupsRasterWritePixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to write to. pixels The pixel data to write. length The number of bytes to write. Returns The number of bytes written. Description cupsRasterWritePixels() writes the specified pixel data to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader() cupsServer() Usage const char * cupsServer(void); Returns A pointer to the default server name. Description cupsServer() 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 cupsServer() The default server is determined from the following locations: The CUPS_SERVER environment variable, The ServerName directive in the client.conf file, The default host, "localhost". Example #include <cups/cups.h> const char *server; server = cupsServer(); See Also cupsGetPassword(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetPasswordCB() Usage void cupsSetPasswordCB(const char *(*cb)(const char *prompt)); Arguments Argument Description cb The password callback function. Description cupsSetPasswordCB() 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 NULL if the user did not enter a password string or a pointer to the password string otherwise. Example #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:"); See Also cupsServer(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetServer() Usage void cupsSetServer(const char *server); Arguments Argument Description server The default server to use. Description cupsSetServer() sets the default server to use for the CUPS API. If the server argument is NULL, the default server is used. Example #include <cups/cups.h> cupsSetServer("foo.bar.com"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetUser(), cupsUser() cupsSetUser() Usage void cupsSetUser(const char *user); Arguments Argument Description user The user name string to use. Description cupsSetUser() sets the default user name for authentication. If the user argument is NULL then the current login user is used. Example #include <cups/cups.h> ... cupsSetUser("root"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsUser() cupsTempFile() Usage char * cupsTempFile(char *filename, int length); Arguments Argument Description filename The character string to hold the temporary filename. length The size of the filename string in bytes. Returns A pointer to filename. Description cupsTempFile() generates a temporary filename for the /var/tmp directory or the directory specified by the TMPDIR environment variable. Example #include <cups/cups.h> char filename[256]; cupsTempFile(filename, sizeof(filename)); cupsUser() Usage const char * cupsUser(void); Returns A pointer to the current username or NULL if the user ID is undefined. Description cupsUser() returns the name associated with the current user ID as reported by the getuid() system call. Example #include <cups/cups.h> const char *user; user = cupsUser(); See Also cupsGetPassword(), cupsServer() httpBlocking() Usage void httpBlocking(http_t *http, int blocking) Arguments Argument Description http The HTTP connection blocking 0 if the connection should be non-blocking, 1 if it should be blocking Description The httpBlocking() 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. Example #include <cups/http.h> http_t *http; http = httpConnect("server", port); httpBlocking(http, 0); See Also httpCheck(), httpConnect() httpCheck() Usage int httpCheck(http_t *http); Arguments Argument Description http The HTTP connection Returns 0 if there is no data pending, 1 otherwise. Description The httpCheck() function checks to see if there is any data pending on an HTTP connection. Example #include <cups/http.h> http_t *http; if (httpCheck(http)) { ... do something ... } See Also httpBlocking(), httpConnect(), httpGets(), httpRead()
const char * cupsGetOption(const char *name, int num_options, cups_option_t *options);
A pointer to the option values or NULL if the option is not defined.
cupsGetOption() returns the first occurrence of the named option. If the option is not included in the options array then a NULL pointer is returned.
#include <cups/cups.h> int num_options; cups_option_t *options; const char *media; ... media = cupsGetOption("media", num_options, options);
cupsAddOption(), cupsFreeOptions(), cupsMarkOptions(), cupsParseOptions()
const char * cupsGetPassword(const char *prompt);
A pointer to the password that was entered or NULL if no password was entered.
cupsGetPassword() displays the prompt string and asks the user for a password. The password text is not echoed to the user.
cupsGetPassword()
#include <cups/cups.h> char *password; ... password = cupsGetPassword("Please enter a password:");
cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser()
const char * cupsGetPPD(const char *printer);
The name of a temporary file containing the PPD file or NULL if the printer cannot be located or does not have a PPD file.
cupsGetPPD() gets a copy of the PPD file for the named printer. The printer name can be of the form "printer" or "printer@hostname".
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 cupsGetPPD().
#include <cups/cups.h> char *ppd; ... ppd = cupsGetPPD("printer@hostname"); ... unlink(ppd);
int cupsGetPrinters(char ***printers);
The number of printer printers available.
cupsGetPrinters() gets a list of the available printers. The returned array should be freed using the free() when it is no longer needed.
cupsGetPrinters()
#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); }
cupsGetClasses(), cupsGetDefault() cupsLangDefault() Usage const char * cupsLangDefault(void); Returns A pointer to the default language structure. Description cupsLangDefault() returns a language structure for the default language. The default language is defined by the LANG environment variable. If the specified language cannot be located then the POSIX (English) locale is used. Call cupsLangFree() to free any memory associated with the language structure when you are done. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangDefault(); ... cupsLangFree(language); See Also cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangEncoding() Usage char * cupsLangEncoding(cups_lang_t *language); Arguments Argument Description language The language structure. Returns A pointer to the encoding string. Description cupsLangEncoding() returns the language encoding used for the specified language, e.g. "iso-8859-1", "utf-8", etc. Example #include <cups/language.h> cups_lang_t *language; char *encoding; ... language = cupsLangDefault(); encoding = cupsLangEncoding(language); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFlush() Usage void cupsLangFlush(void); Description cupsLangFlush() frees all language structures that have been allocated. Example #include <cups/language.h> ... cupsLangFlush(); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFree(), cupsLangGet(), cupsLangString() cupsLangFree() Usage void cupsLangFree(cups_lang_t *language); Arguments Argument Description language The language structure to free. Description cupsLangFree() frees the specified language structure. Example #include <cups/language.h> cups_lang_t *language; ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangGet(), cupsLangString() cupsLangGet() Usage cups_lang_t * cupsLangGet(const char *name); Arguments Argument Description name The name of the locale. Returns A pointer to a language structure. Description cupsLangGet() returns a language structure for the specified locale. If the locale is not defined then the POSIX (English) locale is substituted. Example #include <cups/language.h> cups_lang_t *language; ... language = cupsLangGet("fr"); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangString() cupsLangString() Usage char * cupsLangString(cups_lang_t *language, int message); Arguments Argument Description language The language to query. message The message number. Returns A pointer to the message string or NULL if the message is not defined. Description cupsLangString() returns a pointer to the specified message string in the specified language. Example #include <cups/language.h> cups_lang_t *language; char *s; ... language = cupsLangGet("fr"); s = cupsLangString(language, CUPS_MSG_YES); ... cupsLangFree(language); See Also cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet() cupsLastError() Usage ipp_status_t cupsLastError(void); Returns An enumeration containing the last IPP error. Description cupsLastError() returns the last IPP error that occurred. If no error occurred then it will return IPP_OK or IPP_OK_CONFLICT. Example #include <cups/cups.h> ipp_status_t status; ... status = cupsLastError(); See Also cupsCancelJob(), cupsPrintFile() cupsMarkOptions() Usage int cupsMarkOptions(ppd_file_t *ppd, int num_options, cups_option_t *options); Arguments Argument Description ppd The PPD file to mark. num_options The number of options in the options array. options A pointer to the options array. Returns The number of conflicts found. Description cupsMarkOptions() marks options in the PPD file. It also handles mapping of IPP option names and values to PPD option names. Example #include <cups/cups.h> int num_options; cups_option_t *options; ppd_file_t *ppd; ... cupsMarkOptions(ppd, num_options, options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsParseOptions() cupsParseOptions() Usage int cupsParseOptions(const char *arg, int num_options, cups_option_t **options); Arguments Argument Description arg The string containing one or more options. num_options The number of options in the options array. options A pointer to the options array pointer. Returns The new number of options in the array. Description cupsParseOptions() 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. Example #include <cups/cups.h> int num_options; cups_option_t *options; ... num_options = 0; options = (cups_option_t *)0; num_options = cupsParseOptions(argv[5], num_options, &options); See Also cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsMarkOptions() cupsPrintFile() Usage int cupsPrintFile(const char *printer, const char *filename, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. filename The file to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFile() 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 cupsLastError(). Example #include <cups/cups.h> int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFiles() cupsPrintFiles() Usage int cupsPrintFiles(const char *printer, int num_files, const char **files, const char *title, int num_options, cups_option_t *options); Arguments Argument Description printer The printer or class to print to. num_files The number of files to print. files The files to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns The new job ID number or 0 on error. Description cupsPrintFiles() 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 cupsLastError(). Example #include <cups/cups.h> int num_files; const char *files[100]; int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFiles("printer@hostname", num_files, files, "Job Title", num_options, options); See Also cupsCancelJob(), cupsLastError(), cupsPrintFile() cupsRasterClose() Usage void cupsRasterClose(cups_raster_t *ras); Arguments Argument Description ras The raster stream to close. Description cupsRasterClose() closes the specified raster stream. Example #include <cups/raster.h> cups_raster_t *ras; ... cupsRasterClose(ras); See Also cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterOpen() Usage cups_raster_t * cupsRasterOpen(int fd, cups_mode_t mode); Arguments Argument Description fd The file descriptor to use. mode The mode to use; CUPS_RASTER_READ or CUPS_RASTER_WRITE. Returns A pointer to a raster stream or NULL if there was an error. Description cupsRasterOpen() opens a raster stream for reading or writing. Example #include <cups/raster.h> cups_raster_t *ras; ... ras = cupsRasterOpen(0, CUPS_RASTER_READ); See Also cupsRasterClose(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadHeader() Usage unsigned cupsRasterReadHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to read from. header A pointer to a page header structure to read into. Returns 1 on success, 0 on EOF or error. Description cupsRasterReadHeader() reads a page header from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterReadPixels() Usage unsigned cupsRasterReadPixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to read from. pixels The pointer to a pixel buffer. length The number of bytes of pixel data to read. Returns The number of bytes read or 0 on EOF or error. Description cupsRasterReadPixels() reads pixel data from the specified raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterWriteHeader(), cupsRasterWritePixels() cupsRasterWriteHeader() Usage unsigned cupsRasterWriteHeader(cups_raster_t *ras, cups_page_header_t *header); Arguments Argument Description ras The raster stream to write to. header A pointer to the page header to write. Returns 1 on success, 0 on error. Description cupsRasterWriteHeader() writes the specified page header to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWritePixels() cupsRasterWritePixels() Usage unsigned cupsRasterWritePixels(cups_raster_t *ras, unsigned char *pixels, unsigned length); Arguments Argument Description ras The raster stream to write to. pixels The pixel data to write. length The number of bytes to write. Returns The number of bytes written. Description cupsRasterWritePixels() writes the specified pixel data to a raster stream. Example #include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); } See Also cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader() cupsServer() Usage const char * cupsServer(void); Returns A pointer to the default server name. Description cupsServer() 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 cupsServer() The default server is determined from the following locations: The CUPS_SERVER environment variable, The ServerName directive in the client.conf file, The default host, "localhost". Example #include <cups/cups.h> const char *server; server = cupsServer(); See Also cupsGetPassword(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetPasswordCB() Usage void cupsSetPasswordCB(const char *(*cb)(const char *prompt)); Arguments Argument Description cb The password callback function. Description cupsSetPasswordCB() 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 NULL if the user did not enter a password string or a pointer to the password string otherwise. Example #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:"); See Also cupsServer(), cupsSetServer(), cupsSetUser(), cupsUser() cupsSetServer() Usage void cupsSetServer(const char *server); Arguments Argument Description server The default server to use. Description cupsSetServer() sets the default server to use for the CUPS API. If the server argument is NULL, the default server is used. Example #include <cups/cups.h> cupsSetServer("foo.bar.com"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetUser(), cupsUser() cupsSetUser() Usage void cupsSetUser(const char *user); Arguments Argument Description user The user name string to use. Description cupsSetUser() sets the default user name for authentication. If the user argument is NULL then the current login user is used. Example #include <cups/cups.h> ... cupsSetUser("root"); See Also cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsUser() cupsTempFile() Usage char * cupsTempFile(char *filename, int length); Arguments Argument Description filename The character string to hold the temporary filename. length The size of the filename string in bytes. Returns A pointer to filename. Description cupsTempFile() generates a temporary filename for the /var/tmp directory or the directory specified by the TMPDIR environment variable. Example #include <cups/cups.h> char filename[256]; cupsTempFile(filename, sizeof(filename)); cupsUser() Usage const char * cupsUser(void); Returns A pointer to the current username or NULL if the user ID is undefined. Description cupsUser() returns the name associated with the current user ID as reported by the getuid() system call. Example #include <cups/cups.h> const char *user; user = cupsUser(); See Also cupsGetPassword(), cupsServer() httpBlocking() Usage void httpBlocking(http_t *http, int blocking) Arguments Argument Description http The HTTP connection blocking 0 if the connection should be non-blocking, 1 if it should be blocking Description The httpBlocking() 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. Example #include <cups/http.h> http_t *http; http = httpConnect("server", port); httpBlocking(http, 0); See Also httpCheck(), httpConnect()
const char * cupsLangDefault(void);
A pointer to the default language structure.
cupsLangDefault() returns a language structure for the default language. The default language is defined by the LANG environment variable. If the specified language cannot be located then the POSIX (English) locale is used.
Call cupsLangFree() to free any memory associated with the language structure when you are done.
cupsLangFree()
#include <cups/language.h> cups_lang_t *language; ... language = cupsLangDefault(); ... cupsLangFree(language);
cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString()
char * cupsLangEncoding(cups_lang_t *language);
A pointer to the encoding string.
cupsLangEncoding() returns the language encoding used for the specified language, e.g. "iso-8859-1", "utf-8", etc.
#include <cups/language.h> cups_lang_t *language; char *encoding; ... language = cupsLangDefault(); encoding = cupsLangEncoding(language); ... cupsLangFree(language);
cupsLangDefault(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString()
void cupsLangFlush(void);
cupsLangFlush() frees all language structures that have been allocated.
cupsLangFlush()
#include <cups/language.h> ... cupsLangFlush();
cupsLangDefault(), cupsLangEncoding(), cupsLangFree(), cupsLangGet(), cupsLangString()
void cupsLangFree(cups_lang_t *language);
cupsLangFree() frees the specified language structure.
#include <cups/language.h> cups_lang_t *language; ... cupsLangFree(language);
cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangGet(), cupsLangString()
cups_lang_t * cupsLangGet(const char *name);
A pointer to a language structure.
cupsLangGet() returns a language structure for the specified locale. If the locale is not defined then the POSIX (English) locale is substituted.
cupsLangGet()
#include <cups/language.h> cups_lang_t *language; ... language = cupsLangGet("fr"); ... cupsLangFree(language);
cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangString()
char * cupsLangString(cups_lang_t *language, int message);
A pointer to the message string or NULL if the message is not defined.
cupsLangString() returns a pointer to the specified message string in the specified language.
cupsLangString()
#include <cups/language.h> cups_lang_t *language; char *s; ... language = cupsLangGet("fr"); s = cupsLangString(language, CUPS_MSG_YES); ... cupsLangFree(language);
cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet()
ipp_status_t cupsLastError(void);
An enumeration containing the last IPP error.
cupsLastError() returns the last IPP error that occurred. If no error occurred then it will return IPP_OK or IPP_OK_CONFLICT.
#include <cups/cups.h> ipp_status_t status; ... status = cupsLastError();
cupsCancelJob(), cupsPrintFile()
int cupsMarkOptions(ppd_file_t *ppd, int num_options, cups_option_t *options);
The number of conflicts found.
cupsMarkOptions() marks options in the PPD file. It also handles mapping of IPP option names and values to PPD option names.
#include <cups/cups.h> int num_options; cups_option_t *options; ppd_file_t *ppd; ... cupsMarkOptions(ppd, num_options, options);
cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsParseOptions()
int cupsParseOptions(const char *arg, int num_options, cups_option_t **options);
The new number of options in the array.
cupsParseOptions() 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.
#include <cups/cups.h> int num_options; cups_option_t *options; ... num_options = 0; options = (cups_option_t *)0; num_options = cupsParseOptions(argv[5], num_options, &options);
cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsMarkOptions()
int cupsPrintFile(const char *printer, const char *filename, const char *title, int num_options, cups_option_t *options);
The new job ID number or 0 on error.
cupsPrintFile() 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 cupsLastError().
#include <cups/cups.h> int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title", num_options, options);
cupsCancelJob(), cupsLastError(), cupsPrintFiles()
int cupsPrintFiles(const char *printer, int num_files, const char **files, const char *title, int num_options, cups_option_t *options);
cupsPrintFiles() 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 cupsLastError().
#include <cups/cups.h> int num_files; const char *files[100]; int num_options; cups_option_t *options; int jobid; ... jobid = cupsPrintFiles("printer@hostname", num_files, files, "Job Title", num_options, options);
cupsCancelJob(), cupsLastError(), cupsPrintFile()
void cupsRasterClose(cups_raster_t *ras);
cupsRasterClose() closes the specified raster stream.
cupsRasterClose()
#include <cups/raster.h> cups_raster_t *ras; ... cupsRasterClose(ras);
cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels()
cups_raster_t * cupsRasterOpen(int fd, cups_mode_t mode);
A pointer to a raster stream or NULL if there was an error.
cupsRasterOpen() opens a raster stream for reading or writing.
#include <cups/raster.h> cups_raster_t *ras; ... ras = cupsRasterOpen(0, CUPS_RASTER_READ);
cupsRasterClose(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels()
unsigned cupsRasterReadHeader(cups_raster_t *ras, cups_page_header_t *header);
1 on success, 0 on EOF or error.
cupsRasterReadHeader() reads a page header from the specified raster stream.
cupsRasterReadHeader()
#include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... while (cupsRasterReadHeader(ras, &header)) { ... for (line = 0; line < header.cupsHeight; line ++) { cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine); ... } }
cupsRasterClose(), cupsRasterOpen(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels()
unsigned cupsRasterReadPixels(cups_raster_t *ras, unsigned char *pixels, unsigned length);
The number of bytes read or 0 on EOF or error.
cupsRasterReadPixels() reads pixel data from the specified raster stream.
cupsRasterReadPixels()
cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterWriteHeader(), cupsRasterWritePixels()
unsigned cupsRasterWriteHeader(cups_raster_t *ras, cups_page_header_t *header);
1 on success, 0 on error.
cupsRasterWriteHeader() writes the specified page header to a raster stream.
cupsRasterWriteHeader()
#include <cups/raster.h> int line; cups_raster_t *ras; cups_raster_header_t header; unsigned char pixels[8192]; ... cupsRasterWriteHeader(ras, &header); for (line = 0; line < header.cupsHeight; line ++) { ... cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine); }
cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWritePixels()
unsigned cupsRasterWritePixels(cups_raster_t *ras, unsigned char *pixels, unsigned length);
The number of bytes written.
cupsRasterWritePixels() writes the specified pixel data to a raster stream.
cupsRasterWritePixels()
cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader()
const char * cupsServer(void);
A pointer to the default server name.
cupsServer() 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 cupsServer()
cupsServer()
The default server is determined from the following locations:
CUPS_SERVER
ServerName
#include <cups/cups.h> const char *server; server = cupsServer();
cupsGetPassword(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser()
void cupsSetPasswordCB(const char *(*cb)(const char *prompt));
cupsSetPasswordCB() 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 NULL if the user did not enter a password string or a pointer to the password string otherwise.
#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:");
cupsServer(), cupsSetServer(), cupsSetUser(), cupsUser()
void cupsSetServer(const char *server);
cupsSetServer() sets the default server to use for the CUPS API. If the server argument is NULL, the default server is used.
cupsSetServer()
server
#include <cups/cups.h> cupsSetServer("foo.bar.com");
cupsServer(), cupsSetPasswordCB(), cupsSetUser(), cupsUser()
void cupsSetUser(const char *user);
cupsSetUser() sets the default user name for authentication. If the user argument is NULL then the current login user is used.
#include <cups/cups.h> ... cupsSetUser("root");
cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsUser()
char * cupsTempFile(char *filename, int length);
A pointer to filename.
cupsTempFile() generates a temporary filename for the /var/tmp directory or the directory specified by the TMPDIR environment variable.
TMPDIR
#include <cups/cups.h> char filename[256]; cupsTempFile(filename, sizeof(filename));
const char * cupsUser(void);
A pointer to the current username or NULL if the user ID is undefined.
cupsUser() returns the name associated with the current user ID as reported by the getuid() system call.
getuid()
#include <cups/cups.h> const char *user; user = cupsUser();
cupsGetPassword(), cupsServer()
void httpBlocking(http_t *http, int blocking)
The httpBlocking() 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.
httpBlocking()
#include <cups/http.h> http_t *http; http = httpConnect("server", port); httpBlocking(http, 0);
httpCheck()
int httpCheck(http_t *http);
0 if there is no data pending, 1 otherwise.
The httpCheck() function checks to see if there is any data pending on an HTTP connection.
#include <cups/http.h> http_t *http; if (httpCheck(http)) { ... do something ... }
httpGets()
httpRead()
void httpClearFields(http_t *http)
The httpClearFields() function clears all HTTP request fields for the HTTP connection.
httpClearFields()
#include <cups/http.h> http_t *http; httpClearFields(http);
httpGetField()
httpSetField()
void httpClose(http_t *http);
The httpClose() function closes an active HTTP connection.
httpClose()
#include <cups/http.h> http_t *http; httpClose(http);
http_t *httpConnect(const char *hostname, int port);
A pointer to a HTTP connection structure or NULL if the connection could not be made.
The httpConnect() function opens a HTTP connection to the specified server and port.
#include <cups/http.h> http_t *http; http = httpConnect(cupsServer(), ippPort());
httpGet()
httpPost()
httpWrite()
char *httpDecode64(char *out, const char *in);
A pointer to the decoded string.
The httpDecode64() function decodes a base-64 encoded string to the original string.
httpDecode64()
#include <cups/http.h> char encoded_string[255]; char original_string[255]; httpDecode64(original_string, encoded_string);
httpEncode64()
int httpDelete(http_t *http, const char *uri);
0 on success, non-zero on failure.
The httpDelete() function sends a HTTP DELETE request to the server.
httpDelete()
#include <cups/http.h> http_t *http; httpDelete(http, "/some/uri");
char *httpEncode64(char *out, const char *in);
A pointer to the encoded string.
The httpEncode64() function decodes a base-64 encoded string to the original string.
#include <cups/http.h> char encoded_string[255]; char original_string[255]; httpEncode64(encoded_string, original_string);
int httpError(http_t *http);
The last error that occurred or 0 if no error has occurred.
The httpError() function returns the last error that occurred on the HTTP connection.
httpError()
#include <cups/http.h> http_t *http; if (httpError(http)) { ... show an error message ... }
void httpFlush(http_t *http);
The httpFlush() function flushes any remaining data left from a GET or POST operation.
httpFlush()
#include <cups/http.h> http_t *http; httpFlush(http);
int httpGet(http_t *http, const char *uri);
The httpGet() function sends a HTTP GET request to the server.
#include <cups/http.h> http_t *http; httpGet(http, "/some/uri");
char *httpGets(char *line, int length, http_t *http)
A pointer to the string or NULL if no line could be retrieved.
The httpGets() function is used to read a request line from the HTTP connection. It is not normally used by a client program.
#include <cups/http.h> http_t *http; char line[1024]; if (httpGets(line, sizeof(line), http)) { ... process the line ... }
const char *httpGetDateString(time_t time)
A pointer to a static string containing the HTTP date/time string for the specified UNIX time value.
The httpGetDateString() function generates a date/time string suitable for HTTP requests from a UNIX time value.
httpGetDateString()
#include <cups/http.h> puts(httpGetDateString(time(NULL)));
httpGetDateTime()
time_t httpGetDateTime(const char *date)
A UNIX time value.
The httpGetDateTime() function converts a HTTP date/time string to a UNIX time value.
#include <cups/http.h> printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT"));
const char *httpGetField(http_t *http, http_field_t field);
A pointer to the field value string.
The httpGetField() function returns the current value for the specified HTTP field.
#include <cups/http.h> http_t *http; httpGet(http, "/some/uri"); while (httpUpdate(http) == HTTP_CONTINUE); puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));
int httpHead(http_t *http, const char *uri);
The httpHead() function sends a HTTP HEAD request to the server.
httpHead()
#include <cups/http.h> http_t *http; httpHead(http, "/some/uri");
void httpInitialize(void);
The httpInitialize() function initializes the networking code as needed by the underlying platform. It is called automatically by the httpConnect() function.
httpInitialize()
#include <cups/http.h> httpInitialize();
int httpOptions(http_t *http, const char *uri);
The httpOptions() function sends a HTTP OPTIONS request to the server.
httpOptions()
#include <cups/http.h> http_t *http; httpOptions(http, "/some/uri");
int httpPost(http_t *http, const char *uri);
The httpPost() function sends a HTTP POST request to the server.
#include <cups/http.h> http_t *http; httpPost(http, "/some/uri");
int httpPrintf(http_t *http, const char *format, ...);
The httpPrintf() function sends a formatted string to the HTTP connection. It is normally only used by the CUPS API and scheduler.
httpPrintf()
#include <cups/http.h> http_t *http; httpPrintf(http, "GET / HTTP/1.1 \r\n");
int httpPut(http_t *http, const char *uri);
The httpPut() function sends a HTTP PUT request to the server.
httpPut()
int httpRead(http_t *http, char *buffer, int length);
The number of bytes read or -1 on error.
The httpRead() function reads data from the HTTP connection, possibly the result of a GET or POST request.
#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); }
int httpReconnect(http_t *http);
The httpReconnect() function reconnects to the HTTP server. This is usually done automatically if the HTTP functions detect that the server connection has terminated.
httpReconnect()
#include <cups/http.h> http_t *http; httpReconnect(http);
void httpSeparate(const char *uri, char *method, char *username, char *host, int *port, char *resource);
The httpSeparate() function separates the specified URI into its component parts. The method, username, hostname, and resource strings should be at least HTTP_MAX_URI characters long to avoid potential buffer overflow problems.
httpSeparate()
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);
void httpSetField(http_t *http, http_field_t field, const char *value);
The httpSetField() function sets the current value for the specified HTTP field.
#include <cups/http.h> http_t *http; httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325")); httpGet(http, "/some/uri"); while (httpUpdate(http) == HTTP_CONTINUE);
int httpTrace(http_t *http, const char *uri);
The httpTrace() function sends a HTTP TRACE request to the server.
httpTrace()
#include <cups/http.h> http_t *http; httpTrace(http, "/some/uri");
http_status_t httpUpdate(http_t *http);
The HTTP status of the current request.
The httpUpdate() 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.
Since proxies and the current blocking mode can cause the request to take longer, programs should continue calling httpUpdate() until the return status is not the constant value HTTP_CONTINUE.
#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);
int httpWrite(http_t *http, char *buffer, int length);
The httpWrite() function reads data from the HTTP connection, possibly the result of a GET or POST request.
#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); }
ipp_attribute_t *ippAddBoolean(ipp_t *ipp, ipp_tag_t group, const char *name, char value);
A pointer to the new attribute or NULL if the attribute could not be created.
The ippAddBoolean() function adds a single boolean attribute value to the specified IPP request.
ippAddBoolean()
#include <cups/ipp.h> ipp_t *ipp; ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1);
ippAddBooleans()
ippAddDate()
ippAddInteger()
ippAddIntegers()
ippAddRange()
ippAddRanges()
ippAddResolution()
ippAddResolutions()
ippAddSeparator()
ippAddStrings()
ipp_attribute_t *ippAddBooleans(ipp_t *ipp, ipp_tag_t group, const char *name, int num_values, const char *values);
The ippAddBooleans() function adds one or more boolean attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values false values is created.
values
num_values
#include <cups/ipp.h> ipp_t *ipp; char values[10]; ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values);
ipp_attribute_t *ippAddDate(ipp_t *ipp, ipp_tag_t group, const char *name, ipp_uchar_t *value);
The ippAddDate() function adds a single date-time attribute value to the specified IPP request.
#include <cups/ipp.h> ipp_t *ipp; ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute", ippTimeToDate(time(NULL));
ippTimeToDate()
ipp_attribute_t *ippAddInteger(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, int value);
The ippAddInteger() function adds a single integer attribute value to the specified IPP request.
#include <cups/ipp.h> ipp_t *ipp; ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100);
ipp_attribute_t *ippAddIntegers(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, int num_values, const int *values);
The ippAddIntegers() function adds one or more integer attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0 values is created.
#include <cups/ipp.h> ipp_t *ipp; int values[100]; ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values);
ipp_attribute_t *ippAddRange(ipp_t *ipp, ipp_tag_t group, const char *name, int low, int high);
The ippAddRange() function adds a single range attribute value to the specified IPP request.
#include <cups/ipp.h> ipp_t *ipp; ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10);
ipp_attribute_t *ippAddRanges(ipp_t *ipp, ipp_tag_t group, const char *name, int num_values, const int *lows, const int *highs);
The ippAddRanges() function adds one or more range attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0,0 ranges is created.
#include <cups/ipp.h> ipp_t *ipp; int lows[2]; int highs[2]; ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs);
ipp_attribute_t *ippAddResolution(ipp_t *ipp, ipp_tag_t group, const char *name, int xres, int yres, ipp_res_t units);
The ippAddResolution() function adds a single resolution attribute value to the specified IPP request.
#include <cups/ipp.h> ipp_t *ipp; ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution", 720, 720, IPP_RES_PER_INCH);
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);
The ippAddResolutions() function adds one or more resolution attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0,0 resolutions is created.
#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);
ipp_attribute_t *ippAddSeparator(ipp_t *ipp);
A pointer to the new separator or NULL if the separator could not be created.
The ippAddSeparator() function adds a group separator to the specified IPP request.
#include <cups/ipp.h> ipp_t *ipp; ippAddSeparator(ipp);
ipp_attribute_t *ippAddString(ipp_t *ipp, ipp_tag_t group, ipp_tag_t tag, const char *name, const char *charset, const char *value);
The ippAddString() function adds a single string attribute value to the specified IPP request. For IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the charset value is provided with the string to identify the string encoding used. Otherwise the charset value is ignored.
#include <cups/ipp.h> ipp_t *ipp; ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name", NULL, "abc123");
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);
The ippAddStrings() function adds one or more string attribute values to the specified IPP request. For IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the charset value is provided with the strings to identify the string encoding used. Otherwise the charset value is ignored. If the values pointer is NULL then an array of num_values NULL strings is created.
#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);
time_t ippDateToTime(const ipp_uchar_t date[11]);
The ippDateToTime() function converts an IPP date-time value to a UNIX time value.
ippDateToTime()
#include <cups/ipp.h> ipp_uchar_t date[11]; printf("UNIX time is %d\n", ippDateToTime(date));
void ippDelete(ipp_t *ipp);
The ippDelete() function deletes all memory used by an IPP request or response.
ippDelete()
#include <cups/ipp.h> ipp_t *ipp; ippDelete(ipp);
ipp_attribute_t *ippFindAttribute(ipp_t *ipp, const char *name, ipp_tag_t tag);
A pointer to the first occurrence of the requested attribute, or NULL if it was not found.
ippFindAttribute() finds the first occurrence of the named attribute. The tag parameter restricts the search to a specific value type - use IPP_TAG_ZERO to find any value with the name.
ippFindAttribute()
tag
The value tags IPP_TAG_NAME and IPP_TAG_TEXT match the name/text values with or without the language code.
ipp_attribute_t *attr; attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
int ippLength(ipp_t *ipp);
The total encoded length of the IPP request or response in bytes.
ippLength() returns the length of the IPP request or response in bytes.
ippLength()
printf("The length of the response is %d bytes.\n", ippLength(response));
ipp_t *ippNew(void);
A pointer to a new IPP request or response.
The ippNew() function creates a new IPP request or response.
#include <cups/ipp.h> ipp_t *ipp; ipp = ippNew();
int ippPort(void);
The default TCP/IP port number for IPP requests.
The ippPort() function returns the default IPP port number for requests.
ippPort()
#include <cups/http.h> #include <cups/ipp.h> http_t *http; http = httpConnect(cupsServer(), ippPort());
ippSetPort()
ipp_state_t ippRead(http_t *http, ipp_t *ipp);
The current read state.
The ippRead() function reads IPP attributes from the specified HTTP connection. Programs should continue calling ippRead() until IPP_ERROR or IPP_DATA is returned.
ippRead()
IPP_ERROR
IPP_DATA
#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() ... }
ippWrite()
void ippSetPort(int port);
The ippSetPort() function sets the default IPP port number for requests.
#include <cups/http.h> #include <cups/ipp.h> ... ippSetPort(8631);
ipp_uchar_t *ippTimeToDate(time_t time);
A static pointer to an IPP date-time value.
The ippTimeToDate() function converts a UNIX time to an IPP date-time value.
#include <cups/ipp.h> ipp_uchar_t *date; date = ippTimeToDate(time(NULL));
ipp_state_t ippWrite(http_t *http, ipp_t *ipp);
The current write state.
The ippWrite() function writes IPP attributes to the specified HTTP connection. Programs should continue calling ippWrite() until IPP_ERROR or IPP_DATA is returned.
#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() ... }
void ppdClose(ppd_file_t *ppd);
The ppdClose() function frees all memory associated with the PPD file.
#include <cups/ppd.h> ppd_file_t *ppd; ppdClose(ppd);
ppdOpen()
ppdOpenFd()
int ppdConflicts(ppd_file_t *ppd);
The number of option conflicts in the file.
The ppdConflicts() function returns the number of conflicts with the currently selected options.
#include <cups/ppd.h> ppd_file_t *ppd; printf("%d conflicts\n", ppdConflicts(ppd));
ppdIsMarked()
int ppdEmit(ppd_file_t *ppd, FILE *file, ppd_section_t section);
0 on success, -1 on error.
The ppdEmit() function sends printer-specific option commands to the specified file.
ppdEmit()
#include <cups/ppd.h> ppd_file_t *ppd; ppdEmit(ppd, stdout, PPD_ORDER_PAGE);
ppdEmitFd()
int ppdEmitFd(ppd_file_t *ppd, int fd, ppd_section_t section);
The ppdEmitFd() function sends printer-specific option commands to the specified file descriptor.
#include <cups/ppd.h> ppd_file_t *ppd; ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);
ppd_choice_t *ppdFindChoice(ppd_option_t *option, const char *choice);
A pointer to the choice data or NULL if the choice does not exist.
The ppdFindChoice() function returns a pointer to the choice data for the specified option.
ppdFindChoice()
#include <cups/ppd.h> ppd_file_t *ppd; ppd_option_t *option; ppd_choice_t *choice; option = ppdFindOption(ppd, "PageSize"); choice = ppdFindChoice(option, "Letter");
ppdFindMarkedChoice()
ppdFindOption()
ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword);
A pointer to the choice data or NULL if the choice does not exist or is not marked.
The ppdFindMarkedChoice() function returns a pointer to the marked choice data for the specified option.
#include <cups/ppd.h> ppd_file_t *ppd; ppd_choice_t *choice; choice = ppdFindMarkedChoice(ppd, "PageSize");
ppd_option_t *ppdFindOption(ppd_file_t *ppd, const char *keyword);
A pointer to the option data or NULL if the option does not exist.
The ppdFindOption() function returns a pointer to the option data for the specified option.
#include <cups/ppd.h> ppd_file_t *ppd; ppd_option_t *option; option = ppdFindOption(ppd, "PageSize");
int ppdIsMarked(ppd_file_t *ppd, const char *keyword, char char *choice);
1 if the choice is marked, 0 otherwise.
The ppdIsMarked() function returns whether or not the specified option choice is marked.
#include <cups/ppd.h> ppd_file_t *ppd; printf("Letter size %s selected.\n", ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not");
void ppdMarkDefaults(ppd_file_t *ppd);
The ppdMarkDefaults() function marks all of the default choices in the PPD file.
#include <cups/ppd.h> ppd_file_t *ppd; ppdMarkDefaults(ppd);
int ppdMarkOption(ppd_file_t *ppd, const char *keyword, const char *choice);
The number of conflicts in the PPD file.
The ppdMarkOption() function marks the specified option choice.
#include <cups/ppd.h> ppd_file_t *ppd; ppdMarkOption(ppd, "PageSize", "Letter");
ppd_file_t *ppdOpen(FILE *file);
A pointer to a PPD file structure or NULL if the PPD file could not be read.
The ppdOpen() function reads a PPD file from the specified file into memory.
#include <cups/ppd.h> ppd_file_t *ppd; FILE *file; file = fopen("filename.ppd", "rb"); ppd = ppdOpen(file); fclose(file);
ppd_file_t *ppdOpenFd(int fd);
The ppdOpenFd() function reads a PPD file from the specified file descriptor into memory.
#include <cups/ppd.h> ppd_file_t *ppd; int fd; fd = open("filename.ppd", O_RDONLY); ppd = ppdOpenFd(fd); close(fd);
ppd_file_t *ppdOpenFile(const char *filename);
The ppdOpenFile() function reads a PPD file from the named file into memory.
#include <cups/ppd.h> ppd_file_t *ppd; ppd = ppdOpenFile("filename.ppd");
float ppdPageLength(ppd_file_t *ppd, const char *name);
The length of the specified page size in points or 0 if the page size does not exist.
The ppdPageLength() function returns the page length of the specified page size.
#include <cups/ppd.h> ppd_file_t *ppd; printf("Length = %.0f\n", ppdPageLength(ppd, "Letter"));
ppd_size_t *ppdPageSize(ppd_file_t *ppd, const char *name);
A pointer to the page size record of the specified page size in points or NULL if the page size does not exist.
The ppdPageSize() function returns the page size record for the specified page size.
#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); }
float ppdPageWidth(ppd_file_t *ppd, const char *name);
The width of the specified page size in points or 0 if the page size does not exist.
The ppdPageWidth() function returns the page width of the specified page size.
#include <cups/ppd.h> ppd_file_t *ppd; printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter"));