+ Documentation for CUPS Local Services
cancel - cancel jobs +
+cancel +[ +-h +hostname[:port] +] [ +-E +] [ +-U +username +] [ +-a +] [ +-u +username +] [ +-x +] [ +id +] [ +destination +] [ +destination-id +] +
+The cancel command cancels print jobs. +If no destination or id is specified, the currently printing job on the default destination is canceled. +
+The following options are recognized by cancel: +
+-a
+Cancel all jobs on the named destination, or all jobs on all
+destinations if none is provided.
+
-E
+Forces encryption when connecting to the server.
+
-h hostname[:port]
+Specifies an alternate server.
+Note: This option must occur before all others.
+
-U username
+Specifies the username to use when connecting to the server.
+
-u username
+Cancels jobs owned by username.
+
-x
+Deletes job data files in addition to canceling.
+
Unlike the System V printing system, CUPS allows printer names to contain any printable character except SPACE, TAB, "/", or "#". Also, printer and class names are not case-sensitive. +
+Cancel the current print job: +
++ cancel + ++
Cancel job "myprinter-42": +
++ cancel myprinter-42 + ++
Cancel all jobs: +
++ cancel -a ++
Administrators wishing to prevent unauthorized cancellation of jobs via the -u option should require authentication for Cancel-Jobs operations in +cupsd.conf(5). + +
+cupsd.conf(5), + +lp(1), + +lpmove(8), + +lpstat(1), + +CUPS Online Help (http://localhost:631/help) +
+Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/client.conf.html b/cups-local/client.conf.html new file mode 100644 index 0000000000..70778b2379 --- /dev/null +++ b/cups-local/client.conf.html @@ -0,0 +1,202 @@ + + +
+ + +client.conf - client configuration file for cups (deprecated on macos) +
+The client.conf file configures the CUPS client and is normally located in the /etc/cups and/or ~/.cups directories. +Each line in the file can be a configuration directive, a blank line, or a comment. Comment lines start with the # character. +
+Note: Starting with macOS 10.7, this file is only used by command-line and X11 applications plus the IPP backend. +The ServerName directive is not supported on macOS at all. +Starting with macOS 10.12, all applications can access these settings in the /Library/Preferences/org.cups.PrintingPrefs.plist file instead. +See the NOTES section below for more information. +
+The following directives are understood by the client. Consult the online help for detailed descriptions: +
+AllowAnyRoot Yes
+
AllowAnyRoot No
+Specifies whether to allow TLS with certificates that have not been signed by a trusted Certificate Authority.
+The default is "Yes".
+
AllowExpiredCerts Yes
+
AllowExpiredCerts No
+Specifies whether to allow TLS with expired certificates.
+The default is "No".
+
DigestOptions DenyMD5
+
DigestOptions None
+Specifies HTTP Digest authentication options.
+DenyMD5 disables support for the original MD5 hash algorithm.
+
Encryption IfRequested
+
Encryption Never
+
Encryption Required
+Specifies the level of encryption that should be used.
+
GSSServiceName name
+Specifies the Kerberos service name that is used for authentication, typically "host", "http", or "ipp".
+CUPS adds the remote hostname ("name@server.example.com") for you. The default name is "http".
+
ServerName hostname-or-ip-address[:port]
+
ServerName /domain/socket
+Specifies the address and optionally the port to use when connecting to the server.
+Note: This directive is not supported on macOS 10.7 or later.
+
ServerName hostname-or-ip-address[:port]/version=1.1
+Specifies the address and optionally the port to use when connecting to a server running CUPS 1.3.12 and earlier.
+
SSLOptions [AllowDH] [AllowRC4] [AllowSSL3] [DenyCBC] [DenyTLS1.0] [MaxTLS1.0] [MaxTLS1.1] [MaxTLS1.2] [MaxTLS1.3] [MinTLS1.0] [MinTLS1.1] [MinTLS1.2] [MinTLS1.3]
+
SSLOptions None
+Sets encryption options (only in /etc/cups/client.conf).
+By default, CUPS only supports encryption using TLS v1.0 or higher using known secure cipher suites.
+Security is reduced when Allow options are used.
+Security is enhanced when Deny options are used.
+The AllowDH option enables cipher suites using plain Diffie-Hellman key negotiation (not supported on systems using GNU TLS).
+The AllowRC4 option enables the 128-bit RC4 cipher suites, which are required for some older clients.
+The AllowSSL3 option enables SSL v3.0, which is required for some older clients that do not support TLS v1.0.
+The DenyCBC option disables all CBC cipher suites.
+The DenyTLS1.0 option disables TLS v1.0 support - this sets the minimum protocol version to TLS v1.1.
+The MinTLS options set the minimum TLS version to support.
+The MaxTLS options set the maximum TLS version to support.
+Not all operating systems support TLS 1.3 at this time.
+
TrustOnFirstUse Yes
+
TrustOnFirstUse No
+Specifies whether to trust new TLS certificates by default.
+The default is "Yes".
+
User name
+Specifies the default user name to use for requests.
+
UserAgentTokens None
+
UserAgentTokens ProductOnly
+
UserAgentTokens Major
+
UserAgentTokens Minor
+
UserAgentTokens Minimal
+
UserAgentTokens OS
+
UserAgentTokens Full
+Specifies what information is included in the User-Agent header of HTTP requests.
+"None" disables the User-Agent header.
+"ProductOnly" reports "CUPS".
+"Major" reports "CUPS/major IPP/2".
+"Minor" reports "CUPS/major.minor IPP/2.1".
+"Minimal" reports "CUPS/major.minor.patch IPP/2.1".
+"OS" reports "CUPS/major.minor.path (osname osversion) IPP/2.1".
+"Full" reports "CUPS/major.minor.path (osname osversion; architecture) IPP/2.1".
+The default is "Minimal".
+
ValidateCerts Yes
+
ValidateCerts No
+Specifies whether to only allow TLS with certificates whose common name matches the hostname.
+The default is "No".
+
The client.conf file is deprecated on macOS and will no longer be supported in a future version of CUPS. +Configuration settings can instead be viewed or changed using the +defaults(1) + +command: +
+defaults write /Library/Preferences/org.cups.PrintingPrefs.plist Encryption Required +defaults write /Library/Preferences/org.cups.PrintingPrefs.plist TrustOnFirstUse -bool NO + +defaults read /Library/Preferences/org.cups.PrintingPrefs.plist Encryption ++
On Linux and other systems using GNU TLS, the /etc/cups/ssl/site.crl file, if present, provides a list of revoked X.509 certificates and is used when validating certificates. +
+cups(1), + +default(1), + +CUPS Online Help (http://localhost:631/help) +
+Copyright © 2021-2023 by OpenPrinting. + + diff --git a/cups-local/cups.html b/cups-local/cups.html new file mode 100644 index 0000000000..4f582ec451 --- /dev/null +++ b/cups-local/cups.html @@ -0,0 +1,229 @@ + + +
+ + +cups - a standards-based, open source printing system +
+CUPS +is the software you use to print from applications like word processors, email readers, photo editors, and web browsers. It converts the page descriptions produced by your application (put a paragraph here, draw a line there, and so forth) into something your printer can understand and then sends the information to the printer for printing. +
+Now, since every printer manufacturer does things differently, printing can be very complicated. +CUPS +does its best to hide this from you and your application so that you can concentrate on printing and less on how to print. Generally, the only time you need to know anything about your printer is when you use it for the first time, and even then +CUPS +can often figure things out on its own. +
+The first time you print to a printer, +CUPS +creates a queue to keep track of the current status of the printer (everything OK, out of paper, etc.) and any pages you have printed. Most of the time the queue points to a printer connected directly to your computer via a USB port, however it can also point to a printer on your network, a printer on the Internet, or multiple printers depending on the configuration. Regardless of where the queue points, it will look like any other printer to you and your applications. +
+Every time you print something, +CUPS +creates a job which contains the queue you are sending the print to, the name of the document you are printing, and the page descriptions. Job are numbered (queue-1, queue-2, and so forth) so you can monitor the job as it is printed or cancel it if you see a mistake. When +CUPS +gets a job for printing, it determines the best programs (filters, printer drivers, port monitors, and backends) to convert the pages into a printable format and then runs them to actually print the job. +
+When the print job is completely printed, +CUPS +removes the job from the queue and moves on to any other jobs you have submitted. You can also be notified when the job is finished, or if there are any errors during printing, in several different ways. +
+The easiest way to start is by using the web interface to configure your printer. Go to "http://localhost:631" and choose the Administration tab at the top of the page. Click/press on the Add Printer button and follow the prompts. +
+When you are asked for a username and password, enter your login username and password or the "root" username and password. +
+After the printer is added you will be asked to set the default printer options (paper size, output mode, etc.) for the printer. Make any changes as needed and then click/press on the Set Default Options button to save them. Some printers also support auto-configuration - click/press on the Query Printer for Default Options button to update the options automatically. +
+Once you have added the printer, you can print to it from any application. You can also choose Print Test Page from the maintenance menu to print a simple test page and verify that everything is working properly. +
+You can also use the +lpadmin(8) + +and +lpinfo(8) + +commands to add printers to +CUPS. + +Additionally, your operating system may include graphical user interfaces or automatically create printer queues when you connect a printer to your computer. +
+The +OpenPrinting CUPS +web site (https://openprinting.github.io/cups) provides access to the +cups +and +cups-devel +mailing lists, additional documentation and resources, and a bug report database. Most vendors also provide online discussion forums to ask printing questions for your operating system of choice. +
+CUPS +commands use the following environment variables to override the default locations of files and so forth. For security reasons, these environment variables are ignored for setuid programs: +
+CUPS_ANYROOT
+Whether to allow any X.509 certificate root (Y or N).
+
CUPS_CACHEDIR
+The directory where semi-persistent cache files can be found.
+
CUPS_DATADIR
+The directory where data files can be found.
+
CUPS_ENCRYPTION
+The default level of encryption (Always, IfRequested, Never, Required).
+
CUPS_EXPIREDCERTS
+Whether to allow expired X.509 certificates (Y or N).
+
CUPS_GSSSERVICENAME
+The Kerberos service name used for authentication.
+
CUPS_SERVER
+The hostname/IP address and port number of the CUPS scheduler (hostname:port or ipaddress:port).
+
CUPS_SERVERBIN
+The directory where server helper programs, filters, backend, etc. can be found.
+
CUPS_SERVERROOT
+The root directory of the server.
+
CUPS_STATEDIR
+The directory where state files can be found.
+
CUPS_USER
+Specifies the name of the user for print requests.
+
HOME
+Specifies the home directory of the current user.
+
IPP_PORT
+Specifies the default port number for IPP requests.
+
LOCALEDIR
+Specifies the location of localization files.
+
LPDEST
+Specifies the default print queue (System V standard).
+
PRINTER
+Specifies the default print queue (Berkeley standard).
+
TMPDIR
+Specifies the location of temporary files.
+
~/.cups/client.conf +~/.cups/lpoptions ++
CUPS +conforms to the Internet Printing Protocol version 2.1 and implements the Berkeley and System V UNIX print commands. +
+CUPS printer drivers, backends, and PPD files are deprecated and will no longer be supported in a future feature release of CUPS. +Printers that do not support IPP can be supported using applications such as +ippeveprinter(1). + +
+cancel(1), + +client.conf(5), + +cupsctl(8), + +cupsd(8), + +lp(1), + +lpadmin(8), + +lpinfo(8), + +lpoptions(1), + +lpr(1), + +lprm(1), + +lpq(1), + +lpstat(1), + +CUPS Online Help (http://localhost:631/help), +OpenPrinting CUPS Web Site (https://openprinting.github.io/cups), +PWG Internet Printing Protocol Workgroup (http://www.pwg.org/ipp) +
+Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/cups.png b/cups-local/cups.png new file mode 100644 index 0000000000..7de089536a Binary files /dev/null and b/cups-local/cups.png differ diff --git a/cups-local/cupsaccept.html b/cups-local/cupsaccept.html new file mode 100644 index 0000000000..bdcf4e6676 --- /dev/null +++ b/cups-local/cupsaccept.html @@ -0,0 +1,160 @@ + + +
+ + +cupsaccept/cupsreject - accept/reject jobs sent to a destination +
+cupsaccept
+[
+-E
+] [
+-U
+username
+] [
+-h
+hostname[:port]
+]
+destination(s)
+
+cupsreject
+[
+-E
+] [
+-U
+username
+] [
+-h
+hostname[:port]
+] [
+-r
+reason
+]
+destination(s)
+
The +cupsaccept +command instructs the printing system to accept print jobs to the specified destinations. +
+The +cupsreject +command instructs the printing system to reject print jobs to the +specified destinations. +The -r option sets the reason for rejecting print jobs. If not specified, the reason defaults to "Reason Unknown". +
+The following options are supported by both +cupsaccept +and +cupsreject: + +
+-E
+Forces encryption when connecting to the server.
+
-U username
+Sets the username that is sent when connecting to the server.
+
-h hostname[:port]
+Chooses an alternate server.
+
-r "reason"
+Sets the reason string that is shown for a printer that is rejecting jobs.
+
The +cupsaccept +and +cupsreject +commands correspond to the System V printing system commands "accept" and "reject", respectively. +Unlike the System V printing system, CUPS allows printer names to contain any printable character except SPACE, TAB, "/", or "#". +Also, printer and class names are not case-sensitive. +
+Finally, the CUPS versions may ask the user for an access password depending on the printing system configuration. +
+cancel(1),
+
+cupsenable(8),
+
+lp(1),
+
+lpadmin(8),
+
+lpstat(1),
+
+
+CUPS Online Help (http://localhost:631/help)
+
Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/cupsenable.html b/cups-local/cupsenable.html new file mode 100644 index 0000000000..d422eaf6e3 --- /dev/null +++ b/cups-local/cupsenable.html @@ -0,0 +1,172 @@ + + +
+ + +cupsdisable, cupsenable - stop/start printers and classes +
+cupsdisable
+[
+-E
+] [
+-U
+username
+] [
+-c
+] [
+-h server[:port]
+] [
+-r
+reason
+] [
+--hold
+]
+destination(s)
+
+cupsenable
+[
+-E
+] [
+-U
+username
+] [
+-c
+] [
+-h server[:port]
+] [
+--release
+]
+destination(s)
+
cupsenable +starts the named printers or classes while +cupsdisable +stops the named printers or classes. +
+The following options may be used: +
+-E
+Forces encryption of the connection to the server.
+
-U username
+Uses the specified username when connecting to the server.
+
-c
+Cancels all jobs on the named destination.
+
-h server[:port]
+Uses the specified server and port.
+
--hold
+Holds remaining jobs on the named printer.
+Useful for allowing the current job to complete before performing maintenance.
+
-r "reason"
+Sets the message associated with the stopped state.
+If no reason is specified then the message is set to "Reason Unknown".
+
--release
+Releases pending jobs for printing.
+Use after running cupsdisable with the --hold option to resume printing.
+
Unlike the System V printing system, CUPS allows printer names to contain any printable character except SPACE, TAB, "/", or "#". +Also, printer and class names are not case-sensitive. +
+The System V versions of these commands are disable and enable, respectively. +They have been renamed to avoid conflicts with the +bash(1) + +build-in commands of the same names. +
+The CUPS versions of disable and enable may ask the user for an access password depending on the printing system configuration. +This differs from the System V versions which require the root user to execute these commands. +
+cupsaccept(8), + +cupsreject(8), + +cancel(1), + +lp(1), + +lpadmin(8), + +lpstat(1), + +CUPS Online Help (http://localhost:631/help) +
+Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/index.html b/cups-local/index.html new file mode 100644 index 0000000000..9d1e483b6d --- /dev/null +++ b/cups-local/index.html @@ -0,0 +1,92 @@ + + +
+ +lp - print files +
+lp
+[
+-h hostname[:port]
+] [
+-E
+] [
+-U
+username
+] [
+-c
+] [
+-d destination[/instance]
+] [
+-m
+] [
+-n
+num-copies
+] [
+-o option[=value]
+] [
+-q
+priority
+] [
+-s
+] [
+-t
+title
+] [
+-H
+handling
+] [
+-P
+page-list
+] [
+--
+] [
+file(s)
+]
+
+lp
+[
+-h hostname[:port]
+] [
+-E
+] [
+-U
+username
+] [
+-c
+] [
+-i
+job-id
+] [
+-n
+num-copies
+] [
+-o option[=value]
+] [
+-q
+priority
+] [
+-t
+title
+] [
+-H
+handling
+] [
+-P
+page-list
+]
+
lp submits files for printing or alters a pending job. +Use a filename of "-" to force printing from the standard input. +
+CUPS provides many ways to set the default destination. The LPDEST and PRINTER environment variables are consulted first. +If neither are set, the current default set using the +lpoptions(1) + +command is used, followed by the default set using the +lpadmin(8) + +command. +
+The following options are recognized by lp: +
+--
+Marks the end of options; use this to print a file whose name begins with a dash (-).
+
-E
+Forces encryption when connecting to the server.
+
-U username
+Specifies the username to use when connecting to the server.
+
-c
+This option is provided for backwards-compatibility only. On systems that support it, this option forces the print file to be copied to the spool directory before printing.
+In CUPS, print files are always sent to the scheduler via IPP which has the same effect.
+
-d destination
+Prints files to the named printer.
+
-h hostname[:port]
+Chooses an alternate server.
+Note: This option must occur before all others.
+
-i job-id
+Specifies an existing job to modify.
+
-m
+Sends an email when the job is completed.
+
-n copies
+Sets the number of copies to print.
+
-o "name=value [ ... name=value ]"
+Sets one or more job options.
+See "COMMON JOB OPTIONS" below.
+
-q priority
+Sets the job priority from 1 (lowest) to 100 (highest).
+The default priority is 50.
+
-s
+Do not report the resulting job IDs (silent mode.)
+
-t "name"
+Sets the job name.
+
-H hh:mm
+
-H hold
+
-H immediate
+
-H restart
+
-H resume
+Specifies when the job should be printed.
+A value of immediate will print the file immediately, a value of hold will hold the job indefinitely, and a UTC time value (HH:MM) will hold the job until the specified UTC (not local) time.
+Use a value of resume with the -i option to resume a held job.
+Use a value of restart with the -i option to restart a completed job.
+
-P page-list
+Specifies which pages to print in the document.
+The list can contain a list of numbers and ranges (#-#) separated by commas, e.g., "1,3-5,16".
+The page numbers refer to the output pages and not the document's original pages - options like "number-up" can affect the numbering of the pages.
+
Aside from the printer-specific options reported by the +lpoptions(1) + +command, the following generic options are available: +
+-o job-sheets=name
+Prints a cover page (banner) with the document.
+The "name" can be "classified", "confidential", "secret", "standard", "topsecret", or "unclassified".
+
-o media=size
+Sets the page size to size. Most printers support at least the size names "a4", "letter", and "legal".
+
-o number-up={2|4|6|9|16}
+Prints 2, 4, 6, 9, or 16 document (input) pages on each output page.
+
-o orientation-requested=4
+Prints the job in landscape (rotated 90 degrees counter-clockwise).
+
-o orientation-requested=5
+Prints the job in landscape (rotated 90 degrees clockwise).
+
-o orientation-requested=6
+Prints the job in reverse portrait (rotated 180 degrees).
+
-o print-quality=3
+
-o print-quality=4
+
-o print-quality=5
+Specifies the output quality - draft (3), normal (4), or best (5).
+
-o sides=one-sided
+Prints on one side of the paper.
+
-o sides=two-sided-long-edge
+Prints on both sides of the paper for portrait output.
+
-o sides=two-sided-short-edge
+Prints on both sides of the paper for landscape output.
+
Unlike the System V printing system, CUPS allows printer names to contain any printable character except SPACE, TAB, "/", or "#". +Also, printer and class names are not case-sensitive. +
+The -q option accepts a different range of values than the Solaris lp command, matching the IPP job priority values (1-100, 100 is highest priority) instead of the Solaris values (0-39, 0 is highest priority). +
+Print two copies of a document to the default printer: +
++ lp -n 2 filename + ++
Print a double-sided legal document to a printer called "foo": +
++ lp -d foo -o media=legal -o sides=two-sided-long-edge filename + ++
Print a presentation document 2-up to a printer called "bar": +
++ lp -d bar -o number-up=2 filename ++
cancel(1), + +lpadmin(8), + +lpoptions(1), + +lpq(1), + +lpr(1), + +lprm(1), + +lpstat(1), + +CUPS Online Help (http://localhost:631/help) +
+Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/lpadmin.html b/cups-local/lpadmin.html new file mode 100644 index 0000000000..87602aee59 --- /dev/null +++ b/cups-local/lpadmin.html @@ -0,0 +1,314 @@ + + +
+ + +lpadmin - configure cups printers and classes +
+lpadmin
+[
+-E
+] [
+-U
+username
+] [
+-h server[:port]
+]
+-d
+destination
+
+lpadmin
+[
+-E
+] [
+-U
+username
+] [
+-h server[:port]
+]
+-p
+destination
+[
+-R
+name-default
+]
+option(s)
+
+lpadmin
+[
+-E
+] [
+-U
+username
+] [
+-h server[:port]
+]
+-x
+destination
+
lpadmin configures printer and class queues provided by CUPS. +It can also be used to set the server default printer or class. +
+When specified before the -d, -p, or -x options, the -E option forces encryption when connecting to the server. +
+The first form of the command (-d) sets the default printer or class to destination. +Subsequent print jobs submitted via the +lp(1) + +or +lpr(1) + +commands will use this destination unless the user specifies otherwise with the +lpoptions(1) + +command. +
+The second form of the command (-p) configures the named printer or class. The additional options are described below. +
+The third form of the command (-x) deletes the printer or class destination. +Any jobs that are pending for the destination will be removed and any job that is currently printed will be aborted. +
+The following options are recognized when configuring a printer queue: +
+-c class
+Adds the named printer to class.
+If class does not exist it is created automatically.
+
-m model
+Sets a standard PPD file for the printer from the model directory or using one of the driver interfaces.
+Use the -m option with the
+lpinfo(8)
+
+command to get a list of supported models.
+The model "raw" clears any existing PPD file and the model "everywhere" queries the printer referred to by the specified IPP device-uri.
+Note: Models other than "everywhere" are deprecated and will not be supported in a future version of CUPS.
+
-o cupsIPPSupplies=true
+
-o cupsIPPSupplies=false
+Specifies whether IPP supply level values should be reported.
+
-o cupsSNMPSupplies=true
+
-o cupsSNMPSupplies=false
+Specifies whether SNMP supply level (RFC 3805) values should be reported.
+
-o job-k-limit=value
+Sets the kilobyte limit for per-user quotas.
+The value is an integer number of kilobytes; one kilobyte is 1024 bytes.
+
-o job-page-limit=value
+Sets the page limit for per-user quotas.
+The value is the integer number of pages that can be printed; double-sided pages are counted as two pages.
+
-o job-quota-period=value
+Sets the accounting period for per-user quotas.
+The value is an integer number of seconds; 86,400 seconds are in one day.
+
-o job-sheets-default=banner
+
-o job-sheets-default=banner,banner
+Sets the default banner page(s) to use for print jobs.
+
-o name=value
+Sets a PPD option for the printer.
+PPD options can be listed using the -l option with the
+lpoptions(1)
+
+command.
+
-o name-default=value
+Sets a default server-side option for the destination.
+Any print-time option can be defaulted, e.g., "-o number-up-default=2" to set the default "number-up" option value to 2.
+
-o port-monitor=name
+Sets the binary communications program to use when printing, "none", "bcp", or "tbcp".
+The default program is "none".
+The specified port monitor must be listed in the printer's PPD file.
+
-o printer-error-policy=name
+Sets the policy for errors such as printers that cannot be found or accessed, don't support the format being printed, fail during submission of the print data, or cause one or more filters to crash.
+The name must be one of "abort-job" (abort the job on error), "retry-job" (retry the job at a future time), "retry-current-job" (retry the current job immediately), or "stop-printer" (stop the printer on error).
+The default error policy is "stop-printer" for printers and "retry-current-job" for
+classes.
+
-o printer-is-shared=true
+
-o printer-is-shared=false
+Sets the destination to shared/published or unshared/unpublished.
+Shared/published destinations are publicly announced by the server on the LAN based on the browsing configuration in cupsd.conf, while unshared/unpublished destinations are not announced.
+The default value is "true".
+
-o printer-op-policy=name
+Sets the IPP operation policy associated with the destination.
+The name must be defined in the cupsd.conf in a Policy section.
+The default operation policy is "default".
+
-R name-default
+Deletes the named option from printer.
+
-r class
+Removes the named printer from class.
+If the resulting class becomes empty it is removed.
+
-u allow:{user|@group}{,user|,@group}*
+
-u deny:{user|@group}{,user|,@group}*
+
-u allow:all
+
-u deny:none
+Sets user-level access control on a destination.
+Names starting with "@" are interpreted as UNIX groups.
+The latter two forms turn user-level access control off.
+Note: The user 'root' is not granted special access - using "-u allow:foo,bar" will allow users 'foo' and 'bar' to access the printer but NOT 'root'.
+
-v "device-uri"
+Sets the device-uri attribute of the printer queue.
+Use the -v option with the
+lpinfo(8)
+
+command to get a list of supported device URIs and schemes.
+
-D "info"
+Provides a textual description of the destination.
+
-E
+When specified before the -d, -p, or -x options, forces the use of TLS encryption on the connection to the scheduler.
+Otherwise, enables the destination and accepts jobs; this is the same as running the
+cupsaccept(8)
+
+and
+cupsenable(8)
+
+programs on the destination.
+
-L "location"
+Provides a textual location of the destination.
+
The following lpadmin options are deprecated: +
+-i filename
+This option historically has been used to provide either a System V interface script or (as an implementation side-effect) a PPD file.
+Note: Interface scripts are not supported by CUPS.
+PPD files and printer drivers are deprecated and will not be supported in a future version of CUPS.
+
-P ppd-file
+Specifies a PostScript Printer Description (PPD) file to use with the printer.
+Note: PPD files and printer drivers are deprecated and will not be supported in a future version of CUPS.
+
Unlike the System V printing system, CUPS allows printer names to contain any printable character except SPACE, TAB, "/", or "#". +Also, printer and class names are not case-sensitive. +
+Finally, the CUPS version of lpadmin may ask the user for an access password depending on the printing system configuration. +This differs from the System V version which requires the root user to execute this command. +
+CUPS printer drivers and backends are deprecated and will no longer be supported in a future feature release of CUPS. +Printers that do not support IPP can be supported using applications such as +ippeveprinter(1). + +
+The CUPS version of lpadmin does not support all of the System V or Solaris printing system configuration options. +
+Interface scripts are not supported for security reasons. +
+The double meaning of the -E option is an unfortunate historical oddity. +
+The lpadmin command communicates with the scheduler (cupsd) to make changes to the printing system configuration. +This configuration information is stored in several files including printers.conf and classes.conf. +These files should not be edited directly and are an implementation detail of CUPS that is subject to change at any time. +
+Create an IPP Everywhere print queue: +
++ lpadmin -p myprinter -E -v ipp://myprinter.local/ipp/print -m everywhere + ++
cupsaccept(8), + +cupsenable(8), + +lpinfo(8), + +lpoptions(1), + +CUPS Online Help (http://localhost:631/help) +
+Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/lpc.html b/cups-local/lpc.html new file mode 100644 index 0000000000..12543d9cd9 --- /dev/null +++ b/cups-local/lpc.html @@ -0,0 +1,135 @@ + + +
+ + +lpc - line printer control program (deprecated) +
+lpc +[ +command +[ +parameter(s) +] ] +
+lpc provides limited control over printer and class queues provided by CUPS. It can also be used to query the state of queues. +
+If no command is specified on the command-line, lpc displays a prompt and accepts commands from the standard input. +
+The lpc program accepts a subset of commands accepted by the Berkeley lpc program of the same name: +
+exit
+Exits the command interpreter.
+
help [command]
+
? [command]
+Displays a short help message.
+
quit
+Exits the command interpreter.
+
status [queue]
+Displays the status of one or more printer or class queues.
+
This program is deprecated and will be removed in a future feature release of CUPS. +
+Since lpc is geared towards the Berkeley printing system, it is impossible to use lpc to configure printer or class queues provided by CUPS. +To configure printer or class queues you must use the +lpadmin(8) + +command or another CUPS-compatible client with that functionality. +
+cancel(1), + +cupsaccept(8), + +cupsenable(8), + +lp(1), + +lpadmin(8), + +lpr(1), + +lprm(1), + +lpstat(1), + +CUPS Online Help (http://localhost:631/help) +
+Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/lpmove.html b/cups-local/lpmove.html new file mode 100644 index 0000000000..8a1d3fb7da --- /dev/null +++ b/cups-local/lpmove.html @@ -0,0 +1,146 @@ + + +
+ + +lpmove - move a job or all jobs to a new destination +
+lpmove
+[
+-h server[:port]
+] [
+-E
+] [
+-U
+username
+]
+job
+destination
+
+lpmove
+[
+-h server[:port]
+] [
+-E
+] [
+-U
+username
+]
+source
+destination
+
lpmove moves the specified job or all jobs from source to destination. job can be the job ID number or the old destination and job ID. +
+The lpmove command supports the following options: +
+-E
+Forces encryption when connecting to the server.
+
-U username
+Specifies an alternate username.
+
-h server[:port]
+Specifies an alternate server.
+Note: This option must occur before all others.
+
Move job 123 from "oldprinter" to "newprinter": +
++ lpmove 123 newprinter + + or + + lpmove oldprinter-123 newprinter + ++
Move all jobs from "oldprinter" to "newprinter": +
++ lpmove oldprinter newprinter ++
cancel(1),
+
+lp(1),
+
+lpr(1),
+
+lprm(1),
+
+
+CUPS Online Help (http://localhost:631/help)
+
Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/lpoptions.html b/cups-local/lpoptions.html new file mode 100644 index 0000000000..efa07d249d --- /dev/null +++ b/cups-local/lpoptions.html @@ -0,0 +1,198 @@ + + +
+ + +lpoptions - display or set printer options and defaults +
+lpoptions
+[
+-h server[:port]
+] [
+-E
+]
+-d destination[/instance]
+[
+-l
+]
+
+lpoptions
+[
+-h server[:port]
+] [
+-E
+] [
+-p destination[/instance]
+]
+-o option[=value] ...
+
+lpoptions
+[
+-h server[:port]
+] [
+-E
+] [
+-p destination[/instance]
+]
+-r
+option
+
+lpoptions
+[
+-h server[:port]
+] [
+-E
+]
+-x destination[/instance]
+
lpoptions displays or sets printer options and defaults. +If no printer is specified using the -p option, the default printer is used as described in +lp(1). + +
+If no -l, -o, or -r options are specified, the current options are reported on the standard output. +
+Options set with the lpoptions command are used by the +lp(1) + +and +lpr(1) + +commands when submitting jobs. +
+When run by the root user, lpoptions gets and sets default options and instances for all users in the /etc/cups/lpoptions file. +Otherwise, the per-user defaults are managed in the ~/.cups/lpoptions file. +
+lpoptions supports the following options: +
+-E
+Enables encryption when communicating with the CUPS server.
+
-d destination[/instance]
+Sets the user default printer to destination.
+If instance is supplied then that particular instance is used.
+This option overrides the system default printer for the current user.
+
-h server[:port]
+Uses an alternate server.
+Note: This option must occur before all others.
+
-l
+Lists the printer specific options and their current settings.
+
-o option[=value]
+Specifies a new option for the named destination.
+
-p destination[/instance]
+Sets the destination and instance, if specified, for any options that follow.
+If the named instance does not exist then it is created.
+Destinations can only be created using the
+lpadmin(8)
+
+program.
+
-r option
+Removes the specified option from the named destination.
+
-x destination[/instance]
+Removes the options for the named destination and instance, if specified.
+If the named instance does not exist then this does nothing.
+Destinations can only be removed using the
+lpadmin(8)
+
+command.
+
~/.cups/lpoptions - user defaults and instances created by non-root users.
+
+/etc/cups/lpoptions - system-wide defaults and instances created by the root user.
+
The lpoptions command is unique to CUPS. +
+cancel(1), + +lp(1), + +lpadmin(8), + +lpr(1), + +lprm(1), + +CUPS Online Help (http://localhost:631/help) +
+Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/lpq.html b/cups-local/lpq.html new file mode 100644 index 0000000000..73a2dec30e --- /dev/null +++ b/cups-local/lpq.html @@ -0,0 +1,138 @@ + + +
+ + +lpq - show printer queue status +
+lpq +[ +-h server[:port] +] [ +-E +] [ +-U +username +] [ +-P destination[/instance] +] [ +-a +] [ +-l +] [ ++interval + +] +
+lpq shows the current print queue status on the named printer. +Jobs queued on the default destination will be shown if no printer or class is specified on the command-line. +
+The +interval option allows you to continuously report the jobs in the queue until the queue is empty; the list of jobs is shown once every interval seconds. +
+lpq supports the following options: +
+-E
+Forces encryption when connecting to the server.
+
-P destination[/instance]
+Specifies an alternate printer or class name.
+
-U username
+Specifies an alternate username.
+
-a
+Reports jobs on all printers.
+
-h server[:port]
+Specifies an alternate server.
+Note: This option must occur before all others.
+
-l
+Requests a more verbose (long) reporting format.
+
cancel(1), + +lp(1), + +lpr(1), + +lprm(1), + +lpstat(1), + +CUPS Online Help (http://localhost:631/help) +
+Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/lpr.html b/cups-local/lpr.html new file mode 100644 index 0000000000..c8b64811c1 --- /dev/null +++ b/cups-local/lpr.html @@ -0,0 +1,262 @@ + + +
+ + +lpr - print files +
+lpr +[ +-H server[:port] +] [ +-E +] [ +-U +username +] [ +-P destination[/instance] +] [ +-# +num-copies +[ +-h +] [ +-l +] [ +-m +] [ +-o option[=value] +] [ +-p +] [ +-q +] [ +-r +] [ +-C +title +] [ +-J +title +] [ +-T +title +] [ +file(s) +] +
+lpr submits files for printing. +Files named on the command line are sent to the named printer or the default destination if no destination is specified. +If no files are listed on the command-line, lpr reads the print file from the standard input. +
+CUPS provides many ways to set the default destination. The LPDEST and PRINTER environment variables are consulted first. +If neither are set, the current default set using the +lpoptions(1) + +command is used, followed by the default set using the +lpadmin(8) + +command. +
+The following options are recognized by lpr: +
+-E
+Forces encryption when connecting to the server.
+
-H server[:port]
+Specifies an alternate server.
+Note: This option must occur before all others.
+
-C "name"
+
-J "name"
+
-T "name"
+Sets the job name/title.
+
-P destination[/instance]
+Prints files to the named printer.
+
-U username
+Specifies an alternate username.
+
-# copies
+Sets the number of copies to print.
+
-h
+Disables banner printing. This option is equivalent to -o job-sheets=none.
+
-l
+Specifies that the print file is already formatted for the destination and should be sent without filtering.
+This option is equivalent to -o raw.
+
-m
+Send an email on job completion.
+
-o option[=value]
+Sets a job option.
+See "COMMON JOB OPTIONS" below.
+
-p
+Specifies that the print file should be formatted with a shaded header with the date, time, job name, and page number.
+This option is equivalent to -o prettyprint and is only useful when printing text files.
+
-q
+Hold job for printing.
+
-r
+Specifies that the named print files should be deleted after submitting them.
+
Aside from the printer-specific options reported by the +lpoptions(1) + +command, the following generic options are available: +
+-o job-sheets=name
+Prints a cover page (banner) with the document.
+The "name" can be "classified", "confidential", "secret", "standard", "topsecret", or "unclassified".
+
-o media=size
+Sets the page size to size. Most printers support at least the size names "a4", "letter", and "legal".
+
-o number-up={2|4|6|9|16}
+Prints 2, 4, 6, 9, or 16 document (input) pages on each output page.
+
-o orientation-requested=4
+Prints the job in landscape (rotated 90 degrees counter-clockwise).
+
-o orientation-requested=5
+Prints the job in landscape (rotated 90 degrees clockwise).
+
-o orientation-requested=6
+Prints the job in reverse portrait (rotated 180 degrees).
+
-o print-quality=3
+
-o print-quality=4
+
-o print-quality=5
+Specifies the output quality - draft (3), normal (4), or best (5).
+
-o sides=one-sided
+Prints on one side of the paper.
+
-o sides=two-sided-long-edge
+Prints on both sides of the paper for portrait output.
+
-o sides=two-sided-short-edge
+Prints on both sides of the paper for landscape output.
+
The -c, -d, -f, -g, -i, -n, -t, -v, and -w options are not supported by CUPS and produce a warning message if used. +
+Print two copies of a document to the default printer: +
++ lpr -# 2 filename + ++
Print a double-sided legal document to a printer called "foo": +
++ lpr -P foo -o media=legal -o sides=two-sided-long-edge filename + ++
Print a presentation document 2-up to a printer called "foo": +
++ lpr -P foo -o number-up=2 filename ++
cancel(1), + +lp(1), + +lpadmin(8), + +lpoptions(1), + +lpq(1), + +lprm(1), + +lpstat(1), + +CUPS Online Help (http://localhost:631/help) +
+Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/lprm.html b/cups-local/lprm.html new file mode 100644 index 0000000000..fa8177cd40 --- /dev/null +++ b/cups-local/lprm.html @@ -0,0 +1,156 @@ + + +
+ + +lprm - cancel print jobs +
+lprm +[ +-h hostname[:port] +] [ +-E +] [ +-U +username +] [ +-P +destination[/instance] + +] [ +- +] [ +job-id(s) +] +
+lprm +cancels print jobs that have been queued for printing. +If no arguments are supplied, the current job on the default destination is canceled. +You can specify one or more job ID numbers to cancel those jobs or use the - option to cancel all jobs. +
+The +lprm +command supports the following options: +
+-E
+Forces encryption when connecting to the server.
+
-P destination[/instance]
+Specifies the destination printer or class.
+
-U username
+Specifies an alternate username.
+
-h server[:port]
+Specifies an alternate server.
+Note: This option must occur before all others.
+
The CUPS version of +lprm +is compatible with the standard Berkeley command of the same name. +
+Cancel the current job on the default printer: +
++ lprm + ++
Cancel job 1234: +
++ lprm 1234 + ++
Cancel all jobs: +
++ lprm - ++
cancel(1), + +lp(1), + +lpq(1), + +lpr(1), + +lpstat(1), + +CUPS Online Help (http://localhost:631/help) +
+Copyright © 2021-2022 by OpenPrinting. + + diff --git a/cups-local/lpstat.html b/cups-local/lpstat.html new file mode 100644 index 0000000000..f1fec41fc4 --- /dev/null +++ b/cups-local/lpstat.html @@ -0,0 +1,223 @@ + + +
+ + +lpstat - print cups status information +
+lpstat +[ +-h hostname[:port] +] [ +-E +] [ +-H +] [ +-U +username +] [ +-l +] [ +-W +which-jobs +] [ +-a +[ +destination(s) +] ] [ +-c +[ +class(es) +] ] [ +-d +] [ +-e +] [ +-o +[ +destination(s) +] ] [ +-p +[ +printer(s) +] ] [ +-r +] [ +-R +] [ +-s +] [ +-t +] [ +-u +[ +user(s) +] ] [ +-v +[ +printer(s) +] ] +
+lpstat displays status information about the current classes, jobs, and printers. +When run with no arguments, lpstat will list active jobs queued by the current user. +
+The lpstat command supports the following options: +
+-E
+Forces encryption when connecting to the server.
+
-H
+Shows the server hostname and port.
+
-R
+Shows the ranking of print jobs.
+
-U username
+Specifies an alternate username.
+
-W which-jobs
+Specifies which jobs to show, "completed" or "not-completed" (the default).
+This option must appear before the -o option and/or any printer names, otherwise the default ("not-completed") value will be used in the request to the scheduler.
+
-a [printer(s)]
+Shows the accepting state of printer queues.
+If no printers are specified then all printers are listed.
+
-c [class(es)]
+Shows the printer classes and the printers that belong to them.
+If no classes are specified then all classes are listed.
+
-d
+Shows the current default destination.
+
-e
+Shows all available destinations on the local network.
+
-h server[:port]
+Specifies an alternate server.
+Note: This option must occur before all others.
+
-l
+Shows a long listing of printers, classes, or jobs.
+
-o [destination(s)]
+Shows the jobs queued on the specified destinations.
+If no destinations are specified all jobs are shown.
+
-p [printer(s)]
+Shows the printers and whether they are enabled for printing.
+If no printers are specified then all printers are listed.
+
-r
+Shows whether the CUPS server is running.
+
-s
+Shows a status summary, including the default destination, a list of classes and their member printers, and a list of printers and their associated devices.
+This is equivalent to using the -d, -c, and -v options.
+
-t
+Shows all status information.
+This is equivalent to using the -r, -d, -c, -v, -a, -p, and -o options.
+
-u [user(s)]
+Shows a list of print jobs queued by the specified users.
+If no users are specified, lists the jobs queued by the current user.
+
-v [printer(s)]
+Shows the printers and what device they are attached to.
+If no printers are specified then all printers are listed.
+
Unlike the System V printing system, CUPS allows printer names to contain any printable character except SPACE, TAB, "/", and "#". +Also, printer and class names are not case-sensitive. +
+The -h, -e, -E, -U, and -W options are unique to CUPS. +
+The Solaris -f, -P, and -S options are silently ignored. +
+cancel(1), + +lp(1), + +lpq(1), + +lpr(1), + +lprm(1), + +CUPS Online Help (http://localhost:631/help) +
+Copyright © 2021-2022 by OpenPrinting. + + diff --git a/libcups/cups.png b/libcups/cups.png new file mode 100644 index 0000000000..7de089536a Binary files /dev/null and b/libcups/cups.png differ diff --git a/libcups/cupspm.html b/libcups/cupspm.html new file mode 100644 index 0000000000..471fda09ca --- /dev/null +++ b/libcups/cupspm.html @@ -0,0 +1,12082 @@ + + + +
+Michael R Sweet
+Copyright © 2021-2023 by OpenPrinting. All Rights Reserved.
+++Please file issues on Github to provide feedback on this document.
+
CUPS provides the "cups" library to talk to the different parts of CUPS and with Internet Printing Protocol (IPP) printers. The "cups" library functions are accessed by including the <cups/cups.h> header.
CUPS is based on the Internet Printing Protocol ("IPP"), which allows clients (applications) to communicate with a server (the scheduler, printers, etc.) to get a list of destinations, send print jobs, and so forth. You identify which server you want to communicate with using a pointer to the opaque structure http_t. The CUPS_HTTP_DEFAULT constant can be used when you want to talk to the CUPS scheduler.
When writing software (other than printer drivers) that uses the "cups" library:
+Do not use undocumented or deprecated APIs,
+Do not rely on pre-configured printers,
+Do not assume that printers support specific features or formats, and
+Do not rely on implementation details.
+CUPS is designed to insulate users and developers from the implementation details of printers and file formats. The goal is to allow an application to supply a print file in a standard format with the user intent ("print four copies, two-sided on A4 media, and staple each copy") and have the printing system manage the printer communication and format conversion needed.
+Similarly, printer and job management applications can use standard query operations to obtain the status information in a common, generic form and use standard management operations to control the state of those printers and jobs.
+A Destination is a printer or print queue that accepts print jobs. A Print Job is a collection of one or more documents that are processed by a destination using options supplied when creating the job. A Document is a file (JPEG image, PDF file, etc.) suitable for printing. An Option controls some aspect of printing, such as the media used. Media is the sheets or roll that is printed on. An Attribute is an option encoded for an Internet Printing Protocol (IPP) request.
+The CUPS libraries can be used from any C, C++, or Objective C program. The method of compiling against the libraries varies depending on the operating system and installation of CUPS. The following sections show how to compile a simple program (shown below) in two common environments.
+The following simple program lists the available destinations:
+#include <stdio.h>
+#include <cups/cups.h>
+
+bool print_dest(void *cb_data, unsigned flags, cups_dest_t *dest)
+{
+ if (dest->instance)
+ printf("%s/%s\n", dest->name, dest->instance);
+ else
+ puts(dest->name);
+
+ return (true);
+}
+
+int main(void)
+{
+ cupsEnumDests(CUPS_DEST_FLAGS_NONE, 1000, NULL, 0, 0, print_dest, NULL);
+
+ return (0);
+}
+In Xcode, choose New Project... from the File menu (or press SHIFT+CMD+N), then select the Command Line Tool under the macOS Application project type. Click Next and enter a name for the project, for example "firstcups". Click Next and choose a project directory. The click Next to create the project.
+In the project window, click on the Build Phases group and expand the Link Binary with Libraries section. Click +, choose "Other...", and then find and choose the libcups3.dylib file in /usr/local/lib.
Finally, click on the main.c file in the sidebar and copy the example program to the file. Build and run (CMD+R) to see the list of destinations.
From the command-line, create a file called simple.c using your favorite editor, copy the example to this file, and save. Then run the following command to compile it with GCC and run it:
gcc -o simple `pkg-config --cflags cups3` simple.c `pkg-config --libs cups3`
+./simple
+The pkg-config command provides the compiler flags (pkg-config --cflags cups) and libraries (pkg-config --libs cups) needed for the local system.
Destinations, which in CUPS represent individual printers or classes (collections or pools) of printers, are represented by the cups_dest_t structure which includes the name ("name"), instance ("instance", saved options/settings), whether the destination is the default for the user ("is_default"), and the options and basic information associated with that destination ("num_options" and "options").
Historically destinations have been manually maintained by the administrator of a system or network, but CUPS also supports dynamic discovery of destinations on the current network.
+The cupsEnumDests function finds all of the available destinations:
bool
+cupsEnumDests(unsigned flags, int msec, int *cancel,
+ cups_ptype_t type, cups_ptype_t mask,
+ cups_dest_cb_t cb, void *cb_data)
+The "flags" argument specifies enumeration options, which at present must be CUPS_DEST_FLAGS_NONE.
The "msec" argument specifies the maximum amount of time that should be used for enumeration in milliseconds - interactive applications should keep this value to 5000 or less when run on the main thread.
+The "cancel" argument points to an integer variable that, when set to a non-zero value, will cause enumeration to stop as soon as possible. It can be NULL if not needed.
The "type" and "mask" arguments are bitfields that allow the caller to filter the destinations based on categories and/or capabilities. The destination's "printer-type" value is masked by the "mask" value and compared to the "type" value when filtering. For example, to only enumerate destinations that are hosted on the local system, pass CUPS_PRINTER_LOCAL for the "type" argument and CUPS_PRINTER_DISCOVERED for the "mask" argument. The following constants can be used for filtering:
CUPS_PRINTER_CLASS: A collection of destinations.
CUPS_PRINTER_FAX: A facsimile device.
CUPS_PRINTER_LOCAL: A local printer or class. This constant has the value 0 (no bits set) and is only used for the "type" argument and is paired with the CUPS_PRINTER_REMOTE or CUPS_PRINTER_DISCOVERED constant passed in the "mask" argument.
CUPS_PRINTER_REMOTE: A remote (shared) printer or class.
CUPS_PRINTER_DISCOVERED: An available network printer or class.
CUPS_PRINTER_BW: Can do B&W printing.
CUPS_PRINTER_COLOR: Can do color printing.
CUPS_PRINTER_DUPLEX: Can do two-sided printing.
CUPS_PRINTER_STAPLE: Can staple output.
CUPS_PRINTER_COLLATE: Can quickly collate copies.
CUPS_PRINTER_PUNCH: Can punch output.
CUPS_PRINTER_COVER: Can cover output.
CUPS_PRINTER_BIND: Can bind output.
CUPS_PRINTER_SORT: Can sort output (mailboxes, etc.)
CUPS_PRINTER_SMALL: Can print on Letter/Legal/A4-size media.
CUPS_PRINTER_MEDIUM: Can print on Tabloid/B/C/A3/A2-size media.
CUPS_PRINTER_LARGE: Can print on D/E/A1/A0-size media.
CUPS_PRINTER_VARIABLE: Can print on rolls and custom-size media.
The "cb" argument specifies a function to call for every destination that is found:
+typedef bool (*cups_dest_cb_t)(void *cb_data,
+ unsigned flags,
+ cups_dest_t *dest);
+The callback function receives a copy of the "cb_data" argument along with a bitfield ("flags") and the destination that was found. The "flags" argument can have any of the following constant (bit) values set:
+CUPS_DEST_FLAGS_MORE: There are more destinations coming.
CUPS_DEST_FLAGS_REMOVED: The destination has gone away and should be removed from the list of destinations a user can select.
CUPS_DEST_FLAGS_ERROR: An error occurred. The reason for the error can be found by calling the cupsLastError and/or cupsLastErrorString functions.
The callback function returns false to stop enumeration or true to continue.
++Note:
+The callback function will likely be called multiple times for the same destination, so it is up to the caller to suppress any duplicate destinations.
+
The following example shows how to use cupsEnumDests to get a filtered array of destinations:
typedef struct
+{
+ size_t num_dests;
+ cups_dest_t *dests;
+} my_cb_data_t;
+
+bool
+my_dest_cb(my_cb_data_t *cb_data, unsigned flags,
+ cups_dest_t *dest)
+{
+ if (flags & CUPS_DEST_FLAGS_REMOVED)
+ {
+ // Remove destination from array...
+ cb_data->num_dests =
+ cupsRemoveDest(dest->name, dest->instance,
+ cb_data->num_dests,
+ &(cb_data->dests));
+ }
+ else
+ {
+ // Add destination to array...
+ cb_data->num_dests =
+ cupsCopyDest(dest, cb_data->num_dests,
+ &(cb_data->dests));
+ }
+
+ return (true);
+}
+
+size_t // O - Number of destinations
+my_get_dests(
+ cups_ptype_t type, // I - Printer type bit values
+ cups_ptype_t mask, // I - Printer type mask values
+ cups_dest_t **dests) // O - Destinations
+{
+ my_cb_data_t cb_data = { 0, NULL };
+
+ if (!cupsEnumDests(CUPS_DEST_FLAGS_NONE, 1000, NULL, type,
+ mask, (cups_dest_cb_t)my_dest_cb,
+ &cb_data))
+ {
+ // An error occurred, free all of the destinations and
+ // return...
+ cupsFreeDests(cb_data.num_dests, cb_data.dests);
+
+ *dests = NULL;
+
+ return (0);
+ }
+
+ // Return the destination array...
+ *dests = cb_data.dests;
+
+ return (cb_data.num_dests);
+}
+The "num_options" and "options" members of the cups_dest_t structure provide basic attributes about the destination in addition to the user default options and values for that destination. The following names are predefined for various destination attributes:
"auth-info-required": The type of authentication required for printing to this destination: "none", "username,password", "domain,username,password", or "negotiate" (Kerberos).
+"printer-info": The human-readable description of the destination such as "My Laser Printer".
+"printer-is-accepting-jobs": "true" if the destination is accepting new jobs, "false" otherwise.
+"printer-is-shared": "true" if the destination is being shared with other computers, "false" otherwise.
+"printer-location": The human-readable location of the destination such as "Lab 4".
+"printer-make-and-model": The human-readable make and model of the destination such as "ExampleCorp LaserPrinter 4000 Series".
+"printer-state": "3" if the destination is idle, "4" if the destination is printing a job, and "5" if the destination is stopped.
+"printer-state-change-time": The UNIX time when the destination entered the current state.
+"printer-state-reasons": Additional comma-delimited state keywords for the destination such as "media-tray-empty-error" and "toner-low-warning".
+"printer-type": The cups_ptype_t value associated with the destination.
"printer-uri-supported": The URI associated with the destination; if not set, this destination was discovered but is not yet setup as a local printer.
+Use the cupsGetOption function to retrieve the value. For example, the following code gets the make and model of a destination:
const char *model = cupsGetOption("printer-make-and-model",
+ dest->num_options,
+ dest->options);
+Once a destination has been chosen, the cupsCopyDestInfo function can be used to gather detailed information about the destination:
cups_dinfo_t *
+cupsCopyDestInfo(http_t *http, cups_dest_t *dest);
+The "http" argument specifies a connection to the CUPS scheduler and is typically the constant CUPS_HTTP_DEFAULT. The "dest" argument specifies the destination to query.
The cups_dinfo_t structure that is returned contains a snapshot of the supported options and their supported, ready, and default values. It also can report constraints between different options and values, and recommend changes to resolve those constraints.
The cupsCheckDestSupported function can be used to test whether a particular option or option and value is supported:
bool
+cupsCheckDestSupported(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *info,
+ const char *option,
+ const char *value);
+The "option" argument specifies the name of the option to check. The following constants can be used to check the various standard options:
+CUPS_COPIES: Controls the number of copies that are produced.
CUPS_FINISHINGS: A comma-delimited list of integer constants that control the finishing processes that are applied to the job, including stapling, punching, and folding.
CUPS_MEDIA: Controls the media size that is used, typically one of the following: CUPS_MEDIA_3X5, CUPS_MEDIA_4X6, CUPS_MEDIA_5X7, CUPS_MEDIA_8X10, CUPS_MEDIA_A3, CUPS_MEDIA_A4, CUPS_MEDIA_A5, CUPS_MEDIA_A6, CUPS_MEDIA_ENV10, CUPS_MEDIA_ENVDL, CUPS_MEDIA_LEGAL, CUPS_MEDIA_LETTER, CUPS_MEDIA_PHOTO_L, CUPS_MEDIA_SUPERBA3, or CUPS_MEDIA_TABLOID.
CUPS_MEDIA_SOURCE: Controls where the media is pulled from, typically either CUPS_MEDIA_SOURCE_AUTO or CUPS_MEDIA_SOURCE_MANUAL.
CUPS_MEDIA_TYPE: Controls the type of media that is used, typically one of the following: CUPS_MEDIA_TYPE_AUTO, CUPS_MEDIA_TYPE_ENVELOPE, CUPS_MEDIA_TYPE_LABELS, CUPS_MEDIA_TYPE_LETTERHEAD, CUPS_MEDIA_TYPE_PHOTO, CUPS_MEDIA_TYPE_PHOTO_GLOSSY, CUPS_MEDIA_TYPE_PHOTO_MATTE, CUPS_MEDIA_TYPE_PLAIN, or CUPS_MEDIA_TYPE_TRANSPARENCY.
CUPS_NUMBER_UP: Controls the number of document pages that are placed on each media side.
CUPS_ORIENTATION: Controls the orientation of document pages placed on the media: CUPS_ORIENTATION_PORTRAIT or CUPS_ORIENTATION_LANDSCAPE.
CUPS_PRINT_COLOR_MODE: Controls whether the output is in color (CUPS_PRINT_COLOR_MODE_COLOR), grayscale (CUPS_PRINT_COLOR_MODE_MONOCHROME), or either (CUPS_PRINT_COLOR_MODE_AUTO).
CUPS_PRINT_QUALITY: Controls the generate quality of the output: CUPS_PRINT_QUALITY_DRAFT, CUPS_PRINT_QUALITY_NORMAL, or CUPS_PRINT_QUALITY_HIGH.
CUPS_SIDES: Controls whether prints are placed on one or both sides of the media: CUPS_SIDES_ONE_SIDED, CUPS_SIDES_TWO_SIDED_PORTRAIT, or CUPS_SIDES_TWO_SIDED_LANDSCAPE.
If the "value" argument is NULL, the cupsCheckDestSupported function returns whether the option is supported by the destination. Otherwise, the function returns whether the specified value of the option is supported.
The cupsFindDestSupported function returns the IPP attribute containing the supported values for a given option:
ipp_attribute_t *
+cupsFindDestSupported(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ const char *option);
+For example, the following code prints the supported finishing processes for a destination, if any, to the standard output:
+cups_dinfo_t *info = cupsCopyDestInfo(CUPS_HTTP_DEFAULT, dest);
+
+if (cupsCheckDestSupported(CUPS_HTTP_DEFAULT, dest, info,
+ CUPS_FINISHINGS, NULL))
+{
+ ipp_attribute_t *finishings =
+ cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info,
+ CUPS_FINISHINGS);
+ size_t i, count = ippGetCount(finishings);
+
+ puts("finishings supported:");
+ for (i = 0; i < count; i ++)
+ printf(" %d\n", ippGetInteger(finishings, i));
+}
+else
+ puts("finishings not supported.");
+The "job-creation-attributes" option can be queried to get a list of supported options. For example, the following code prints the list of supported options to the standard output:
+ipp_attribute_t *attrs =
+ cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info,
+ "job-creation-attributes");
+size_t i, count = ippGetCount(attrs);
+
+for (i = 0; i < count; i ++)
+ puts(ippGetString(attrs, i, NULL));
+There are two sets of default values - user defaults that are available via the "num_options" and "options" members of the cups_dest_t structure, and destination defaults that available via the cups_dinfo_t structure and the cupsFindDestDefault function which returns the IPP attribute containing the default value(s) for a given option:
ipp_attribute_t *
+cupsFindDestDefault(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ const char *option);
+The user defaults from cupsGetOption should always take preference over the destination defaults. For example, the following code prints the default finishings value(s) to the standard output:
const char *def_value =
+ cupsGetOption(CUPS_FINISHINGS, dest->num_options,
+ dest->options);
+ipp_attribute_t *def_attr =
+ cupsFindDestDefault(CUPS_HTTP_DEFAULT, dest, info,
+ CUPS_FINISHINGS);
+
+if (def_value != NULL)
+{
+ printf("Default finishings: %s\n", def_value);
+}
+else
+{
+ int i, count = ippGetCount(def_attr);
+
+ printf("Default finishings: %d",
+ ippGetInteger(def_attr, 0));
+ for (i = 1; i < count; i ++)
+ printf(",%d", ippGetInteger(def_attr, i));
+ putchar('\n');
+}
+The finishings and media options also support queries for the ready, or loaded, values. For example, a printer may have punch and staple finishers installed but be out of staples - the supported values will list both punch and staple finishing processes but the ready values will only list the punch processes. Similarly, a printer may support hundreds of different sizes of media but only have a single size loaded at any given time - the ready values are limited to the media that is actually in the printer.
+The cupsFindDestReady function finds the IPP attribute containing the ready values for a given option:
ipp_attribute_t *
+cupsFindDestReady(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *dinfo, const char *option);
+For example, the following code lists the ready finishing processes:
+ipp_attribute_t *ready_finishings =
+ cupsFindDestReady(CUPS_HTTP_DEFAULT, dest, info,
+ CUPS_FINISHINGS);
+
+if (ready_finishings != NULL)
+{
+ int i, count = ippGetCount(ready_finishings);
+
+ puts("finishings ready:");
+ for (i = 0; i < count; i ++)
+ printf(" %d\n", ippGetInteger(ready_finishings, i));
+}
+else
+ puts("no finishings are ready.");
+CUPS provides functions for querying the dimensions, margins, color, source (tray/roll), and type for each of the supported media size options. The cups_size_t structure is used to describe media:
typedef struct cups_size_s
+{
+ char media[128];
+ char color[128];
+ char source[128];
+ char type[128];
+ int width, length;
+ int bottom, left, right, top;
+} cups_size_t;
+The "media" member specifies a PWG self-describing media size name such as "na_letter_8.5x11in", "iso_a4_210x297mm", etc. The "color" member specifies a PWG media color name such as "white", "blue", etc. The "source" member specifies a standard keyword for the paper tray or roll such as "tray-1", "manual", "by-pass-tray" (multi-purpose tray), etc. The "type" member specifies a PWG media type name such as "stationery", "photographic", "envelope", "transparency", etc.
+The "width" and "length" members specify the dimensions of the media in hundredths of millimeters (1/2540th of an inch). The "bottom", "left", "right", and "top" members specify the margins of the printable area, also in hundredths of millimeters.
+The cupsGetDestMediaByName and cupsGetDestMediaBySize functions lookup the media size information using a standard media size name or dimensions in hundredths of millimeters:
bool
+cupsGetDestMediaByName(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ const char *media,
+ unsigned flags, cups_size_t *size);
+
+bool
+cupsGetDestMediaBySize(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ int width, int length,
+ unsigned flags, cups_size_t *size);
+The "media", "width", and "length" arguments specify the size to lookup. The "flags" argument specifies a bitfield controlling various lookup options:
+CUPS_MEDIA_FLAGS_DEFAULT: Find the closest size supported by the printer.
CUPS_MEDIA_FLAGS_BORDERLESS: Find a borderless size.
CUPS_MEDIA_FLAGS_DUPLEX: Find a size compatible with two-sided printing.
CUPS_MEDIA_FLAGS_EXACT: Find an exact match for the size.
CUPS_MEDIA_FLAGS_READY: If the printer supports media sensing or configuration of the media in each tray/source, find the size amongst the "ready" media.
If a matching size is found for the destination, the size information is stored in the structure pointed to by the "size" argument and true is returned. Otherwise false is returned.
For example, the following code prints the margins for two-sided printing on US Letter media:
+cups_size_t size;
+
+if (cupsGetDestMediaByName(CUPS_HTTP_DEFAULT, dest, info,
+ CUPS_MEDIA_LETTER,
+ CUPS_MEDIA_FLAGS_DUPLEX, &size))
+{
+ puts("Margins for duplex US Letter:");
+ printf(" Bottom: %.2fin\n", size.bottom / 2540.0);
+ printf(" Left: %.2fin\n", size.left / 2540.0);
+ printf(" Right: %.2fin\n", size.right / 2540.0);
+ printf(" Top: %.2fin\n", size.top / 2540.0);
+}
+else
+ puts("Margins for duplex US Letter are not available.");
+You can also enumerate all of the sizes that match a given "flags" value using the cupsGetDestMediaByIndex and cupsGetDestMediaCount functions:
bool
+cupsGetDestMediaByIndex(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *dinfo, int n,
+ unsigned flags, cups_size_t *size);
+
+size_t
+cupsGetDestMediaCount(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *dinfo, unsigned flags);
+For example, the following code prints the list of ready media and corresponding margins:
+cups_size_t size;
+size_t i;
+size_t count = cupsGetDestMediaCount(CUPS_HTTP_DEFAULT,
+ dest, info,
+ CUPS_MEDIA_FLAGS_READY);
+
+for (i = 0; i < count; i ++)
+{
+ if (cupsGetDestMediaByIndex(CUPS_HTTP_DEFAULT, dest, info,
+ i, CUPS_MEDIA_FLAGS_READY,
+ &size))
+ {
+ printf("%s:\n", size.name);
+ printf(" Width: %.2fin\n", size.width / 2540.0);
+ printf(" Length: %.2fin\n", size.length / 2540.0);
+ printf(" Bottom: %.2fin\n", size.bottom / 2540.0);
+ printf(" Left: %.2fin\n", size.left / 2540.0);
+ printf(" Right: %.2fin\n", size.right / 2540.0);
+ printf(" Top: %.2fin\n", size.top / 2540.0);
+ }
+}
+Finally, the cupsGetDestMediaDefault function returns the default media size:
bool
+cupsGetDestMediaDefault(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *dinfo, unsigned flags,
+ cups_size_t *size);
+CUPS provides three functions to get localized, human-readable strings in the user's current locale for options and values: cupsLocalizeDestMedia, cupsLocalizeDestOption, and cupsLocalizeDestValue:
const char *
+cupsLocalizeDestMedia(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *info, unsigned flags,
+ cups_size_t *size);
+
+const char *
+cupsLocalizeDestOption(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *info,
+ const char *option);
+
+const char *
+cupsLocalizeDestValue(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *info,
+ const char *option, const char *value);
+Once you are ready to submit a print job, you create a job using the cupsCreateDestJob function:
ipp_status_t
+cupsCreateDestJob(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *info, int *job_id,
+ const char *title, int num_options,
+ cups_option_t *options);
+The "title" argument specifies a name for the print job such as "My Document". The "num_options" and "options" arguments specify the options for the print job which are allocated using the cupsAddOption function.
When successful, the job's numeric identifier is stored in the integer pointed to by the "job_id" argument and IPP_STATUS_OK is returned. Otherwise, an IPP error status is returned.
For example, the following code creates a new job that will print 42 copies of a two-sided US Letter document:
+int job_id = 0;
+size_ num_options = 0;
+cups_option_t *options = NULL;
+
+num_options = cupsAddIntegerOption(CUPS_COPIES, 42,
+ num_options, &options);
+num_options = cupsAddOption(CUPS_MEDIA, CUPS_MEDIA_LETTER,
+ num_options, &options);
+num_options = cupsAddOption(CUPS_SIDES,
+ CUPS_SIDES_TWO_SIDED_PORTRAIT,
+ num_options, &options);
+
+if (cupsCreateDestJob(CUPS_HTTP_DEFAULT, dest, info,
+ &job_id, "My Document", num_options,
+ options) == IPP_STATUS_OK)
+ printf("Created job: %d\n", job_id);
+else
+ printf("Unable to create job: %s\n",
+ cupsLastErrorString());
+Once the job is created, you submit documents for the job using the cupsStartDestDocument, cupsWriteRequestData, and cupsFinishDestDocument functions:
http_status_t
+cupsStartDestDocument(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *info, int job_id,
+ const char *docname,
+ const char *format,
+ size_t num_options,
+ cups_option_t *options,
+ bool last_document);
+
+http_status_t
+cupsWriteRequestData(http_t *http, const char *buffer,
+ size_t length);
+
+ipp_status_t
+cupsFinishDestDocument(http_t *http, cups_dest_t *dest,
+ cups_dinfo_t *info);
+The "docname" argument specifies the name of the document, typically the original filename. The "format" argument specifies the MIME media type of the document, including the following constants:
+CUPS_FORMAT_JPEG: "image/jpeg"
CUPS_FORMAT_PDF: "application/pdf"
CUPS_FORMAT_POSTSCRIPT: "application/postscript"
CUPS_FORMAT_TEXT: "text/plain"
The "num_options" and "options" arguments specify per-document print options, which at present must be 0 and NULL. The "last_document" argument specifies whether this is the last document in the job.
For example, the following code submits a PDF file to the job that was just created:
+FILE *fp = fopen("filename.pdf", "rb");
+size_t bytes;
+char buffer[65536];
+
+if (cupsStartDestDocument(CUPS_HTTP_DEFAULT, dest, info,
+ job_id, "filename.pdf", 0, NULL,
+ 1) == HTTP_STATUS_CONTINUE)
+{
+ while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0)
+ if (cupsWriteRequestData(CUPS_HTTP_DEFAULT, buffer,
+ bytes) != HTTP_STATUS_CONTINUE)
+ break;
+
+ if (cupsFinishDestDocument(CUPS_HTTP_DEFAULT, dest,
+ info) == IPP_STATUS_OK)
+ puts("Document send succeeded.");
+ else
+ printf("Document send failed: %s\n",
+ cupsLastErrorString());
+}
+
+fclose(fp);
+CUPS provides a rich API for sending IPP requests to the scheduler or printers, typically from management or utility applications whose primary purpose is not to send print jobs.
+The connection to the scheduler or printer is represented by the HTTP connection type http_t. The cupsConnectDest function connects to the scheduler or printer associated with the destination:
http_t *
+cupsConnectDest(cups_dest_t *dest, unsigned flags, int msec,
+ int *cancel, char *resource,
+ size_t resourcesize, cups_dest_cb_t cb,
+ void *cb_data);
+The "dest" argument specifies the destination to connect to.
+The "flags" argument specifies whether you want to connect to the scheduler (CUPS_DEST_FLAGS_NONE) or device/printer (CUPS_DEST_FLAGS_DEVICE) associated with the destination.
The "msec" argument specifies how long you are willing to wait for the connection to be established in milliseconds. Specify a value of -1 to wait indefinitely.
The "cancel" argument specifies the address of an integer variable that can be set to a non-zero value to cancel the connection. Specify a value of NULL to not provide a cancel variable.
The "resource" and "resourcesize" arguments specify the address and size of a character string array to hold the path to use when sending an IPP request.
+The "cb" and "cb_data" arguments specify a destination callback function that returns true to continue connecting or false to stop. The destination callback works the same way as the one used for the cupsEnumDests function.
On success, a HTTP connection is returned that can be used to send IPP requests and get IPP responses.
+For example, the following code connects to the printer associated with a destination with a 30 second timeout:
+char resource[256];
+http_t *http = cupsConnectDest(dest, CUPS_DEST_FLAGS_DEVICE,
+ 30000, NULL, resource,
+ sizeof(resource), NULL, NULL);
+IPP requests are represented by the IPP message type ipp_t and each IPP attribute in the request is representing using the type ipp_attribute_t. Each IPP request includes an operation code (IPP_OP_CREATE_JOB, IPP_OP_GET_PRINTER_ATTRIBUTES, etc.) and a 32-bit integer identifier.
The ippNewRequest function creates a new IPP request with a process-unique identifier:
ipp_t *
+ippNewRequest(ipp_op_t op);
+The "op" argument specifies the IPP operation code for the request. For example, the following code creates an IPP Get-Printer-Attributes request:
+ipp_t *request = ippNewRequest(IPP_OP_GET_PRINTER_ATTRIBUTES);
+The request identifier is automatically set to a unique value for the current process.
+Each IPP request starts with two IPP attributes, "attributes-charset" and "attributes-natural-language", followed by IPP attribute(s) that specify the target of the operation. The ippNewRequest function automatically adds the correct "attributes-charset" and "attributes-natural-language" attributes, but you must add the target attribute(s). For example, the following code adds the "printer-uri" attribute to the IPP Get-Printer-Attributes request to specify which printer is being queried:
const char *printer_uri = cupsGetOption("device-uri",
+ dest->num_options,
+ dest->options);
+
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI,
+ "printer-uri", NULL, printer_uri);
+++Note:
+If we wanted to query the scheduler instead of the device, we would look up the "printer-uri-supported" option instead of the "device-uri" value.
+
The ippAddString function adds the "printer-uri" attribute the the IPP request. The IPP_TAG_OPERATION argument specifies that the attribute is part of the operation attributes group. The IPP_TAG_URI argument specifies that the value is a Universal Resource Identifier (URI) string. The NULL argument specifies there is no language (English, French, Japanese, etc.) associated with the string, and the "printer_uri" argument specifies the string value.
The IPP Get-Printer-Attributes request also supports an IPP attribute called "requested-attributes" that lists the attributes and values you are interested in. For example, the following code requests the printer state attributes:
+static const char * const requested_attributes[] =
+{
+ "printer-state",
+ "printer-state-message",
+ "printer-state-reasons"
+};
+
+ippAddStrings(request, IPP_TAG_OPERATION, IPP_TAG_KEYWORD,
+ "requested-attributes", 3, NULL,
+ requested_attributes);
+The ippAddStrings function adds an attribute with one or more strings, in this case three. The IPP_TAG_KEYWORD argument specifies that the strings are keyword values, which are used for attribute names. All strings use the same language (NULL), and the attribute will contain the three strings in the array requested_attributes.
CUPS provides many functions to adding attributes of different types:
+ippAddBoolean adds a boolean (IPP_TAG_BOOLEAN) attribute with one value.
ippAddCollection adds a collection (IPP_TAG_BEGIN_COLLECTION) attribute with one value.
ippAddCollections adds a collection (IPP_TAG_BEGIN_COLLECTION) attribute with one or more values.
ippAddInteger adds an enum (IPP_TAG_ENUM) or integer (IPP_TAG_INTEGER) attribute with one value.
ippAddIntegers adds an enum or integer attribute with one or more values.
ippAddOctetString adds an octetString attribute with one value.
ippAddOutOfBand adds a admin-defined (IPP_TAG_ADMINDEFINE), default (IPP_TAG_DEFAULT), delete-attribute (IPP_TAG_DELETEATTR), no-value (IPP_TAG_NOVALUE), not-settable (IPP_TAG_NOTSETTABLE), unknown (IPP_TAG_UNKNOWN), or unsupported (IPP_TAG_UNSUPPORTED_VALUE) out-of-band attribute.
ippAddRange adds a rangeOfInteger attribute with one range.
ippAddRanges adds a rangeOfInteger attribute with one or more ranges.
ippAddResolution adds a resolution attribute with one resolution.
ippAddResolutions adds a resolution attribute with one or more resolutions.
ippAddString adds a charset (IPP_TAG_CHARSET), keyword (IPP_TAG_KEYWORD), mimeMediaType (IPP_TAG_MIMETYPE), name (IPP_TAG_NAME and IPP_TAG_NAMELANG), naturalLanguage (IPP_TAG_NATURAL_LANGUAGE), text (IPP_TAG_TEXT and IPP_TAG_TEXTLANG), uri (IPP_TAG_URI), or uriScheme (IPP_TAG_URISCHEME) attribute with one value.
ippAddStrings adds a charset, keyword, mimeMediaType, name, naturalLanguage, text, uri, or uriScheme attribute with one or more values.
Once you have created the IPP request, you can send it using the cupsDoRequest function. For example, the following code sends the IPP Get-Printer-Attributes request to the destination and saves the response:
ipp_t *response = cupsDoRequest(http, request, resource);
+For requests like Send-Document that include a file, the cupsDoFileRequest function should be used:
ipp_t *response = cupsDoFileRequest(http, request, resource,
+ filename);
+Both cupsDoRequest and cupsDoFileRequest free the IPP request. If a valid IPP response is received, it is stored in a new IPP message (ipp_t) and returned to the caller. Otherwise NULL is returned.
The status from the most recent request can be queried using the cupsLastError function, for example:
if (cupsLastError() >= IPP_STATUS_ERROR_BAD_REQUEST)
+{
+ /* request failed */
+}
+A human-readable error message is also available using the cupsLastErrorString function:
if (cupsLastError() >= IPP_STATUS_ERROR_BAD_REQUEST)
+{
+ /* request failed */
+ printf("Request failed: %s\n", cupsLastErrorString());
+}
+Each response to an IPP request is also an IPP message (ipp_t) with its own IPP attributes (ipp_attribute_t) that includes a status code (IPP_STATUS_OK, IPP_STATUS_ERROR_BAD_REQUEST, etc.) and the corresponding 32-bit integer identifier from the request.
CUPS provides many functions to access the attributes and values in an IPP response message:
+ippFindAttribute finds the first occurrence of an attribute.
ippFindNextAttribute finds the next occurrence of an attribute.
ippGetBoolean gets a boolean value for an attribute.
ippGetCollection gets a collection value for an attribute.
ippGetCount gets the number of values in an attribute.
ippGetDate gets a date value for an attribute.
ippGetFirstAttribute gets the first attribute in the IPP response.
ippGetGroupTag gets the group tag associated with an attribute.
ippGetInteger gets the integer or enum value for an attribute.
ippGetName gets the name of an attribute.
ippGetNextAttribute gets the next attribute in the IPP response.
ippGetOctetString gets an octetString value for an attribute.
ippGetRange gets a rangeOfInteger value for an attribute.
ippGetRequestId gets the request ID number for the IPP response.
ippGetResolution gets a resolution value for an attribute.
ippGetStatusCode gets the status code for the IPP response.
ippGetString gets a string value for an attribute.
ippGetValueTag gets the value tag ("syntax") for an attribute.
ippGetVersion gets the IPP version used for the IPP response.
ippRestore restores a previous position in the IPP response.
ippSave saves the current position in the IPP response.
For example, the following code finds the printer state attributes and prints their values:
+ipp_attribute_t *attr;
+
+if ((attr = ippFindAttribute(response, "printer-state",
+ IPP_TAG_ENUM)) != NULL)
+{
+ printf("printer-state=%s\n",
+ ippEnumString("printer-state", ippGetInteger(attr, 0)));
+}
+else
+{
+ puts("printer-state=unknown");
+}
+
+if ((attr = ippFindAttribute(response, "printer-state-message",
+ IPP_TAG_TEXT)) != NULL)
+{
+ printf("printer-state-message=\"%s\"\n",
+ ippGetString(attr, 0, NULL)));
+}
+
+if ((attr = ippFindAttribute(response, "printer-state-reasons",
+ IPP_TAG_KEYWORD)) != NULL)
+{
+ size_t i, count = ippGetCount(attr);
+
+ puts("printer-state-reasons=");
+ for (i = 0; i < count; i ++)
+ printf(" %s\n", ippGetString(attr, i, NULL)));
+}
+Once you are done using the IPP response message, free it using the ippDelete function:
ippDelete(response);
+CUPS normally handles authentication through the console. GUI applications should set a password callback using the cupsSetPasswordCB function:
void
+cupsSetPasswordCB(cups_password_cb_t cb, void *cb_data);
+The password callback will be called when needed and is responsible for setting the current user name using cupsSetUser and returning a string:
const char *
+cups_password_cb(const char *prompt, http_t *http,
+ const char *method, const char *resource,
+ void *cb_data);
+The "prompt" argument is a string from CUPS that should be displayed to the user.
+The "http" argument is the connection hosting the request that is being authenticated. The password callback can call the httpGetField and httpGetSubField functions to look for additional details concerning the authentication challenge.
The "method" argument specifies the HTTP method used for the request and is typically "POST".
+The "resource" argument specifies the path used for the request.
+The "cb_data" argument provides the user data pointer from the cupsSetPasswordCB call.
The CUPS 3.x library removes all of the deprecated and obsolete APIs from CUPS 2.x and earlier and makes other naming changes for consistency. As a result, the CUPS 3.x library is no longer binary compatible with programs compiled against the CUPS 2.x library and earlier, and some source code may need minor changes to compile with the new library. This file describes the changes and how to migrate to the new library.
+The following general changes have been made to the CUPS API:
+Boolean values now use the C99 bool type.
Counts, indices, and lengths now use the size_t type - this affects the array, HTTP, IPP, and option APIs in particular.
Accessor functions have been renamed (as necessary) to use the "get" and "set" verbs, for example cupsServer is now cupsGetServer and httpEncryption is now httpSetEncryption.
cupsDoAuthentication now returns a bool value - true on success or false on failure - instead of the old int values 0 and -1, respectively.
httpGets now has the http_t pointer as the first argument.
The cups_size_t structure now includes "color", "source", and "type" members to allow specification of media color, source (input tray/roll), and type.
The cups_encoding_t enumeration values now use the CUPS_ENCODING_ prefix for consistency with other enumerated types.
X.509 certificates are now passed as C strings containing the PEM-encoded data instead of a cups_array_t * of raw data.
The following CUPS 2.x API functions have been removed from the CUPS library:
+Old class/printer functions: cupsGetClasses and cupsGetPrinters.
HTTP functions: httpAddCredential, httpCheck, httpCompareCredentials, httpConnect2, httpConnectEncrypt, httpCreateCredentials, httpDecode64_2, httpEncode64_2, and httpFreeCredentials.
PPD file functions: ppdClose, ppdCollect, ppdCollect2, ppdConflicts, ppdEmit, ppdEmitAfterOrder, ppdEmitFd, ppdEmitJCL, ppdEmitJCLEnd, ppdEmitString, ppdErrorString, ppdFindAttr, ppdFindChoice, ppdFindCustomOption, ppdFindCustomParam, ppdFindMarkedChoice, ppdFindNextAttr, ppdFindOption, ppdFirstCustomParam, ppdFirstOption, ppdInstallableConflict, ppdIsMarked, ppdLastError, ppdLocalize, ppdLocalizeAttr, ppdLocalizeIPPReason, ppdLocalizeMarkerName, ppdMarkDefaults, ppdMarkOption, ppdNextCustomParam, ppdNextOption, ppdOpen, ppdOpen2, ppdOpenFd, ppdOpenFile, ppdPageLength, ppdPageSize, ppdPageSizeLimits, ppdPageWidth, and ppdSetConformance.
PPD helper functions: cupsGetConflicts, cupsGetPPD, cupsGetPPD2, cupsGetPPD3, cupsGetServerPPD, cupsMarkOptions, cupsRasterInterpretPPD, and cupsResolveConflicts.
Deprecated functions: cupsTempFile.
Non-destination print functions: cupsCancelJob, cupsCancelJob2, cupsCreateJob, cupsCloseJob, cupsFinishDocument, cupsGetDefault, cupsGetDefault2, cupsPrintFile, cupsPrintFile2, cupsPrintFiles, cupsPrintFiles2, and cupsSendDocument.
Array functions: cupsArrayNew2 and cupsArrayNew3.
Raster functions: cupsRasterReadHeader2 and cupsRasterWriteHeader2.
The following functions have been renamed in CUPS 3.0:
+| Old CUPS 2.x Name | +New CUPS 3.0 Name | +
|---|---|
cupsArrayCount |
+ cupsArrayGetCount |
+
cupsArrayFirst |
+ cupsArrayGetFirst |
+
cupsArrayIndex |
+ cupsArrayGetElement |
+
cupsArrayLast |
+ cupsArrayGetLast |
+
cupsArrayNew3 |
+ cupsArrayNew |
+
cupsArrayNext |
+ cupsArrayGetNext |
+
cupsArrayPrev |
+ cupsArrayGetPrev |
+
cupsEncryption |
+ cupsGetEncryption |
+
cupsFileCompression |
+ cupsFileIsCompressed |
+
cupsGetDests2 |
+ cupsGetDests |
+
cupsGetPassword2 |
+ cupsGetPassword |
+
cupsLangGet |
+ cupsLangFind |
+
cupsLastError |
+ cupsGetError |
+
cupsLastErrorString |
+ cupsGetErrorString |
+
cupsNotifySubject |
+ cupsLocalizeNotifySubject |
+
cupsNotifyText |
+ cupsLocalizeNotifyText |
+
cupsRasterInitPWGHeader |
+ cupsRasterInitHeader |
+
cupsRasterReadHeader2 |
+ cupsRasterReadHeader |
+
cupsRasterWriteHeader2 |
+ cupsRasterWriteHeader |
+
cupsServer |
+ cupsGetServer |
+
cupsSetPasswordCB2 |
+ cupsSetPasswordCB |
+
cupsTempFile2 |
+ cupsTempFile |
+
cupsUser |
+ cupsGetUser |
+
cupsUserAgent |
+ cupsGetUserAgent |
+
httpAddrAny |
+ httpAddrIsAny |
+
httpAddrEqual |
+ httpAddrIsEqual |
+
httpAddrFamily |
+ httpAddrGetFamily |
+
httpAddrLength |
+ httpAddrGetLength |
+
httpAddrLocalhost |
+ httpAddrIsLocalhost |
+
httpAddrPort |
+ httpAddrGetPort |
+
httpAddrString |
+ httpAddrGetString |
+
httpBlocking |
+ httpSetBlocking |
+
httpConnect2 |
+ httpConnect |
+
httpCopyCredentials |
+ httpCopyPeerCredentials |
+
httpCredentialsAreValidForName |
+ cupsAreCredentialsValidForName |
+
httpCredentialsGetExpiration |
+ cupsGetCredentialsExpiration |
+
httpCredentialsGetTrust |
+ cupsGetCredentialsTrust |
+
httpCredentialsString |
+ cupsGetCredentialsInfo |
+
httpDecode64_2 |
+ httpDecode64 |
+
httpDelete |
+ httpWriteRequest |
+
httpEncode64_2 |
+ httpEncode64 |
+
httpEncryption |
+ httpSetEncryption |
+
httpError |
+ httpGetError |
+
httpGet |
+ httpWriteRequest |
+
httpGetDateString2 |
+ httpGetDateString |
+
httpGetLength2 |
+ httpGetLength |
+
httpLoadCredentials |
+ cupsLoadCredentials |
+
httpOptions |
+ httpWriteRequest |
+
httpPost |
+ httpWriteRequest |
+
httpPut |
+ httpWriteRequest |
+
httpRead2 |
+ httpRead |
+
httpReconnect2 |
+ httpReconnect |
+
httpSaveCredentials |
+ cupsSaveCredentials |
+
httpStatus |
+ httpStatusString |
+
httpTrace |
+ httpWriteRequest |
+
httpWrite2 |
+ httpWrite |
+
ippFirstAttribute |
+ ippGetFirstAttribute |
+
ippLength |
+ ippGetLength |
+
ippNextAttribute |
+ ippGetNextAttribute |
+
ippPort |
+ ippGetPort |
+
Similarly, the following types have been renamed in CUPS 3.0:
+| Old CUPS 2.x Name | +New CUPS 3.0 Name | +
|---|---|
cups_acopy_func_t |
+ cups_acopy_cb_t |
+
cups_afree_func_t |
+ cups_afree_cb_t |
+
cups_array_func_t |
+ cups_array_cb_t |
+
cups_mode_t |
+ cups_raster_mode_t |
+
cups_raster_iocb_t |
+ cups_raster_cb_t |
+
cups_password_cb2_t |
+ cups_password_cb_t |
+
cups_page_header2_t |
+ cups_page_header_t |
+
ipp_copycb_t |
+ ipp_copy_cb_t |
+
ipp_iocb_t |
+ ipp_io_cb_t |
+
Add a destination to the list of destinations.
++size_t cupsAddDest(const char *name, const char *instance, size_t num_dests, cups_dest_t **dests);
+| name | +Destination name |
|---|---|
| instance | +Instance name or NULL for none/primary |
| num_dests | +Number of destinations |
| dests | +Destinations |
New number of destinations
+This function cannot be used to add a new class or printer queue,
+it only adds a new container of saved options for the named
+destination or instance.
+
+If the named destination already exists, the destination list is
+returned unchanged. Adding a new instance of a destination creates
+a copy of that destination's options.
+
+Use the cupsSaveDests function to save the updated list of
+destinations to the user's lpoptions file.
Add the option corresponding to the specified media size.
++size_t cupsAddDestMediaOptions(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, unsigned flags, cups_size_t *size, size_t num_options, cups_option_t **options);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| flags | +Media matching flags |
| size | +Media size |
| num_options | +Current number of options |
| options | +Options |
New number of options
+Add an integer option to an option array.
++size_t cupsAddIntegerOption(const char *name, int value, size_t num_options, cups_option_t **options);
+| name | +Name of option |
|---|---|
| value | +Value of option |
| num_options | +Number of options |
| options | +Pointer to options |
Number of options
+New option arrays can be initialized simply by passing 0 for the +"num_options" parameter.
+Add an option to an option array.
++size_t cupsAddOption(const char *name, const char *value, size_t num_options, cups_option_t **options);
+| name | +Name of option |
|---|---|
| value | +Value of option |
| num_options | +Number of options |
| options | +Pointer to options |
Number of options
+New option arrays can be initialized simply by passing 0 for the +"num_options" parameter.
+Return whether the credentials are valid + for the given name.
++bool cupsAreCredentialsValidForName(const char *common_name, const char *credentials);
+| common_name | +Name to check |
|---|---|
| credentials | +Credentials |
true if valid, false otherwise
Add an element to an array.
++bool cupsArrayAdd(cups_array_t *a, void *e);
+| a | +Array |
|---|---|
| e | +Element |
true on success, false on failure
This function adds an element to an array. When adding an element to a +sorted array, non-unique elements are appended at the end of the run of +identical elements. For unsorted arrays, the element is appended to the end +of the array.
+Add zero or more delimited strings to an array.
++bool cupsArrayAddStrings(cups_array_t *a, const char *s, char delim);
+| a | +Array |
|---|---|
| s | +Delimited strings |
| delim | +Delimiter character |
true on success, false on failure
This function adds zero or more delimited strings to an array created using
+the cupsArrayNewStrings function. Duplicate strings are not added.
+If the string pointer "s" is NULL or the empty string, no strings are
+added to the array. If "delim" is the space character, then all whitespace
+is recognized as a delimiter.
+
+Strings can be delimited by quotes ("foo", 'bar') and curly braces ("{foo}"),
+and characters can be escaped using the backslash () character. Outer
+quotes are stripped but inner ones are preserved.
Clear an array.
++void cupsArrayClear(cups_array_t *a);
+| a | +Array |
|---|
This function is equivalent to removing all elements in the array, so the +free callback (if any) is called for each element that is removed.
+Free all memory used by an array.
++void cupsArrayDelete(cups_array_t *a);
+| a | +Array |
|---|
This function frees all memory used by an array. The free callback (if any) +is called for each element in the array.
+Duplicate an array.
++cups_array_t *cupsArrayDup(cups_array_t *a);
+| a | +Array |
|---|
Duplicate array
+Find an element in an array.
++void *cupsArrayFind(cups_array_t *a, void *e);
+| a | +Array |
|---|---|
| e | +Element |
Element found or NULL
Get the number of elements in an array.
++size_t cupsArrayGetCount(cups_array_t *a);
+| a | +Array |
|---|
Number of elements
+Return the current element in an array.
++void *cupsArrayGetCurrent(cups_array_t *a);
+| a | +Array |
|---|
Element
+This function returns the current element in an array. The current element
+is undefined until you call cupsArrayFind, cupsArrayGetElement,
+cupsArrayGetFirst, or cupsArrayGetLast.
Get the N-th element in the array.
++void *cupsArrayGetElement(cups_array_t *a, size_t n);
+| a | +Array |
|---|---|
| n | +Index into array, starting at 0 |
N-th element or NULL
Get the first element in an array.
++void *cupsArrayGetFirst(cups_array_t *a);
+| a | +Array |
|---|
First element or NULL if the array is empty
Get the index of the current element.
++size_t cupsArrayGetIndex(cups_array_t *a);
+| a | +Array |
|---|
Index of the current element, starting at 0
+This function returns the index of the current element or SIZE_MAX if
+there is no current element. The current element is undefined until you call
+cupsArrayFind, cupsArrayGetElement, cupsArrayGetFirst,
+or cupsArrayGetLast.
Get the index of the last added or inserted element.
++size_t cupsArrayGetInsert(cups_array_t *a);
+| a | +Array |
|---|
Index of the last added or inserted element, starting at 0
+This function returns the index of the last added or inserted element or
+SIZE_MAX if no elements have been added or inserted.
Get the last element in the array.
++void *cupsArrayGetLast(cups_array_t *a);
+| a | +Array |
|---|
Last element orNULL if the array is empty
Get the next element in an array.
++void *cupsArrayGetNext(cups_array_t *a);
+| a | +Array |
|---|
Next element or NULL
This function returns the next element in an array. The next element is
+undefined until you call cupsArrayFind, cupsArrayGetElement,
+cupsArrayGetFirst, or cupsArrayGetLast to set the current
+element.
Get the previous element in an array.
++void *cupsArrayGetPrev(cups_array_t *a);
+| a | +Array |
|---|
Previous element or NULL
This function returns the previous element in an array. The previous element
+is undefined until you call cupsArrayFind, cupsArrayGetElement,
+cupsArrayGetFirst, or cupsArrayGetLast to set the current
+element.
Return the user data for an array.
++void *cupsArrayGetUserData(cups_array_t *a);
+| a | +Array |
|---|
User data
+Insert an element in an array.
++bool cupsArrayInsert(cups_array_t *a, void *e);
+| a | +Array |
|---|---|
| e | +Element |
true on success, false on failure
This function inserts an element in an array. When inserting an element +in a sorted array, non-unique elements are inserted at the beginning of the +run of identical elements. For unsorted arrays, the element is inserted at +the beginning of the array.
+Create a new array with callback functions.
++cups_array_t *cupsArrayNew(cups_array_cb_t f, void *d, cups_ahash_cb_t hf, size_t hsize, cups_acopy_cb_t cf, cups_afree_cb_t ff);
+| f | +Comparison callback function or NULL for an unsorted array |
|---|---|
| d | +User data or NULL |
| hf | +Hash callback function or NULL for unhashed lookups |
| hsize | +Hash size (>= 0) |
| cf | +Copy callback function or NULL for none |
| ff | +Free callback function or NULL for none |
Array
+This function creates a new array with optional callback functions. The
+comparison callback function ("f") is used to create a sorted array. The
+function receives pointers to two elements and the user data pointer ("d").
+The user data pointer argument can safely be omitted when not required so
+functions like strcmp can be used for sorted string arrays.
+
+
+int // Return -1 if a < b, 0 if a == b, and 1 if a > b
+compare_cb(void *a, void *b, void *d)
+{
+ ... "a" and "b" are the elements, "d" is the user data pointer
+}
+
+
+The hash callback function ("hf") is used to implement cached lookups with
+the specified hash size ("hsize"). The function receives a pointer to an
+element and the user data pointer ("d") and returns an unsigned integer
+representing a hash into the array. The hash value is of type size_t which
+provides at least 32-bits of resolution.
+
+
+size_t // Return hash value from 0 to (hashsize - 1)
+hash_cb(void *e, void *d)
+{
+ ... "e" is the element, "d" is the user data pointer
+}
+
+
+The copy callback function ("cf") is used to automatically copy/retain
+elements when added to the array or the array is copied with
+cupsArrayDup. The function receives a pointer to the element and the
+user data pointer ("d") and returns a new pointer that is stored in the array.
+
+
+void * // Return pointer to copied/retained element or NULL
+copy_cb(void *e, void *d)
+{
+ ... "e" is the element, "d" is the user data pointer
+}
+
+
+Finally, the free callback function ("cf") is used to automatically
+free/release elements when removed or the array is deleted. The function
+receives a pointer to the element and the user data pointer ("d").
+
+
+void
+free_cb(void *e, void *d)
+{
+ ... "e" is the element, "d" is the user data pointer
+}
+
+
+Create a new array of delimited strings.
++cups_array_t *cupsArrayNewStrings(const char *s, char delim);
+| s | +Delimited strings or NULL to create an empty array |
|---|---|
| delim | +Delimiter character |
Array
+This function creates an array that holds zero or more strings. The created
+array automatically manages copies of the strings passed and sorts them in
+ascending order using a case-sensitive comparison. If the string pointer "s"
+is NULL or the empty string, no strings are added to the newly created
+array.
+
+Additional strings can be added using the cupsArrayAdd or
+cupsArrayAddStrings functions.
Remove an element from an array.
++bool cupsArrayRemove(cups_array_t *a, void *e);
+| a | +Array |
|---|---|
| e | +Element |
true on success, false on failure
This function removes an element from an array. If more than one element +matches "e", only the first matching element is removed.
+Reset the current element to the last cupsArraySave.
+void *cupsArrayRestore(cups_array_t *a);
+| a | +Array |
|---|
New current element
+Mark the current element for a later cupsArrayRestore.
+bool cupsArraySave(cups_array_t *a);
+| a | +Array |
|---|
true on success, false on failure
The current element is undefined until you call cupsArrayFind,
+cupsArrayGetElement, cupsArrayGetFirst, or
+cupsArrayGetLast to set the current element.
+
+The save/restore stack is guaranteed to be at least 32 elements deep.
Cancel a job on a destination.
++ipp_status_t cupsCancelDestJob(http_t *http, cups_dest_t *dest, int job_id);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| job_id | +Job ID |
Status of cancel operation
+This function cancels the specified job. The "dest" argument is the name
+of the destination printer while the "job_id" is the number returned by
+cupsCreateDestJob.
+
+Returns IPP_STATUS_OK on success and
+IPP_STATUS_ERROR_NOT_AUTHORIZED or
+IPP_STATUS_ERROR_FORBIDDEN on failure.
Convert legacy character set to UTF-8.
++ssize_t cupsCharsetToUTF8(char *dest, const char *src, const size_t maxout, const cups_encoding_t encoding);
+| dest | +Target string |
|---|---|
| src | +Source string |
| maxout | +Max output size in bytes |
| encoding | +Encoding |
Number of bytes or -1 on error
Check that the option and value are supported + by the destination.
++bool cupsCheckDestSupported(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, const char *option, const char *value);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| option | +Option |
| value | +Value or NULL |
true if supported, false if not
Returns 1 if supported, 0 otherwise.
+Close a job and start printing.
++ipp_status_t cupsCloseDestJob(http_t *http, cups_dest_t *dest, cups_dinfo_t *info, int job_id);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| info | +Destination information |
| job_id | +Job ID |
IPP status code
+This function closes a job and starts printing. Use when the last call to
+cupsStartDestDocument passed false for "last_document". "job_id"
+is the job ID returned by cupsCreateDestJob. Returns IPP_STATUS_OK
+on success.
Safely concatenate two strings.
++size_t cupsConcatString(char *dst, const char *src, size_t dstsize);
+| dst | +Destination string |
|---|---|
| src | +Source string |
| dstsize | +Size of destination string buffer |
Length of string
+Wake up waiting threads.
++void cupsCondBroadcast(cups_cond_t *cond);
+| cond | +Condition |
|---|
Destroy a condition variable.
++void cupsCondDestroy(cups_cond_t *cond);
+| cond | +Condition |
|---|
Initialize a condition variable.
++void cupsCondInit(cups_cond_t *cond);
+| cond | +Condition |
|---|
Wait for a condition with optional timeout.
++void cupsCondWait(cups_cond_t *cond, cups_mutex_t *mutex, double timeout);
+| cond | +Condition |
|---|---|
| mutex | +Mutex |
| timeout | +Timeout in seconds (0 or negative for none) |
Open a connection to the destination.
++http_t *cupsConnectDest(cups_dest_t *dest, unsigned flags, int msec, int *cancel, char *resource, size_t resourcesize, cups_dest_cb_t cb, void *user_data);
+| dest | +Destination |
|---|---|
| flags | +Connection flags |
| msec | +Timeout in milliseconds |
| cancel | +Pointer to "cancel" variable |
| resource | +Resource buffer |
| resourcesize | +Size of resource buffer |
| cb | +Callback function |
| user_data | +User data pointer |
Connection to destination or NULL
Connect to the destination, returning a new http_t connection object
+and optionally the resource path to use for the destination. These calls
+will block until a connection is made, the timeout expires, the integer
+pointed to by "cancel" is non-zero, or the callback function (or block)
+returns 0. The caller is responsible for calling httpClose on the
+returned connection.
+
+The caller can pass CUPS_DEST_FLAGS_DEVICE for the "flags" argument to
+connect directly to the device associated with the destination. Otherwise,
+the connection is made to the CUPS scheduler associated with the destination.
+char *cupsCopyCredentials(const char *path, const char *common_name);
+| path | +Directory path for certificate/key store or NULL for default |
|---|---|
| common_name | +Common name |
Copy the X.509 certificate chain to a string.
++char *cupsCopyCredentialsKey(const char *path, const char *common_name);
+| path | +Directory path for certificate/key store or NULL for default |
|---|---|
| common_name | +Common name |
Copy the private key to a string.
++char *cupsCopyCredentialsRequest(const char *path, const char *common_name);
+| path | +Directory path for certificate/key store or NULL for default |
|---|---|
| common_name | +Common name |
Copy the X.509 certificate signing request to a string.
+Copy a destination.
++size_t cupsCopyDest(cups_dest_t *dest, size_t num_dests, cups_dest_t **dests);
+| dest | +Destination to copy |
|---|---|
| num_dests | +Number of destinations |
| dests | +Destination array |
New number of destinations
+Make a copy of the destination to an array of destinations (or just a single
+copy) - for use with the cupsEnumDests* functions. The caller is
+responsible for calling cupsFreeDests on the returned object(s).
Get conflicts and resolutions for a new + option/value pair.
++int cupsCopyDestConflicts(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, size_t num_options, cups_option_t *options, const char *new_option, const char *new_value, size_t *num_conflicts, cups_option_t **conflicts, size_t *num_resolved, cups_option_t **resolved);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| num_options | +Number of current options |
| options | +Current options |
| new_option | +New option |
| new_value | +New value |
| num_conflicts | +Number of conflicting options |
| conflicts | +Conflicting options |
| num_resolved | +Number of options to resolve |
| resolved | +Resolved options |
1 if there is a conflict, 0 if none, -1 on error
+"num_options" and "options" represent the currently selected options by the
+user. "new_option" and "new_value" are the setting the user has just
+changed.
+
+Returns 1 if there is a conflict, 0 if there are no conflicts, and -1 if
+there was an unrecoverable error such as a resolver loop.
+
+If "num_conflicts" and "conflicts" are not NULL, they are set to
+contain the list of conflicting option/value pairs. Similarly, if
+"num_resolved" and "resolved" are not NULL they will be set to the
+list of changes needed to resolve the conflict.
+
+If cupsCopyDestConflicts returns 1 but "num_resolved" and "resolved" are set
+to 0 and NULL, respectively, then the conflict cannot be resolved.
Get the supported values/capabilities for the + destination.
++cups_dinfo_t *cupsCopyDestInfo(http_t *http, cups_dest_t *dest);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
Destination information
+The caller is responsible for calling cupsFreeDestInfo on the return
+value. NULL is returned on error.
Safely copy two strings.
++size_t cupsCopyString(char *dst, const char *src, size_t dstsize);
+| dst | +Destination string |
|---|---|
| src | +Source string |
| dstsize | +Size of destination string buffer |
Length of string
+Make an X.509 certificate and private key pair.
++bool cupsCreateCredentials(const char *path, bool ca_cert, cups_credpurpose_t purpose, cups_credtype_t type, cups_credusage_t usage, const char *organization, const char *org_unit, const char *locality, const char *state_province, const char *country, const char *common_name, size_t num_alt_names, const char *const *alt_names, const char *root_name, time_t expiration_date);
+| path | +Directory path for certificate/key store or NULL for default |
|---|---|
| ca_cert | +true to create a CA certificate, false for a client/server certificate |
| purpose | +Credential purposes |
| type | +Credential type |
| usage | +Credential usages |
| organization | +Organization or NULL to use common name |
| org_unit | +Organizational unit or NULL for none |
| locality | +City/town or NULL for "Unknown" |
| state_province | +State/province or NULL for "Unknown" |
| country | +Country or NULL for locale-based default |
| common_name | +Common name |
| num_alt_names | +Number of subject alternate names |
| alt_names | +Subject Alternate Names |
| root_name | +Root certificate/domain name or NULL for site/self-signed |
| expiration_date | +Expiration date |
true on success, false on failure
This function creates an X.509 certificate and private key pair. The
+certificate and key are stored in the directory "path" or, if "path" is
+NULL, in a per-user or system-wide (when running as root) certificate/key
+store. The generated certificate is signed by the named root certificate or,
+if "root_name" is NULL, a site-wide default root certificate. When
+"root_name" is NULL and there is no site-wide default root certificate, a
+self-signed certificate is generated instead.
+
+The "ca_cert" argument specifies whether a CA certificate should be created.
+
+The "purpose" argument specifies the purpose(s) used for the credentials as a
+bitwise OR of the following constants:
+
+
CUPS_CREDPURPOSE_SERVER_AUTH for validating TLS servers,
+CUPS_CREDPURPOSE_CLIENT_AUTH for validating TLS clients,
+CUPS_CREDPURPOSE_CODE_SIGNING for validating compiled code,
+CUPS_CREDPURPOSE_EMAIL_PROTECTION for validating email messages,
+CUPS_CREDPURPOSE_TIME_STAMPING for signing timestamps to objects, and/or
+CUPS_CREDPURPOSE_OCSP_SIGNING for Online Certificate Status Protocol
+ message signing.The "type" argument specifies the type of credentials using one of the +following constants: + +
CUPS_CREDTYPE_DEFAULT: default type (RSA-3072 or P-384),
+CUPS_CREDTYPE_RSA_2048_SHA256: RSA with 2048-bit keys and SHA-256 hash,
+CUPS_CREDTYPE_RSA_3072_SHA256: RSA with 3072-bit keys and SHA-256 hash,
+CUPS_CREDTYPE_RSA_4096_SHA256: RSA with 4096-bit keys and SHA-256 hash,
+CUPS_CREDTYPE_ECDSA_P256_SHA256: ECDSA using the P-256 curve with SHA-256 hash,
+CUPS_CREDTYPE_ECDSA_P384_SHA256: ECDSA using the P-384 curve with SHA-256 hash, or
+CUPS_CREDTYPE_ECDSA_P521_SHA256: ECDSA using the P-521 curve with SHA-256 hash.The "usage" argument specifies the usage(s) for the credentials as a bitwise +OR of the following constants: + +
CUPS_CREDUSAGE_DIGITAL_SIGNATURE: digital signatures,
+CUPS_CREDUSAGE_NON_REPUDIATION: non-repudiation/content commitment,
+CUPS_CREDUSAGE_KEY_ENCIPHERMENT: key encipherment,
+CUPS_CREDUSAGE_DATA_ENCIPHERMENT: data encipherment,
+CUPS_CREDUSAGE_KEY_AGREEMENT: key agreement,
+CUPS_CREDUSAGE_KEY_CERT_SIGN: key certicate signing,
+CUPS_CREDUSAGE_CRL_SIGN: certificate revocation list signing,
+CUPS_CREDUSAGE_ENCIPHER_ONLY: encipherment only,
+CUPS_CREDUSAGE_DECIPHER_ONLY: decipherment only,
+CUPS_CREDUSAGE_DEFAULT_CA: defaults for CA certificates,
+CUPS_CREDUSAGE_DEFAULT_TLS: defaults for TLS certificates, and/or
+CUPS_CREDUSAGE_ALL: all usages.The "organization", "org_unit", "locality", "state_province", and "country"
+arguments specify information about the identity and geolocation of the
+issuer.
+
+The "common_name" argument specifies the common name and the "num_alt_names"
+and "alt_names" arguments specify a list of DNS hostnames for the
+certificate.
+
+The "expiration_date" argument specifies the expiration date and time as a
+Unix time_t value in seconds.
Make an X.509 Certificate Signing Request.
++bool cupsCreateCredentialsRequest(const char *path, cups_credpurpose_t purpose, cups_credtype_t type, cups_credusage_t usage, const char *organization, const char *org_unit, const char *locality, const char *state_province, const char *country, const char *common_name, size_t num_alt_names, const char *const *alt_names);
+| path | +Directory path for certificate/key store or NULL for default |
|---|---|
| purpose | +Credential purposes |
| type | +Credential type |
| usage | +Credential usages |
| organization | +Organization or NULL to use common name |
| org_unit | +Organizational unit or NULL for none |
| locality | +City/town or NULL for "Unknown" |
| state_province | +State/province or NULL for "Unknown" |
| country | +Country or NULL for locale-based default |
| common_name | +Common name |
| num_alt_names | +Number of subject alternate names |
| alt_names | +Subject Alternate Names |
true on success, false on error
This function creates an X.509 certificate signing request (CSR) and
+associated private key. The CSR and key are stored in the directory "path"
+or, if "path" is NULL, in a per-user or system-wide (when running as root)
+certificate/key store.
+
+The "purpose" argument specifies the purpose(s) used for the credentials as a
+bitwise OR of the following constants:
+
+
CUPS_CREDPURPOSE_SERVER_AUTH for validating TLS servers,
+CUPS_CREDPURPOSE_CLIENT_AUTH for validating TLS clients,
+CUPS_CREDPURPOSE_CODE_SIGNING for validating compiled code,
+CUPS_CREDPURPOSE_EMAIL_PROTECTION for validating email messages,
+CUPS_CREDPURPOSE_TIME_STAMPING for signing timestamps to objects, and/or
+CUPS_CREDPURPOSE_OCSP_SIGNING for Online Certificate Status Protocol
+ message signing.The "type" argument specifies the type of credentials using one of the +following constants: + +
CUPS_CREDTYPE_DEFAULT: default type (RSA-3072 or P-384),
+CUPS_CREDTYPE_RSA_2048_SHA256: RSA with 2048-bit keys and SHA-256 hash,
+CUPS_CREDTYPE_RSA_3072_SHA256: RSA with 3072-bit keys and SHA-256 hash,
+CUPS_CREDTYPE_RSA_4096_SHA256: RSA with 4096-bit keys and SHA-256 hash,
+CUPS_CREDTYPE_ECDSA_P256_SHA256: ECDSA using the P-256 curve with SHA-256 hash,
+CUPS_CREDTYPE_ECDSA_P384_SHA256: ECDSA using the P-384 curve with SHA-256 hash, or
+CUPS_CREDTYPE_ECDSA_P521_SHA256: ECDSA using the P-521 curve with SHA-256 hash.The "usage" argument specifies the usage(s) for the credentials as a bitwise +OR of the following constants: + +
CUPS_CREDUSAGE_DIGITAL_SIGNATURE: digital signatures,
+CUPS_CREDUSAGE_NON_REPUDIATION: non-repudiation/content commitment,
+CUPS_CREDUSAGE_KEY_ENCIPHERMENT: key encipherment,
+CUPS_CREDUSAGE_DATA_ENCIPHERMENT: data encipherment,
+CUPS_CREDUSAGE_KEY_AGREEMENT: key agreement,
+CUPS_CREDUSAGE_KEY_CERT_SIGN: key certicate signing,
+CUPS_CREDUSAGE_CRL_SIGN: certificate revocation list signing,
+CUPS_CREDUSAGE_ENCIPHER_ONLY: encipherment only,
+CUPS_CREDUSAGE_DECIPHER_ONLY: decipherment only,
+CUPS_CREDUSAGE_DEFAULT_CA: defaults for CA certificates,
+CUPS_CREDUSAGE_DEFAULT_TLS: defaults for TLS certificates, and/or
+CUPS_CREDUSAGE_ALL: all usages.The "organization", "org_unit", "locality", "state_province", and "country"
+arguments specify information about the identity and geolocation of the
+issuer.
+
+The "common_name" argument specifies the common name and the "num_alt_names"
+and "alt_names" arguments specify a list of DNS hostnames for the
+certificate.
Create a job on a destination.
++ipp_status_t cupsCreateDestJob(http_t *http, cups_dest_t *dest, cups_dinfo_t *info, int *job_id, const char *title, size_t num_options, cups_option_t *options);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| info | +Destination information |
| job_id | +Job ID or 0 on error |
| title | +Job name |
| num_options | +Number of job options |
| options | +Job options |
IPP status code
+This function creates a job on the specified destination "dest". The "info"
+argument contains information about the destination obtained using the
+cupsCopyDestInfo function.
+
+The "job_id" argument provides an integer to hold the new job's ID number.
+The "title" argument provides the title of the job. The "num_options" and
+"options" arguments provide an array of job options for the job.
+
+Returns IPP_STATUS_OK or IPP_STATUS_OK_SUBST on success, saving the job ID
+in the variable pointed to by "job_id".
Create a full service name from the instance + name, registration type, and domain.
++bool cupsDNSSDAssembleFullName(char *fullname, size_t fullsize, const char *name, const char *type, const char *domain);
+| fullname | +Buffer for full name |
|---|---|
| fullsize | +Size of buffer |
| name | +Service instance name |
| type | +Registration type |
| domain | +Domain |
true on success, false on failure
This function combines an instance name ("Example Name"), registration type +("_ipp._tcp"), and domain ("local.") to create a properly escaped full +service name ("Example032Name._ipp._tcp.local.").
+Cancel and delete a browse request.
++void cupsDNSSDBrowseDelete(cups_dnssd_browse_t *browse);
+| browse | +Browse request |
|---|
Get the DNS-SD context for the browse request.
++cups_dnssd_t *cupsDNSSDBrowseGetContext(cups_dnssd_browse_t *browse);
+| browse | +Browse request |
|---|
Context or NULL
Create a new DNS-SD browse request.
++cups_dnssd_browse_t *cupsDNSSDBrowseNew(cups_dnssd_t *dnssd, uint32_t if_index, const char *types, const char *domain, cups_dnssd_browse_cb_t browse_cb, void *cb_data);
+| dnssd | +DNS-SD context |
|---|---|
| if_index | +Interface index, CUPS_DNSSD_IF_ANY, or CUPS_DNSSD_IF_LOCAL |
| types | +Service types |
| domain | +Domain name or NULL for default |
| browse_cb | +Browse callback function |
| cb_data | +Browse callback data |
Browse request or NULL on error
This function creates a new DNS-SD browse request for the specified service
+types and optional domain and interface index. The "types" argument can be a
+single service type ("_ipp._tcp") or a service type and comma-delimited list
+of sub-types ("_ipp._tcp,_print,_universal").
+
+Newly discovered services are reported using the required browse callback
+function, with the "flags" argument set to CUPS_DNSSD_FLAGS_ADD for newly
+discovered services, CUPS_DNSSD_FLAGS_NONE for removed services, or
+CUPS_DNSSD_FLAGS_ERROR on an error:
+
+
+void
+browse_cb(
+ cups_dnssd_browse_t *browse,
+ void *cb_data,
+ cups_dnssd_flags_t flags,
+ uint32_t if_index,
+ const char *name,
+ const char *regtype,
+ const char *domain)
+{
+ // Process added/removed service
+}
+
+
+Decode a TXT record into key/value pairs.
++size_t cupsDNSSDDecodeTXT(const unsigned char *txtrec, uint16_t txtlen, cups_option_t **txt);
+| txtrec | +TXT record data |
|---|---|
| txtlen | +TXT record length |
| txt | +Key/value pairs |
Number of key/value pairs
+This function converts the DNS TXT record encoding of key/value pairs into
+cups_option_t elements that can be accessed using the cupsGetOption
+function and freed using the cupsFreeOptions function.
Delete a DNS-SD context and all its requests.
++void cupsDNSSDDelete(cups_dnssd_t *dnssd);
+| dnssd | +DNS-SD context |
|---|
Get the number of host name/network + configuration changes seen.
++size_t cupsDNSSDGetConfigChanges(cups_dnssd_t *dnssd);
+| dnssd | +DNS-SD context |
|---|
Number of host name changes
+This function returns the number of host name or network configuration
+changes that have been seen since the context was created. The value can be
+used to track when local services need to be updated. Registered services
+will also get a callback with the CUPS_DNSSD_FLAGS_HOST_CHANGE bit set in
+the "flags" argument for host name changes and/or
+CUPS_DNSSD_FLAGS_NETWORK_CHANGE for network changes.
Get the current mDNS host name for the system.
++const char *cupsDNSSDGetHostName(cups_dnssd_t *dnssd, char *buffer, size_t bufsize);
+| dnssd | +DNS-SD context |
|---|---|
| buffer | +Host name buffer |
| bufsize | +Size of host name buffer |
Local host name or NULL for none
This function gets the current mDNS (".local") host name for the system.
+Create a new DNS-SD context.
++cups_dnssd_t *cupsDNSSDNew(cups_dnssd_error_cb_t error_cb, void *cb_data);
+| error_cb | +Error callback function |
|---|---|
| cb_data | +Error callback data |
DNS-SD context
+This function creates a new DNS-SD context for browsing, querying, resolving,
+and/or registering services. Call cupsDNSSDDelete to stop any pending
+browses, queries, or resolves, unregister any services, and free the DNS-SD
+context.
Cancel and delete a query request.
++void cupsDNSSDQueryDelete(cups_dnssd_query_t *query);
+| query | +Query request |
|---|
Get the DNS-SD context for the query request.
++cups_dnssd_t *cupsDNSSDQueryGetContext(cups_dnssd_query_t *query);
+| query | +Query request |
|---|
DNS-SD context or NULL
Create a new query request.
++cups_dnssd_query_t *cupsDNSSDQueryNew(cups_dnssd_t *dnssd, uint32_t if_index, const char *fullname, uint16_t rrtype, cups_dnssd_query_cb_t query_cb, void *cb_data);
+| dnssd | +DNS-SD context |
|---|---|
| if_index | +Interface index or CUPS_DNSSD_IF_ANY or CUPS_DNSSD_IF_LOCAL |
| fullname | +Full DNS name including types and domain |
| rrtype | +Record type to query (CUPS_DNSSD_RRTYPE_TXT, etc.) |
| query_cb | +Query callback function |
| cb_data | +Query callback data |
Query request or NULL on error
This function creates a new DNS-SD query request for the specified full
+service name and DNS record type. The "fullname" parameter specifies the
+full DNS name of the service (instance name, type, and domain) being queried.
+Responses to the query are reported using the required query callback
+function with the "flags" argument set to CUPS_DNSSD_FLAGS_NONE on success
+or CUPS_DNSSD_FLAGS_ERROR on error:
+
+
+void
+query_cb(
+ cups_dnssd_query_t *query,
+ void *cb_data,
+ cups_dnssd_flags_t flags,
+ uint32_t if_index,
+ const char *fullname,
+ uint16_t rrtype,
+ const void *qdata,
+ uint16_t qlen)
+{
+ // Process query record
+}
+
+
+Cancel and free a resolve request.
++void cupsDNSSDResolveDelete(cups_dnssd_resolve_t *res);
+| res | +Resolve request |
|---|
Get the DNS-SD context for the resolve request.
++cups_dnssd_t *cupsDNSSDResolveGetContext(cups_dnssd_resolve_t *resolve);
+| resolve | +Resolve request |
|---|
DNS-SD context or NULL
Create a new DNS-SD resolve request.
++cups_dnssd_resolve_t *cupsDNSSDResolveNew(cups_dnssd_t *dnssd, uint32_t if_index, const char *name, const char *type, const char *domain, cups_dnssd_resolve_cb_t resolve_cb, void *cb_data);
+| dnssd | +DNS-SD context |
|---|---|
| if_index | +Interface index or CUPS_DNSSD_IF_ANY or CUPS_DNSSD_IF_LOCAL |
| name | +Service name |
| type | +Service type |
| domain | +Domain name or NULL for default |
| resolve_cb | +Resolve callback function |
| cb_data | +Resolve callback data |
Resolve request or NULL on error
This function creates a new DNS-SD resolver for the specified instance name,
+service type, and optional domain and interface index. Resikved services
+are reported using the required resolve callback function, with the "flags"
+argument set to CUPS_DNSSD_FLAGS_NONE on success or
+CUPS_DNSSD_FLAGS_ERROR on error:
+
+
+void
+resolve_cb(
+ cups_dnssd_resolve_t *resolve,
+ void *cb_data,
+ cups_dnssd_flags_t flags,
+ uint32_t if_index,
+ const char *fullname,
+ const char *host,
+ uint16_t port,
+ size_t num_txt,
+ cups_option_t *txt)
+{
+ // Process resolved service
+}
+
+
+Separate a full service name into an instance + name, registration type, and domain.
++bool cupsDNSSDSeparateFullName(const char *fullname, char *name, size_t namesize, char *type, size_t typesize, char *domain, size_t domainsize);
+| fullname | +Full service name |
|---|---|
| name | +Instance name buffer |
| namesize | +Size of instance name buffer |
| type | +Registration type buffer |
| typesize | +Size of registration type buffer |
| domain | +Domain name buffer |
| domainsize | +Size of domain name buffer |
true on success, false on error
This function separates a full service name such as +"Example032Name._ipp._tcp.local.") into its instance name ("Example Name"), +registration type ("_ipp._tcp"), and domain ("local.").
+Add a service instance.
++bool cupsDNSSDServiceAdd(cups_dnssd_service_t *service, const char *types, const char *domain, const char *host, uint16_t port, size_t num_txt, cups_option_t *txt);
+| service | +Service |
|---|---|
| types | +Service types |
| domain | +Domain name or NULL for default |
| host | +Host name or NULL for default |
| port | +Port number or 0 for none |
| num_txt | +Number of TXT record values |
| txt | +TXT record values |
true on success, false on failure
This function adds a service instance for the specified service types,
+domain, host, and port. The "types" argument can be a single service type
+("_ipp._tcp") or a service type and comma-delimited list of sub-types
+("_ipp._tcp,_print,_universal").
+
+Call the cupsDNSSDServicePublish function after all service instances
+have been added.
Cancel and free a service registration.
++void cupsDNSSDServiceDelete(cups_dnssd_service_t *service);
+| service | +Service |
|---|
Get the DNS-SD context for the service + registration.
++cups_dnssd_t *cupsDNSSDServiceGetContext(cups_dnssd_service_t *service);
+| service | +Service registration |
|---|
DNS-SD context or NULL
Get the service instance name for the service registration.
++const char *cupsDNSSDServiceGetName(cups_dnssd_service_t *service);
+| service | +Service registration |
|---|
Service instance name
+Create a new named service.
++cups_dnssd_service_t *cupsDNSSDServiceNew(cups_dnssd_t *dnssd, uint32_t if_index, const char *name, cups_dnssd_service_cb_t cb, void *cb_data);
+| dnssd | +DNS-SD context |
|---|---|
| if_index | +Interface index, CUPS_DNSSD_IF_ANY, or CUPS_DNSSD_IF_LOCAL |
| name | +Name of service |
| cb | +Service registration callback function |
| cb_data | +Service registration callback data |
Service or NULL on error
This function creates a new DNS-SD service registration for the given service
+instance name and interface. Specific services using the name are added
+using the cupsDNSSDServiceAdd function.
+
+The required service callback is called for select events, with the "flags"
+argument set to CUPS_DNSSD_FLAGS_NONE for a successful registration,
+CUPS_DNSSD_FLAGS_COLLISION when there is a name collision, or
+CUPS_DNSSD_FLAGS_ERROR when there is a problem completing the service
+registration.
Publish a service.
++bool cupsDNSSDServicePublish(cups_dnssd_service_t *service);
+| service | +Service |
|---|
true on success, false on failure
This function publishes the DNS-SD services added using the
+cupsDNSSDServiceAdd function.
Set the geolocation (LOC record) of a + service.
++bool cupsDNSSDServiceSetLocation(cups_dnssd_service_t *service, const char *geo_uri);
+| service | +Service |
|---|---|
| geo_uri | +Geolocation as a 'geo:' URI |
true on success, false on failure
This function sets the geolocation of a service using a 'geo:' URI (RFC 5870)
+of the form
+'geo:LATITUDE,LONGITUDE[,ALTITUDE][;crs=CRSLABEL][;u=UNCERTAINTY]'. The
+specified coordinates and uncertainty are converted into a DNS LOC record
+for the service name label. Only the "wgs84" CRSLABEL string is supported.
+
+You must call this function prior to cupsDNSSDServiceAdd.
Close a directory.
++void cupsDirClose(cups_dir_t *dp);
+| dp | +Directory pointer |
|---|
Open a directory.
++cups_dir_t *cupsDirOpen(const char *directory);
+| directory | +Directory name |
|---|
Directory pointer or NULL if the directory could not be opened.
Read the next directory entry.
++cups_dentry_t *cupsDirRead(cups_dir_t *dp);
+| dp | +Directory pointer |
|---|
Directory entry or NULL when there are no more
Rewind to the start of the directory.
++void cupsDirRewind(cups_dir_t *dp);
+| dp | +Directory pointer |
|---|
Authenticate a request.
++bool cupsDoAuthentication(http_t *http, const char *method, const char *resource);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| method | +Request method ("GET", "POST", "PUT") |
| resource | +Resource path |
true on success, false on failure/error
This function performs authentication for a request. It should be called in
+response to a HTTP_STATUS_UNAUTHORIZED status, prior to resubmitting your
+request.
Do an IPP request with a file.
++ipp_t *cupsDoFileRequest(http_t *http, ipp_t *request, const char *resource, const char *filename);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| request | +IPP request |
| resource | +HTTP resource for POST |
| filename | +File to send or NULL for none |
Response data
+This function sends the IPP request and attached file to the specified
+server, retrying and authenticating as necessary. The request is freed with
+ippDelete.
Do an IPP request with file descriptors.
++ipp_t *cupsDoIORequest(http_t *http, ipp_t *request, const char *resource, int infile, int outfile);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| request | +IPP request |
| resource | +HTTP resource for POST |
| infile | +File to read from or -1 for none |
| outfile | +File to write to or -1 for none |
Response data
+This function sends the IPP request with the optional input file "infile" to
+the specified server, retrying and authenticating as necessary. The request
+is freed with ippDelete.
+
+If "infile" is a valid file descriptor, cupsDoIORequest copies
+all of the data from the file after the IPP request message.
+
+If "outfile" is a valid file descriptor, cupsDoIORequest copies
+all of the data after the IPP response message to the file.
Do an IPP request.
++ipp_t *cupsDoRequest(http_t *http, ipp_t *request, const char *resource);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| request | +IPP request |
| resource | +HTTP resource for POST |
Response data
+This function sends the IPP request to the specified server, retrying
+and authenticating as necessary. The request is freed with ippDelete.
Encode a single option into an IPP attribute.
++ipp_attribute_t *cupsEncodeOption(ipp_t *ipp, ipp_tag_t group_tag, const char *name, const char *value);
+| ipp | +IPP request/response |
|---|---|
| group_tag | +Attribute group |
| name | +Option name |
| value | +Option string value |
New attribute or NULL on error
Encode printer options into IPP attributes for a group.
++void cupsEncodeOptions(ipp_t *ipp, size_t num_options, cups_option_t *options, ipp_tag_t group_tag);
+| ipp | +IPP request/response |
|---|---|
| num_options | +Number of options |
| options | +Options |
| group_tag | +Group to encode |
This function encodes options as IPP attributes for a single group. Call this +function multiple times for each group as needed.
+Return the character encoding name string for the + given encoding enumeration.
++const char *cupsEncodingString(cups_encoding_t value);
+| value | +Encoding value |
|---|
Character encoding string
+Return the encoding enumeration value for a given + character encoding name string.
++cups_encoding_t cupsEncodingValue(const char *s);
+| s | +Character encoding string |
|---|
Encoding value
+Enumerate available destinations with a callback function.
++bool cupsEnumDests(unsigned flags, int msec, int *cancel, cups_ptype_t type, cups_ptype_t mask, cups_dest_cb_t cb, void *user_data);
+| flags | +Enumeration flags |
|---|---|
| msec | +Timeout in milliseconds, -1 for indefinite |
| cancel | +Pointer to "cancel" variable |
| type | +Printer type bits |
| mask | +Mask for printer type bits |
| cb | +Callback function |
| user_data | +User data |
true on success, false on failure
Destinations are enumerated from one or more sources. The callback function
+receives the "user_data" pointer and the destination pointer which can be
+used as input to the cupsCopyDest function. The function must return
+true to continue enumeration or false to stop.
+
+The "type" and "mask" arguments allow the caller to filter the destinations
+that are enumerated. Passing 0 for both will enumerate all printers. The
+constant CUPS_PRINTER_DISCOVERED is used to filter on destinations that are
+available but have not yet been added locally.
+
+Enumeration happens on the current thread and does not return until all
+destinations have been enumerated or the callback function returns false.
+
+Note: The callback function will likely receive multiple updates for the same
+destinations - it is up to the caller to suppress any duplicate destinations.
Close a CUPS file.
++bool cupsFileClose(cups_file_t *fp);
+| fp | +CUPS file |
|---|
true on success, false on error
Return the end-of-file status.
++bool cupsFileEOF(cups_file_t *fp);
+| fp | +CUPS file |
|---|
true on end of file, false otherwise
Find a file using the specified path.
++const char *cupsFileFind(const char *filename, const char *path, bool executable, char *buffer, size_t bufsize);
+| filename | +File to find |
|---|---|
| path | +Colon/semicolon-separated path |
| executable | +true = executable files, false = any file/dir |
| buffer | +Filename buffer |
| bufsize | +Size of filename buffer |
Full path to file or NULL if not found
This function allows the paths in the path string to be separated by
+colons (POSIX standard) or semicolons (Windows standard) and stores the
+result in the buffer supplied. If the file cannot be found in any of
+the supplied paths, NULL is returned. A NULL path only matches the
+current directory.
Flush pending output.
++bool cupsFileFlush(cups_file_t *fp);
+| fp | +CUPS file |
|---|
true on success, false on error
Get a single character from a file.
++int cupsFileGetChar(cups_file_t *fp);
+| fp | +CUPS file |
|---|
Character or -1 on end of file
Get a line from a configuration file.
++char *cupsFileGetConf(cups_file_t *fp, char *buf, size_t buflen, char **value, int *linenum);
+| fp | +CUPS file |
|---|---|
| buf | +String buffer |
| buflen | +Size of string buffer |
| value | +Pointer to value |
| linenum | +Current line number |
Line read or NULL on end of file or error
Get a CR and/or LF-terminated line that may + contain binary data.
++size_t cupsFileGetLine(cups_file_t *fp, char *buf, size_t buflen);
+| fp | +File to read from |
|---|---|
| buf | +Buffer |
| buflen | +Size of buffer |
Number of bytes on line or 0 on end of file
+This function differs from cupsFileGets in that the trailing CR
+and LF are preserved, as is any binary data on the line. The buffer is
+nul-terminated, however you should use the returned length to determine
+the number of bytes on the line.
Get a CR and/or LF-terminated line.
++char *cupsFileGets(cups_file_t *fp, char *buf, size_t buflen);
+| fp | +CUPS file |
|---|---|
| buf | +String buffer |
| buflen | +Size of string buffer |
Line read or NULL on end of file or error
Return whether a file is compressed.
++bool cupsFileIsCompressed(cups_file_t *fp);
+| fp | +CUPS file |
|---|
true if compressed, false if not
Temporarily lock access to a file.
++bool cupsFileLock(cups_file_t *fp, bool block);
+| fp | +CUPS file |
|---|---|
| block | +true to wait for the lock, false to fail right away |
true on success, false on error
Return the file descriptor associated with a CUPS file.
++int cupsFileNumber(cups_file_t *fp);
+| fp | +CUPS file |
|---|
File descriptor
+Open a CUPS file.
++cups_file_t *cupsFileOpen(const char *filename, const char *mode);
+| filename | +Name of file |
|---|---|
| mode | +Open mode |
CUPS file or NULL if the file or socket cannot be opened
This function opens a file or socket for use with the CUPS file API.
+
+The "filename" argument is a filename or socket address.
+
+The "mode" parameter can be "r" to read, "w" to write, overwriting any
+existing file, "a" to append to an existing file or create a new file,
+or "s" to open a socket connection.
+
+When opening for writing ("w"), an optional number from 1 to 9 can be
+supplied which enables Flate compression of the file. Compression is
+not supported for the "a" (append) mode.
+
+When opening a socket connection, the filename is a string of the form
+"address:port" or "hostname:port". The socket will make an IPv4 or IPv6
+connection as needed, generally preferring IPv6 connections when there is
+a choice.
Open a CUPS file using a file descriptor.
++cups_file_t *cupsFileOpenFd(int fd, const char *mode);
+| fd | +File descriptor |
|---|---|
| mode | +Open mode |
CUPS file or NULL if the file could not be opened
This function prepares a file descriptor for use with the CUPS file API.
+
+The "fd" argument specifies the file descriptor.
+
+The "mode" argument can be "r" to read, "w" to write, "a" to append,
+or "s" to treat the file descriptor as a bidirectional socket connection.
+
+When opening for writing ("w"), an optional number from 1 to 9 can be
+supplied which enables Flate compression of the file. Compression is
+not supported for the "a" (append) mode.
Peek at the next character from a file.
++int cupsFilePeekChar(cups_file_t *fp);
+| fp | +CUPS file |
|---|
Character or -1 on end of file
Write a formatted string.
++bool cupsFilePrintf(cups_file_t *fp, const char *format, ...);
+| fp | +CUPS file |
|---|---|
| format | +Printf-style format string |
| ... | +Additional args as necessary |
true on success, false on error
Write a character.
++bool cupsFilePutChar(cups_file_t *fp, int c);
+| fp | +CUPS file |
|---|---|
| c | +Character to write |
true on success, false on error
Write a configuration line.
++bool cupsFilePutConf(cups_file_t *fp, const char *directive, const char *value);
+| fp | +CUPS file |
|---|---|
| directive | +Directive |
| value | +Value |
true on success, false on error
This function handles any comment escaping of the value.
+Write a string.
++bool cupsFilePuts(cups_file_t *fp, const char *s);
+| fp | +CUPS file |
|---|---|
| s | +String to write |
true on success, false on error
Like the fputs function, no newline is appended to the string.
Read from a file.
++ssize_t cupsFileRead(cups_file_t *fp, char *buf, size_t bytes);
+| fp | +CUPS file |
|---|---|
| buf | +Buffer |
| bytes | +Number of bytes to read |
Number of bytes read or -1 on error
+Set the current file position to the beginning of the file.
++off_t cupsFileRewind(cups_file_t *fp);
+| fp | +CUPS file |
|---|
New file position or -1 on error
Seek in a file.
++off_t cupsFileSeek(cups_file_t *fp, off_t pos);
+| fp | +CUPS file |
|---|---|
| pos | +Position in file |
New file position or -1 on error
Return a CUPS file associated with stderr.
++cups_file_t *cupsFileStderr(void);
+CUPS file
+Return a CUPS file associated with stdin.
++cups_file_t *cupsFileStdin(void);
+CUPS file
+Return a CUPS file associated with stdout.
++cups_file_t *cupsFileStdout(void);
+CUPS file
+Return the current file position.
++off_t cupsFileTell(cups_file_t *fp);
+| fp | +CUPS file |
|---|
File position
+Unlock access to a file.
++bool cupsFileUnlock(cups_file_t *fp);
+| fp | +CUPS file |
|---|
true on success, false on error
Write to a file.
++bool cupsFileWrite(cups_file_t *fp, const char *buf, size_t bytes);
+| fp | +CUPS file |
|---|---|
| buf | +Buffer |
| bytes | +Number of bytes to write |
true on success, false on error
Find the default value(s) for the given option.
++ipp_attribute_t *cupsFindDestDefault(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, const char *option);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| option | +Option/attribute name |
Default attribute or NULL for none
The returned value is an IPP attribute. Use the ippGetBoolean,
+ippGetCollection, ippGetCount, ippGetDate,
+ippGetInteger, ippGetOctetString, ippGetRange,
+ippGetResolution, ippGetString, and ippGetValueTag
+functions to inspect the default value(s) as needed.
Find the default value(s) for the given option.
++ipp_attribute_t *cupsFindDestReady(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, const char *option);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| option | +Option/attribute name |
Default attribute or NULL for none
The returned value is an IPP attribute. Use the ippGetBoolean,
+ippGetCollection, ippGetCount, ippGetDate,
+ippGetInteger, ippGetOctetString, ippGetRange,
+ippGetResolution, ippGetString, and ippGetValueTag
+functions to inspect the default value(s) as needed.
Find the default value(s) for the given option.
++ipp_attribute_t *cupsFindDestSupported(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, const char *option);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| option | +Option/attribute name |
Default attribute or NULL for none
The returned value is an IPP attribute. Use the ippGetBoolean,
+ippGetCollection, ippGetCount, ippGetDate,
+ippGetInteger, ippGetOctetString, ippGetRange,
+ippGetResolution, ippGetString, and ippGetValueTag
+functions to inspect the default value(s) as needed.
Finish the current document.
++ipp_status_t cupsFinishDestDocument(http_t *http, cups_dest_t *dest, cups_dinfo_t *info);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| info | +Destination information |
Status of document submission
+This function finished the current document for a job on the specified
+destination "dest". The "info" argument contains information about the
+destination obtained using the cupsCopyDestInfo function.
+
+Returns IPP_STATUS_OK or IPP_STATUS_OK_SUBST on success.
Decode URL-encoded form data.
++size_t cupsFormDecode(const char *data, cups_option_t **vars);
+| data | +URL-encoded form data |
|---|---|
| vars | +Array of variables |
Number of variables
+This function decodes URL-encoded form data, returning the number of
+variables and a pointer to a cups_option_t array of the variables.
+
+Use the cupsFreeOptions function to return the memory used when you
+are done with the form variables.
Encode options as URL-encoded form data.
++char *cupsFormEncode(const char *url, size_t num_vars, cups_option_t *vars);
+| url | +URL or NULL for none |
|---|---|
| num_vars | +Number of variables |
| vars | +Variables |
URL-encoded form data
+This function encodes a CUPS options array as URL-encoded form data with an
+optional URL prefix, returning an allocated string.
+
+Use free to return the memory used for the string.
Free destination information obtained using
+ cupsCopyDestInfo.
+void cupsFreeDestInfo(cups_dinfo_t *dinfo);
+| dinfo | +Destination information |
|---|
Free the memory used by the list of destinations.
++void cupsFreeDests(size_t num_dests, cups_dest_t *dests);
+| num_dests | +Number of destinations |
|---|---|
| dests | +Destinations |
Free memory used by job data.
++void cupsFreeJobs(size_t num_jobs, cups_job_t *jobs);
+| num_jobs | +Number of jobs |
|---|---|
| jobs | +Jobs |
Free all memory used by options.
++void cupsFreeOptions(size_t num_options, cups_option_t *options);
+| num_options | +Number of options |
|---|---|
| options | +Pointer to options |
Return the expiration date of the credentials.
++time_t cupsGetCredentialsExpiration(const char *credentials);
+| credentials | +Credentials |
|---|
Expiration date of credentials
+Return a string describing the credentials.
++char *cupsGetCredentialsInfo(const char *credentials, char *buffer, size_t bufsize);
+| credentials | +Credentials |
|---|---|
| buffer | +Buffer |
| bufsize | +Size of buffer |
Credentials description or NULL on error
Return the trust of credentials.
++http_trust_t cupsGetCredentialsTrust(const char *path, const char *common_name, const char *credentials);
+| path | +Directory path for certificate/key store or NULL for default |
|---|---|
| common_name | +Common name for trust lookup |
| credentials | +Credentials |
Level of trust
+Get the default printer or class for the specified server.
++const char *cupsGetDefault(http_t *http);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|
Default printer or NULL for none
This function returns the default printer or class as defined by
+the LPDEST or PRINTER environment variables. If these environment
+variables are not set, the server default destination is returned.
+Applications should use the cupsGetDests and cupsGetDest
+functions to get the user-defined default printer, as this function does
+not support the lpoptions-defined default printer.
Get the named destination from the list.
++cups_dest_t *cupsGetDest(const char *name, const char *instance, size_t num_dests, cups_dest_t *dests);
+| name | +Destination name or NULL for the default destination |
|---|---|
| instance | +Instance name or NULL |
| num_dests | +Number of destinations |
| dests | +Destinations |
Destination pointer or NULL
This function gets the named destination from the list of destinations. Use
+the cupsEnumDests or cupsGetDests functions to get a list of
+supported destinations for the current user.
Get a media name, dimension, and margins for a + specific size.
++bool cupsGetDestMediaByIndex(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, size_t n, unsigned flags, cups_size_t *size);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| n | +Media size number (0-based) |
| flags | +Media flags |
| size | +Media size information |
true on success, false on failure
The "flags" parameter determines which set of media are indexed. For
+example, passing CUPS_MEDIA_FLAGS_BORDERLESS will get the Nth borderless
+size supported by the printer.
Get media names, dimensions, and margins.
++bool cupsGetDestMediaByName(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, const char *media, unsigned flags, cups_size_t *size);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| media | +Media name |
| flags | +Media matching flags |
| size | +Media size information |
true on match, false on failure
The "media" string is a PWG media name. "Flags" provides some matching +guidance (multiple flags can be combined): + +
CUPS_MEDIA_FLAGS_DEFAULT: find the closest size supported by the printer,
+CUPS_MEDIA_FLAGS_BORDERLESS: find a borderless size,
+CUPS_MEDIA_FLAGS_DUPLEX: find a size compatible with 2-sided printing,
+CUPS_MEDIA_FLAGS_EXACT: find an exact match for the size, and
+CUPS_MEDIA_FLAGS_READY: if the printer supports media sensing, find the
+ size amongst the "ready" media.The matching result (if any) is returned in the cups_size_t structure.
+
+Returns true when there is a match and false if there is not a match.
Get media names, dimensions, and margins.
++bool cupsGetDestMediaBySize(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, int width, int length, unsigned flags, cups_size_t *size);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| width | +Media width in hundredths of millimeters |
| length | +Media length in hundredths of millimeters |
| flags | +Media matching flags |
| size | +Media size information |
true on match, false on failure
"Width" and "length" are the dimensions in hundredths of millimeters. +"Flags" provides some matching guidance (multiple flags can be combined): + +
CUPS_MEDIA_FLAGS_DEFAULT: find the closest size supported by the printer,
+CUPS_MEDIA_FLAGS_BORDERLESS: find a borderless size,
+CUPS_MEDIA_FLAGS_DUPLEX: find a size compatible with 2-sided printing,
+CUPS_MEDIA_FLAGS_EXACT: find an exact match for the size, and
+CUPS_MEDIA_FLAGS_READY: if the printer supports media sensing, find the
+ size amongst the "ready" media.The matching result (if any) is returned in the cups_size_t structure.
+
+Returns true when there is a match and false if there is not a match.
Get the number of sizes supported by a + destination.
++size_t cupsGetDestMediaCount(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, unsigned flags);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| flags | +Media flags |
Number of sizes
+The "flags" parameter determines the set of media sizes that are counted.
+For example, passing CUPS_MEDIA_FLAGS_BORDERLESS will return the number of
+borderless sizes.
Get the default size for a destination.
++bool cupsGetDestMediaDefault(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, unsigned flags, cups_size_t *size);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| flags | +Media flags |
| size | +Media size information |
true on match, false on failure
The "flags" parameter determines which default size is returned. For
+example, passing CUPS_MEDIA_FLAGS_BORDERLESS will return the default
+borderless size, typically US Letter or A4, but sometimes 4x6 photo media.
Get a destination associated with a URI.
++cups_dest_t *cupsGetDestWithURI(const char *name, const char *uri);
+| name | +Desired printer name or NULL |
|---|---|
| uri | +URI for the printer |
Destination or NULL
"name" is the desired name for the printer. If NULL, a name will be
+created using the URI.
+
+"uri" is the 'ipp:' or 'ipps:' URI for the printer.
Get the list of destinations from the specified server.
++size_t cupsGetDests(http_t *http, cups_dest_t **dests);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| dests | +Destinations |
Number of destinations
+Starting with CUPS 1.2, the returned list of destinations include the
+"printer-info", "printer-is-accepting-jobs", "printer-is-shared",
+"printer-make-and-model", "printer-state", "printer-state-change-time",
+"printer-state-reasons", "printer-type", and "printer-uri-supported"
+attributes as options.
+
+CUPS 1.4 adds the "marker-change-time", "marker-colors",
+"marker-high-levels", "marker-levels", "marker-low-levels", "marker-message",
+"marker-names", "marker-types", and "printer-commands" attributes as options.
+
+CUPS 2.2 adds accessible IPP printers to the list of destinations that can
+be used. The "printer-uri-supported" option will be present for those IPP
+printers that have been recently used.
+
+Use the cupsFreeDests function to free the destination list and
+the cupsGetDest function to find a particular destination.
Get the current encryption settings.
++http_encryption_t cupsGetEncryption(void);
+Encryption settings
+The default encryption setting comes from the CUPS_ENCRYPTION
+environment variable, then the ~/.cups/client.conf file, and finally the
+/etc/cups/client.conf file. If not set, the default is
+HTTP_ENCRYPTION_IF_REQUESTED.
+
+Note: The current encryption setting is tracked separately for each thread
+in a program. Multi-threaded programs that override the setting via the
+cupsSetEncryption function need to do so in each thread for the same
+setting to be used.
Return the last IPP status code received on the current + thread.
++ipp_status_t cupsGetError(void);
+IPP status code from last request
+Return the last IPP status-message received on the + current thread.
++const char *cupsGetErrorString(void);
+"status-message" text from last request
+Get a file from the server.
++http_status_t cupsGetFd(http_t *http, const char *resource, int fd);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| resource | +Resource name |
| fd | +File descriptor |
HTTP status
+This function returns HTTP_STATUS_OK when the file is successfully retrieved.
Get a file from the server.
++http_status_t cupsGetFile(http_t *http, const char *resource, const char *filename);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| resource | +Resource name |
| filename | +Filename |
HTTP status
+This function returns HTTP_STATUS_OK when the file is successfully retrieved.
Get an integer option value.
++int cupsGetIntegerOption(const char *name, size_t num_options, cups_option_t *options);
+| name | +Name of option |
|---|---|
| num_options | +Number of options |
| options | +Options |
Option value or INT_MIN
INT_MIN is returned when the option does not exist, is not an integer, or +exceeds the range of values for the "int" type.
+Get the jobs from the specified server.
++size_t cupsGetJobs(http_t *http, cups_job_t **jobs, const char *name, bool myjobs, cups_whichjobs_t whichjobs);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| jobs | +Job data |
| name | +NULL = all destinations, otherwise show jobs for named destination |
| myjobs | +false = all users, true = mine |
| whichjobs | +CUPS_WHICHJOBS_ALL, CUPS_WHICHJOBS_ACTIVE, or CUPS_WHICHJOBS_COMPLETED |
Number of jobs
+This function gets an array of jobs from the specified server.
+
+The "name" argument specifies a destination name. The "myjobs" argument
+specifies whether to only show jobs for the current user (true) or for
+all users (false).
+
+The "whichjobs" argument specifies which jobs to return -
+CUPS_WHICHJOBS_ALL to return all jobs regardless of state,
+CUPS_WHICHJOBS_ACTIVE to return jobs that are pending, processing, or held,
+and CUPS_WHICHJOBS_COMPLETED to return jobs that are stopped, canceled,
+aborted, or completed.
Get options for the named destination.
++cups_dest_t *cupsGetNamedDest(http_t *http, const char *name, const char *instance);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| name | +Destination name or NULL for the default destination |
| instance | +Instance name or NULL |
Destination or NULL
This function is optimized for retrieving a single destination and should
+be used instead of cupsGetDests2 and cupsGetDest when you
+either know the name of the destination or want to print to the default
+destination. If NULL is returned, the destination does not exist or
+there is no default destination.
+
+If "http" is CUPS_HTTP_DEFAULT, the connection to the default print
+server will be used.
+
+If "name" is NULL, the default printer for the current user will be
+returned.
+
+The returned destination must be freed using cupsFreeDests with a
+"num_dests" value of 1.
Get an option value.
++const char *cupsGetOption(const char *name, size_t num_options, cups_option_t *options);
+| name | +Name of option |
|---|---|
| num_options | +Number of options |
| options | +Options |
Option value or NULL
Get a password from the user using the current + password callback.
++const char *cupsGetPassword(const char *prompt, http_t *http, const char *method, const char *resource);
+| prompt | +Prompt string |
|---|---|
| http | +Connection to server or CUPS_HTTP_DEFAULT |
| method | +Request method ("GET", "POST", "PUT") |
| resource | +Resource path |
Password
+Uses the current password callback function. Returns NULL if the
+user does not provide a password.
+
+Note: The current password callback function is tracked separately for each
+thread in a program. Multi-threaded programs that override the setting via
+the cupsSetPasswordCB function need to do so in each thread for the
+same function to be used.
Return a 32-bit pseudo-random number.
++unsigned cupsGetRand(void);
+Random number
+This function returns a 32-bit pseudo-random number suitable for use as +one-time identifiers or nonces. The random numbers are generated/seeded +using system entropy.
+Get a response to an IPP request.
++ipp_t *cupsGetResponse(http_t *http, const char *resource);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| resource | +HTTP resource for POST |
Response or NULL on HTTP error
Use this function to get the response for an IPP request sent using
+cupsSendRequest. For requests that return additional data, use
+cupsReadResponseData after getting a successful response,
+otherwise call httpFlush to complete the response processing.
Return the hostname/address of the current server.
++const char *cupsGetServer(void);
+Server name
+The default server comes from the CUPS_SERVER environment variable, then the
+~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not
+set, the default is the local system - either "localhost" or a domain socket
+path.
+
+The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6
+address, or a domain socket pathname.
+
+Note: The current server is tracked separately for each thread in a program.
+Multi-threaded programs that override the server via the
+cupsSetServer function need to do so in each thread for the same
+server to be used.
Return the current user's name.
++const char *cupsGetUser(void);
+User name
+Note: The current user name is tracked separately for each thread in a
+program. Multi-threaded programs that override the user name with the
+cupsSetUser function need to do so in each thread for the same user
+name to be used.
Return the default HTTP User-Agent string.
++const char *cupsGetUserAgent(void);
+User-Agent string
+Perform a HMAC function on the given data.
++ssize_t cupsHMACData(const char *algorithm, const unsigned char *key, size_t keylen, const void *data, size_t datalen, unsigned char *hmac, size_t hmacsize);
+| algorithm | +Hash algorithm |
|---|---|
| key | +Key |
| keylen | +Length of key |
| data | +Data to hash |
| datalen | +Length of data to hash |
| hmac | +HMAC buffer |
| hmacsize | +Size of HMAC buffer |
The length of the HMAC or -1 on error
This function performs a HMAC function on the given data with the given key.
+The "algorithm" argument can be any of the registered, non-deprecated IPP
+hash algorithms for the "job-password-encryption" attribute, including
+"sha" for SHA-1, "sha2-256" for SHA2-256, etc.
+
+The "hmac" argument points to a buffer of "hmacsize" bytes and should be at
+least 64 bytes in length for all of the supported algorithms.
+
+The returned HMAC is binary data.
Perform a hash function on the given data.
++ssize_t cupsHashData(const char *algorithm, const void *data, size_t datalen, unsigned char *hash, size_t hashsize);
+| algorithm | +Algorithm name |
|---|---|
| data | +Data to hash |
| datalen | +Length of data to hash |
| hash | +Hash buffer |
| hashsize | +Size of hash buffer |
Size of hash or -1 on error
+This function performs a hash function on the given data. The "algorithm"
+argument can be any of the registered, non-deprecated IPP hash algorithms for
+the "job-password-encryption" attribute, including "sha" for SHA-1,
+"sha2-256" for SHA2-256, etc.
+
+The "hash" argument points to a buffer of "hashsize" bytes and should be at
+least 64 bytes in length for all of the supported algorithms.
+
+The returned hash is binary data.
Format a hash value as a hexadecimal string.
++const char *cupsHashString(const unsigned char *hash, size_t hashsize, char *buffer, size_t bufsize);
+| hash | +Hash |
|---|---|
| hashsize | +Size of hash |
| buffer | +String buffer |
| bufsize | +Size of string buffer |
Formatted string
+The passed buffer must be at least 2 * hashsize + 1 characters in length.
+Delete a JSON node and all of its children.
++void cupsJSONDelete(cups_json_t *json);
+| json | +JSON node |
|---|
Save a JSON node tree to a file.
++bool cupsJSONExportFile(cups_json_t *json, const char *filename);
+| json | +JSON root node |
|---|---|
| filename | +JSON filename |
true on success, false on failure
Save a JSON node tree to a string.
++char *cupsJSONExportString(cups_json_t *json);
+| json | +JSON root node |
|---|
JSON string or NULL on error
This function saves a JSON node tree to an allocated string. The resulting
+string must be freed using the free function.
Find the value(s) associated with a given key.
++cups_json_t *cupsJSONFind(cups_json_t *json, const char *key);
+| json | +JSON object node |
|---|---|
| key | +Object key |
JSON value or NULL
Get the first child node of an array or object node.
++cups_json_t *cupsJSONGetChild(cups_json_t *json, size_t n);
+| json | +JSON array or object node |
|---|---|
| n | +Child node number (starting at 0) |
First child node or NULL
Get the number of child nodes.
++size_t cupsJSONGetCount(cups_json_t *json);
+| json | +JSON array or object node |
|---|
Number of child nodes
+Get the key string, if any.
++const char *cupsJSONGetKey(cups_json_t *json);
+| json | +JSON string node |
|---|
String value
+This function returns the key string for a JSON key node or NULL if
+the node is not a key.
Get the number value, if any.
++double cupsJSONGetNumber(cups_json_t *json);
+| json | +JSON number node |
|---|
Number value
+This function returns the number value for a JSON number node or 0.0 if
+the node is not a number.
Get the parent node, if any.
++cups_json_t *cupsJSONGetParent(cups_json_t *json);
+| json | +JSON node |
|---|
Parent node or NULL if none
Get the next sibling node, if any.
++cups_json_t *cupsJSONGetSibling(cups_json_t *json);
+| json | +JSON node |
|---|
Sibling node or NULL if none
Get the string value, if any.
++const char *cupsJSONGetString(cups_json_t *json);
+| json | +JSON string node |
|---|
String value
+This function returns the string value for a JSON string node or NULL if
+the node is not a string.
Get the type of a JSON node.
++cups_jtype_t cupsJSONGetType(cups_json_t *json);
+| json | +JSON node |
|---|
JSON node type
+Load a JSON object file.
++cups_json_t *cupsJSONImportFile(const char *filename);
+| filename | +JSON filename |
|---|
Root JSON object node
+Load a JSON object from a string.
++cups_json_t *cupsJSONImportString(const char *s);
+| s | +JSON string |
|---|
Root JSON object node
+Load a JSON object from a URL.
++cups_json_t *cupsJSONImportURL(const char *url, time_t *last_modified);
+| url | +URL |
|---|---|
| last_modified | +Last modified date/time or NULL |
Root JSON object node
+This function loads a JSON object from a URL. The "url" can be a "http:" or
+"https:" URL. The "last_modified" argument provides a pointer to a time_t
+variable with the last modified date and time from a previous load. If
+NULL or the variable has a value of 0, the JSON is loaded unconditionally
+from the URL.
+
+On success, a pointer to the root JSON object node is returned and the
+"last_modified" variable, if not NULL, is updated to the Last-Modified
+date and time returned by the server. Otherwise, NULL is returned with
+the cupsGetError value set to IPP_STATUS_OK_EVENTS_COMPLETE if
+the JSON data has not been updated since the "last_modified" date and time
+or a suitable IPP_STATUS_ERROR_ value if an error occurred.
Create a new JSON node.
++cups_json_t *cupsJSONNew(cups_json_t *parent, cups_json_t *after, cups_jtype_t type);
+| parent | +Parent JSON node or NULL for a root node |
|---|---|
| after | +Previous sibling node or NULL to append to the end |
| type | +JSON node type |
JSON node
+Create a new JSON key node.
++cups_json_t *cupsJSONNewKey(cups_json_t *parent, cups_json_t *after, const char *value);
+| parent | +Parent JSON node or NULL for a root node |
|---|---|
| after | +Previous sibling node or NULL to append to the end |
| value | +Key string |
JSON node
+Create a new JSON number node.
++cups_json_t *cupsJSONNewNumber(cups_json_t *parent, cups_json_t *after, double value);
+| parent | +Parent JSON node or NULL for a root node |
|---|---|
| after | +Previous sibling node or NULL to append to the end |
| value | +Number value |
JSON node
+Create a new JSON string node.
++cups_json_t *cupsJSONNewString(cups_json_t *parent, cups_json_t *after, const char *value);
+| parent | +Parent JSON node or NULL for a root node |
|---|---|
| after | +Previous sibling node or NULL to append to the end |
| value | +String value |
JSON node
+Free the memory used for a JSON Web Token.
++void cupsJWTDelete(cups_jwt_t *jwt);
+| jwt | +JWT object |
|---|
Export a JWT with the JWS Compact or JWS JSON (Flattened) Serialization format.
++char *cupsJWTExportString(cups_jwt_t *jwt, cups_jws_format_t format);
+| jwt | +JWT object |
|---|---|
| format | +JWS serialization format |
JWT/JWS Serialization string
+This function exports a JWT to a JWS Compact or JWS JSON Serialization
+string. The JSON output is always the "flattened" format since the JWT
+only contains a single signature.
+
+The return value must be freed using the free function.
Get the signature algorithm used by a JSON Web Token.
++cups_jwa_t cupsJWTGetAlgorithm(cups_jwt_t *jwt);
+| jwt | +JWT object |
|---|
Signature algorithm
+Get the number value of a claim.
++double cupsJWTGetClaimNumber(cups_jwt_t *jwt, const char *claim);
+| jwt | +JWT object |
|---|---|
| claim | +Claim name |
Number value
+Get the string value of a claim.
++const char *cupsJWTGetClaimString(cups_jwt_t *jwt, const char *claim);
+| jwt | +JWT object |
|---|---|
| claim | +Claim name |
String value
+Get the value type of a claim.
++cups_jtype_t cupsJWTGetClaimType(cups_jwt_t *jwt, const char *claim);
+| jwt | +JWT object |
|---|---|
| claim | +Claim name |
JSON value type
+Get the value node of a claim.
++cups_json_t *cupsJWTGetClaimValue(cups_jwt_t *jwt, const char *claim);
+| jwt | +JWT object |
|---|---|
| claim | +Claim name |
JSON value node
+Get the JWT claims as a JSON object.
++cups_json_t *cupsJWTGetClaims(cups_jwt_t *jwt);
+| jwt | +JWT object |
|---|
JSON object
+Get the number value of a protected header.
++double cupsJWTGetHeaderNumber(cups_jwt_t *jwt, const char *header);
+| jwt | +JWT object |
|---|---|
| header | +Header name |
Number value
+Get the string value of a protected header.
++const char *cupsJWTGetHeaderString(cups_jwt_t *jwt, const char *header);
+| jwt | +JWT object |
|---|---|
| header | +Header name |
String value
+Get the value type of a protected header.
++cups_jtype_t cupsJWTGetHeaderType(cups_jwt_t *jwt, const char *header);
+| jwt | +JWT object |
|---|---|
| header | +Header name |
JSON value type
+Get the value node of a protected header.
++cups_json_t *cupsJWTGetHeaderValue(cups_jwt_t *jwt, const char *header);
+| jwt | +JWT object |
|---|---|
| header | +Header name |
JSON value node
+Get the JWT protected headers as a JSON object.
++cups_json_t *cupsJWTGetHeaders(cups_jwt_t *jwt);
+| jwt | +JWT object |
|---|
JSON object
+Determine whether the JWT has a valid signature.
++bool cupsJWTHasValidSignature(cups_jwt_t *jwt, cups_json_t *jwk);
+| jwt | +JWT object |
|---|---|
| jwk | +JWK key set |
true if value, false otherwise
Import a JSON Web Token or JSON Web Signature.
++cups_jwt_t *cupsJWTImportString(const char *s, cups_jws_format_t format);
+| s | +JWS string |
|---|---|
| format | +JWS serialization format |
JWT object
+Make a JSON Web Key for encryption and signing.
++cups_json_t *cupsJWTMakePrivateKey(cups_jwa_t alg);
+| alg | +Signing/encryption algorithm |
|---|
Private JSON Web Key or NULL on error
This function makes a JSON Web Key (JWK) for the specified JWS/JWE algorithm
+for use when signing or encrypting JSON Web Tokens. The resulting JWK
+must not be provided to clients - instead, call cupsJWTMakePublicKey
+to produce a public key subset suitable for verification and decryption.
Make a JSON Web Key for decryption and verification.
++cups_json_t *cupsJWTMakePublicKey(cups_json_t *jwk);
+| jwk | +Private JSON Web Key |
|---|
Public JSON Web Key or NULL on error
This function makes a public JSON Web Key (JWK) from the specified private +JWK suitable for use when decrypting or verifying a JWE/JWS message.
+Create a new, empty JSON Web Token.
++cups_jwt_t *cupsJWTNew(const char *type);
+| type | +JWT type or NULL for default ("JWT") |
|---|
JWT object
+Set a claim number.
++void cupsJWTSetClaimNumber(cups_jwt_t *jwt, const char *claim, double value);
+| jwt | +JWT object |
|---|---|
| claim | +Claim name |
| value | +Number value |
Set a claim string.
++void cupsJWTSetClaimString(cups_jwt_t *jwt, const char *claim, const char *value);
+| jwt | +JWT object |
|---|---|
| claim | +Claim name |
| value | +String value |
Set a claim value.
++void cupsJWTSetClaimValue(cups_jwt_t *jwt, const char *claim, cups_json_t *value);
+| jwt | +JWT object |
|---|---|
| claim | +Claim name |
| value | +JSON value node |
Set a protected header number.
++void cupsJWTSetHeaderNumber(cups_jwt_t *jwt, const char *header, double value);
+| jwt | +JWT object |
|---|---|
| header | +Header name |
| value | +Number value |
Set a protected header string.
++void cupsJWTSetHeaderString(cups_jwt_t *jwt, const char *header, const char *value);
+| jwt | +JWT object |
|---|---|
| header | +Header name |
| value | +String value |
Set a protected header value.
++void cupsJWTSetHeaderValue(cups_jwt_t *jwt, const char *header, cups_json_t *value);
+| jwt | +JWT object |
|---|---|
| header | +Header name |
| value | +JSON value node |
Sign a JSON Web Token, creating a JSON Web Signature.
++bool cupsJWTSign(cups_jwt_t *jwt, cups_jwa_t alg, cups_json_t *jwk);
+| jwt | +JWT object |
|---|---|
| alg | +Signing algorithm |
| jwk | +JWK key set |
true on success, false on error
Add strings for the specified language.
++bool cupsLangAddStrings(const char *language, const char *strings);
+| language | +Language name |
|---|---|
| strings | +Contents of ".strings" file |
true on success, false on failure
Return the default language.
++cups_lang_t *cupsLangDefault(void);
+Language data
+Find a language localization.
++cups_lang_t *cupsLangFind(const char *language);
+| language | +Language or locale name |
|---|
Language data
+Create a localized formatted string.
++const char *cupsLangFormatString(cups_lang_t *lang, char *buffer, size_t bufsize, const char *format, ...);
+| lang | +Language data |
|---|---|
| buffer | +Output buffer |
| bufsize | +Size of output buffer |
| format | +Printf-style format string |
| ... | +Additional arguments |
Formatted string
+Get the default encoding for the current locale.
++cups_encoding_t cupsLangGetEncoding(void);
+Character encoding
+Get the language name.
++const char *cupsLangGetName(cups_lang_t *lang);
+| lang | +Language data |
|---|
Language name
+Get a localized message string.
++const char *cupsLangGetString(cups_lang_t *lang, const char *message);
+| lang | +Language |
|---|---|
| message | +Message |
Localized message
+This function gets a localized UTF-8 message string for the specified +language. If the message is not localized, the original message pointer is +returned.
+Load a message catalog for a language.
++bool cupsLangLoadStrings(cups_lang_t *lang, const char *filename, const char *strings);
+| lang | +Language data |
|---|---|
| filename | +Filename of NULL for none |
| strings | +Strings or NULL for none |
true on success, false on failure
Print a formatted message string to a file.
++ssize_t cupsLangPrintf(FILE *fp, const char *format, ...);
+| fp | +File to write to |
|---|---|
| format | +Message string to use |
| ... | +Additional arguments as needed |
Number of bytes written
+Print a static message string to a file.
++ssize_t cupsLangPuts(FILE *fp, const char *message);
+| fp | +File to write to |
|---|---|
| message | +Message string to use |
Number of bytes written
+Set a directory containing localizations.
++void cupsLangSetDirectory(const char *d);
+| d | +Directory name |
|---|
Set the current locale and transcode the command-line.
++void cupsLangSetLocale(char *argv[]);
+| argv[] | +Command-line arguments |
|---|
Get the localized string for a destination media + size.
++const char *cupsLocalizeDestMedia(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, unsigned flags, cups_size_t *size);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| flags | +Media flags |
| size | +Media size |
Localized string
+The returned string is stored in the destination information and will become +invalid if the destination information is deleted.
+Get the localized string for a destination + option.
++const char *cupsLocalizeDestOption(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, const char *option);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| option | +Option to localize |
Localized string
+The returned string is stored in the destination information and will become +invalid if the destination information is deleted.
+Get the localized string for a destination + option+value pair.
++const char *cupsLocalizeDestValue(http_t *http, cups_dest_t *dest, cups_dinfo_t *dinfo, const char *option, const char *value);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| dinfo | +Destination information |
| option | +Option to localize |
| value | +Value to localize |
Localized string
+The returned string is stored in the destination information and will become +invalid if the destination information is deleted.
+Return the localized subject for the given notification message.
++char *cupsLocalizeNotifySubject(cups_lang_t *lang, ipp_t *event);
+| lang | +Language data |
|---|---|
| event | +Event data |
Subject string or NULL
This function returns a localized subject string for the given notification
+message. The returned string must be freed by the caller using free.
Return the localized text for the given notification message.
++char *cupsLocalizeNotifyText(cups_lang_t *lang, ipp_t *event);
+| lang | +Language data |
|---|---|
| event | +Event data |
Message text or NULL
This function returns a localized text string for the given notification
+message. The returned string must be freed by the caller using free.
Destroy a mutex.
++void cupsMutexDestroy(cups_mutex_t *mutex);
+| mutex | +Mutex |
|---|
Initialize a mutex.
++void cupsMutexInit(cups_mutex_t *mutex);
+| mutex | +Mutex |
|---|
Lock a mutex.
++void cupsMutexLock(cups_mutex_t *mutex);
+| mutex | +Mutex |
|---|
Unlock a mutex.
++void cupsMutexUnlock(cups_mutex_t *mutex);
+| mutex | +Mutex |
|---|
Parse options from a command-line argument.
++size_t cupsParseOptions(const char *arg, size_t num_options, cups_option_t **options);
+| arg | +Argument to parse |
|---|---|
| num_options | +Number of options |
| options | +Options found |
Number of options found
+This function converts space-delimited name/value pairs according
+to the PAPI text option ABNF specification. Collection values
+("name={a=... b=... c=...}") are stored with the curley brackets
+intact - use cupsParseOptions on the value to extract the
+collection attributes.
Put a file on the server.
++http_status_t cupsPutFd(http_t *http, const char *resource, int fd);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| resource | +Resource name |
| fd | +File descriptor |
HTTP status
+This function returns HTTP_STATUS_CREATED when the file is stored
+successfully.
Put a file on the server.
++http_status_t cupsPutFile(http_t *http, const char *resource, const char *filename);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| resource | +Resource name |
| filename | +Filename |
HTTP status
+This function returns HTTP_CREATED when the file is stored
+successfully.
Destroy a reader/writer lock.
++void cupsRWDestroy(cups_rwlock_t *rwlock);
+| rwlock | +Reader/writer lock |
|---|
Initialize a reader/writer lock.
++void cupsRWInit(cups_rwlock_t *rwlock);
+| rwlock | +Reader/writer lock |
|---|
Acquire a reader/writer lock for reading.
++void cupsRWLockRead(cups_rwlock_t *rwlock);
+| rwlock | +Reader/writer lock |
|---|
Acquire a reader/writer lock for writing.
++void cupsRWLockWrite(cups_rwlock_t *rwlock);
+| rwlock | +Reader/writer lock |
|---|
Release a reader/writer lock.
++void cupsRWUnlock(cups_rwlock_t *rwlock);
+| rwlock | +Reader/writer lock |
|---|
Close a raster stream.
++void cupsRasterClose(cups_raster_t *r);
+| r | +Stream to free |
|---|
The file descriptor associated with the raster stream must be closed +separately as needed.
+Return the last error from a raster function.
++const char *cupsRasterErrorString(void);
+Last error
+If there are no recent errors, NULL is returned.
Initialize a page header for PWG Raster output.
++bool cupsRasterInitHeader(cups_page_header_t *h, cups_size_t *media, const char *optimize, ipp_quality_t quality, const char *intent, ipp_orient_t orientation, const char *sides, const char *type, int xdpi, int ydpi, const char *sheet_back);
+| h | +Page header |
|---|---|
| media | +Media information |
| optimize | +IPP "print-content-optimize" value |
| quality | +IPP "print-quality" value |
| intent | +IPP "print-rendering-intent" value |
| orientation | +IPP "orientation-requested" value |
| sides | +IPP "sides" value |
| type | +PWG raster type string |
| xdpi | +Cross-feed direction (horizontal) resolution |
| ydpi | +Feed direction (vertical) resolution |
| sheet_back | +Transform for back side or NULL for none |
true on success, false on failure
The "media" argument specifies the media to use. The "optimize", "quality",
+"intent", "orientation", and "sides" arguments specify additional IPP Job
+Template attribute values that are reflected in the raster header.
+
+The "type" argument specifies a "pwg-raster-document-type-supported" value
+that controls the color space and bit depth of the raster data. Supported
+values include:
+
+
The "xres" and "yres" arguments specify the raster resolution in dots per
+inch.
+
+The "sheet_back" argument specifies a "pwg-raster-document-sheet-back" value
+to apply for the back side of a page. Pass NULL for the front side.
Open a raster stream using a file descriptor.
++cups_raster_t *cupsRasterOpen(int fd, cups_raster_mode_t mode);
+| fd | +File descriptor |
|---|---|
| mode | +Mode - CUPS_RASTER_READ, CUPS_RASTER_WRITE, CUPS_RASTER_WRITE_COMPRESSED, CUPS_RASTER_WRITE_PWG |
New stream
+This function associates a raster stream with the given file descriptor.
+For most printer driver filters, "fd" will be 0 (stdin). For most raster
+image processor (RIP) filters that generate raster data, "fd" will be 1
+(stdout).
+
+When writing raster data, the CUPS_RASTER_WRITE,
+CUPS_RASTER_WRITE_COMPRESS, or CUPS_RASTER_WRITE_PWG mode can
+be used - compressed and PWG output is generally 25-50% smaller but adds a
+100-300% execution time overhead.
Open a raster stream using a callback function.
++cups_raster_t *cupsRasterOpenIO(cups_raster_cb_t iocb, void *ctx, cups_raster_mode_t mode);
+| iocb | +Read/write callback |
|---|---|
| ctx | +Context pointer for callback |
| mode | +Mode - CUPS_RASTER_READ, CUPS_RASTER_WRITE, CUPS_RASTER_WRITE_COMPRESSED, CUPS_RASTER_WRITE_PWG |
New stream
+This function associates a raster stream with the given callback function and
+context pointer.
+
+When writing raster data, the CUPS_RASTER_WRITE,
+CUPS_RASTER_WRITE_COMPRESS, or CUPS_RASTER_WRITE_PWG mode can
+be used - compressed and PWG output is generally 25-50% smaller but adds a
+100-300% execution time overhead.
Read a raster page header.
++bool cupsRasterReadHeader(cups_raster_t *r, cups_page_header_t *h);
+| r | +Raster stream |
|---|---|
| h | +Pointer to header data |
true on success, false on failure
Read raster pixels.
++unsigned cupsRasterReadPixels(cups_raster_t *r, unsigned char *p, unsigned len);
+| r | +Raster stream |
|---|---|
| p | +Pointer to pixel buffer |
| len | +Number of bytes to read |
Number of bytes read
+For best performance, filters should read one or more whole lines. +The "cupsBytesPerLine" value from the page header can be used to allocate +the line buffer and as the number of bytes to read.
+Write a raster page header.
++bool cupsRasterWriteHeader(cups_raster_t *r, cups_page_header_t *h);
+| r | +Raster stream |
|---|---|
| h | +Pointer to header data |
true on success, false on failure
Write raster pixels.
++unsigned cupsRasterWritePixels(cups_raster_t *r, unsigned char *p, unsigned len);
+| r | +Raster stream |
|---|---|
| p | +Bytes to write |
| len | +Number of bytes to write |
Number of bytes written
+For best performance, filters should write one or more whole lines. +The "cupsBytesPerLine" value from the page header can be used to allocate +the line buffer and as the number of bytes to write.
+Read additional data after the IPP response.
++ssize_t cupsReadResponseData(http_t *http, char *buffer, size_t length);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| buffer | +Buffer to use |
| length | +Number of bytes to read |
Bytes read, 0 on EOF, -1 on error
+This function is used after cupsGetResponse to read any trailing
+document data after an IPP response.
Remove a destination from the destination list.
++size_t cupsRemoveDest(const char *name, const char *instance, size_t num_dests, cups_dest_t **dests);
+| name | +Destination name |
|---|---|
| instance | +Instance name or NULL |
| num_dests | +Number of destinations |
| dests | +Destinations |
New number of destinations
+Removing a destination/instance does not delete the class or printer
+queue, merely the lpoptions for that destination/instance. Use the
+cupsSetDests function to save the new options for the user.
Remove an option from an option array.
++size_t cupsRemoveOption(const char *name, size_t num_options, cups_option_t **options);
+| name | +Option name |
|---|---|
| num_options | +Current number of options |
| options | +Options |
New number of options
+Save the credentials associated with a printer/server.
++bool cupsSaveCredentials(const char *path, const char *common_name, const char *credentials, const char *key);
+| path | +Directory path for certificate/key store or NULL for default |
|---|---|
| common_name | +Common name for certificate |
| credentials | +PEM-encoded certificate chain |
| key | +PEM-encoded private key or NULL for none |
true on success, false on failure
This function saves the the PEM-encoded X.509 certificate chain string and
+private key (if not NULL) to the directory "path" or, if "path" is NULL,
+in a per-user or system-wide (when running as root) certificate/key store.
Send an IPP request.
++http_status_t cupsSendRequest(http_t *http, ipp_t *request, const char *resource, size_t length);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| request | +IPP request |
| resource | +Resource path |
| length | +Length of data to follow or CUPS_LENGTH_VARIABLE |
Initial HTTP status
+Use cupsWriteRequestData to write any additional data (document, etc.)
+for the request, cupsGetResponse to get the IPP response, and
+cupsReadResponseData to read any additional data following the
+response. Only one request can be sent/queued at a time per http_t
+connection.
+
+Returns the initial HTTP status code, which will be HTTP_STATUS_CONTINUE
+on a successful send of the request.
+
+Note: Unlike cupsDoFileRequest, cupsDoIORequest, and
+cupsDoRequest, the request is NOT freed with ippDelete.
Set the client certificate callback.
++void cupsSetClientCertCB(cups_client_cert_cb_t cb, void *user_data);
+| cb | +Callback function |
|---|---|
| user_data | +User data pointer |
Pass NULL to restore the default callback.
+
+Note: The current certificate callback is tracked separately for each thread
+in a program. Multi-threaded programs that override the callback need to do
+so in each thread for the same callback to be used.
Set the default credentials to be used for TLS + connections.
++bool cupsSetCredentials(const char *credentials);
+| credentials | +PEM-encoded X.509 credentials string |
|---|
true on success, false on failure
Note: The default credentials are tracked separately for each thread in a +program. Multi-threaded programs that override the setting need to do so in +each thread for the same setting to be used.
+Set the default destination.
++void cupsSetDefaultDest(const char *name, const char *instance, size_t num_dests, cups_dest_t *dests);
+| name | +Destination name |
|---|---|
| instance | +Instance name or NULL |
| num_dests | +Number of destinations |
| dests | +Destinations |
Save the list of destinations for the specified server.
++bool cupsSetDests(http_t *http, size_t num_dests, cups_dest_t *dests);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| num_dests | +Number of destinations |
| dests | +Destinations |
true on success, false on error
This function saves the destinations to /etc/cups/lpoptions when run +as root and ~/.../lpoptions when run as a normal user.
+Set the encryption preference.
++void cupsSetEncryption(http_encryption_t e);
+| e | +New encryption preference |
|---|
The default encryption setting comes from the CUPS_ENCRYPTION
+environment variable, then the ~/.cups/client.conf file, and finally the
+/etc/cups/client.conf file. If not set, the default is
+HTTP_ENCRYPTION_IF_REQUESTED.
+
+Note: The current encryption setting is tracked separately for each thread
+in a program. Multi-threaded programs that override the setting need to do
+so in each thread for the same setting to be used.
Set the OAuth 2.0 callback for CUPS.
++void cupsSetOAuthCB(cups_oauth_cb_t cb, void *user_data);
+| cb | +Callback function |
|---|---|
| user_data | +User data pointer |
This function sets the OAuth 2.0 callback for the various CUPS APIs that
+send HTTP requests. Pass NULL to restore the default (console-based)
+callback.
+
+The OAuth callback receives the HTTP connection, realm name, scope name (if
+any), resource path, and the "user_data" pointer for each request that
+requires an OAuth access token. The function then returns either the Bearer
+token string or NULL if no authorization could be obtained.
+
+Beyond reusing the Bearer token for subsequent requests on the same HTTP
+connection, no caching of the token is done by the CUPS library. The
+callback can determine whether to refresh a cached token by examining any
+existing token returned by the httpGetAuthString function.
+
+Note: The current OAuth callback is tracked separately for each thread in a
+program. Multi-threaded programs that override the callback need to do so in
+each thread for the same callback to be used.
Set the password callback for CUPS.
++void cupsSetPasswordCB(cups_password_cb_t cb, void *user_data);
+| cb | +Callback function |
|---|---|
| user_data | +User data pointer |
Pass NULL to restore the default (console) password callback, which
+reads the password from the console.
+
+Note: The current password callback is tracked separately for each thread
+in a program. Multi-threaded programs that override the callback need to do
+so in each thread for the same callback to be used.
Set the default server name and port.
++void cupsSetServer(const char *server);
+| server | +Server name |
|---|
The "server" string can be a fully-qualified hostname, a numeric
+IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP
+addresses can be optionally followed by a colon and port number to override
+the default port 631, e.g. "hostname:8631". Pass NULL to restore the
+default server name and port.
+
+Note: The current server is tracked separately for each thread in a program.
+Multi-threaded programs that override the server need to do so in each
+thread for the same server to be used.
Set the server certificate callback.
++void cupsSetServerCertCB(cups_server_cert_cb_t cb, void *user_data);
+| cb | +Callback function |
|---|---|
| user_data | +User data pointer |
Pass NULL to restore the default callback.
+
+Note: The current credentials callback is tracked separately for each thread
+in a program. Multi-threaded programs that override the callback need to do
+so in each thread for the same callback to be used.
Set the default server credentials.
++bool cupsSetServerCredentials(const char *path, const char *common_name, bool auto_create);
+| path | +Directory path for certificate/key store or NULL for default |
|---|---|
| common_name | +Default common name for server |
| auto_create | +true = automatically create self-signed certificates |
true on success, false on failure
Note: The server credentials are used by all threads in the running process. +This function is threadsafe.
+Set the default user name.
++void cupsSetUser(const char *user);
+| user | +User name |
|---|
Pass NULL to restore the default user name.
+
+Note: The current user name is tracked separately for each thread in a
+program. Multi-threaded programs that override the user name need to do so
+in each thread for the same user name to be used.
Set the default HTTP User-Agent string.
++void cupsSetUserAgent(const char *user_agent);
+| user_agent | +User-Agent string or NULL |
|---|
Setting the string to NULL forces the default value containing the CUPS +version, IPP version, and operating system version and architecture.
+Sign an X.509 certificate signing request to produce an X.509 certificate chain.
++bool cupsSignCredentialsRequest(const char *path, const char *common_name, const char *request, const char *root_name, cups_credpurpose_t allowed_purpose, cups_credusage_t allowed_usage, cups_cert_san_cb_t cb, void *cb_data, time_t expiration_date);
+| path | +Directory path for certificate/key store or NULL for default |
|---|---|
| common_name | +Common name to use |
| request | +PEM-encoded CSR |
| root_name | +Root certificate |
| allowed_purpose | +Allowed credential purpose(s) |
| allowed_usage | +Allowed credential usage(s) |
| cb | +subjectAltName callback or NULL to allow just .local |
| cb_data | +Callback data |
| expiration_date | +Certificate expiration date |
true on success, false on failure
This function creates an X.509 certificate from a signing request. The
+certificate is stored in the directory "path" or, if "path" is NULL, in a
+per-user or system-wide (when running as root) certificate/key store. The
+generated certificate is signed by the named root certificate or, if
+"root_name" is NULL, a site-wide default root certificate. When
+"root_name" is NULL and there is no site-wide default root certificate, a
+self-signed certificate is generated instead.
+
+The "allowed_purpose" argument specifies the allowed purpose(s) used for the
+credentials as a bitwise OR of the following constants:
+
+
CUPS_CREDPURPOSE_SERVER_AUTH for validating TLS servers,
+CUPS_CREDPURPOSE_CLIENT_AUTH for validating TLS clients,
+CUPS_CREDPURPOSE_CODE_SIGNING for validating compiled code,
+CUPS_CREDPURPOSE_EMAIL_PROTECTION for validating email messages,
+CUPS_CREDPURPOSE_TIME_STAMPING for signing timestamps to objects, and/or
+CUPS_CREDPURPOSE_OCSP_SIGNING for Online Certificate Status Protocol
+ message signing.The "allowed_usage" argument specifies the allowed usage(s) for the +credentials as a bitwise OR of the following constants: + +
CUPS_CREDUSAGE_DIGITAL_SIGNATURE: digital signatures,
+CUPS_CREDUSAGE_NON_REPUDIATION: non-repudiation/content commitment,
+CUPS_CREDUSAGE_KEY_ENCIPHERMENT: key encipherment,
+CUPS_CREDUSAGE_DATA_ENCIPHERMENT: data encipherment,
+CUPS_CREDUSAGE_KEY_AGREEMENT: key agreement,
+CUPS_CREDUSAGE_KEY_CERT_SIGN: key certicate signing,
+CUPS_CREDUSAGE_CRL_SIGN: certificate revocation list signing,
+CUPS_CREDUSAGE_ENCIPHER_ONLY: encipherment only,
+CUPS_CREDUSAGE_DECIPHER_ONLY: decipherment only,
+CUPS_CREDUSAGE_DEFAULT_CA: defaults for CA certificates,
+CUPS_CREDUSAGE_DEFAULT_TLS: defaults for TLS certificates, and/or
+CUPS_CREDUSAGE_ALL: all usages.The "cb" and "cb_data" arguments specify a function and its data that are +used to validate any subjectAltName values in the signing request: + +
+bool san_cb(const char *common_name, const char *alt_name, void *cb_data) {
+ ... return true if OK and false if not ...
+}
+
+
+If NULL, a default validation function is used that allows "localhost" and
+variations of the common name.time_t value in seconds.
+Start a new document.
++http_status_t cupsStartDestDocument(http_t *http, cups_dest_t *dest, cups_dinfo_t *info, int job_id, const char *docname, const char *format, size_t num_options, cups_option_t *options, bool last_document);
+| http | +Connection to destination |
|---|---|
| dest | +Destination |
| info | +Destination information |
| job_id | +Job ID |
| docname | +Document name |
| format | +Document format |
| num_options | +Number of document options |
| options | +Document options |
| last_document | +true if this is the last document |
Status of document creation
+This function starts a new document for the specified destination "dest" and
+job "job_id". The "info" argument contains information about the destination
+obtained using the cupsCopyDestInfo function.
+
+The "docname" argument specifies the name of the document/file being printed.
+The "format" argument specifies the MIME media type for the document; the
+following constants are provided for convenience:
+
+
CUPS_FORMAT_AUTO: Auto-type the file using its contents
+CUPS_FORMAT_JPEG: JPEG image file
+CUPS_FORMAT_PDF: PDF file
+CUPS_FORMAT_TEXT: Plain text fileThe "num_options" and "options" arguments provide the options to be applied
+to the document. The "last_document" argument specifies whether this is the
+final document in the job (true) or not (false).
+
+Returns HTTP_CONTINUE on success.
Creates a temporary file.
++int cupsTempFd(const char *prefix, const char *suffix, char *filename, size_t len);
+| prefix | +Filename prefix or NULL for none |
|---|---|
| suffix | +Filename suffix or NULL for none |
| filename | +Pointer to buffer |
| len | +Size of buffer |
New file descriptor or -1 on error
This function creates a temporary file and returns a file descriptor for the +file. The unique temporary filename uses the "prefix" and "suffix" arguments +and is returned in the filename buffer. The temporary file is opened for +reading and writing.
+Creates a temporary CUPS file.
++cups_file_t *cupsTempFile(const char *prefix, const char *suffix, char *filename, size_t len);
+| prefix | +Filename prefix or NULL for none |
|---|---|
| suffix | +Filename suffix or NULL for none |
| filename | +Pointer to buffer |
| len | +Size of buffer |
CUPS file or NULL on error
This function creates a temporary file and returns a file descriptor for the +file. The unique temporary filename uses the "prefix" and "suffix" arguments +and is returned in the filename buffer. The temporary file is opened for +writing.
+Cancel (kill) a thread.
++void cupsThreadCancel(cups_thread_t thread);
+| thread | +Thread ID |
|---|
Create a thread.
++cups_thread_t cupsThreadCreate(cups_thread_func_t func, void *arg);
+| func | +Entry point |
|---|---|
| arg | +Entry point context |
Thread ID or CUPS_THREAD_INVALID on failure
Tell the OS that the thread is running independently.
++void cupsThreadDetach(cups_thread_t thread);
+| thread | +Thread ID |
|---|
Wait for a thread to exit.
++void *cupsThreadWait(cups_thread_t thread);
+| thread | +Thread ID |
|---|
Return value
+Convert UTF-32 to UTF-8.
++ssize_t cupsUTF32ToUTF8(char *dest, const cups_utf32_t *src, const size_t maxout);
+| dest | +Target string |
|---|---|
| src | +Source string |
| maxout | +Max output in bytes |
Number of bytes or -1 on error
This function converts a UTF-32 (32-bit encoding of Unicode) string to a
+UTF-8 (8-bit encoding of Unicode) nul-terminated C string.
Convert UTF-8 to legacy character set.
++ssize_t cupsUTF8ToCharset(char *dest, const char *src, const size_t maxout, const cups_encoding_t encoding);
+| dest | +Target string |
|---|---|
| src | +Source string |
| maxout | +Max output in bytes |
| encoding | +Encoding |
Number of bytes or -1 on error
Convert UTF-8 to UTF-32.
++ssize_t cupsUTF8ToUTF32(cups_utf32_t *dest, const char *src, const size_t maxout);
+| dest | +Target string |
|---|---|
| src | +Source string |
| maxout | +Max output in words |
Number of words or -1 on error
This function converts a UTF-8 (8-bit encoding of Unicode) nul-terminated
+C string to a UTF-32 (32-bit encoding of Unicode) string.
Write additional data after an IPP request.
++http_status_t cupsWriteRequestData(http_t *http, const char *buffer, size_t length);
+| http | +Connection to server or CUPS_HTTP_DEFAULT |
|---|---|
| buffer | +Bytes to write |
| length | +Number of bytes to write |
HTTP_STATUS_CONTINUE if OK or HTTP status on error
This function is used after cupsSendRequest to provide a PPD and
+after cupsStartDocument to provide a document file.
Accept a new HTTP client connection.
++http_t *httpAcceptConnection(int fd, bool blocking);
+| fd | +Listen socket file descriptor |
|---|---|
| blocking | +true if the connection should be blocking, false otherwise |
HTTP connection or NULL
This function accepts a new HTTP client connection from the specified +listening socket "fd". The "blocking" argument specifies whether the new +HTTP connection is blocking.
+Close a socket created by httpAddrConnect or
+ httpAddrListen.
+bool httpAddrClose(http_addr_t *addr, int fd);
+| addr | +Listen address or NULL |
|---|---|
| fd | +Socket file descriptor |
true on success, false on failure
Pass NULL for sockets created with httpAddrConnect and the
+listen address for sockets created with httpAddrListen. This function
+ensures that domain sockets are removed when closed.
Connect to any of the addresses in the list with a + timeout and optional cancel.
++http_addrlist_t *httpAddrConnect(http_addrlist_t *addrlist, int *sock, int msec, int *cancel);
+| addrlist | +List of potential addresses |
|---|---|
| sock | +Socket |
| msec | +Timeout in milliseconds |
| cancel | +Pointer to "cancel" variable |
Connected address or NULL on failure
+Copy an address list.
++http_addrlist_t *httpAddrCopyList(http_addrlist_t *src);
+| src | +Source address list |
|---|
New address list or NULL on error
Free an address list.
++void httpAddrFreeList(http_addrlist_t *addrlist);
+| addrlist | +Address list to free |
|---|
Get the address family of an address.
++int httpAddrGetFamily(http_addr_t *addr);
+| addr | +Address |
|---|
Address family
+Return the length of the address in bytes.
++size_t httpAddrGetLength(const http_addr_t *addr);
+| addr | +Address |
|---|
Length in bytes
+Get a list of addresses for a hostname.
++http_addrlist_t *httpAddrGetList(const char *hostname, int family, const char *service);
+| hostname | +Hostname, IP address, or NULL for passive listen address |
|---|---|
| family | +Address family or AF_UNSPEC |
| service | +Service name or port number |
List of addresses or NULL
+Get the port number associated with an address.
++int httpAddrGetPort(http_addr_t *addr);
+| addr | +Address |
|---|
Port number
+Convert an address to a numeric string.
++char *httpAddrGetString(const http_addr_t *addr, char *s, size_t slen);
+| addr | +Address to convert |
|---|---|
| s | +String buffer |
| slen | +Length of string buffer |
Numeric address string
+Check for the "any" address.
++bool httpAddrIsAny(const http_addr_t *addr);
+| addr | +Address to check |
|---|
true if "any", false otherwise
Compare two addresses.
++bool httpAddrIsEqual(const http_addr_t *addr1, const http_addr_t *addr2);
+| addr1 | +First address |
|---|---|
| addr2 | +Second address |
true if equal, false if not
Check for the local loopback address.
++bool httpAddrIsLocalhost(const http_addr_t *addr);
+| addr | +Address to check |
|---|
true if local host, false otherwise
Create a listening socket bound to the specified address and port.
++int httpAddrListen(http_addr_t *addr, int port);
+| addr | +Address to bind to |
|---|---|
| port | +Port number to bind to |
Socket or -1 on error
Lookup the hostname associated with the address.
++char *httpAddrLookup(const http_addr_t *addr, char *name, size_t namelen);
+| addr | +Address to lookup |
|---|---|
| name | +Host name buffer |
| namelen | +Size of name buffer |
Host name
+Set the port number associated with an address.
++void httpAddrSetPort(http_addr_t *addr, int port);
+| addr | +Address |
|---|---|
| port | +Port |
Assemble a uniform resource identifier from its + components.
++http_uri_status_t httpAssembleURI(http_uri_coding_t encoding, char *uri, size_t urilen, const char *scheme, const char *username, const char *host, int port, const char *resource);
+| encoding | +Encoding flags |
|---|---|
| uri | +URI buffer |
| urilen | +Size of URI buffer |
| scheme | +Scheme name |
| username | +Username |
| host | +Hostname or address |
| port | +Port number |
| resource | +Resource |
URI status
+This function escapes reserved characters in the URI depending on the +value of the "encoding" argument. You should use this function in +place of traditional string functions whenever you need to create a +URI string.
+Assemble a uniform resource identifier from its + components with a formatted resource.
++http_uri_status_t httpAssembleURIf(http_uri_coding_t encoding, char *uri, size_t urilen, const char *scheme, const char *username, const char *host, int port, const char *resourcef, ...);
+| encoding | +Encoding flags |
|---|---|
| uri | +URI buffer |
| urilen | +Size of URI buffer |
| scheme | +Scheme name |
| username | +Username |
| host | +Hostname or address |
| port | +Port number |
| resourcef | +Printf-style resource |
| ... | +Additional arguments as needed |
URI status
+This function creates a formatted version of the resource string +argument "resourcef" and escapes reserved characters in the URI +depending on the value of the "encoding" argument. You should use +this function in place of traditional string functions whenever +you need to create a URI string.
+Assemble a name-based UUID URN conforming to RFC 4122.
++char *httpAssembleUUID(const char *server, int port, const char *name, int number, char *buffer, size_t bufsize);
+| server | +Server name |
|---|---|
| port | +Port number |
| name | +Object name or NULL |
| number | +Object number or 0 |
| buffer | +String buffer |
| bufsize | +Size of buffer |
UUID string
+This function creates a unique 128-bit identifying number using the server
+name, port number, random data, and optionally an object name and/or object
+number. The result is formatted as a UUID URN as defined in RFC 4122.
+
+The buffer needs to be at least 46 bytes in size.
Clear the cookie value(s).
++void httpClearCookie(http_t *http);
+| http | +HTTP connection |
|---|
Clear HTTP request/response fields.
++void httpClearFields(http_t *http);
+| http | +HTTP connection |
|---|
Close a HTTP connection.
++void httpClose(http_t *http);
+| http | +HTTP connection |
|---|
Connect to a HTTP server.
++http_t *httpConnect(const char *host, int port, http_addrlist_t *addrlist, int family, http_encryption_t encryption, bool blocking, int msec, int *cancel);
+| host | +Host to connect to |
|---|---|
| port | +Port number |
| addrlist | +List of addresses or NULL to lookup |
| family | +Address family to use or AF_UNSPEC for any |
| encryption | +Type of encryption to use |
| blocking | +true for blocking connection, false for non-blocking |
| msec | +Connection timeout in milliseconds, 0 means don't connect |
| cancel | +Pointer to "cancel" variable |
New HTTP connection
+This function creates a connection to a HTTP server. The "host" and "port"
+arguments specify a hostname or IP address and port number to use while the
+"addrlist" argument specifies a list of addresses to use or NULL to do a
+fresh lookup. The "family" argument specifies the address family to use -
+AF_UNSPEC to try both IPv4 and IPv6, AF_INET for IPv4, or AF_INET6 for
+IPv6.
+
+The "encryption" argument specifies whether to encrypt the connection and the
+"blocking" argument specifies whether to use blocking behavior when reading
+or writing data.
+
+The "msec" argument specifies how long to try to connect to the server or 0
+to just create an unconnected http_t object. The "cancel" argument
+specifies an integer variable that can be set to a non-zero value to cancel
+the connection process.
Copy the credentials associated with the peer in an encrypted connection.
++char *httpCopyPeerCredentials(http_t *http);
+| http | +Connection to server |
|---|
PEM-encoded X.509 certificate chain or NULL
Base64-decode a string.
++char *httpDecode64(char *out, size_t *outlen, const char *in, const char **end);
+| out | +String to write to |
|---|---|
| outlen | +Size of output string |
| in | +String to read from |
| end | +Pointer to end of Base64 data (NULL if don't care) |
Decoded string or NULL on error
This function decodes a Base64 string as defined by RFC 4648. The caller
+must initialize "outlen" to the maximum size of the decoded string. On
+return "outlen" contains the decoded length of the string and "end" (if not
+NULL) points to the end of the Base64 data that has been decoded.
+
+This function always reserves one byte in the output buffer for a nul
+terminating character, even if the result is not a regular string. Callers
+should ensure that the output buffer is at least one byte larger than the
+expected size, for example 33 bytes for a SHA-256 hash which is 32 bytes in
+length.
+
+This function supports both Base64 and Base64url strings.
Base64-encode a string.
++char *httpEncode64(char *out, size_t outlen, const char *in, size_t inlen, bool url);
+| out | +String to write to |
|---|---|
| outlen | +Maximum size of output string |
| in | +String to read from |
| inlen | +Size of input string |
| url | +true for Base64url, false for Base64 |
Encoded string
+This function encodes a Base64 string as defined by RFC 4648. The "url"
+parameter controls whether the original Base64 ("url" = false) or the
+Base64url ("url" = true) alphabet is used.
Return the HTTP field enumeration value for a field + name.
++http_field_t httpFieldValue(const char *name);
+| name | +String name |
|---|
Field index
+Flush data read from a HTTP connection.
++void httpFlush(http_t *http);
+| http | +HTTP connection |
|---|
Flush data written to a HTTP connection.
++int httpFlushWrite(http_t *http);
+| http | +HTTP connection |
|---|
Bytes written or -1 on error
+Get the most recent activity for a connection.
++time_t httpGetActivity(http_t *http);
+| http | +HTTP connection |
|---|
Time of last read or write
+The return value is the time in seconds of the last read or write.
+Get the address of the connected peer of a connection.
++http_addr_t *httpGetAddress(http_t *http);
+| http | +HTTP connection |
|---|
Connected address or NULL
For connections created with httpConnect2, the address is for the
+server. For connections created with httpAccept, the address is for
+the client.
+
+Returns NULL if the socket is currently unconnected.
Get the current authorization string.
++const char *httpGetAuthString(http_t *http);
+| http | +HTTP connection |
|---|
Authorization string
+The authorization string is set by cupsDoAuthentication and
+httpSetAuthString. Use httpGetAuthString to retrieve the
+string to use with httpSetField for the
+HTTP_FIELD_AUTHORIZATION value.
Get the blocking/non-blocking state of a connection.
++bool httpGetBlocking(http_t *http);
+| http | +HTTP connection |
|---|
true if blocking, false if non-blocking
Get a common content encoding, if any, between + the client and server.
++const char *httpGetContentEncoding(http_t *http);
+| http | +HTTP connection |
|---|
Content-Coding value or NULL for the identity coding.
This function uses the value of the Accepts-Encoding HTTP header and must be +called after receiving a response from the server or a request from the +client. The value returned can be use in subsequent requests (for clients) +or in the response (for servers) in order to compress the content stream.
+Get any cookie data from the response.
++const char *httpGetCookie(http_t *http);
+| http | +HTTP connection |
|---|
Cookie data or NULL
Get a formatted date/time string from a time value.
++const char *httpGetDateString(time_t t, char *s, size_t slen);
+| t | +Time in seconds |
|---|---|
| s | +String buffer |
| slen | +Size of string buffer |
Date/time string
+Get a time value from a formatted date/time string.
++time_t httpGetDateTime(const char *s);
+| s | +Date/time string |
|---|
Time in seconds
+Get the current encryption mode of a connection.
++http_encryption_t httpGetEncryption(http_t *http);
+| http | +HTTP connection |
|---|
Current encryption mode
+This function returns the encryption mode for the connection. Use the
+httpIsEncrypted function to determine whether a TLS session has
+been established.
Get the last error on a connection.
++int httpGetError(http_t *http);
+| http | +HTTP connection |
|---|
Error code (errno) value
+Get the value of the Expect header, if any.
++http_status_t httpGetExpect(http_t *http);
+| http | +HTTP connection |
|---|
Expect: status, if any
+Returns HTTP_STATUS_NONE if there is no Expect header, otherwise
+returns the expected HTTP status code, typically HTTP_STATUS_CONTINUE.
Get the file descriptor associated with a connection.
++int httpGetFd(http_t *http);
+| http | +HTTP connection |
|---|
File descriptor or -1 if none
+Get a field value from a request/response.
++const char *httpGetField(http_t *http, http_field_t field);
+| http | +HTTP connection |
|---|---|
| field | +Field to get |
Field value
+Get the FQDN for the connection or local system.
++const char *httpGetHostname(http_t *http, char *s, size_t slen);
+| http | +HTTP connection or NULL |
|---|---|
| s | +String buffer for name |
| slen | +Size of buffer |
FQDN for connection or system
+When "http" points to a connected socket, return the hostname or address that
+was used in the call to httpConnect or the address of the client for
+the connection from httpAcceptConnection.
+
+When "http" is NULL, return the FQDN for the local system.
Get the current Keep-Alive state of the connection.
++http_keepalive_t httpGetKeepAlive(http_t *http);
+| http | +HTTP connection |
|---|
Keep-Alive state
+Get the amount of data remaining from the content-length + or transfer-encoding fields.
++off_t httpGetLength(http_t *http);
+| http | +HTTP connection |
|---|
Content length
+This function returns the complete content length, even for content larger +than 2^31 - 1.
+Get the number of bytes that are buffered for writing.
++size_t httpGetPending(http_t *http);
+| http | +HTTP connection |
|---|
Number of bytes buffered
+Get the number of bytes that can be read without blocking.
++size_t httpGetReady(http_t *http);
+| http | +HTTP connection |
|---|
Number of bytes available
+Get the number of remaining bytes in the message + body or current chunk.
++size_t httpGetRemaining(http_t *http);
+| http | +HTTP connection |
|---|
Remaining bytes
+The httpIsChunked function can be used to determine whether the
+message body is chunked or fixed-length.
Get the current state of the HTTP request.
++http_state_t httpGetState(http_t *http);
+| http | +HTTP connection |
|---|
HTTP state
+Get the status of the last HTTP request.
++http_status_t httpGetStatus(http_t *http);
+| http | +HTTP connection |
|---|
HTTP status
+Get a sub-field value.
++char *httpGetSubField(http_t *http, http_field_t field, const char *name, char *value, size_t valuelen);
+| http | +HTTP connection |
|---|---|
| field | +Field index |
| name | +Name of sub-field |
| value | +Value string |
| valuelen | +Size of value buffer |
Value or NULL
Get the HTTP version at the other end.
++http_version_t httpGetVersion(http_t *http);
+| http | +HTTP connection |
|---|
Version number
+Get a line of text from a HTTP connection.
++char *httpGets(http_t *http, char *line, size_t length);
+| http | +HTTP connection |
|---|---|
| line | +Line to read into |
| length | +Max length of buffer |
Line or NULL
Initialize the HTTP interface library and set the default HTTP proxy (if any).
++void httpInitialize(void);
+Report whether a message body is chunked.
++bool httpIsChunked(http_t *http);
+| http | +HTTP connection |
|---|
true if chunked, false if not
This function returns true if the message body is composed of
+variable-length chunks.
Report whether a connection is encrypted.
++bool httpIsEncrypted(http_t *http);
+| http | +HTTP connection |
|---|
true if encrypted, false if not
This function returns true if the connection is currently encrypted.
Peek at data from a HTTP connection.
++ssize_t httpPeek(http_t *http, char *buffer, size_t length);
+| http | +HTTP connection |
|---|---|
| buffer | +Buffer for data |
| length | +Maximum number of bytes |
Number of bytes copied
+This function copies available data from the given HTTP connection, reading
+a buffer as needed. The data is still available for reading using
+httpRead.
+
+For non-blocking connections the usual timeouts apply.
Print a formatted string to a HTTP connection.
++ssize_t httpPrintf(http_t *http, const char *format, ...);
+| http | +HTTP connection |
|---|---|
| format | +printf-style format string |
| ... | +Additional args as needed |
Number of bytes written or -1 on error
Read data from a HTTP connection.
++ssize_t httpRead(http_t *http, char *buffer, size_t length);
+| http | +HTTP connection |
|---|---|
| buffer | +Buffer for data |
| length | +Maximum number of bytes |
Number of bytes read
+Read a HTTP request from a connection.
++http_state_t httpReadRequest(http_t *http, char *uri, size_t urilen);
+| http | +HTTP connection |
|---|---|
| uri | +URI buffer |
| urilen | +Size of URI buffer |
New state of connection
+Reconnect to a HTTP server with timeout and optional cancel.
++bool httpReconnect(http_t *http, int msec, int *cancel);
+| http | +HTTP connection |
|---|---|
| msec | +Timeout in milliseconds |
| cancel | +Pointer to "cancel" variable |
true on success, false on failure
Resolve the hostname of the HTTP connection + address.
++const char *httpResolveHostname(http_t *http, char *buffer, size_t bufsize);
+| http | +HTTP connection |
|---|---|
| buffer | +Hostname buffer |
| bufsize | +Size of buffer |
Resolved hostname or NULL
Resolve a DNS-SD URI.
++const char *httpResolveURI(const char *uri, char *resolved_uri, size_t resolved_size, http_resolve_t options, http_resolve_cb_t cb, void *cb_data);
+| uri | +DNS-SD URI |
|---|---|
| resolved_uri | +Buffer for resolved URI |
| resolved_size | +Size of URI buffer |
| options | +Resolve options |
| cb | +Continue callback function |
| cb_data | +Context pointer for callback |
Resolved URI
+This function resolves a DNS-SD URI of the form +"scheme://service-instance-name._protocol._tcp.domain/...". The "options" +parameter specifies a bitfield of resolution options including: + +
HTTP_RESOLVE_DEFAULT: Use default options
+HTTP_RESOLVE_FQDN: Resolve the fully-qualified domain name instead of an IP address
+HTTP_RESOLVE_FAXOUT: Resolve the FaxOut service instead of Print (IPP/IPPS)The "cb" parameter specifies a callback that allows resolution to be
+terminated. The callback is provided the "cb_data" value and returns a
+bool value that is true to continue and false to stop. If no callback
+is specified ("cb" is NULL), then this function will block up to 90 seconds
+to resolve the specified URI.
Separate a Universal Resource Identifier into its + components.
++http_uri_status_t httpSeparateURI(http_uri_coding_t decoding, const char *uri, char *scheme, size_t schemelen, char *username, size_t usernamelen, char *host, size_t hostlen, int *port, char *resource, size_t resourcelen);
+| decoding | +Decoding flags |
|---|---|
| uri | +Universal Resource Identifier |
| scheme | +Scheme (http, https, etc.) |
| schemelen | +Size of scheme buffer |
| username | +Username |
| usernamelen | +Size of username buffer |
| host | +Hostname |
| hostlen | +Size of hostname buffer |
| port | +Port number to use |
| resource | +Resource/filename |
| resourcelen | +Size of resource buffer |
Result of separation
+Set the current authorization string.
++void httpSetAuthString(http_t *http, const char *scheme, const char *data);
+| http | +HTTP connection |
|---|---|
| scheme | +Auth scheme (NULL to clear it) |
| data | +Auth data (NULL for none) |
This function stores a copy of the current authorization string in the HTTP
+connection object. You must still call httpSetField to set
+HTTP_FIELD_AUTHORIZATION prior to issuing a HTTP request using
+httpWriteRequest.
Set blocking/non-blocking behavior on a connection.
++void httpSetBlocking(http_t *http, bool blocking);
+| http | +HTTP connection |
|---|---|
| blocking | +true = blocking, false = non-blocking |
This function sets whether a connection uses blocking behavior when reading +or writing data. The "http" argument specifies the HTTP connection and the +"blocking" argument specifies whether to use blocking behavior.
+Set the cookie value(s).
++void httpSetCookie(http_t *http, const char *cookie);
+| http | +Connection |
|---|---|
| cookie | +Cookie string |
Set the credentials associated with an encrypted connection.
++bool httpSetCredentials(http_t *http, const char *credentials);
+| http | +HTTP connection |
|---|---|
| credentials | +Credentials string |
true on success, false on error
Set the default value of a HTTP header.
++void httpSetDefaultField(http_t *http, http_field_t field, const char *value);
+| http | +HTTP connection |
|---|---|
| field | +Field index |
| value | +Value |
This function sets the default value for a HTTP header.
+
+
+Note: Currently only the+HTTP_FIELD_ACCEPT_ENCODING, +HTTP_FIELD_SERVER, andHTTP_FIELD_USER_AGENTfields can be set.
Set the required encryption on a HTTP connection.
++bool httpSetEncryption(http_t *http, http_encryption_t e);
+| http | +HTTP connection |
|---|---|
| e | +New encryption preference |
true on success, false on error
Set the Expect: header in a request.
++void httpSetExpect(http_t *http, http_status_t expect);
+| http | +HTTP connection |
|---|---|
| expect | +HTTP status to expect (HTTP_STATUS_NONE or HTTP_STATUS_CONTINUE) |
This function sets the Expect: header in a request. Currently only
+HTTP_STATUS_NONE or HTTP_STATUS_CONTINUE is supported for the "expect"
+argument.
Set the value of a HTTP header.
++void httpSetField(http_t *http, http_field_t field, const char *value);
+| http | +HTTP connection |
|---|---|
| field | +Field index |
| value | +Value |
Set the current Keep-Alive state of a connection.
++void httpSetKeepAlive(http_t *http, http_keepalive_t keep_alive);
+| http | +HTTP connection |
|---|---|
| keep_alive | +New Keep-Alive value |
Set the Content-Length and Transfer-Encoding fields.
+void httpSetLength(http_t *http, size_t length);
+| http | +HTTP connection |
|---|---|
| length | +Length (0 for chunked) |
This function sets the Content-Length and Transfer-Encoding fields.
+Passing 0 to the "length" argument specifies a chunked transfer encoding
+while other values specify a fixed Content-Length.
Set read/write timeouts and an optional callback.
++void httpSetTimeout(http_t *http, double timeout, http_timeout_cb_t cb, void *cb_data);
+| http | +HTTP connection |
|---|---|
| timeout | +Number of seconds for timeout, must be greater than 0 |
| cb | +Callback function or NULL for none |
| cb_data | +Callback data pointer |
This function sets the read/write timeouts for a HTTP connection with an
+optional timeout callback. The timeout callback receives both the HTTP
+connection pointer and a user data pointer, and returns true to continue or
+false to error (time) out.
+
+
+bool // true to continue, false to stop
+timeout_cb(http_t *http, void *user_data)
+{
+ ... "http" contains the HTTP connection, "user_data" contains the callback pointer
+}
+
+
+Shutdown one side of a HTTP connection.
++void httpShutdown(http_t *http);
+| http | +HTTP connection |
|---|
Return the string describing a HTTP state value.
++const char *httpStateString(http_state_t state);
+| state | +HTTP state value |
|---|
State string
+Return a short string describing a HTTP status code.
++const char *httpStatusString(http_status_t status);
+| status | +HTTP status code |
|---|
Localized status string
+This function returns a short (localized) string describing a HTTP status +code. The strings are taken from the IANA HTTP Status Code registry.
+Return a string describing a URI status value.
++const char *httpURIStatusString(http_uri_status_t status);
+| status | +URI status value |
|---|
Localized status string
+This function returns a short (localized) string describing a URI status +value.
+Update the current HTTP state for incoming data.
++http_status_t httpUpdate(http_t *http);
+| http | +HTTP connection |
|---|
HTTP status
+Wait for data available on a connection.
++bool httpWait(http_t *http, int msec);
+| http | +HTTP connection |
|---|---|
| msec | +Milliseconds to wait |
true when data is available, false otherwise
Write data to a HTTP connection.
++ssize_t httpWrite(http_t *http, const char *buffer, size_t length);
+| http | +HTTP connection |
|---|---|
| buffer | +Buffer for data |
| length | +Number of bytes to write |
Number of bytes written
+TODO: Expand this documentation to talk about chunking.
+Write a HTTP request.
++bool httpWriteRequest(http_t *http, const char *method, const char *uri);
+| http | +HTTP connection |
|---|---|
| method | +Request method ("GET", "POST", "PUT", etc.) |
| uri | +Request URI |
true on success, false on failure
This function writes a HTTP request to the specified connection. The
+"method" parameter specifies the HTTP method ("GET", "POST", "PUT", etc)
+while the "uri" parameter specifies the request URI. All fields must be
+set using the httpSetCookie, httpSetField, and
+httpSetLength functions prior to writing the request.
Write a HTTP response to a client connection.
++bool httpWriteResponse(http_t *http, http_status_t status);
+| http | +HTTP connection |
|---|---|
| status | +Status code |
true on success, false on error
Add a boolean attribute to an IPP message.
++ipp_attribute_t *ippAddBoolean(ipp_t *ipp, ipp_tag_t group, const char *name, bool value);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| name | +Name of attribute |
| value | +Value of attribute |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add an array of boolean values.
++ipp_attribute_t *ippAddBooleans(ipp_t *ipp, ipp_tag_t group, const char *name, size_t num_values, const bool *values);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| name | +Name of attribute |
| num_values | +Number of values |
| values | +Values |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add a collection value.
++ipp_attribute_t *ippAddCollection(ipp_t *ipp, ipp_tag_t group, const char *name, ipp_t *value);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| name | +Name of attribute |
| value | +Value |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add an array of collection values.
++ipp_attribute_t *ippAddCollections(ipp_t *ipp, ipp_tag_t group, const char *name, size_t num_values, const ipp_t **values);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| name | +Name of attribute |
| num_values | +Number of values |
| values | +Values |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add a credentials string attribute to an IPP message.
++ipp_attribute_t *ippAddCredentialsString(ipp_t *ipp, ipp_tag_t group, const char *name, const char *credentials);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| name | +Attribute name |
| credentials | +Credentials string |
New attribute
+This function adds a 1setOf text attribute to an IPP message corresponding to
+the specified credentials string.
+
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add a dateTime attribute to an IPP message.
++ipp_attribute_t *ippAddDate(ipp_t *ipp, ipp_tag_t group, const char *name, const ipp_uchar_t *value);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| name | +Name of attribute |
| value | +Value |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add a integer attribute to an IPP message.
++ipp_attribute_t *ippAddInteger(ipp_t *ipp, ipp_tag_t group, ipp_tag_t value_tag, const char *name, int value);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| value_tag | +Type of attribute |
| name | +Name of attribute |
| value | +Value of attribute |
New attribute
+This function adds an integer or enum attribute to an IPP message.
+
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
+
+Supported values include enum (IPP_TAG_ENUM) and integer
+(IPP_TAG_INTEGER).
Add an array of integer values.
++ipp_attribute_t *ippAddIntegers(ipp_t *ipp, ipp_tag_t group, ipp_tag_t value_tag, const char *name, size_t num_values, const int *values);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| value_tag | +Type of attribute |
| name | +Name of attribute |
| num_values | +Number of values |
| values | +Values |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
+
+Supported values include enum (IPP_TAG_ENUM) and integer
+(IPP_TAG_INTEGER).
Add an octetString value to an IPP message.
++ipp_attribute_t *ippAddOctetString(ipp_t *ipp, ipp_tag_t group, const char *name, const void *data, size_t datalen);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| name | +Name of attribute |
| data | +octetString data |
| datalen | +Length of data in bytes |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add an out-of-band value to an IPP message.
++ipp_attribute_t *ippAddOutOfBand(ipp_t *ipp, ipp_tag_t group, ipp_tag_t value_tag, const char *name);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| value_tag | +Type of attribute |
| name | +Name of attribute |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
+
+Supported out-of-band values include unsupported-value
+(IPP_TAG_UNSUPPORTED_VALUE), default (IPP_TAG_DEFAULT), unknown
+(IPP_TAG_UNKNOWN), no-value (IPP_TAG_NOVALUE), not-settable
+(IPP_TAG_NOTSETTABLE), delete-attribute (IPP_TAG_DELETEATTR), and
+admin-define (IPP_TAG_ADMINDEFINE).
Add a range of values to an IPP message.
++ipp_attribute_t *ippAddRange(ipp_t *ipp, ipp_tag_t group, const char *name, int lower, int upper);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| name | +Name of attribute |
| lower | +Lower value |
| upper | +Upper value |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
+
+The "lower parameter must be less than or equal to the upper" parameter.
Add ranges of values to an IPP message.
++ipp_attribute_t *ippAddRanges(ipp_t *ipp, ipp_tag_t group, const char *name, size_t num_values, const int *lower, const int *upper);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| name | +Name of attribute |
| num_values | +Number of values |
| lower | +Lower values |
| upper | +Upper values |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add a resolution value to an IPP message.
++ipp_attribute_t *ippAddResolution(ipp_t *ipp, ipp_tag_t group, const char *name, ipp_res_t units, int xres, int yres);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| name | +Name of attribute |
| units | +Units for resolution |
| xres | +X resolution |
| yres | +Y resolution |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add resolution values to an IPP message.
++ipp_attribute_t *ippAddResolutions(ipp_t *ipp, ipp_tag_t group, const char *name, size_t num_values, ipp_res_t units, const int *xres, const int *yres);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| name | +Name of attribute |
| num_values | +Number of values |
| units | +Units for resolution |
| xres | +X resolutions |
| yres | +Y resolutions |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Add a group separator to an IPP message.
++ipp_attribute_t *ippAddSeparator(ipp_t *ipp);
+| ipp | +IPP message |
|---|
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
Add a language-encoded string to an IPP message.
++ipp_attribute_t *ippAddString(ipp_t *ipp, ipp_tag_t group, ipp_tag_t value_tag, const char *name, const char *language, const char *value);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| value_tag | +Type of attribute |
| name | +Name of attribute |
| language | +Language code |
| value | +Value |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
+
+Supported string values include charset (IPP_TAG_CHARSET), keyword
+(IPP_TAG_KEYWORD), language (IPP_TAG_LANGUAGE), mimeMediaType
+(IPP_TAG_MIMETYPE), name (IPP_TAG_NAME), nameWithLanguage
+(IPP_TAG_NAMELANG), text (`IPP_TAG_TEXT`), textWithLanguage
+(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
+(`IPP_TAG_URISCHEME`).
+
+The "language" parameter must be non-`NULL` for nameWithLanguage and
+textWithLanguage string values and must be `NULL` for all other string values.
Add a formatted string to an IPP message.
++ipp_attribute_t *ippAddStringf(ipp_t *ipp, ipp_tag_t group, ipp_tag_t value_tag, const char *name, const char *language, const char *format, ...);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| value_tag | +Type of attribute |
| name | +Name of attribute |
| language | +Language code (NULL for default) |
| format | +Printf-style format string |
| ... | +Additional arguments as needed |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document
+(IPP_TAG_DOCUMENT), event notification
+(IPP_TAG_EVENT_NOTIFICATION), operation (IPP_TAG_OPERATION),
+printer (IPP_TAG_PRINTER), subscription (IPP_TAG_SUBSCRIPTION),
+or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
+
+Supported string values include charset (IPP_TAG_CHARSET), keyword
+(IPP_TAG_KEYWORD), language (IPP_TAG_LANGUAGE), mimeMediaType
+(IPP_TAG_MIMETYPE), name (IPP_TAG_NAME), nameWithLanguage
+(IPP_TAG_NAMELANG), text (`IPP_TAG_TEXT`), textWithLanguage
+(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
+(`IPP_TAG_URISCHEME`).
+
+The "language" parameter must be non-`NULL` for nameWithLanguage
+and textWithLanguage string values and must be `NULL` for all other
+string values.
+
+The "format" parameter uses formatting characters compatible with the
+printf family of standard functions. Additional arguments follow it as
+needed. The formatted string is truncated as needed to the maximum length of
+the corresponding value type.
Add a formatted string to an IPP message.
++ipp_attribute_t *ippAddStringfv(ipp_t *ipp, ipp_tag_t group, ipp_tag_t value_tag, const char *name, const char *language, const char *format, va_list ap);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| value_tag | +Type of attribute |
| name | +Name of attribute |
| language | +Language code (NULL for default) |
| format | +Printf-style format string |
| ap | +Additional arguments |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document
+(IPP_TAG_DOCUMENT), event notification
+(IPP_TAG_EVENT_NOTIFICATION), operation (IPP_TAG_OPERATION),
+printer (IPP_TAG_PRINTER), subscription (IPP_TAG_SUBSCRIPTION),
+or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
+
+Supported string values include charset (IPP_TAG_CHARSET), keyword
+(IPP_TAG_KEYWORD), language (IPP_TAG_LANGUAGE), mimeMediaType
+(IPP_TAG_MIMETYPE), name (IPP_TAG_NAME), nameWithLanguage
+(IPP_TAG_NAMELANG), text (`IPP_TAG_TEXT`), textWithLanguage
+(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
+(`IPP_TAG_URISCHEME`).
+
+The "language" parameter must be non-`NULL` for nameWithLanguage
+and textWithLanguage string values and must be `NULL` for all other
+string values.
+
+The "format" parameter uses formatting characters compatible with the
+printf family of standard functions. Additional arguments are passed in the
+stdarg pointer `ap`. The formatted string is truncated as needed to the
+maximum length of the corresponding value type.
Add language-encoded strings to an IPP message.
++ipp_attribute_t *ippAddStrings(ipp_t *ipp, ipp_tag_t group, ipp_tag_t value_tag, const char *name, size_t num_values, const char *language, const char *const *values);
+| ipp | +IPP message |
|---|---|
| group | +IPP group |
| value_tag | +Type of attribute |
| name | +Name of attribute |
| num_values | +Number of values |
| language | +Language code (NULL for default) |
| values | +Values |
New attribute
+The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
+
+Supported string values include charset (IPP_TAG_CHARSET), keyword
+(IPP_TAG_KEYWORD), language (IPP_TAG_LANGUAGE), mimeMediaType
+(IPP_TAG_MIMETYPE), name (IPP_TAG_NAME), nameWithLanguage
+(IPP_TAG_NAMELANG), text (`IPP_TAG_TEXT`), textWithLanguage
+(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
+(`IPP_TAG_URISCHEME`).
+
+The "language" parameter must be non-`NULL` for nameWithLanguage and
+textWithLanguage string values and must be `NULL` for all other string values.
Convert the attribute's value to a string.
++size_t ippAttributeString(ipp_attribute_t *attr, char *buffer, size_t bufsize);
+| attr | +Attribute |
|---|---|
| buffer | +String buffer or NULL |
| bufsize | +Size of string buffer |
Number of bytes less nul
This function converts an attribute's values into a string and returns the
+number of bytes that would be written, not including the trailing nul. The
+buffer pointer can be NULL to get the required length, just like
+(v)snprintf.
Determine whether an attribute contains the + specified value or is within the list of ranges.
++bool ippContainsInteger(ipp_attribute_t *attr, int value);
+| attr | +Attribute |
|---|---|
| value | +Integer/enum value |
true on a match, false on no match
This function returns true when the attribute contains either a matching
+integer or enum value, or the value falls within one of the rangeOfInteger
+values for the attribute.
Determine whether an attribute contains the + specified string value.
++bool ippContainsString(ipp_attribute_t *attr, const char *value);
+| attr | +Attribute |
|---|---|
| value | +String value |
true on a match, false on no match
This function returns true when the attribute contains a matching charset,
+keyword, naturalLanguage, mimeMediaType, name, text, uri, or uriScheme value.
Copy an attribute.
++ipp_attribute_t *ippCopyAttribute(ipp_t *dst, ipp_attribute_t *srcattr, bool quickcopy);
+| dst | +Destination IPP message |
|---|---|
| srcattr | +Attribute to copy |
| quickcopy | +true for a referenced copy, false for a new copy |
New attribute
+This function copies an attribute to another IPP message. When "quickcopy"
+is true, a shallow reference copy of the attribute is created - this should
+only be done as long as the original source IPP message will not be freed for
+the life of the destination.
Copy attributes from one IPP message to another.
++bool ippCopyAttributes(ipp_t *dst, ipp_t *src, bool quickcopy, ipp_copy_cb_t cb, void *cb_data);
+| dst | +Destination IPP message |
|---|---|
| src | +Source IPP message |
| quickcopy | +true for a referenced copy, false for a new copy |
| cb | +Copy callback or NULL for none |
| cb_data | +Callback data pointer |
true on success, false on error
This function copies zero or more attributes from the source to the
+destination IPP message. When "quickcopy" is true, a shallow reference
+copy of the attribute is created - this should only be done as long as the
+original source IPP message will not be freed for the life of the
+destination.
+
+The "cb" and "cb_data" parameters provide a generic way to "filter" the
+attributes that are copied - the function must return true to copy the
+attribute or false to skip it. The function may also choose to do a
+partial copy of the source attribute itself.
Copy a credentials value from an IPP attribute.
++char *ippCopyCredentialsString(ipp_attribute_t *attr);
+| attr | +Attribute |
|---|
Combined string or NULL on error
This function concatenates the 1setOf text credential values of an attribute,
+separated by newlines. The returned string must be freed using the free
+function.
Create a CUPS array of attribute names from the + given requested-attributes attribute.
++cups_array_t *ippCreateRequestedArray(ipp_t *request);
+| request | +IPP request |
|---|
CUPS array or NULL if all
This function creates a (sorted) CUPS array of attribute names matching the
+list of "requested-attribute" values supplied in an IPP request. All IANA-
+registered values are supported in addition to the CUPS IPP extension
+attributes.
+
+The "request" parameter specifies the request message that was read from
+the client.
+
+NULL is returned if all attributes should be returned. Otherwise, the
+result is a sorted array of attribute names, where
+cupsArrayFind(array, "attribute-name") will return a non-NULL pointer. The
+array must be freed using cupsArrayDelete.
Convert from RFC 2579 Date/Time format to time in + seconds.
++time_t ippDateToTime(const ipp_uchar_t *date);
+| date | +RFC 2579 date info |
|---|
UNIX time value
+Delete an IPP message.
++void ippDelete(ipp_t *ipp);
+| ipp | +IPP message |
|---|
Delete a single attribute in an IPP message.
++void ippDeleteAttribute(ipp_t *ipp, ipp_attribute_t *attr);
+| ipp | +IPP message |
|---|---|
| attr | +Attribute to delete |
Delete values in an attribute.
++bool ippDeleteValues(ipp_t *ipp, ipp_attribute_t **attr, size_t element, size_t count);
+| ipp | +IPP message |
|---|---|
| attr | +Attribute |
| element | +Index of first value to delete (0-based) |
| count | +Number of values to delete |
true on success, false on failure
This function deletes one or more values in an attribute. The "element"
+parameter specifies the first value to delete, starting at 0. It must be
+less than the number of values returned by ippGetCount.
+
+The "attr" parameter may be modified as a result of setting the value,
+which will set the variable to NULL.
+
+Deleting all values in an attribute deletes the attribute.
Return a string corresponding to the enum value.
++const char *ippEnumString(const char *attrname, int enumvalue);
+| attrname | +Attribute name |
|---|---|
| enumvalue | +Enum value |
Enum string
+Return the value associated with a given enum string.
++int ippEnumValue(const char *attrname, const char *enumstring);
+| attrname | +Attribute name |
|---|---|
| enumstring | +Enum string |
Enum value or -1 if unknown
Return a name for the given status code.
++const char *ippErrorString(ipp_status_t error);
+| error | +Error status |
|---|
Text string
+Return a status code for the given name.
++ipp_status_t ippErrorValue(const char *name);
+| name | +Name |
|---|
IPP status code
+Close an IPP data file.
++bool ippFileClose(ipp_file_t *file);
+| file | +IPP data file |
|---|
true on success, false on error
This function closes the current IPP data file. The ipp_file_t object can
+be reused for another file as needed.
Close an IPP data file and free all memory.
++bool ippFileDelete(ipp_file_t *file);
+| file | +IPP data file |
|---|
true on success, false on error
This function closes an IPP data file, if necessary, and frees all memory +associated with it.
+Expand IPP data file and environment variables in a string.
++size_t ippFileExpandVars(ipp_file_t *file, char *dst, const char *src, size_t dstsize);
+| file | +IPP data file |
|---|---|
| dst | +Destination buffer |
| src | +Source string |
| dstsize | +Size of destination buffer |
Required size for expanded variables
+This function expands IPP data file variables of the form "$name" and +environment variables of the form "$ENV[name]" in the source string to the +destination string. The
+Get a single named attribute from an IPP data file.
++ipp_attribute_t *ippFileGetAttribute(ipp_file_t *file, const char *name, ipp_tag_t value_tag);
+| file | +IPP data file |
|---|---|
| name | +Attribute name |
| value_tag | +Value tag or IPP_TAG_ZERO for any |
Attribute or NULL if none
This function finds the first occurence of a named attribute in the current
+IPP attributes in the specified data file. Unlike
+ippFileGetAttributes, this function does not clear the attribute
+state.
Get the current set of attributes from an IPP data file.
++ipp_t *ippFileGetAttributes(ipp_file_t *file);
+| file | +IPP data file |
|---|
IPP attributes
+This function gets the current set of attributes from an IPP data file.
+Get the filename for an IPP data file.
++const char *ippFileGetFilename(ipp_file_t *file);
+| file | +IPP data file |
|---|
Filename
+This function returns the filename associated with an IPP data file.
+Get the current line number in an IPP data file.
++int ippFileGetLineNumber(ipp_file_t *file);
+| file | +IPP data file |
|---|
Line number
+This function returns the current line number in an IPP data file.
+Get the value of an IPP data file variable.
++const char *ippFileGetVar(ipp_file_t *file, const char *name);
+| file | +IPP data file |
|---|---|
| name | +Variable name |
Variable value or NULL if none.
This function returns the value of an IPP data file variable. NULL is
+returned if the variable is not set.
Create a new IPP data file object for reading or writing.
++ipp_file_t *ippFileNew(ipp_file_t *parent, ipp_fattr_cb_t attr_cb, ipp_ferror_cb_t error_cb, void *cb_data);
+| parent | +Parent data file or NULL for none |
|---|---|
| attr_cb | +Attribute filtering callback, if any |
| error_cb | +Error reporting callback, if any |
| cb_data | +Callback data, if any |
IPP data file
+This function opens an IPP data file for reading (mode="r") or writing
+(mode="w"). If the "parent" argument is not NULL, all variables from the
+parent data file are copied to the new file.
Open an IPP data file for reading or writing.
++bool ippFileOpen(ipp_file_t *file, const char *filename, const char *mode);
+| file | +IPP data file |
|---|---|
| filename | +Filename to open |
| mode | +Open mode - "r" to read and "w" to write |
true on success, false on error
This function opens an IPP data file for reading (mode="r") or writing
+(mode="w"). If the "parent" argument is not NULL, all variables from the
+parent data file are copied to the new file.
Read an IPP data file.
++bool ippFileRead(ipp_file_t *file, ipp_ftoken_cb_t token_cb, bool with_groups);
+| file | +IPP data file |
|---|---|
| token_cb | +Token callback |
| with_groups | +Read attributes with GROUP directives |
true on success, false on error
Read a collection from an IPP data file.
++ipp_t *ippFileReadCollection(ipp_file_t *file);
+| file | +IPP data file |
|---|
Collection value
+This function reads a collection value from an IPP data file. Collection +values are surrounded by curly braces ("{" and "}") and have "MEMBER" +directives to define member attributes in the collection.
+Read a token from an IPP data file.
++bool ippFileReadToken(ipp_file_t *file, char *token, size_t tokensize);
+| file | +IPP data file |
|---|---|
| token | +Token buffer |
| tokensize | +Size of token buffer |
true on success, false on error
This function reads a single token or value from an IPP data file, skipping +comments and whitespace as needed.
+Restore the previous position in an IPP data file.
++bool ippFileRestorePosition(ipp_file_t *file);
+| file | +IPP data file |
|---|
true on success, false on failure
This function restores the previous position in an IPP data file that is open +for reading.
+Save the current position in an IPP data file.
++bool ippFileSavePosition(ipp_file_t *file);
+| file | +IPP data file |
|---|
true on success, false on failure
This function saves the current position in an IPP data file that is open +for reading.
+Set the attributes for an IPP data file.
++bool ippFileSetAttributes(ipp_file_t *file, ipp_t *attrs);
+| file | +IPP data file |
|---|---|
| attrs | +IPP attributes |
true on success, false otherwise
This function sets the current set of attributes for an IPP data file,
+typically an empty collection created with ippNew.
Set the group tag for an IPP data file.
++bool ippFileSetGroupTag(ipp_file_t *file, ipp_tag_t group_tag);
+| file | +IPP data file |
|---|---|
| group_tag | +Group tag |
true on success, false otherwise
This function sets the group tag associated with attributes that are read +from an IPP data file.
+Set an IPP data file variable to a constant value.
++bool ippFileSetVar(ipp_file_t *file, const char *name, const char *value);
+| file | +IPP data file |
|---|---|
| name | +Variable name |
| value | +Value |
true on success, false on failure
This function sets an IPP data file variable to a constant value. Setting +the "uri" variable also initializes the "scheme", "uriuser", "hostname", +"port", and "resource" variables.
+Set an IPP data file variable to a formatted value.
++bool ippFileSetVarf(ipp_file_t *file, const char *name, const char *value, ...);
+| file | +IPP data file |
|---|---|
| name | +Variable name |
| value | +Printf-style value |
| ... | +Additional arguments as needed |
true on success, false on error
This function sets an IPP data file variable to a formatted value. Setting +the "uri" variable also initializes the "scheme", "uriuser", "hostname", +"port", and "resource" variables.
+Write an IPP message to an IPP data file.
++bool ippFileWriteAttributes(ipp_file_t *file, ipp_t *ipp, bool with_groups);
+| file | +IPP data file |
|---|---|
| ipp | +IPP attributes to write |
| with_groups | +true to include GROUPs, false otherwise |
true on success, false on error
This function writes an IPP message to an IPP data file using the attribute
+filter specified in the call to ippFileOpen. If "with_group" is
+true, "GROUP" directives are written as necessary to place the attributes
+in the correct groups.
Write a comment to an IPP data file.
++bool ippFileWriteComment(ipp_file_t *file, const char *comment, ...);
+| file | +IPP data file |
|---|---|
| comment | +Printf-style comment string |
| ... | +Additional arguments as needed |
true on success, false on error
This function writes a comment to an IPP data file. Every line in the string +is prefixed with the "#" character and indented as needed.
+Write a token or value string to an IPP data file.
++bool ippFileWriteToken(ipp_file_t *file, const char *token);
+| file | +IPP data file |
|---|---|
| token | +Token/value string |
true on success, false on error
This function writes a token or value string to an IPP data file, quoting +and indenting the string as needed.
+Write a formatted token or value string to an IPP data file.
++bool ippFileWriteTokenf(ipp_file_t *file, const char *token, ...);
+| file | +IPP data file |
|---|---|
| token | +Printf-style token/value string |
| ... | +Additional arguments as needed |
true on success, false on error
This function writes a formatted token or value string to an IPP data file, +quoting and indenting the string as needed.
+Find a named attribute in an IPP message.
++ipp_attribute_t *ippFindAttribute(ipp_t *ipp, const char *name, ipp_tag_t type);
+| ipp | +IPP message |
|---|---|
| name | +Name of attribute |
| type | +Type of attribute |
Matching attribute
+This function finds the first occurrence of a named attribute in an IPP +message. The attribute name can contain a hierarchical list of attribute and +member names separated by slashes, for example "media-col/media-size".
+Find the next named attribute in an IPP message.
++ipp_attribute_t *ippFindNextAttribute(ipp_t *ipp, const char *name, ipp_tag_t type);
+| ipp | +IPP message |
|---|---|
| name | +Name of attribute |
| type | +Type of attribute |
Matching attribute
+This function finds the next named attribute in an IPP message. The +attribute name can contain a hierarchical list of attribute and member names +separated by slashes, for example "media-col/media-size".
+Get a boolean value for an attribute.
++bool ippGetBoolean(ipp_attribute_t *attr, size_t element);
+| attr | +IPP attribute |
|---|---|
| element | +Value number (0-based) |
Boolean value or false on error
The "element" parameter specifies which value to get from 0 to
+ippGetCount(attr) - 1.
Get a collection value for an attribute.
++ipp_t *ippGetCollection(ipp_attribute_t *attr, size_t element);
+| attr | +IPP attribute |
|---|---|
| element | +Value number (0-based) |
Collection value or NULL on error
The "element" parameter specifies which value to get from 0 to
+ippGetCount(attr) - 1.
Get the number of values in an attribute.
++size_t ippGetCount(ipp_attribute_t *attr);
+| attr | +IPP attribute |
|---|
Number of values or 0 on error
+Get a dateTime value for an attribute.
++const ipp_uchar_t *ippGetDate(ipp_attribute_t *attr, size_t element);
+| attr | +IPP attribute |
|---|---|
| element | +Value number (0-based) |
dateTime value or NULL
The "element" parameter specifies which value to get from 0 to
+ippGetCount(attr) - 1.
Return the first attribute in the message.
++ipp_attribute_t *ippGetFirstAttribute(ipp_t *ipp);
+| ipp | +IPP message |
|---|
First attribute or NULL if none
Get the group associated with an attribute.
++ipp_tag_t ippGetGroupTag(ipp_attribute_t *attr);
+| attr | +IPP attribute |
|---|
Group tag or IPP_TAG_ZERO on error
Get the integer/enum value for an attribute.
++int ippGetInteger(ipp_attribute_t *attr, size_t element);
+| attr | +IPP attribute |
|---|---|
| element | +Value number (0-based) |
Value or 0 on error
The "element" parameter specifies which value to get from 0 to
+ippGetCount(attr) - 1.
Compute the length of an IPP message.
++size_t ippGetLength(ipp_t *ipp);
+| ipp | +IPP message |
|---|
Size of IPP message
+Get the attribute name.
++const char *ippGetName(ipp_attribute_t *attr);
+| attr | +IPP attribute |
|---|
Attribute name or NULL for separators
Return the next attribute in the message.
++ipp_attribute_t *ippGetNextAttribute(ipp_t *ipp);
+| ipp | +IPP message |
|---|
Next attribute or NULL if none
Get an octetString value from an IPP attribute.
++void *ippGetOctetString(ipp_attribute_t *attr, size_t element, size_t *datalen);
+| attr | +IPP attribute |
|---|---|
| element | +Value number (0-based) |
| datalen | +Length of octetString data |
Pointer to octetString data
+The "element" parameter specifies which value to get from '0' to
+ippGetCount(attr) - 1.
Get the operation ID in an IPP message.
++ipp_op_t ippGetOperation(ipp_t *ipp);
+| ipp | +IPP request message |
|---|
Operation ID or 0 on error
+Return the default IPP port number.
++int ippGetPort(void);
+Port number
+Get a rangeOfInteger value from an attribute.
++int ippGetRange(ipp_attribute_t *attr, size_t element, int *uppervalue);
+| attr | +IPP attribute |
|---|---|
| element | +Value number (0-based) |
| uppervalue | +Upper value of range |
Lower value of range or 0
+The "element" parameter specifies which value to get from 0 to
+ippGetCount(attr) - 1.
Get the request ID from an IPP message.
++int ippGetRequestId(ipp_t *ipp);
+| ipp | +IPP message |
|---|
Request ID or 0 on error
+Get a resolution value for an attribute.
++int ippGetResolution(ipp_attribute_t *attr, size_t element, int *yres, ipp_res_t *units);
+| attr | +IPP attribute |
|---|---|
| element | +Value number (0-based) |
| yres | +Vertical/feed resolution |
| units | +Units for resolution |
Horizontal/cross feed resolution or 0
+The "element" parameter specifies which value to get from 0 to
+ippGetCount(attr) - 1.
Get the IPP message state.
++ipp_state_t ippGetState(ipp_t *ipp);
+| ipp | +IPP message |
|---|
IPP message state value
+Get the status code from an IPP response or event message.
++ipp_status_t ippGetStatusCode(ipp_t *ipp);
+| ipp | +IPP response or event message |
|---|
Status code in IPP message
++const char *ippGetString(ipp_attribute_t *attr, size_t element, const char **language);
+| attr | +IPP attribute |
|---|---|
| element | +Value number (0-based) |
| language | +Language code (NULL for don't care) |
Get the string and optionally the language code for an attribute.
+The "element" parameter specifies which value to get from 0 to
+ippGetCount(attr) - 1.
Get the value tag for an attribute.
++ipp_tag_t ippGetValueTag(ipp_attribute_t *attr);
+| attr | +IPP attribute |
|---|
Value tag or IPP_TAG_ZERO on error
Get the major and minor version number from an IPP message.
++int ippGetVersion(ipp_t *ipp, int *minor);
+| ipp | +IPP message |
|---|---|
| minor | +Minor version number or NULL for don't care |
Major version number or 0 on error
+Allocate a new IPP message.
++ipp_t *ippNew(void);
+New IPP message
+Allocate a new IPP request message.
++ipp_t *ippNewRequest(ipp_op_t op);
+| op | +Operation code |
|---|
IPP request message
+The new request message is initialized with the "attributes-charset" and +"attributes-natural-language" attributes added. The +"attributes-natural-language" value is derived from the current locale.
+Allocate a new IPP response message.
++ipp_t *ippNewResponse(ipp_t *request);
+| request | +IPP request message |
|---|
IPP response message
+The new response message is initialized with the same "version-number", +"request-id", "attributes-charset", and "attributes-natural-language" as the +provided request message. If the "attributes-charset" or +"attributes-natural-language" attributes are missing from the request, +'utf-8' and a value derived from the current locale are substituted, +respectively.
+Return a name for the given operation id.
++const char *ippOpString(ipp_op_t op);
+| op | +Operation ID |
|---|
Name
+Return an operation id for the given name.
++ipp_op_t ippOpValue(const char *name);
+| name | +Textual name |
|---|
Operation ID
+Read data for an IPP message from a HTTP connection.
++ipp_state_t ippRead(http_t *http, ipp_t *ipp);
+| http | +HTTP connection |
|---|---|
| ipp | +IPP data |
Current state
+Read data for an IPP message from a file.
++ipp_state_t ippReadFile(int fd, ipp_t *ipp);
+| fd | +HTTP data |
|---|---|
| ipp | +IPP data |
Current state
+Read data for an IPP message.
++ipp_state_t ippReadIO(void *src, ipp_io_cb_t cb, bool blocking, ipp_t *parent, ipp_t *ipp);
+| src | +Data source |
|---|---|
| cb | +Read callback function |
| blocking | +Use blocking IO? |
| parent | +Parent request, if any |
| ipp | +IPP data |
Current state
+Restore a previously saved find position.
++void ippRestore(ipp_t *ipp);
+| ipp | +IPP message |
|---|
Save the current find position.
++void ippSave(ipp_t *ipp);
+| ipp | +IPP message |
|---|
Set a boolean value in an attribute.
++bool ippSetBoolean(ipp_t *ipp, ipp_attribute_t **attr, size_t element, bool boolvalue);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| element | +Value number (0-based) |
| boolvalue | +Boolean value |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+The "element" parameter specifies which value to set from 0 to
+ippGetCount(attr).
Set a collection value in an attribute.
++bool ippSetCollection(ipp_t *ipp, ipp_attribute_t **attr, size_t element, ipp_t *colvalue);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| element | +Value number (0-based) |
| colvalue | +Collection value |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+The "element" parameter specifies which value to set from 0 to
+ippGetCount(attr).
Set a dateTime value in an attribute.
++bool ippSetDate(ipp_t *ipp, ipp_attribute_t **attr, size_t element, const ipp_uchar_t *datevalue);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| element | +Value number (0-based) |
| datevalue | +dateTime value |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+The "element" parameter specifies which value to set from 0 to
+ippGetCount(attr).
Set the group tag of an attribute.
++bool ippSetGroupTag(ipp_t *ipp, ipp_attribute_t **attr, ipp_tag_t group_tag);
+| ipp | +IPP message |
|---|---|
| attr | +Attribute |
| group_tag | +Group tag |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+The "group" parameter specifies the IPP attribute group tag: none
+(IPP_TAG_ZERO, for member attributes), document (IPP_TAG_DOCUMENT),
+event notification (IPP_TAG_EVENT_NOTIFICATION), operation
+(IPP_TAG_OPERATION), printer (IPP_TAG_PRINTER), subscription
+(IPP_TAG_SUBSCRIPTION), or unsupported (IPP_TAG_UNSUPPORTED_GROUP).
Set an integer or enum value in an attribute.
++bool ippSetInteger(ipp_t *ipp, ipp_attribute_t **attr, size_t element, int intvalue);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| element | +Value number (0-based) |
| intvalue | +Integer/enum value |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+The "element" parameter specifies which value to set from 0 to
+ippGetCount(attr).
Set the name of an attribute.
++bool ippSetName(ipp_t *ipp, ipp_attribute_t **attr, const char *name);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| name | +Attribute name |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
Set an octetString value in an IPP attribute.
++bool ippSetOctetString(ipp_t *ipp, ipp_attribute_t **attr, size_t element, const void *data, size_t datalen);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| element | +Value number (0-based) |
| data | +Pointer to octetString data |
| datalen | +Length of octetString data |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+The "element" parameter specifies which value to set from 0 to
+ippGetCount(attr).
Set the operation ID in an IPP request message.
++bool ippSetOperation(ipp_t *ipp, ipp_op_t op);
+| ipp | +IPP request message |
|---|---|
| op | +Operation ID |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
Set the default port number.
++void ippSetPort(int p);
+| p | +Port number to use |
|---|
Set a rangeOfInteger value in an attribute.
++bool ippSetRange(ipp_t *ipp, ipp_attribute_t **attr, size_t element, int lowervalue, int uppervalue);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| element | +Value number (0-based) |
| lowervalue | +Lower bound for range |
| uppervalue | +Upper bound for range |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+The "element" parameter specifies which value to set from 0 to
+ippGetCount(attr).
Set the request ID in an IPP message.
++bool ippSetRequestId(ipp_t *ipp, int request_id);
+| ipp | +IPP message |
|---|---|
| request_id | +Request ID |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "request_id" parameter must be greater than 0.
Set a resolution value in an attribute.
++bool ippSetResolution(ipp_t *ipp, ipp_attribute_t **attr, size_t element, ipp_res_t unitsvalue, int xresvalue, int yresvalue);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| element | +Value number (0-based) |
| unitsvalue | +Resolution units |
| xresvalue | +Horizontal/cross feed resolution |
| yresvalue | +Vertical/feed resolution |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+The "element" parameter specifies which value to set from 0 to
+ippGetCount(attr).
Set the current state of the IPP message.
++bool ippSetState(ipp_t *ipp, ipp_state_t state);
+| ipp | +IPP message |
|---|---|
| state | +IPP state value |
true on success, false on failure
Set the status code in an IPP response or event message.
++bool ippSetStatusCode(ipp_t *ipp, ipp_status_t status);
+| ipp | +IPP response or event message |
|---|---|
| status | +Status code |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
Set a string value in an attribute.
++bool ippSetString(ipp_t *ipp, ipp_attribute_t **attr, size_t element, const char *strvalue);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| element | +Value number (0-based) |
| strvalue | +String value |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+The "element" parameter specifies which value to set from 0 to
+ippGetCount(attr).
Set a formatted string value of an attribute.
++bool ippSetStringf(ipp_t *ipp, ipp_attribute_t **attr, size_t element, const char *format, ...);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| element | +Value number (0-based) |
| format | +Printf-style format string |
| ... | +Additional arguments as needed |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+The "element" parameter specifies which value to set from 0 to
+ippGetCount(attr).
+
+The "format" parameter uses formatting characters compatible with the
+printf family of standard functions. Additional arguments follow it as
+needed. The formatted string is truncated as needed to the maximum length of
+the corresponding value type.
Set a formatted string value of an attribute.
++bool ippSetStringfv(ipp_t *ipp, ipp_attribute_t **attr, size_t element, const char *format, va_list ap);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| element | +Value number (0-based) |
| format | +Printf-style format string |
| ap | +Pointer to additional arguments |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+The "element" parameter specifies which value to set from 0 to
+ippGetCount(attr).
+
+The "format" parameter uses formatting characters compatible with the
+printf family of standard functions. Additional arguments follow it as
+needed. The formatted string is truncated as needed to the maximum length of
+the corresponding value type.
Set the value tag of an attribute.
++bool ippSetValueTag(ipp_t *ipp, ipp_attribute_t **attr, ipp_tag_t value_tag);
+| ipp | +IPP message |
|---|---|
| attr | +IPP attribute |
| value_tag | +Value tag |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The "attr" parameter may be modified as a result of setting the value.
+
+Integer (IPP_TAG_INTEGER) values can be promoted to rangeOfInteger
+(IPP_TAG_RANGE) values, the various string tags can be promoted to name
+(IPP_TAG_NAME) or nameWithLanguage (IPP_TAG_NAMELANG) values, text
+(IPP_TAG_TEXT) values can be promoted to textWithLanguage
+(IPP_TAG_TEXTLANG) values, and all values can be demoted to the various
+out-of-band value tags such as no-value (IPP_TAG_NOVALUE). All other changes
+will be rejected.
+
+Promoting a string attribute to nameWithLanguage or textWithLanguage adds the language
+code in the "attributes-natural-language" attribute or, if not present, the language
+code for the current locale.
Set the version number in an IPP message.
++bool ippSetVersion(ipp_t *ipp, int major, int minor);
+| ipp | +IPP message |
|---|---|
| major | +Major version number (major.minor) |
| minor | +Minor version number (major.minor) |
true on success, false on failure
The "ipp" parameter refers to an IPP message previously created using
+the ippNew, ippNewRequest, or ippNewResponse functions.
+
+The valid version numbers are currently 1.0, 1.1, 2.0, 2.1, and 2.2.
Return the name corresponding to a state value.
++const char *ippStateString(ipp_state_t state);
+| state | +State value |
|---|
State name
+Return the tag name corresponding to a tag value.
++const char *ippTagString(ipp_tag_t tag);
+| tag | +Tag value |
|---|
Tag name
+The returned names are defined in RFC 8011 and the IANA IPP Registry. +/
+Return the tag value corresponding to a tag name.
++ipp_tag_t ippTagValue(const char *name);
+| name | +Tag name |
|---|
Tag value
+The tag names are defined in RFC 8011 and the IANA IPP Registry.
+Convert from time in seconds to RFC 2579 format.
++const ipp_uchar_t *ippTimeToDate(time_t t);
+| t | +Time in seconds |
|---|
RFC-2579 date/time data
+Validate the contents of an attribute.
++bool ippValidateAttribute(ipp_attribute_t *attr);
+| attr | +Attribute |
|---|
true if valid, false otherwise
This function validates the contents of an attribute based on the name and
+value tag. true is returned if the attribute is valid, false otherwise.
+On failure, cupsGetErrorString is set to a human-readable message.
Validate all attributes in an IPP message.
++bool ippValidateAttributes(ipp_t *ipp);
+| ipp | +IPP message |
|---|
true if valid, false otherwise
This function validates the contents of the IPP message, including each
+attribute. Like ippValidateAttribute, cupsGetErrorString is
+set to a human-readable message on failure.
Write data for an IPP message to a HTTP connection.
++ipp_state_t ippWrite(http_t *http, ipp_t *ipp);
+| http | +HTTP connection |
|---|---|
| ipp | +IPP data |
Current state
+Write data for an IPP message to a file.
++ipp_state_t ippWriteFile(int fd, ipp_t *ipp);
+| fd | +HTTP data |
|---|---|
| ipp | +IPP data |
Current state
+Write data for an IPP message.
++ipp_state_t ippWriteIO(void *dst, ipp_io_cb_t cb, bool blocking, ipp_t *parent, ipp_t *ipp);
+| dst | +Destination |
|---|---|
| cb | +Write callback function |
| blocking | +Use blocking IO? |
| parent | +Parent IPP message |
| ipp | +IPP data |
Current state
+Generate a PWG self-describing media size name.
++bool pwgFormatSizeName(char *keyword, size_t keysize, const char *prefix, const char *name, int width, int length, const char *units);
+| keyword | +Keyword buffer |
|---|---|
| keysize | +Size of keyword buffer |
| prefix | +Prefix for PWG size or NULL for automatic |
| name | +Size name or NULL |
| width | +Width of page in 2540ths |
| length | +Length of page in 2540ths |
| units | +Units - "in", "mm", or NULL for automatic |
true on success, false on failure
This function generates a PWG self-describing media size name of the form
+"prefix_name_WIDTHxLENGTHunits". The prefix is typically "custom" or "roll"
+for user-supplied sizes but can also be "disc", "iso", "jis", "jpn", "na",
+"oe", "om", "prc", or "roc". A value of NULL automatically chooses
+"oe" or "om" depending on the units.
+
+The size name may only contain lowercase letters, numbers, "-", and ".". If
+NULL is passed, the size name will contain the formatted dimensions.
+
+The width and length are specified in hundredths of millimeters, equivalent
+to 1/100000th of a meter or 1/2540th of an inch. The width, length, and
+units used for the generated size name are calculated automatically if the
+units string is NULL, otherwise inches ("in") or millimeters ("mm")
+are used.
Initialize a pwg_size_t structure using IPP Job Template + attributes.
++bool pwgInitSize(pwg_size_t *size, ipp_t *job, bool *margins_set);
+| size | +Size to initialize |
|---|---|
| job | +Job template attributes |
| margins_set | +true if margins were set, false otherwise |
true on success, false on failure
This function initializes a pwg_size_t structure from an IPP "media" or
+"media-col" attribute in the specified IPP message. 0 is returned if neither
+attribute is found in the message or the values are not valid.
+
+The "margins_set" variable is initialized to 1 if any "media-xxx-margin"
+member attribute was specified in the "media-col" Job Template attribute,
+otherwise it is initialized to 0.
Find a PWG media size by ISO/IPP legacy name.
++pwg_media_t *pwgMediaForLegacy(const char *legacy);
+| legacy | +Legacy size name |
|---|
Matching size or NULL
+The "name" argument specifies the legacy ISO media size name, for example +"iso-a4" or "na-letter".
+Find a PWG media size by Adobe PPD name.
++pwg_media_t *pwgMediaForPPD(const char *ppd);
+| ppd | +PPD size name |
|---|
Matching size or NULL
+The "ppd" argument specifies an Adobe page size name as defined in Table B.1
+of the Adobe PostScript Printer Description File Format Specification Version
+4.3.
+
+If the name is non-standard, the returned PWG media size is stored in
+thread-local storage and is overwritten by each call to the function in the
+thread. Custom names can be of the form "Custom.WIDTHxLENGTH[units]" or
+"WIDTHxLENGTH[units]".
Find a PWG media size by 5101.1 self-describing name.
++pwg_media_t *pwgMediaForPWG(const char *pwg);
+| pwg | +PWG size name |
|---|
Matching size or NULL
+The "pwg" argument specifies a self-describing media size name of the form
+"prefix_name_WIDTHxLENGTHunits" as defined in PWG 5101.1.
+
+If the name is non-standard, the returned PWG media size is stored in
+thread-local storage and is overwritten by each call to the function in the
+thread.
Get the PWG media size for the given dimensions.
++pwg_media_t *pwgMediaForSize(int width, int length);
+| width | +Width in hundredths of millimeters |
|---|---|
| length | +Length in hundredths of millimeters |
PWG media name
+The "width" and "length" are in hundredths of millimeters, equivalent to
+1/100000th of a meter or 1/2540th of an inch.
+
+If the dimensions are non-standard, the returned PWG media size is stored in
+thread-local storage and is overwritten by each call to the function in the
+thread.
Array element copy function
++typedef void *(*)(void *element, void *data)cups_acopy_cb_t; +
+AdvanceMedia attribute values
++typedef enum cups_adv_e cups_adv_t; +
+Array element free function
++typedef void(*)(void *element, void *data)cups_afree_cb_t; +
+Array hash function
++typedef size_t(*)(void *element, void *data)cups_ahash_cb_t; +
+Array comparison function
++typedef int(*)(void *first, void *second, void *data)cups_array_cb_t; +
+CUPS array type
++typedef struct _cups_array_s cups_array_t; +
+Boolean type
++typedef enum cups_bool_e cups_bool_t; +
+Certificate signing subjectAltName callback
++typedef bool(*)(const char *common_name, const char *subject_alt_name, void *user_data)cups_cert_san_cb_t; +
+Client credentials callback
++typedef bool(*)(http_t *http, void *tls, cups_array_t *distinguished_names, void *user_data)cups_client_cert_cb_t; +
+Condition variable
++typedef pthread_cond_t cups_cond_t; +
+Combined X.509 credential purposes for cupsCreateCredentials and cupsCreateCredentialsRequest
+typedef unsigned cups_credpurpose_t; +
+X.509 credential types for cupsCreateCredentials and cupsCreateCredentialsRequest
+typedef enum cups_credtype_e cups_credtype_t; +
+Combined X.509 keyUsage flags for cupsCreateCredentials and cupsCreateCredentialsRequest
+typedef unsigned cups_credusage_t; +
+cupsColorSpace attribute values
++typedef enum cups_cspace_e cups_cspace_t; +
+CutMedia attribute values
++typedef enum cups_cut_e cups_cut_t; +
+Directory entry type
++typedef struct cups_dentry_s cups_dentry_t; +
+Destination enumeration callback
++typedef bool(*)(void *user_data, cups_dest_flags_t flags, cups_dest_t *dest)cups_dest_cb_t; +
+Combined flags for cupsConnectDest and cupsEnumDests
+typedef unsigned cups_dest_flags_t; +
+Destination
++typedef struct cups_dest_s cups_dest_t; +
+Destination capability and status information
++typedef struct _cups_dinfo_s cups_dinfo_t; +
+Directory type
++typedef struct _cups_dir_s cups_dir_t; +
+DNS-SD browse callback
++typedef void(*)(cups_dnssd_browse_t *browse, void *cb_data, cups_dnssd_flags_t flags, uint32_t if_index, const char *name, const char *regtype, const char *domain)cups_dnssd_browse_cb_t; +
+DNS-SD error callback
++typedef void(*)(void *cb_data, const char *message)cups_dnssd_error_cb_t; +
+DNS-SD callback flag bitmask
++typedef unsigned cups_dnssd_flags_t; +
+DNS-SD query callback
++typedef void(*)(cups_dnssd_query_t *query, void *cb_data, cups_dnssd_flags_t flags, uint32_t if_index, const char *fullname, uint16_t rrtype, const void *qdata, uint16_t qlen) cups_dnssd_query_cb_t; +
+DNS query request
++typedef struct _cups_dnssd_query_s cups_dnssd_query_t; +
+DNS-SD resolve callback
++typedef void(*)(cups_dnssd_resolve_t *res, void *cb_data, cups_dnssd_flags_t flags, uint32_t if_index, const char *fullname, const char *host, uint16_t port, size_t num_txt, cups_option_t *txt)cups_dnssd_resolve_cb_t; +
+DNS resolve request
++typedef struct _cups_dnssd_resolve_s cups_dnssd_resolve_t; +
+DNS record type values
++typedef typedef struct _cups_dnssd_browse_s cups_dnssd_browse_t; +
+DNS-SD service registration callback
++typedef void(*)(cups_dnssd_service_t *service, void *cb_data, cups_dnssd_flags_t flags) cups_dnssd_service_cb_t; +
+DNS service registration
++typedef struct _cups_dnssd_service_s cups_dnssd_service_t; +
+DNS-SD context
++typedef struct _cups_dnssd_s cups_dnssd_t; +
+LeadingEdge attribute values
++typedef enum cups_edge_e cups_edge_t; +
+Language Encodings
++typedef typedef unsigned long cups_utf32_t; +
+CUPS file type
++typedef struct _cups_file_s cups_file_t; +
+Job
++typedef struct cups_job_s cups_job_t; +
+Jog attribute values
++typedef enum cups_jog_e cups_jog_t; +
+JSON node
++typedef struct _cups_json_s cups_json_t; +
+JSON node type
++typedef enum cups_jtype_e cups_jtype_t; +
+JSON Web Algorithms
++typedef enum cups_jwa_e cups_jwa_t; +
+JSON Web Signature Formats
++typedef enum cups_jws_format_e cups_jws_format_t; +
+JSON Web Token
++typedef struct _cups_jwt_s cups_jwt_t; +
+Language Cache
++typedef struct _cups_lang_s cups_lang_t; +
+Combined flags for cupsGetDestMediaByName and cupsGetDestMediaBySize
+typedef unsigned cups_media_flags_t; +
+MediaPosition values
++typedef enum cups_mediapos_e cups_mediapos_t; +
+Mutual exclusion lock
++typedef pthread_mutex_t cups_mutex_t; +
+OAuth callback
++typedef const char *(*)(http_t *http, const char *realm, const char *scope, const char *resource, void *user_data)cups_oauth_cb_t; +
+Printer Options
++typedef struct cups_option_s cups_option_t; +
+cupsColorOrder attribute values
++typedef enum cups_order_e cups_order_t; +
+Orientation attribute values
++typedef enum cups_orient_e cups_orient_t; +
+Version 2 page header
++typedef struct cups_page_header_s cups_page_header_t; +
+New password callback
++typedef const char *(*)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data)cups_password_cb_t; +
+Combined printer type/capability flags
++typedef unsigned cups_ptype_t; +
+cupsRasterOpen modes
++typedef enum cups_raster_mode_e cups_raster_mode_t; +
+Raster stream data
++typedef struct _cups_raster_s cups_raster_t; +
+Reader/writer lock
++typedef pthread_rwlock_t cups_rwlock_t; +
+Server credentials callback
++typedef bool(*)(http_t *http, void *tls, cups_array_t *certs, void *user_data)cups_server_cert_cb_t; +
+Media information
++typedef struct cups_size_s cups_size_t; +
+Thread function
++typedef void *(*)(void *arg)cups_thread_func_t; +
+Thread data key
++typedef pthread_key_t cups_thread_key_t; +
+Thread identifier
++typedef pthread_t cups_thread_t; +
+Which jobs for cupsGetJobs
+typedef enum cups_whichjobs_e cups_whichjobs_t; +
+Socket address union
++typedef union _http_addr_u http_addr_t; +
+Socket address list, which is used to enumerate all of the addresses that are associated with a hostname.
++typedef struct http_addrlist_s http_addrlist_t; +
+HTTP transfer encoding values
++typedef enum http_encoding_e http_encoding_t; +
+HTTP encryption values
++typedef enum http_encryption_e http_encryption_t; +
+HTTP field names
++typedef enum http_field_e http_field_t; +
+HTTP keep-alive values
++typedef enum http_keepalive_e http_keepalive_t; +
+httpResolveURI callback
+typedef bool(*)(void *data)http_resolve_cb_t; +
+httpResolveURI options bitfield
+typedef unsigned http_resolve_t; +
+HTTP state values; states are server-oriented...
++typedef enum http_state_e http_state_t; +
+HTTP status codes
++typedef enum http_status_e http_status_t; +
+HTTP connection type
++typedef struct _http_s http_t; +
+HTTP timeout callback
++typedef bool(*)(http_t *http, void *user_data)http_timeout_cb_t; +
+Level of trust for credentials
++typedef enum http_trust_e http_trust_t; +
+URI en/decode flags
++typedef enum http_uri_coding_e http_uri_coding_t; +
+URI separation status
++typedef enum http_uri_status_e http_uri_status_t; +
+IPP attribute
++typedef struct _ipp_attribute_s ipp_attribute_t; +
+ippCopyAttributes callback function
++typedef bool(*)(void *context, ipp_t *dst, ipp_attribute_t *attr)ipp_copy_cb_t; +
+"document-state" values
++typedef enum ipp_dstate_e ipp_dstate_t; +
+IPP data file attribute callback
++typedef bool(*)(ipp_file_t *file, void *cb_data, const char *name)ipp_fattr_cb_t; +
+IPP data file error callback
++typedef bool(*)(ipp_file_t *file, void *cb_data, const char *error)ipp_ferror_cb_t; +
+IPP data file
++typedef struct _ipp_file_s ipp_file_t; +
+IPP data file token callback
++typedef bool(*)(ipp_file_t *file, void *cb_data, const char *token)ipp_ftoken_cb_t; +
+ippReadIO/ippWriteIO callback function
++typedef ssize_t(*)(void *context, ipp_uchar_t *buffer, size_t bytes) ipp_io_cb_t; +
+"job-state" values
++typedef enum ipp_jstate_e ipp_jstate_t; +
+IPP operations
++typedef enum ipp_op_e ipp_op_t; +
+"orientation-requested" values
++typedef enum ipp_orient_e ipp_orient_t; +
+"printer-state" values
++typedef enum ipp_pstate_e ipp_pstate_t; +
+"print-quality" values
++typedef enum ipp_quality_e ipp_quality_t; +
+Resolution units
++typedef enum ipp_res_e ipp_res_t; +
+"resource-state" values
++typedef enum ipp_rstate_e ipp_rstate_t; +
+"system-state" values
++typedef enum ipp_sstate_e ipp_sstate_t; +
+ipp_t state values
+typedef enum ipp_state_e ipp_state_t; +
+IPP request/response data
++typedef struct _ipp_s ipp_t; +
+Unsigned 8-bit integer/character
++typedef unsigned char ipp_uchar_t; +
+Common media size data
++typedef struct pwg_media_s pwg_media_t; +
+Directory entry type
+struct cups_dentry_s {
+ struct stat fileinfo;
+ char filename[260];
+};
| fileinfo | +File information |
|---|---|
| filename[260] | +File name |
Destination
+struct cups_dest_s {
+ char *name, *instance;
+ bool is_default;
+ size_t num_options;
+ cups_option_t *options;
+};
| instance | +Local instance name or NULL |
|---|---|
| is_default | +Is this printer the default? |
| num_options | +Number of options |
| options | +Options |
Job
+struct cups_job_s {
+ time_t completed_time;
+ time_t creation_time;
+ char *dest;
+ char *format;
+ int id;
+ int priority;
+ time_t processing_time;
+ int size;
+ ipp_jstate_t state;
+ char *title;
+ char *user;
+};
| completed_time | +Time the job was completed |
|---|---|
| creation_time | +Time the job was created |
| dest | +Printer or class name |
| format | +Document format |
| id | +The job ID |
| priority | +Priority (1-100) |
| processing_time | +Time the job was processed |
| size | +Size in kilobytes |
| state | +Job state |
| title | +Title/job name |
| user | +User that submitted the job |
Printer Options
+struct cups_option_s {
+ char *name;
+ char *value;
+};
| name | +Name of option |
|---|---|
| value | +Value of option |
Version 2 page header
+struct cups_page_header_s {
+ unsigned AdvanceDistance;
+ cups_adv_t AdvanceMedia;
+ cups_bool_t Collate;
+ cups_cut_t CutMedia;
+ cups_bool_t Duplex;
+ unsigned HWResolution[2];
+ unsigned ImagingBoundingBox[4];
+ cups_bool_t InsertSheet;
+ cups_jog_t Jog;
+ cups_edge_t LeadingEdge;
+ cups_bool_t ManualFeed;
+ unsigned Margins[2];
+ char MediaClass[64];
+ char MediaColor[64];
+ unsigned MediaPosition;
+ char MediaType[64];
+ unsigned MediaWeight;
+ cups_bool_t MirrorPrint;
+ cups_bool_t NegativePrint;
+ unsigned NumCopies;
+ cups_orient_t Orientation;
+ cups_bool_t OutputFaceUp;
+ char OutputType[64];
+ unsigned PageSize[2];
+ cups_bool_t Separations;
+ cups_bool_t TraySwitch;
+ cups_bool_t Tumble;
+ unsigned cupsBitsPerColor;
+ unsigned cupsBitsPerPixel;
+ float cupsBorderlessScalingFactor;
+ unsigned cupsBytesPerLine;
+ cups_order_t cupsColorOrder;
+ cups_cspace_t cupsColorSpace;
+ unsigned cupsCompression;
+ unsigned cupsHeight;
+ float cupsImagingBBox[4];
+ unsigned cupsInteger[16];
+ char cupsMarkerType[64];
+ unsigned cupsMediaType;
+ unsigned cupsNumColors;
+ char cupsPageSizeName[64];
+ float cupsPageSize[2];
+ float cupsReal[16];
+ char cupsRenderingIntent[64];
+ unsigned cupsRowCount;
+ unsigned cupsRowFeed;
+ unsigned cupsRowStep;
+ char cupsString[16][64];
+ unsigned cupsWidth;
+};
| AdvanceDistance | +AdvanceDistance value in points |
|---|---|
| AdvanceMedia | +AdvanceMedia value (cups_adv_t) |
| Collate | +Collated copies value |
| CutMedia | +CutMedia value (cups_cut_t) |
| Duplex | +Duplexed (double-sided) value |
| HWResolution[2] | +Resolution in dots-per-inch |
| ImagingBoundingBox[4] | +Pixel region that is painted (points, left, bottom, right, top) |
| InsertSheet | +InsertSheet value |
| Jog | +Jog value (cups_jog_t) |
| LeadingEdge | +LeadingEdge value (cups_edge_t) |
| ManualFeed | +ManualFeed value |
| Margins[2] | +Lower-lefthand margins in points |
| MediaClass[64] | +MediaClass string |
| MediaColor[64] | +MediaColor string |
| MediaPosition | +MediaPosition value |
| MediaType[64] | +MediaType string |
| MediaWeight | +MediaWeight value in grams/m^2 |
| MirrorPrint | +MirrorPrint value |
| NegativePrint | +NegativePrint value |
| NumCopies | +Number of copies to produce |
| Orientation | +Orientation value (cups_orient_t) |
| OutputFaceUp | +OutputFaceUp value |
| OutputType[64] | +OutputType string |
| PageSize[2] | +Width and length of page in points |
| Separations | +Separations value |
| TraySwitch | +TraySwitch value |
| Tumble | +Tumble value |
| cupsBitsPerColor | +Number of bits for each color |
| cupsBitsPerPixel | +Number of bits for each pixel |
| cupsBorderlessScalingFactor | +Scaling that was applied to page data |
| cupsBytesPerLine | +Number of bytes per line |
| cupsColorOrder | +Order of colors |
| cupsColorSpace | +True colorspace |
| cupsCompression | +Device compression to use |
| cupsHeight | +Height of page image in pixels |
| cupsImagingBBox[4] | +Floating point ImagingBoundingBox +(scaling factor not applied, left, +bottom, right, top) |
| cupsInteger[16] | +User-defined integer values |
| cupsMarkerType[64] | +Ink/toner type |
| cupsMediaType | +Media type code |
| cupsNumColors | +Number of color compoents |
| cupsPageSizeName[64] | +PageSize name |
| cupsPageSize[2] | +Floating point PageSize (scaling * +factor not applied) |
| cupsReal[16] | +User-defined floating-point values |
| cupsRenderingIntent[64] | +Color rendering intent |
| cupsRowCount | +Rows per band |
| cupsRowFeed | +Feed between bands |
| cupsRowStep | +Spacing between lines |
| cupsString[16][64] | +User-defined string values |
| cupsWidth | +Width of page image in pixels |
Media information
+struct cups_size_s {
+ int width, length, bottom, left, right, top;
+ char media[128], color[128], source[128], type[128];
+};
| top | +Top margin in hundredths of millimeters |
|---|---|
| type[128] | +Media type (blank for any/auto) |
Socket address list, which is used to enumerate all of the addresses that are associated with a hostname.
+struct http_addrlist_s {
+ http_addr_t addr;
+ struct http_addrlist_s *next;
+};
| addr | +Address |
|---|---|
| next | +Pointer to next address in list |
Common media size data
+struct pwg_media_s {
+ int width, length;
+ const char *pwg, *legacy, *ppd;
+};
| length | +Length in 2540ths |
|---|---|
| ppd | +Standard Adobe PPD name |
AdvanceMedia attribute values
+| CUPS_ADVANCE_FILE | Advance the roll after this file |
|---|---|
| CUPS_ADVANCE_JOB | Advance the roll after this job |
| CUPS_ADVANCE_NONE | Never advance the roll |
| CUPS_ADVANCE_PAGE | Advance the roll after this page |
| CUPS_ADVANCE_SET | Advance the roll after this set |
Boolean type
+| CUPS_FALSE | Logical false |
|---|---|
| CUPS_TRUE | Logical true |
X.509 credential purposes
+| CUPS_CREDPURPOSE_ALL | All purposes |
|---|---|
| CUPS_CREDPURPOSE_CLIENT_AUTH | clientAuth |
| CUPS_CREDPURPOSE_CODE_SIGNING | codeSigning |
| CUPS_CREDPURPOSE_EMAIL_PROTECTION | emailProtection |
| CUPS_CREDPURPOSE_OCSP_SIGNING | OCSPSigning |
| CUPS_CREDPURPOSE_SERVER_AUTH | serverAuth |
| CUPS_CREDPURPOSE_TIME_STAMPING | timeStamping |
X.509 credential types for cupsCreateCredentials and cupsCreateCredentialsRequest
| CUPS_CREDTYPE_DEFAULT | Default type |
|---|---|
| CUPS_CREDTYPE_ECDSA_P256_SHA256 | ECDSA using the P-256 curve with SHA-256 hash |
| CUPS_CREDTYPE_ECDSA_P384_SHA256 | ECDSA using the P-384 curve with SHA-256 hash |
| CUPS_CREDTYPE_ECDSA_P521_SHA256 | ECDSA using the P-521 curve with SHA-256 hash |
| CUPS_CREDTYPE_RSA_2048_SHA256 | RSA with 2048-bit keys and SHA-256 hash |
| CUPS_CREDTYPE_RSA_3072_SHA256 | RSA with 3072-bit keys and SHA-256 hash |
| CUPS_CREDTYPE_RSA_4096_SHA256 | RSA with 4096-bit keys and SHA-256 hash |
X.509 keyUsage flags
+| CUPS_CREDUSAGE_ALL | All keyUsage flags |
|---|---|
| CUPS_CREDUSAGE_CRL_SIGN | cRLSign |
| CUPS_CREDUSAGE_DATA_ENCIPHERMENT | dataEncipherment |
| CUPS_CREDUSAGE_DECIPHER_ONLY | decipherOnly |
| CUPS_CREDUSAGE_DEFAULT_CA | Defaults for CA certs |
| CUPS_CREDUSAGE_DEFAULT_TLS | Defaults for TLS certs |
| CUPS_CREDUSAGE_DIGITAL_SIGNATURE | digitalSignature |
| CUPS_CREDUSAGE_ENCIPHER_ONLY | encipherOnly |
| CUPS_CREDUSAGE_KEY_AGREEMENT | keyAgreement |
| CUPS_CREDUSAGE_KEY_CERT_SIGN | keyCertSign |
| CUPS_CREDUSAGE_KEY_ENCIPHERMENT | keyEncipherment |
| CUPS_CREDUSAGE_NON_REPUDIATION | nonRepudiation/contentCommitment |
cupsColorSpace attribute values
+| CUPS_CSPACE_ADOBERGB | Red, green, blue (Adobe RGB) |
|---|---|
| CUPS_CSPACE_CIELab | CIE Lab |
| CUPS_CSPACE_CIEXYZ | CIE XYZ |
| CUPS_CSPACE_CMY | Cyan, magenta, yellow (DeviceCMY) |
| CUPS_CSPACE_CMYK | Cyan, magenta, yellow, black (DeviceCMYK) |
| CUPS_CSPACE_DEVICE1 | DeviceN, 1 color |
| CUPS_CSPACE_DEVICE2 | DeviceN, 2 colors |
| CUPS_CSPACE_DEVICE3 | DeviceN, 3 colors |
| CUPS_CSPACE_DEVICE4 | DeviceN, 4 colors |
| CUPS_CSPACE_DEVICE5 | DeviceN, 5 colors |
| CUPS_CSPACE_DEVICE6 | DeviceN, 6 colors |
| CUPS_CSPACE_DEVICE7 | DeviceN, 7 colors |
| CUPS_CSPACE_DEVICE8 | DeviceN, 8 colors |
| CUPS_CSPACE_DEVICE9 | DeviceN, 9 colors |
| CUPS_CSPACE_DEVICEA | DeviceN, 10 colors |
| CUPS_CSPACE_DEVICEB | DeviceN, 11 colors |
| CUPS_CSPACE_DEVICEC | DeviceN, 12 colors |
| CUPS_CSPACE_DEVICED | DeviceN, 13 colors |
| CUPS_CSPACE_DEVICEE | DeviceN, 14 colors |
| CUPS_CSPACE_DEVICEF | DeviceN, 15 colors |
| CUPS_CSPACE_GMCK DEPRECATED | Gold, magenta, yellow, black |
| CUPS_CSPACE_GMCS DEPRECATED | Gold, magenta, yellow, silver |
| CUPS_CSPACE_GOLD DEPRECATED | Gold foil |
| CUPS_CSPACE_ICC1 | ICC-based, 1 color |
| CUPS_CSPACE_ICC2 | ICC-based, 2 colors |
| CUPS_CSPACE_ICC3 | ICC-based, 3 colors |
| CUPS_CSPACE_ICC4 | ICC-based, 4 colors |
| CUPS_CSPACE_ICC5 | ICC-based, 5 colors |
| CUPS_CSPACE_ICC6 | ICC-based, 6 colors |
| CUPS_CSPACE_ICC7 | ICC-based, 7 colors |
| CUPS_CSPACE_ICC8 | ICC-based, 8 colors |
| CUPS_CSPACE_ICC9 | ICC-based, 9 colors |
| CUPS_CSPACE_ICCA | ICC-based, 10 colors |
| CUPS_CSPACE_ICCB | ICC-based, 11 colors |
| CUPS_CSPACE_ICCC | ICC-based, 12 colors |
| CUPS_CSPACE_ICCD | ICC-based, 13 colors |
| CUPS_CSPACE_ICCE | ICC-based, 14 colors |
| CUPS_CSPACE_ICCF | ICC-based, 15 colors |
| CUPS_CSPACE_K | Black (DeviceK) |
| CUPS_CSPACE_KCMY DEPRECATED | Black, cyan, magenta, yellow |
| CUPS_CSPACE_KCMYcm DEPRECATED | Black, cyan, magenta, yellow, light-cyan, light-magenta |
| CUPS_CSPACE_RGB | Red, green, blue (DeviceRGB, sRGB by default) |
| CUPS_CSPACE_RGBA | Red, green, blue, alpha (DeviceRGB, sRGB by default) |
| CUPS_CSPACE_RGBW | Red, green, blue, white (DeviceRGB, sRGB by default) |
| CUPS_CSPACE_SILVER DEPRECATED | Silver foil |
| CUPS_CSPACE_SRGB | Red, green, blue (sRGB) |
| CUPS_CSPACE_SW | Luminance (gamma 2.2) |
| CUPS_CSPACE_W | Luminance (DeviceGray, gamma 2.2 by default) |
| CUPS_CSPACE_WHITE DEPRECATED | White ink (as black) |
| CUPS_CSPACE_YMC DEPRECATED | Yellow, magenta, cyan |
| CUPS_CSPACE_YMCK DEPRECATED | Yellow, magenta, cyan, black |
CutMedia attribute values
+| CUPS_CUT_FILE | Cut the roll after this file |
|---|---|
| CUPS_CUT_JOB | Cut the roll after this job |
| CUPS_CUT_NONE | Never cut the roll |
| CUPS_CUT_PAGE | Cut the roll after this page |
| CUPS_CUT_SET | Cut the roll after this set |
Flags for cupsConnectDest and cupsEnumDests
| CUPS_DEST_FLAGS_CANCELED | Operation was canceled |
|---|---|
| CUPS_DEST_FLAGS_CONNECTING | A connection is being established |
| CUPS_DEST_FLAGS_DEVICE | For cupsConnectDest: Connect to device |
| CUPS_DEST_FLAGS_ERROR | An error occurred |
| CUPS_DEST_FLAGS_MORE | There are more destinations |
| CUPS_DEST_FLAGS_NONE | No flags are set |
| CUPS_DEST_FLAGS_REMOVED | The destination has gone away |
| CUPS_DEST_FLAGS_RESOLVING | The destination address is being resolved |
| CUPS_DEST_FLAGS_UNCONNECTED | There is no connection |
DNS-SD callback flag values
+| CUPS_DNSSD_FLAGS_ADD | Added (removed if not set) |
|---|---|
| CUPS_DNSSD_FLAGS_COLLISION | Collision occurred |
| CUPS_DNSSD_FLAGS_ERROR | Error occurred |
| CUPS_DNSSD_FLAGS_HOST_CHANGE | Host name changed |
| CUPS_DNSSD_FLAGS_MORE | More coming |
| CUPS_DNSSD_FLAGS_NETWORK_CHANGE | Network connection changed |
| CUPS_DNSSD_FLAGS_NONE | No flags |
DNS record type values
+| CUPS_DNSSD_RRTYPE_A | Host address |
|---|---|
| CUPS_DNSSD_RRTYPE_AAAA | IPv6 Address. |
| CUPS_DNSSD_RRTYPE_ANY | Wildcard match |
| CUPS_DNSSD_RRTYPE_CERT | Certification record |
| CUPS_DNSSD_RRTYPE_CNAME | Canonical name |
| CUPS_DNSSD_RRTYPE_DHCID | DHCP Client Identifier |
| CUPS_DNSSD_RRTYPE_DNSKEY | DNSKEY |
| CUPS_DNSSD_RRTYPE_HTTPS | HTTPS Service Binding |
| CUPS_DNSSD_RRTYPE_KEY | Security key |
| CUPS_DNSSD_RRTYPE_KX | Key Exchange |
| CUPS_DNSSD_RRTYPE_LOC | Location Information. |
| CUPS_DNSSD_RRTYPE_NS | Name server |
| CUPS_DNSSD_RRTYPE_PTR | Domain name pointer |
| CUPS_DNSSD_RRTYPE_RRSIG | RRSIG |
| CUPS_DNSSD_RRTYPE_RT | Router |
| CUPS_DNSSD_RRTYPE_SIG | Security signature |
| CUPS_DNSSD_RRTYPE_SPF | Sender Policy Framework for E-Mail |
| CUPS_DNSSD_RRTYPE_TXT | One or more text strings |
| CUPS_DNSSD_RRTYPE_WKS | Well known service |
LeadingEdge attribute values
+| CUPS_EDGE_BOTTOM | Leading edge is the bottom of the page |
|---|---|
| CUPS_EDGE_LEFT | Leading edge is the left of the page |
| CUPS_EDGE_RIGHT | Leading edge is the right of the page |
| CUPS_EDGE_TOP | Leading edge is the top of the page |
Language Encodings
+| CUPS_ENCODING_BG18030 | Chinese GB 18030 |
|---|---|
| CUPS_ENCODING_EUC_CN | EUC Simplified Chinese |
| CUPS_ENCODING_EUC_JP | EUC Japanese |
| CUPS_ENCODING_EUC_KR | EUC Korean |
| CUPS_ENCODING_EUC_TW | EUC Traditional Chinese |
| CUPS_ENCODING_ISO8859_1 | ISO-8859-1 |
| CUPS_ENCODING_ISO8859_10 | ISO-8859-10 |
| CUPS_ENCODING_ISO8859_11 | ISO-8859-11 |
| CUPS_ENCODING_ISO8859_13 | ISO-8859-13 |
| CUPS_ENCODING_ISO8859_14 | ISO-8859-14 |
| CUPS_ENCODING_ISO8859_15 | ISO-8859-15 |
| CUPS_ENCODING_ISO8859_16 | ISO-8859-16 |
| CUPS_ENCODING_ISO8859_2 | ISO-8859-2 |
| CUPS_ENCODING_ISO8859_3 | ISO-8859-3 |
| CUPS_ENCODING_ISO8859_4 | ISO-8859-4 |
| CUPS_ENCODING_ISO8859_5 | ISO-8859-5 |
| CUPS_ENCODING_ISO8859_6 | ISO-8859-6 |
| CUPS_ENCODING_ISO8859_7 | ISO-8859-7 |
| CUPS_ENCODING_ISO8859_8 | ISO-8859-8 |
| CUPS_ENCODING_ISO8859_9 | ISO-8859-9 |
| CUPS_ENCODING_JIS_X0213 | JIS X0213 aka Shift JIS |
| CUPS_ENCODING_KOI8_R | KOI-8-R |
| CUPS_ENCODING_KOI8_U | KOI-8-U |
| CUPS_ENCODING_MAC_ROMAN | MacRoman |
| CUPS_ENCODING_US_ASCII | US ASCII |
| CUPS_ENCODING_UTF_8 | UTF-8 |
| CUPS_ENCODING_WINDOWS_1250 | CP-1250 |
| CUPS_ENCODING_WINDOWS_1251 | CP-1251 |
| CUPS_ENCODING_WINDOWS_1252 | CP-1252 |
| CUPS_ENCODING_WINDOWS_1253 | CP-1253 |
| CUPS_ENCODING_WINDOWS_1254 | CP-1254 |
| CUPS_ENCODING_WINDOWS_1255 | CP-1255 |
| CUPS_ENCODING_WINDOWS_1256 | CP-1256 |
| CUPS_ENCODING_WINDOWS_1257 | CP-1257 |
| CUPS_ENCODING_WINDOWS_1258 | CP-1258 |
| CUPS_ENCODING_WINDOWS_1361 | Korean Johab |
| CUPS_ENCODING_WINDOWS_874 | CP-874 |
| CUPS_ENCODING_WINDOWS_932 | Japanese JIS X0208-1990 |
| CUPS_ENCODING_WINDOWS_936 | Simplified Chinese GB 2312-80 |
| CUPS_ENCODING_WINDOWS_949 | Korean KS C5601-1992 |
| CUPS_ENCODING_WINDOWS_950 | Traditional Chinese Big Five |
Jog attribute values
+| CUPS_JOG_FILE | Move pages after this file |
|---|---|
| CUPS_JOG_JOB | Move pages after this job |
| CUPS_JOG_NONE | Never move pages |
| CUPS_JOG_SET | Move pages after this set |
JSON node type
+| CUPS_JTYPE_ARRAY | Array value |
|---|---|
| CUPS_JTYPE_FALSE | Boolean false value |
| CUPS_JTYPE_KEY | Object key (string) |
| CUPS_JTYPE_NULL | Null value |
| CUPS_JTYPE_NUMBER | Number value |
| CUPS_JTYPE_OBJECT | Object value |
| CUPS_JTYPE_STRING | String value |
| CUPS_JTYPE_TRUE | Boolean true value |
JSON Web Algorithms
+| CUPS_JWA_ES256 | ECDSA using P-256 and SHA-256 |
|---|---|
| CUPS_JWA_ES384 | ECDSA using P-384 and SHA-384 |
| CUPS_JWA_ES512 | ECDSA using P-521 and SHA-512 |
| CUPS_JWA_HS256 | HMAC using SHA-256 |
| CUPS_JWA_HS384 | HMAC using SHA-384 |
| CUPS_JWA_HS512 | HMAC using SHA-512 |
| CUPS_JWA_NONE | No algorithm |
| CUPS_JWA_RS256 | RSASSA-PKCS1-v1_5 using SHA-256 |
| CUPS_JWA_RS384 | RSASSA-PKCS1-v1_5 using SHA-384 |
| CUPS_JWA_RS512 | RSASSA-PKCS1-v1_5 using SHA-512 |
JSON Web Signature Formats
+| CUPS_JWS_FORMAT_COMPACT | JWS Compact Serialization |
|---|---|
| CUPS_JWS_FORMAT_JSON | JWS JSON Serialization |
Flags for cupsGetDestMediaByName and cupsGetDestMediaBySize
| CUPS_MEDIA_FLAGS_BORDERLESS | Find a borderless size |
|---|---|
| CUPS_MEDIA_FLAGS_DEFAULT | Find the closest size supported by the printer |
| CUPS_MEDIA_FLAGS_DUPLEX | Find a size compatible with 2-sided printing |
| CUPS_MEDIA_FLAGS_EXACT | Find an exact match for the size |
| CUPS_MEDIA_FLAGS_READY | If the printer supports media sensing, find the size amongst the "ready" media. |
MediaPosition values
+| CUPS_MEDIAPOS_ALTERNATE | 'alternate' |
|---|---|
| CUPS_MEDIAPOS_ALTERNATE_ROLL | 'alternate-roll' |
| CUPS_MEDIAPOS_AUTO | 'auto' |
| CUPS_MEDIAPOS_BOTTOM | 'bottom' |
| CUPS_MEDIAPOS_BY_PASS_TRAY | 'by-pass-tray' |
| CUPS_MEDIAPOS_CENTER | 'center' |
| CUPS_MEDIAPOS_DISC | 'disc' |
| CUPS_MEDIAPOS_ENVELOPE | 'envelope' |
| CUPS_MEDIAPOS_HAGAKI | 'hagaki' |
| CUPS_MEDIAPOS_LARGE_CAPACITY | 'large-capacity' |
| CUPS_MEDIAPOS_LEFT | 'left' |
| CUPS_MEDIAPOS_MAIN | 'main' |
| CUPS_MEDIAPOS_MAIN_ROLL | 'main-roll' |
| CUPS_MEDIAPOS_MANUAL | 'manual' |
| CUPS_MEDIAPOS_MIDDLE | 'middle' |
| CUPS_MEDIAPOS_PHOTO | 'photo' |
| CUPS_MEDIAPOS_REAR | 'rear' |
| CUPS_MEDIAPOS_RIGHT | 'right' |
| CUPS_MEDIAPOS_ROLL_1 | 'roll-1' |
| CUPS_MEDIAPOS_ROLL_10 | 'roll-10' |
| CUPS_MEDIAPOS_ROLL_2 | 'roll-2' |
| CUPS_MEDIAPOS_ROLL_3 | 'roll-3' |
| CUPS_MEDIAPOS_ROLL_4 | 'roll-4' |
| CUPS_MEDIAPOS_ROLL_5 | 'roll-5' |
| CUPS_MEDIAPOS_ROLL_6 | 'roll-6' |
| CUPS_MEDIAPOS_ROLL_7 | 'roll-7' |
| CUPS_MEDIAPOS_ROLL_8 | 'roll-8' |
| CUPS_MEDIAPOS_ROLL_9 | 'roll-9' |
| CUPS_MEDIAPOS_SIDE | 'side' |
| CUPS_MEDIAPOS_TOP | 'top' |
| CUPS_MEDIAPOS_TRAY_1 | 'tray-1' |
| CUPS_MEDIAPOS_TRAY_10 | 'tray-10' |
| CUPS_MEDIAPOS_TRAY_11 | 'tray-11' |
| CUPS_MEDIAPOS_TRAY_12 | 'tray-12' |
| CUPS_MEDIAPOS_TRAY_13 | 'tray-13' |
| CUPS_MEDIAPOS_TRAY_14 | 'tray-14' |
| CUPS_MEDIAPOS_TRAY_15 | 'tray-15' |
| CUPS_MEDIAPOS_TRAY_16 | 'tray-16' |
| CUPS_MEDIAPOS_TRAY_17 | 'tray-17' |
| CUPS_MEDIAPOS_TRAY_18 | 'tray-18' |
| CUPS_MEDIAPOS_TRAY_19 | 'tray-19' |
| CUPS_MEDIAPOS_TRAY_2 | 'tray-2' |
| CUPS_MEDIAPOS_TRAY_20 | 'tray-20' |
| CUPS_MEDIAPOS_TRAY_3 | 'tray-3' |
| CUPS_MEDIAPOS_TRAY_4 | 'tray-4' |
| CUPS_MEDIAPOS_TRAY_5 | 'tray-5' |
| CUPS_MEDIAPOS_TRAY_6 | 'tray-6' |
| CUPS_MEDIAPOS_TRAY_7 | 'tray-7' |
| CUPS_MEDIAPOS_TRAY_8 | 'tray-8' |
| CUPS_MEDIAPOS_TRAY_9 | 'tray-9' |
cupsColorOrder attribute values
+| CUPS_ORDER_BANDED | CCC MMM YYY KKK ... |
|---|---|
| CUPS_ORDER_CHUNKED | CMYK CMYK CMYK ... |
| CUPS_ORDER_PLANAR | CCC ... MMM ... YYY ... KKK ... |
Orientation attribute values
+| CUPS_ORIENT_0 | Don't rotate the page |
|---|---|
| CUPS_ORIENT_180 | Turn the page upside down |
| CUPS_ORIENT_270 | Rotate the page clockwise |
| CUPS_ORIENT_90 | Rotate the page counter-clockwise |
Printer type/capability flags
+| CUPS_PRINTER_AUTHENTICATED | Printer requires authentication |
|---|---|
| CUPS_PRINTER_BIND | Can bind output |
| CUPS_PRINTER_BW | Can do B&W printing |
| CUPS_PRINTER_CLASS | Printer class |
| CUPS_PRINTER_COLLATE | Can quickly collate copies |
| CUPS_PRINTER_COLOR | Can do color printing |
| CUPS_PRINTER_COMMANDS | Printer supports maintenance commands |
| CUPS_PRINTER_COPIES | Can do copies in hardware |
| CUPS_PRINTER_COVER | Can cover output |
| CUPS_PRINTER_DEFAULT | Default printer on network |
| CUPS_PRINTER_DISCOVERED | Printer was discovered |
| CUPS_PRINTER_DUPLEX | Can do two-sided printing |
| CUPS_PRINTER_FAX | Fax queue |
| CUPS_PRINTER_LARGE | Can print on D/E/A1/A0-size media |
| CUPS_PRINTER_LOCAL | Local printer or class |
| CUPS_PRINTER_MEDIUM | Can print on Tabloid/B/C/A3/A2-size media |
| CUPS_PRINTER_MFP | Printer with scanning capabilities |
| CUPS_PRINTER_NOT_SHARED | Printer is not shared |
| CUPS_PRINTER_PUNCH | Can punch output |
| CUPS_PRINTER_REJECTING | Printer is rejecting jobs |
| CUPS_PRINTER_REMOTE | Remote printer or class |
| CUPS_PRINTER_SCANNER | Scanner-only device |
| CUPS_PRINTER_SMALL | Can print on Letter/Legal/A4-size media |
| CUPS_PRINTER_SORT | Can sort output |
| CUPS_PRINTER_STAPLE | Can staple output |
| CUPS_PRINTER_VARIABLE | Can print on rolls and custom-size media |
cupsRasterOpen modes
+| CUPS_RASTER_READ | Open stream for reading |
|---|---|
| CUPS_RASTER_WRITE | Open stream for writing |
| CUPS_RASTER_WRITE_COMPRESSED | Open stream for compressed writing |
| CUPS_RASTER_WRITE_PWG | Open stream for compressed writing in PWG Raster mode |
Which jobs for cupsGetJobs
| CUPS_WHICHJOBS_ACTIVE | Pending/held/processing jobs |
|---|---|
| CUPS_WHICHJOBS_ALL | All jobs |
| CUPS_WHICHJOBS_COMPLETED | Completed/canceled/aborted jobs |
HTTP transfer encoding values
+| HTTP_ENCODING_CHUNKED | Data is chunked |
|---|---|
| HTTP_ENCODING_FIELDS | Sending HTTP fields |
| HTTP_ENCODING_LENGTH | Data is sent with Content-Length |
HTTP encryption values
+| HTTP_ENCRYPTION_ALWAYS | Always encrypt (HTTPS) |
|---|---|
| HTTP_ENCRYPTION_IF_REQUESTED | Encrypt if requested (TLS upgrade) |
| HTTP_ENCRYPTION_NEVER | Never encrypt |
| HTTP_ENCRYPTION_REQUIRED | Encryption is required (TLS upgrade) |
HTTP field names
+| HTTP_FIELD_ACCEPT | Accept field |
|---|---|
| HTTP_FIELD_ACCEPT_CH | RFC 8942 Accept-CH field |
| HTTP_FIELD_ACCEPT_ENCODING | Accept-Encoding field |
| HTTP_FIELD_ACCEPT_LANGUAGE | Accept-Language field |
| HTTP_FIELD_ACCEPT_RANGES | Accept-Ranges field |
| HTTP_FIELD_ACCESS_CONTROL_ALLOW_CREDENTIALS | CORS/Fetch Access-Control-Allow-Cresdentials field |
| HTTP_FIELD_ACCESS_CONTROL_ALLOW_HEADERS | CORS/Fetch Access-Control-Allow-Headers field |
| HTTP_FIELD_ACCESS_CONTROL_ALLOW_METHODS | CORS/Fetch Access-Control-Allow-Methods field |
| HTTP_FIELD_ACCESS_CONTROL_ALLOW_ORIGIN | CORS/Fetch Access-Control-Allow-Origin field |
| HTTP_FIELD_ACCESS_CONTROL_EXPOSE_HEADERS | CORS/Fetch Access-Control-Expose-Headers field |
| HTTP_FIELD_ACCESS_CONTROL_MAX_AGE | CORS/Fetch Access-Control-Max-Age field |
| HTTP_FIELD_ACCESS_CONTROL_REQUEST_HEADERS | CORS/Fetch Access-Control-Request-Headers field |
| HTTP_FIELD_ACCESS_CONTROL_REQUEST_METHOD | CORS/Fetch Access-Control-Request-Method field |
| HTTP_FIELD_AGE | Age field |
| HTTP_FIELD_ALLOW | Allow field |
| HTTP_FIELD_AUTHENTICATION_CONTROL | RFC 8053 Authentication-Control field |
| HTTP_FIELD_AUTHENTICATION_INFO | Authentication-Info field |
| HTTP_FIELD_AUTHORIZATION | Authorization field |
| HTTP_FIELD_CACHE_CONTROL | Cache-Control field |
| HTTP_FIELD_CACHE_STATUS | Cache-Status field |
| HTTP_FIELD_CERT_NOT_AFTER | RFC 8739 (ACME) Cert-Not-After field |
| HTTP_FIELD_CERT_NOT_BEFORE | RFC 8739 (ACME) Cert-Not-Before field |
| HTTP_FIELD_CONNECTION | Connection field |
| HTTP_FIELD_CONTENT_DISPOSITION | RFC 6266 Content-Disposition field |
| HTTP_FIELD_CONTENT_ENCODING | Content-Encoding field |
| HTTP_FIELD_CONTENT_LANGUAGE | Content-Language field |
| HTTP_FIELD_CONTENT_LENGTH | Content-Length field |
| HTTP_FIELD_CONTENT_LOCATION | Content-Location field |
| HTTP_FIELD_CONTENT_RANGE | Content-Range field |
| HTTP_FIELD_CONTENT_SECURITY_POLICY | CSPL3 Content-Security-Policy field |
| HTTP_FIELD_CONTENT_SECURITY_POLICY_REPORT_ONLY | CSPL3 Content-Security-Policy-Report-Only field |
| HTTP_FIELD_CONTENT_TYPE | Content-Type field |
| HTTP_FIELD_CROSS_ORIGIN_EMBEDDER_POLICY | WHATWG Cross-Origin-Embedder-Policy field |
| HTTP_FIELD_CROSS_ORIGIN_EMBEDDER_POLICY_REPORT_ONLY | WHATWG Cross-Origin-Embedder-Policy-Report-Only field |
| HTTP_FIELD_CROSS_ORIGIN_OPENER_POLICY | WHATWG Cross-Origin-Opener-Policy field |
| HTTP_FIELD_CROSS_ORIGIN_OPENER_POLICY_REPORT_ONLY | WHATWG Cross-Origin-Opener-Policy-Report-Only field |
| HTTP_FIELD_CROSS_ORIGIN_RESOURCE_POLICY | WHATWG Cross-Origin-Resource-Policy field |
| HTTP_FIELD_DASL | RFC 5323 (WebDAV) DASL field |
| HTTP_FIELD_DATE | Date field |
| HTTP_FIELD_DAV | RFC 4918 (WebDAV) DAV field |
| HTTP_FIELD_DEPTH | RFC 4918 (WebDAV) Depth field |
| HTTP_FIELD_DESTINATION | RFC 4918 (WebDAV) Destination field |
| HTTP_FIELD_ETAG | ETag field |
| HTTP_FIELD_EXPIRES | Expires field |
| HTTP_FIELD_FORWARDED | RFC 7239 Forwarded field |
| HTTP_FIELD_FROM | From field |
| HTTP_FIELD_HOST | Host field |
| HTTP_FIELD_IF | RFC 4918 (WebDAV) If field |
| HTTP_FIELD_IF_MATCH | If-Match field |
| HTTP_FIELD_IF_MODIFIED_SINCE | If-Modified-Since field |
| HTTP_FIELD_IF_NONE_MATCH | If-None-Match field |
| HTTP_FIELD_IF_RANGE | If-Range field |
| HTTP_FIELD_IF_SCHEDULE_TAG_MATCH | RFC 6638 (CalDAV) If-Schedule-Tag-Match field |
| HTTP_FIELD_IF_UNMODIFIED_SINCE | If-Unmodified-Since field |
| HTTP_FIELD_KEEP_ALIVE | Keep-Alive field |
| HTTP_FIELD_LAST_MODIFIED | Last-Modified field |
| HTTP_FIELD_LINK | Link field |
| HTTP_FIELD_LOCATION | Location field |
| HTTP_FIELD_LOCK_TOKEN | RFC 4918 (WebDAV) Lock-Token field |
| HTTP_FIELD_MAX | Maximum field index |
| HTTP_FIELD_MAX_FORWARDS | Max-Forwards field |
| HTTP_FIELD_OPTIONAL_WWW_AUTHENTICATE | RFC 8053 Optional-WWW-Authenticate field |
| HTTP_FIELD_ORIGIN | RFC 6454 Origin field |
| HTTP_FIELD_OSCORE | RFC 8613 OSCORE field |
| HTTP_FIELD_OVERWRITE | RFC 4918 (WebDAV) Overwrite field |
| HTTP_FIELD_PRAGMA | Pragma field |
| HTTP_FIELD_PROXY_AUTHENTICATE | Proxy-Authenticate field |
| HTTP_FIELD_PROXY_AUTHENTICATION_INFO | Proxy-Authentication-Info field |
| HTTP_FIELD_PROXY_AUTHORIZATION | Proxy-Authorization field |
| HTTP_FIELD_PROXY_STATUS | Proxy-Status field |
| HTTP_FIELD_PUBLIC | Public field |
| HTTP_FIELD_RANGE | Range field |
| HTTP_FIELD_REFERER | Referer field |
| HTTP_FIELD_REFRESH | WHATWG Refresh field |
| HTTP_FIELD_REPLAY_NONCE | RFC 8555 (ACME) Replay-Nonce field |
| HTTP_FIELD_RETRY_AFTER | Retry-After field |
| HTTP_FIELD_SCHEDULE_REPLY | RFC 6638 (CalDAV) Schedule-Reply field |
| HTTP_FIELD_SCHEDULE_TAG | RFC 6638 (CalDAV) Schedule-Tag field |
| HTTP_FIELD_SERVER | Server field |
| HTTP_FIELD_STRICT_TRANSPORT_SECURITY | HSTS Strict-Transport-Security field |
| HTTP_FIELD_TE | TE field |
| HTTP_FIELD_TIMEOUT | RFC 4918 Timeout field |
| HTTP_FIELD_TRAILER | Trailer field |
| HTTP_FIELD_TRANSFER_ENCODING | Transfer-Encoding field |
| HTTP_FIELD_UNKNOWN | Unknown field |
| HTTP_FIELD_UPGRADE | Upgrade field |
| HTTP_FIELD_USER_AGENT | User-Agent field |
| HTTP_FIELD_VARY | Vary field |
| HTTP_FIELD_VIA | Via field |
| HTTP_FIELD_WWW_AUTHENTICATE | WWW-Authenticate field |
| HTTP_FIELD_X_CONTENT_OPTIONS | WHATWG X-Content-Options field |
| HTTP_FIELD_X_FRAME_OPTIONS | WHATWG X-Frame-Options field |
HTTP keep-alive values
+| HTTP_KEEPALIVE_OFF | No keep alive support |
|---|---|
| HTTP_KEEPALIVE_ON | Use keep alive |
httpResolveURI options bit values
| HTTP_RESOLVE_DEFAULT | Resolve with default options |
|---|---|
| HTTP_RESOLVE_FAXOUT | Resolve FaxOut service instead of Print |
| HTTP_RESOLVE_FQDN | Resolve to a FQDN |
HTTP state values; states are server-oriented...
+| HTTP_STATE_CONNECT | CONNECT command, waiting for blank line |
|---|---|
| HTTP_STATE_COPY | COPY command, waiting for blank line |
| HTTP_STATE_COPY_SEND | COPY command, sending data |
| HTTP_STATE_DELETE | DELETE command, waiting for blank line |
| HTTP_STATE_DELETE_SEND | DELETE command, sending data |
| HTTP_STATE_ERROR | Error on socket |
| HTTP_STATE_GET | GET command, waiting for blank line |
| HTTP_STATE_GET_SEND | GET command, sending data |
| HTTP_STATE_HEAD | HEAD command, waiting for blank line |
| HTTP_STATE_LOCK | LOCK command, waiting for blank line |
| HTTP_STATE_LOCK_RECV | LOCK command, receiving data |
| HTTP_STATE_LOCK_SEND | LOCK command, sending data |
| HTTP_STATE_MKCOL | MKCOL command, waiting for blank line |
| HTTP_STATE_MOVE | MOVE command, waiting for blank line |
| HTTP_STATE_MOVE_SEND | MOVE command, sending data |
| HTTP_STATE_OPTIONS | OPTIONS command, waiting for blank line |
| HTTP_STATE_POST | POST command, waiting for blank line |
| HTTP_STATE_POST_RECV | POST command, receiving data |
| HTTP_STATE_POST_SEND | POST command, sending data |
| HTTP_STATE_PROPFIND | PROPFIND command, waiting for blank line |
| HTTP_STATE_PROPFIND_RECV | PROPFIND command, receiving data |
| HTTP_STATE_PROPFIND_SEND | PROPFIND command, sending data |
| HTTP_STATE_PROPPATCH | PROPPATCH command, waiting for blank line |
| HTTP_STATE_PROPPATCH_RECV | PROPPATCH command, receiving data |
| HTTP_STATE_PROPPATCH_SEND | PROPPATCH command, sending data |
| HTTP_STATE_PUT | PUT command, waiting for blank line |
| HTTP_STATE_PUT_RECV | PUT command, receiving data |
| HTTP_STATE_STATUS | Command complete, sending status |
| HTTP_STATE_TRACE | TRACE command, waiting for blank line |
| HTTP_STATE_UNKNOWN_METHOD | Unknown request method, waiting for blank line |
| HTTP_STATE_UNKNOWN_VERSION | Unknown request method, waiting for blank line |
| HTTP_STATE_UNLOCK | UNLOCK command, waiting for blank line |
| HTTP_STATE_WAITING | Waiting for command |
HTTP status codes
+| HTTP_STATUS_ACCEPTED | DELETE command was successful |
|---|---|
| HTTP_STATUS_ALREADY_REPORTED | Already reported (WebDAV) |
| HTTP_STATUS_BAD_GATEWAY | Bad gateway |
| HTTP_STATUS_BAD_REQUEST | Bad request |
| HTTP_STATUS_CONFLICT | Request is self-conflicting |
| HTTP_STATUS_CONTENT_TOO_LARGE | Content too large |
| HTTP_STATUS_CONTINUE | Everything OK, keep going... |
| HTTP_STATUS_CREATED | PUT command was successful |
| HTTP_STATUS_CUPS_AUTHORIZATION_CANCELED | User canceled authorization |
| HTTP_STATUS_CUPS_PKI_ERROR | Error negotiating a secure connection |
| HTTP_STATUS_ERROR | An error response from httpXxxx() |
| HTTP_STATUS_EXPECTATION_FAILED | The expectation given in an Expect header field was not met |
| HTTP_STATUS_FAILED_DEPENDENCY | Failed dependency (WebDAV) |
| HTTP_STATUS_FORBIDDEN | Forbidden to access this URI |
| HTTP_STATUS_FOUND | Document was found at a different URI |
| HTTP_STATUS_GATEWAY_TIMEOUT | Gateway connection timed out |
| HTTP_STATUS_GONE | Server has gone away |
| HTTP_STATUS_HTTP_VERSION_NOT_SUPPORTED | HTTP version not supported |
| HTTP_STATUS_INSUFFICIENT_STORAGE | Insufficient storage (WebDAV) |
| HTTP_STATUS_LENGTH_REQUIRED | A content length or encoding is required |
| HTTP_STATUS_LOCKED | Locked (WebDAV) |
| HTTP_STATUS_LOOP_DETECTED | Loop detected (WebDAV) |
| HTTP_STATUS_METHOD_NOT_ALLOWED | Method is not allowed |
| HTTP_STATUS_MISDIRECTED_REQUEST | Misdirected request |
| HTTP_STATUS_MOVED_PERMANENTLY | Document has moved permanently |
| HTTP_STATUS_MULTIPLE_CHOICES | Multiple files match request |
| HTTP_STATUS_MULTI_STATUS | Multiple status codes (WebDAV) |
| HTTP_STATUS_NETWORK_AUTHENTICATION_REQUIRED | Network Authentication Required (WebDAV) |
| HTTP_STATUS_NONE | No Expect value |
| HTTP_STATUS_NOT_ACCEPTABLE | Not Acceptable |
| HTTP_STATUS_NOT_AUTHORITATIVE | Information isn't authoritative |
| HTTP_STATUS_NOT_FOUND | URI was not found |
| HTTP_STATUS_NOT_IMPLEMENTED | Feature not implemented |
| HTTP_STATUS_NOT_MODIFIED | File not modified |
| HTTP_STATUS_NO_CONTENT | Successful command, no new data |
| HTTP_STATUS_OK | OPTIONS/GET/HEAD/POST/TRACE command was successful |
| HTTP_STATUS_PARTIAL_CONTENT | Only a partial file was received/sent |
| HTTP_STATUS_PAYMENT_REQUIRED | Payment required |
| HTTP_STATUS_PERMANENT_REDIRECT | Permanent redirection |
| HTTP_STATUS_PRECONDITION_FAILED | Precondition failed |
| HTTP_STATUS_PRECONDITION_REQUIRED | Precondition required (WebDAV) |
| HTTP_STATUS_PROXY_AUTHENTICATION_REQUIRED | Proxy Authentication is Required |
| HTTP_STATUS_RANGE_NOT_SATISFIABLE | The requested range is not satisfiable |
| HTTP_STATUS_REQUEST_HEADER_FIELDS_TOO_LARGE | Request Header Fields Too Large (WebDAV) |
| HTTP_STATUS_REQUEST_TIMEOUT | Request timed out |
| HTTP_STATUS_RESET_CONTENT | Content was reset/recreated |
| HTTP_STATUS_SEE_OTHER | See this other link |
| HTTP_STATUS_SERVER_ERROR | Internal server error |
| HTTP_STATUS_SERVICE_UNAVAILABLE | Service is unavailable |
| HTTP_STATUS_SWITCHING_PROTOCOLS | HTTP upgrade to TLS/SSL |
| HTTP_STATUS_TEMPORARY_REDIRECT | Temporary redirection |
| HTTP_STATUS_TOO_EARLY | Too early (WebDAV) |
| HTTP_STATUS_TOO_MANY_REQUESTS | Too many requests (WebDAV) |
| HTTP_STATUS_UNAUTHORIZED | Unauthorized to access host |
| HTTP_STATUS_UNAVAILABLE_FOR_LEGAL_REASONS | Unavailable For Legal Reasons (RFC 7725) |
| HTTP_STATUS_UNPROCESSABLE_CONTENT | Unprocessable content |
| HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE | The requested media type is unsupported |
| HTTP_STATUS_UPGRADE_REQUIRED | Upgrade to SSL/TLS required |
| HTTP_STATUS_URI_TOO_LONG | URI too long |
| HTTP_STATUS_USE_PROXY | Must use a proxy to access this URI |
Level of trust for credentials
+| HTTP_TRUST_CHANGED | Credentials have changed |
|---|---|
| HTTP_TRUST_EXPIRED | Credentials are expired |
| HTTP_TRUST_INVALID | Credentials are invalid |
| HTTP_TRUST_OK | Credentials are OK/trusted |
| HTTP_TRUST_RENEWED | Credentials have been renewed |
| HTTP_TRUST_UNKNOWN | Credentials are unknown/new |
URI en/decode flags
+| HTTP_URI_CODING_ALL | En/decode everything |
|---|---|
| HTTP_URI_CODING_HOSTNAME | En/decode the hostname portion |
| HTTP_URI_CODING_MOST | En/decode all but the query |
| HTTP_URI_CODING_NONE | Don't en/decode anything |
| HTTP_URI_CODING_QUERY | En/decode the query portion |
| HTTP_URI_CODING_RESOURCE | En/decode the resource portion |
| HTTP_URI_CODING_RFC6874 | Use RFC 6874 address format |
| HTTP_URI_CODING_USERNAME | En/decode the username portion |
URI separation status
+| HTTP_URI_STATUS_BAD_ARGUMENTS | Bad arguments to function (error) |
|---|---|
| HTTP_URI_STATUS_BAD_HOSTNAME | Bad hostname in URI (error) |
| HTTP_URI_STATUS_BAD_PORT | Bad port number in URI (error) |
| HTTP_URI_STATUS_BAD_RESOURCE | Bad resource in URI (error) |
| HTTP_URI_STATUS_BAD_SCHEME | Bad scheme in URI (error) |
| HTTP_URI_STATUS_BAD_URI | Bad/empty URI (error) |
| HTTP_URI_STATUS_BAD_USERNAME | Bad username in URI (error) |
| HTTP_URI_STATUS_MISSING_RESOURCE | Missing resource in URI (warning) |
| HTTP_URI_STATUS_MISSING_SCHEME | Missing scheme in URI (warning) |
| HTTP_URI_STATUS_OK | URI decoded OK |
| HTTP_URI_STATUS_OVERFLOW | URI buffer for httpAssembleURI is too small |
| HTTP_URI_STATUS_UNKNOWN_SCHEME | Unknown scheme in URI (warning) |
"document-state" values
+| IPP_DSTATE_ABORTED | Document is aborted |
|---|---|
| IPP_DSTATE_CANCELED | Document is canceled |
| IPP_DSTATE_COMPLETED | Document is completed |
| IPP_DSTATE_PENDING | Document is pending |
| IPP_DSTATE_PROCESSING | Document is processing |
"finishings" values
+| IPP_FINISHINGS_BALE | Bale (any type) |
|---|---|
| IPP_FINISHINGS_BIND | Bind |
| IPP_FINISHINGS_BIND_BOTTOM | Bind on bottom |
| IPP_FINISHINGS_BIND_LEFT | Bind on left |
| IPP_FINISHINGS_BIND_RIGHT | Bind on right |
| IPP_FINISHINGS_BIND_TOP | Bind on top |
| IPP_FINISHINGS_BOOKLET_MAKER | Fold to make booklet |
| IPP_FINISHINGS_COAT | Apply protective liquid or powder coating |
| IPP_FINISHINGS_COVER | Add cover |
| IPP_FINISHINGS_EDGE_STITCH | Stitch along any side |
| IPP_FINISHINGS_EDGE_STITCH_BOTTOM | Stitch along bottom edge |
| IPP_FINISHINGS_EDGE_STITCH_LEFT | Stitch along left side |
| IPP_FINISHINGS_EDGE_STITCH_RIGHT | Stitch along right side |
| IPP_FINISHINGS_EDGE_STITCH_TOP | Stitch along top edge |
| IPP_FINISHINGS_FOLD | Fold (any type) |
| IPP_FINISHINGS_FOLD_ACCORDION | Accordion-fold the paper vertically into four sections |
| IPP_FINISHINGS_FOLD_DOUBLE_GATE | Fold the top and bottom quarters of the paper towards the midline, then fold in half vertically |
| IPP_FINISHINGS_FOLD_ENGINEERING_Z | Fold the paper vertically into two small sections and one larger, forming an elongated Z |
| IPP_FINISHINGS_FOLD_GATE | Fold the top and bottom quarters of the paper towards the midline |
| IPP_FINISHINGS_FOLD_HALF | Fold the paper in half vertically |
| IPP_FINISHINGS_FOLD_HALF_Z | Fold the paper in half horizontally, then Z-fold the paper vertically |
| IPP_FINISHINGS_FOLD_LEFT_GATE | Fold the top quarter of the paper towards the midline |
| IPP_FINISHINGS_FOLD_LETTER | Fold the paper into three sections vertically; sometimes also known as a C fold |
| IPP_FINISHINGS_FOLD_PARALLEL | Fold the paper in half vertically two times, yielding four sections |
| IPP_FINISHINGS_FOLD_POSTER | Fold the paper in half horizontally and vertically; sometimes also called a cross fold |
| IPP_FINISHINGS_FOLD_RIGHT_GATE | Fold the bottom quarter of the paper towards the midline |
| IPP_FINISHINGS_FOLD_Z | Fold the paper vertically into three sections, forming a Z |
| IPP_FINISHINGS_JOG_OFFSET | Offset for binding (any type) |
| IPP_FINISHINGS_LAMINATE | Apply protective (solid) material |
| IPP_FINISHINGS_NONE | No finishing |
| IPP_FINISHINGS_PUNCH | Punch (any location/count) |
| IPP_FINISHINGS_PUNCH_BOTTOM_LEFT | Punch 1 hole bottom left |
| IPP_FINISHINGS_PUNCH_BOTTOM_RIGHT | Punch 1 hole bottom right |
| IPP_FINISHINGS_PUNCH_DUAL_BOTTOM | Punch 2 holes bottom edge |
| IPP_FINISHINGS_PUNCH_DUAL_LEFT | Punch 2 holes left side |
| IPP_FINISHINGS_PUNCH_DUAL_RIGHT | Punch 2 holes right side |
| IPP_FINISHINGS_PUNCH_DUAL_TOP | Punch 2 holes top edge |
| IPP_FINISHINGS_PUNCH_MULTIPLE_BOTTOM | Punch multiple holes bottom edge |
| IPP_FINISHINGS_PUNCH_MULTIPLE_LEFT | Punch multiple holes left side |
| IPP_FINISHINGS_PUNCH_MULTIPLE_RIGHT | Punch multiple holes right side |
| IPP_FINISHINGS_PUNCH_MULTIPLE_TOP | Punch multiple holes top edge |
| IPP_FINISHINGS_PUNCH_QUAD_BOTTOM | Punch 4 holes bottom edge |
| IPP_FINISHINGS_PUNCH_QUAD_LEFT | Punch 4 holes left side |
| IPP_FINISHINGS_PUNCH_QUAD_RIGHT | Punch 4 holes right side |
| IPP_FINISHINGS_PUNCH_QUAD_TOP | Punch 4 holes top edge |
| IPP_FINISHINGS_PUNCH_TOP_LEFT | Punch 1 hole top left |
| IPP_FINISHINGS_PUNCH_TOP_RIGHT | Punch 1 hole top right |
| IPP_FINISHINGS_PUNCH_TRIPLE_BOTTOM | Punch 3 holes bottom edge |
| IPP_FINISHINGS_PUNCH_TRIPLE_LEFT | Punch 3 holes left side |
| IPP_FINISHINGS_PUNCH_TRIPLE_RIGHT | Punch 3 holes right side |
| IPP_FINISHINGS_PUNCH_TRIPLE_TOP | Punch 3 holes top edge |
| IPP_FINISHINGS_SADDLE_STITCH | Staple interior |
| IPP_FINISHINGS_STAPLE | Staple (any location/method) |
| IPP_FINISHINGS_STAPLE_BOTTOM_LEFT | Staple bottom left corner |
| IPP_FINISHINGS_STAPLE_BOTTOM_RIGHT | Staple bottom right corner |
| IPP_FINISHINGS_STAPLE_DUAL_BOTTOM | Two staples on bottom |
| IPP_FINISHINGS_STAPLE_DUAL_LEFT | Two staples on left |
| IPP_FINISHINGS_STAPLE_DUAL_RIGHT | Two staples on right |
| IPP_FINISHINGS_STAPLE_DUAL_TOP | Two staples on top |
| IPP_FINISHINGS_STAPLE_TOP_LEFT | Staple top left corner |
| IPP_FINISHINGS_STAPLE_TOP_RIGHT | Staple top right corner |
| IPP_FINISHINGS_STAPLE_TRIPLE_BOTTOM | Three staples on bottom |
| IPP_FINISHINGS_STAPLE_TRIPLE_LEFT | Three staples on left |
| IPP_FINISHINGS_STAPLE_TRIPLE_RIGHT | Three staples on right |
| IPP_FINISHINGS_STAPLE_TRIPLE_TOP | Three staples on top |
| IPP_FINISHINGS_TRIM | Trim (any type) |
| IPP_FINISHINGS_TRIM_AFTER_COPIES | Trim output after each copy |
| IPP_FINISHINGS_TRIM_AFTER_DOCUMENTS | Trim output after each document |
| IPP_FINISHINGS_TRIM_AFTER_JOB | Trim output after job |
| IPP_FINISHINGS_TRIM_AFTER_PAGES | Trim output after each page |
"job-state" values
+| IPP_JSTATE_ABORTED | Job has aborted due to error |
|---|---|
| IPP_JSTATE_CANCELED | Job has been canceled |
| IPP_JSTATE_COMPLETED | Job has completed successfully |
| IPP_JSTATE_HELD | Job is held for printing |
| IPP_JSTATE_PENDING | Job is waiting to be printed |
| IPP_JSTATE_PROCESSING | Job is currently printing |
| IPP_JSTATE_STOPPED | Job has been stopped |
IPP operations
+| IPP_OP_ACKNOWLEDGE_ENCRYPTED_JOB_ATTRIBUTES | Acknowledge-Encrypted-Job-Attributes: Acknowledge receipt of encrypted job attributes |
|---|---|
| IPP_OP_ALLOCATE_PRINTER_RESOURCES | Allocate-Printer-Resources: Use resources for a printer. |
| IPP_OP_CANCEL_CURRENT_JOB | Cancel-Current-Job: Cancel the current job |
| IPP_OP_CANCEL_JOB | Cancel-Job: Cancel a job |
| IPP_OP_CANCEL_JOBS | Cancel-Jobs: Cancel all jobs (administrative) |
| IPP_OP_CANCEL_MY_JOBS | Cancel-My-Jobs: Cancel a user's jobs |
| IPP_OP_CANCEL_RESOURCE | Cancel-Resource: Uninstall a resource. |
| IPP_OP_CANCEL_SUBSCRIPTION | Cancel-Subscription: Cancel a subscription |
| IPP_OP_CLOSE_JOB | Close-Job: Close a job and start printing |
| IPP_OP_CREATE_JOB | Create-Job: Create an empty print job |
| IPP_OP_CREATE_JOB_SUBSCRIPTIONS | Create-Job-Subscriptions: Create one of more job subscriptions |
| IPP_OP_CREATE_PRINTER | Create-Printer: Create a new service. |
| IPP_OP_CREATE_PRINTER_SUBSCRIPTIONS | Create-Printer-Subscriptions: Create one or more printer subscriptions |
| IPP_OP_CREATE_RESOURCE | Create-Resource: Create a new (empty) resource. |
| IPP_OP_CREATE_RESOURCE_SUBSCRIPTIONS | Create-Resource-Subscriptions: Create event subscriptions for a resource. |
| IPP_OP_CREATE_SYSTEM_SUBSCRIPTIONS | Create-System-Subscriptions: Create event subscriptions for a system. |
| IPP_OP_CUPS_ADD_MODIFY_CLASS | CUPS-Add-Modify-Class: Add or modify a class |
| IPP_OP_CUPS_ADD_MODIFY_PRINTER | CUPS-Add-Modify-Printer: Add or modify a printer |
| IPP_OP_CUPS_AUTHENTICATE_JOB | CUPS-Authenticate-Job: Authenticate a job |
| IPP_OP_CUPS_CREATE_LOCAL_PRINTER | CUPS-Create-Local-Printer: Create a local (temporary) printer |
| IPP_OP_CUPS_DELETE_CLASS | CUPS-Delete-Class: Delete a class |
| IPP_OP_CUPS_DELETE_PRINTER | CUPS-Delete-Printer: Delete a printer |
| IPP_OP_CUPS_GET_DEFAULT | CUPS-Get-Default: Get the default printer |
| IPP_OP_CUPS_GET_DEVICES DEPRECATED | CUPS-Get-Devices: Get a list of supported devices |
| IPP_OP_CUPS_GET_DOCUMENT | CUPS-Get-Document: Get a document file |
| IPP_OP_CUPS_GET_PPD DEPRECATED | CUPS-Get-PPD: Get a PPD file |
| IPP_OP_CUPS_GET_PPDS DEPRECATED | CUPS-Get-PPDs: Get a list of supported drivers |
| IPP_OP_CUPS_GET_PRINTERS | CUPS-Get-Printers: Get a list of printers and/or classes |
| IPP_OP_CUPS_INVALID | Invalid operation name for ippOpValue |
| IPP_OP_CUPS_MOVE_JOB | CUPS-Move-Job: Move a job to a different printer |
| IPP_OP_CUPS_SET_DEFAULT | CUPS-Set-Default: Set the default printer |
| IPP_OP_DEALLOCATE_PRINTER_RESOURCES | Deallocate-Printer-Resources: Stop using resources for a printer. |
| IPP_OP_DELETE_PRINTER | Delete-Printer: Delete an existing service. |
| IPP_OP_DISABLE_ALL_PRINTERS | Disable-All-Printers: Stop accepting new jobs on all services. |
| IPP_OP_DISABLE_PRINTER | Disable-Printer: Reject new jobs for a printer |
| IPP_OP_ENABLE_ALL_PRINTERS | Enable-All-Printers: Start accepting new jobs on all services. |
| IPP_OP_ENABLE_PRINTER | Enable-Printer: Accept new jobs for a printer |
| IPP_OP_FETCH_ENCRYPTED_JOB_ATTRIBUTES | Fetch-Encrypted-Job-Attributes: Download encrypted job attributes |
| IPP_OP_GET_ENCRYPTED_JOB_ATTRIBUTES | Get-Encrypted-Job-Attributes: Query job attributes and return in an encrypted form |
| IPP_OP_GET_JOBS | Get-Jobs: Get a list of jobs |
| IPP_OP_GET_JOB_ATTRIBUTES | Get-Job-Attribute: Get information about a job |
| IPP_OP_GET_NOTIFICATIONS | Get-Notifications: Get notification events |
| IPP_OP_GET_PRINTERS | Get-Printers: Get a list of services. |
| IPP_OP_GET_PRINTER_ATTRIBUTES | Get-Printer-Attributes: Get information about a printer |
| IPP_OP_GET_PRINTER_RESOURCES | Get-Printer-Resources: Get a list of resources for a printer |
| IPP_OP_GET_PRINTER_SUPPORTED_VALUES | Get-Printer-Supported-Values: Get supported values |
| IPP_OP_GET_SUBSCRIPTIONS | Get-Subscriptions: Get list of subscriptions |
| IPP_OP_GET_SUBSCRIPTION_ATTRIBUTES | Get-Subscription-Attributes: Get subscription information |
| IPP_OP_GET_SYSTEM_ATTRIBUTES | Get-System-Attributes: Get system object attributes. |
| IPP_OP_GET_SYSTEM_SUPPORTED_VALUES | Get-System-Supported-Values: Get supported values for system object attributes. |
| IPP_OP_GET_USER_PRINTER_ATTRIBUTES | Get-User-Printer-Attributes: Get printer capabilities with authentication |
| IPP_OP_HOLD_JOB | Hold-Job: Hold a job for printing |
| IPP_OP_HOLD_NEW_JOBS | Hold-New-Jobs: Hold new jobs |
| IPP_OP_IDENTIFY_PRINTER | Identify-Printer: Make the printer beep, flash, or display a message for identification |
| IPP_OP_INSTALL_RESOURCE | Install-Resource: Install a resource. |
| IPP_OP_PAUSE_ALL_PRINTERS | Pause-All-Printers: Stop all services immediately. |
| IPP_OP_PAUSE_ALL_PRINTERS_AFTER_CURRENT_JOB | Pause-All-Printers-After-Current-Job: Stop all services after processing the current jobs. |
| IPP_OP_PAUSE_PRINTER | Pause-Printer: Stop a printer |
| IPP_OP_PAUSE_PRINTER_AFTER_CURRENT_JOB | Pause-Printer-After-Current-Job: Stop printer after the current job |
| IPP_OP_PRINT_JOB | Print-Job: Print a single file |
| IPP_OP_PROMOTE_JOB | Promote-Job: Promote a job to print sooner |
| IPP_OP_REGISTER_OUTPUT_DEVICE | Register-Output-Device: Register a remote service. |
| IPP_OP_RELEASE_HELD_NEW_JOBS | Release-Held-New-Jobs: Release new jobs that were previously held |
| IPP_OP_RELEASE_JOB | Release-Job: Release a job for printing |
| IPP_OP_RENEW_SUBSCRIPTION | Renew-Subscription: Renew a printer subscription |
| IPP_OP_RESTART_JOB DEPRECATED | Restart-Job: Reprint a job |
| IPP_OP_RESTART_ONE_PRINTER | Restart-One-Printer: Restart a single printer/service |
| IPP_OP_RESTART_SYSTEM | Restart-System: Restart all services. |
| IPP_OP_RESUME_ALL_PRINTERS | Resume-All-Printers: Start job processing on all services. |
| IPP_OP_RESUME_JOB | Resume-Job: Resume the current job |
| IPP_OP_RESUME_PRINTER | Resume-Printer: Start a printer |
| IPP_OP_SCHEDULE_JOB_AFTER | Schedule-Job-After: Schedule a job to print after another |
| IPP_OP_SEND_DOCUMENT | Send-Document: Add a file to a job |
| IPP_OP_SEND_RESOURCE_DATA | Send-Resource-Data: Upload the data for a resource. |
| IPP_OP_SET_JOB_ATTRIBUTES | Set-Job-Attributes: Set job values |
| IPP_OP_SET_PRINTER_ATTRIBUTES | Set-Printer-Attributes: Set printer values |
| IPP_OP_SET_RESOURCE_ATTRIBUTES | Set-Resource-Attributes: Set resource object attributes. |
| IPP_OP_SET_SYSTEM_ATTRIBUTES | Set-System-Attributes: Set system object attributes. |
| IPP_OP_SHUTDOWN_ALL_PRINTERS | Shutdown-All-Printers: Shutdown all services. |
| IPP_OP_SHUTDOWN_ONE_PRINTER | Shutdown-One-Printer: Shutdown a service. |
| IPP_OP_STARTUP_ALL_PRINTERS | Startup-All-Printers: Startup all services. |
| IPP_OP_STARTUP_ONE_PRINTER | Startup-One-Printer: Start a service. |
| IPP_OP_SUSPEND_CURRENT_JOB | Suspend-Current-Job: Suspend the current job |
| IPP_OP_VALIDATE_JOB | Validate-Job: Validate job values prior to submission |
"orientation-requested" values
+| IPP_ORIENT_LANDSCAPE | 90 degrees counter-clockwise |
|---|---|
| IPP_ORIENT_NONE | No rotation |
| IPP_ORIENT_PORTRAIT | No rotation |
| IPP_ORIENT_REVERSE_LANDSCAPE | 90 degrees clockwise |
| IPP_ORIENT_REVERSE_PORTRAIT | 180 degrees |
"printer-state" values
+| IPP_PSTATE_IDLE | Printer is idle |
|---|---|
| IPP_PSTATE_PROCESSING | Printer is working |
| IPP_PSTATE_STOPPED | Printer is stopped |
"print-quality" values
+| IPP_QUALITY_DRAFT | Draft quality |
|---|---|
| IPP_QUALITY_HIGH | High quality |
| IPP_QUALITY_NORMAL | Normal quality |
Resolution units
+| IPP_RES_PER_CM | Pixels per centimeter |
|---|---|
| IPP_RES_PER_INCH | Pixels per inch |
"resource-state" values
+| IPP_RSTATE_ABORTED | Resource has been aborted and is pending deletion. |
|---|---|
| IPP_RSTATE_AVAILABLE | Resource is available for installation. |
| IPP_RSTATE_CANCELED | Resource has been canceled and is pending deletion. |
| IPP_RSTATE_INSTALLED | Resource is installed. |
| IPP_RSTATE_PENDING | Resource is created but has no data yet. |
"system-state" values
+| IPP_SSTATE_IDLE | At least one printer is idle and none are processing a job. |
|---|---|
| IPP_SSTATE_PROCESSING | At least one printer is processing a job. |
| IPP_SSTATE_STOPPED | All printers are stopped. |
ipp_t state values
| IPP_STATE_ATTRIBUTE | One or more attributes need to be sent/received |
|---|---|
| IPP_STATE_DATA | IPP request data needs to be sent/received |
| IPP_STATE_ERROR | An error occurred |
| IPP_STATE_HEADER | The request header needs to be sent/received |
| IPP_STATE_IDLE | Nothing is happening/request completed |
IPP status code values
+| IPP_STATUS_CUPS_INVALID | Invalid status name for ippErrorValue |
|---|---|
| IPP_STATUS_ERROR_ACCOUNT_AUTHORIZATION_FAILED | client-error-account-authorization-failed |
| IPP_STATUS_ERROR_ACCOUNT_CLOSED | client-error-account-closed |
| IPP_STATUS_ERROR_ACCOUNT_INFO_NEEDED | client-error-account-info-needed |
| IPP_STATUS_ERROR_ACCOUNT_LIMIT_REACHED | client-error-account-limit-reached |
| IPP_STATUS_ERROR_ATTRIBUTES_NOT_SETTABLE | client-error-attributes-not-settable |
| IPP_STATUS_ERROR_ATTRIBUTES_OR_VALUES | client-error-attributes-or-values-not-supported |
| IPP_STATUS_ERROR_BAD_REQUEST | client-error-bad-request |
| IPP_STATUS_ERROR_BUSY | server-error-busy |
| IPP_STATUS_ERROR_CHARSET | client-error-charset-not-supported |
| IPP_STATUS_ERROR_COMPRESSION_ERROR | client-error-compression-error |
| IPP_STATUS_ERROR_COMPRESSION_NOT_SUPPORTED | client-error-compression-not-supported |
| IPP_STATUS_ERROR_CONFLICTING | client-error-conflicting-attributes |
| IPP_STATUS_ERROR_CUPS_AUTHENTICATION_CANCELED | cups-authentication-canceled - Authentication canceled by user |
| IPP_STATUS_ERROR_CUPS_PKI | cups-pki-error - Error negotiating a secure connection |
| IPP_STATUS_ERROR_CUPS_UPGRADE_REQUIRED | cups-upgrade-required - TLS upgrade required |
| IPP_STATUS_ERROR_DEVICE | server-error-device-error |
| IPP_STATUS_ERROR_DOCUMENT_ACCESS | client-error-document-access-error |
| IPP_STATUS_ERROR_DOCUMENT_FORMAT_ERROR | client-error-document-format-error |
| IPP_STATUS_ERROR_DOCUMENT_FORMAT_NOT_SUPPORTED | client-error-document-format-not-supported |
| IPP_STATUS_ERROR_DOCUMENT_PASSWORD | client-error-document-password-error |
| IPP_STATUS_ERROR_DOCUMENT_PERMISSION | client-error-document-permission-error |
| IPP_STATUS_ERROR_DOCUMENT_SECURITY | client-error-document-security-error |
| IPP_STATUS_ERROR_DOCUMENT_UNPRINTABLE | client-error-document-unprintable-error |
| IPP_STATUS_ERROR_FORBIDDEN | client-error-forbidden |
| IPP_STATUS_ERROR_GONE | client-error-gone |
| IPP_STATUS_ERROR_IGNORED_ALL_SUBSCRIPTIONS | client-error-ignored-all-subscriptions |
| IPP_STATUS_ERROR_INTERNAL | server-error-internal-error |
| IPP_STATUS_ERROR_JOB_CANCELED | server-error-job-canceled |
| IPP_STATUS_ERROR_MULTIPLE_JOBS_NOT_SUPPORTED | server-error-multiple-document-jobs-not-supported |
| IPP_STATUS_ERROR_NOT_ACCEPTING_JOBS | server-error-not-accepting-jobs |
| IPP_STATUS_ERROR_NOT_AUTHENTICATED | client-error-not-authenticated |
| IPP_STATUS_ERROR_NOT_AUTHORIZED | client-error-not-authorized |
| IPP_STATUS_ERROR_NOT_FETCHABLE | client-error-not-fetchable |
| IPP_STATUS_ERROR_NOT_FOUND | client-error-not-found |
| IPP_STATUS_ERROR_NOT_POSSIBLE | client-error-not-possible |
| IPP_STATUS_ERROR_OPERATION_NOT_SUPPORTED | server-error-operation-not-supported |
| IPP_STATUS_ERROR_PRINTER_IS_DEACTIVATED | server-error-printer-is-deactivated |
| IPP_STATUS_ERROR_REQUEST_ENTITY | client-error-request-entity-too-large |
| IPP_STATUS_ERROR_REQUEST_VALUE | client-error-request-value-too-long |
| IPP_STATUS_ERROR_SERVICE_UNAVAILABLE | server-error-service-unavailable |
| IPP_STATUS_ERROR_TEMPORARY | server-error-temporary-error |
| IPP_STATUS_ERROR_TIMEOUT | client-error-timeout |
| IPP_STATUS_ERROR_TOO_MANY_DOCUMENTS | server-error-too-many-documents |
| IPP_STATUS_ERROR_TOO_MANY_JOBS | server-error-too-many-jobs |
| IPP_STATUS_ERROR_TOO_MANY_SUBSCRIPTIONS | client-error-too-many-subscriptions |
| IPP_STATUS_ERROR_URI_SCHEME | client-error-uri-scheme-not-supported |
| IPP_STATUS_ERROR_VERSION_NOT_SUPPORTED | server-error-version-not-supported |
| IPP_STATUS_OK | successful-ok |
| IPP_STATUS_OK_CONFLICTING | successful-ok-conflicting-attributes |
| IPP_STATUS_OK_EVENTS_COMPLETE | successful-ok-events-complete |
| IPP_STATUS_OK_IGNORED_OR_SUBSTITUTED | successful-ok-ignored-or-substituted-attributes |
| IPP_STATUS_OK_IGNORED_SUBSCRIPTIONS | successful-ok-ignored-subscriptions |
| IPP_STATUS_OK_TOO_MANY_EVENTS | successful-ok-too-many-events |
Value and group tag values for attributes
+| IPP_TAG_ADMINDEFINE | Admin-defined value |
|---|---|
| IPP_TAG_BOOLEAN | Boolean value |
| IPP_TAG_CHARSET | Character set value |
| IPP_TAG_CUPS_INVALID | Invalid tag name for ippTagValue |
| IPP_TAG_DATE | Date/time value |
| IPP_TAG_DEFAULT | Default value |
| IPP_TAG_DELETEATTR | Delete-attribute value |
| IPP_TAG_DOCUMENT | Document group |
| IPP_TAG_END | End-of-attributes |
| IPP_TAG_ENUM | Enumeration value |
| IPP_TAG_EVENT_NOTIFICATION | Event group |
| IPP_TAG_INTEGER | Integer value |
| IPP_TAG_JOB | Job group |
| IPP_TAG_KEYWORD | Keyword value |
| IPP_TAG_LANGUAGE | Language value |
| IPP_TAG_MIMETYPE | MIME media type value |
| IPP_TAG_NAME | Name value |
| IPP_TAG_NAMELANG | Name-with-language value |
| IPP_TAG_NOTSETTABLE | Not-settable value |
| IPP_TAG_NOVALUE | No-value value |
| IPP_TAG_OPERATION | Operation group |
| IPP_TAG_PRINTER | Printer group |
| IPP_TAG_RANGE | Range value |
| IPP_TAG_RESOLUTION | Resolution value |
| IPP_TAG_RESOURCE | Resource group |
| IPP_TAG_STRING | Octet string value |
| IPP_TAG_SUBSCRIPTION | Subscription group |
| IPP_TAG_SYSTEM | System group |
| IPP_TAG_TEXT | Text value |
| IPP_TAG_TEXTLANG | Text-with-language value |
| IPP_TAG_UNKNOWN | Unknown value |
| IPP_TAG_UNSUPPORTED_GROUP | Unsupported attributes group |
| IPP_TAG_UNSUPPORTED_VALUE | Unsupported value |
| IPP_TAG_URI | URI value |
| IPP_TAG_URISCHEME | URI scheme value |
| IPP_TAG_ZERO | Zero tag - used for separators |
ippeveprinter - an ipp everywhere printer application for cups +
+ippeveprinter +[ +--help +] [ +--no-web-forms +] [ +--pam-service +service +] [ +--version +] [ +-2 +] [ +-A +] [ +-D +device-uri +] [ +-F +output-type/subtype +] [ +-K +keypath +] [ +-M +manufacturer +] [ +-V +ipp-version +] [ +-a +filename.conf +] [ +-c +command +] [ +-d +spool-directory +] [ +-f +type/subtype[,...] +] [ +-i +iconfile.png +] [ +-k +] [ +-l +location +] [ +-m +model +] [ +-n +hostname +] [ +-p +port +] [ +-r +subtype[,subtype] +] [ +-s +speed[,color-speed] +] [ +-v[vvv] +] +service-name +
+ippeveprinter +is a simple Internet Printing Protocol (IPP) server conforming to the IPP Everywhere (PWG 5100.14) specification. It can be used to test client software or act as a very basic print server that runs a command for every job that is printed. +
+The following options are recognized by +ippeveprinter: +
+--help
+Show program usage.
+
--no-web-forms
+Disable the web interface forms used to update the media and supply levels.
+
--pam-service service
+Set the PAM service name.
+The default service is "cups".
+
--version
+Show the CUPS version.
+
-2
+Report support for two-sided (duplex) printing.
+
-A
+Enable authentication for the created printer.
+ippeveprinter
+uses PAM to authenticate HTTP Basic credentials.
+
-D device-uri
+Set the device URI for print output.
+The URI can be a filename, directory, or a network socket URI of the form "socket://ADDRESS[:PORT]" (where the default port number is 9100).
+When specifying a directory,
+ippeveprinter
+will create an output file using the job ID and name.
+
-F output-type/subtype[,...]
+Specifies the output MIME media type.
+The default is "application/postscript" when the -P option is specified.
+
-M manufacturer
+Set the manufacturer of the printer.
+The default is "Example".
+
-V 1.1
+
-V 2.0
+Specifies the maximum IPP version to report.
+2.0 is the default.
+
-c command
+Run the specified command for each document that is printed.
+
-d spool-directory
+Specifies the directory that will hold the print files.
+The default is a directory under the user's current temporary directory.
+
-f type/subtype[,...]
+Specifies a list of MIME media types that the server will accept.
+The default depends on the type of printer created.
+
-i iconfile.png
+Specifies the printer icon file for the server.
+The file must be a PNG format image.
+The default is an internally-provided PNG image.
+
-k
+Keeps the print documents in the spool directory rather than deleting them.
+
-l location
+Specifies the human-readable location string that is reported by the server.
+The default is the empty string.
+
-m model
+Specifies the model name of the printer.
+The default is "Printer".
+
-n hostname
+Specifies the hostname that is reported by the server.
+The default is the name returned by the
+hostname(1)
+
+command.
+
-p port
+Specifies the port number to listen on.
+The default is a user-specific number from 8000 to 8999.
+
-r off
+Turns off DNS-SD service advertisements entirely.
+
-r subtype[,subtype]
+Specifies the DNS-SD subtype(s) to advertise.
+Separate multiple subtypes with a comma.
+The default is "_print".
+
-s speed[,color-speed]
+Specifies the printer speed in pages per minute.
+If two numbers are specified and the second number is greater than zero, the server will report support for color printing.
+The default is "10,0".
+
-v[vvv]
+Be (very) verbose when logging activity to standard error.
+
The +ippeveprinter +program returns 1 if it is unable to process the command-line arguments or register the IPP service. +Otherwise +ippeveprinter +will run continuously until terminated. +
+The +ippeveprinter +program is unique to CUPS and conforms to the IPP Everywhere (PWG 5100.14) specification. +
+ippeveprinter +adds environment variables starting with "IPP_" for all IPP Job attributes in the print request. +For example, when executing a command for an IPP Job containing the "media" Job Template attribute, the "IPP_MEDIA" environment variable will be set to the value of that attribute. +
+In addition, all IPP "xxx-default" and "pwg-xxx" Printer Description attributes are added to the environment. +For example, the "IPP_MEDIA_DEFAULT" environment variable will be set to the default value for the "media" Job Template attribute. +
+Enumerated values are converted to their keyword equivalents. +For example, a "print-quality" Job Template attribute with a enum value of 3 will become the "IPP_PRINT_QUALITY" environment variable with a value of "draft". +This string conversion only happens for standard Job Template attributes, currently "finishings", "orientation-requested", and "print-quality". +
+Finally, the "CONTENT_TYPE" environment variable contains the MIME media type of the document being printed, the "DEVICE_URI" environment variable contains the device URI as specified with the "-D" option, the "OUTPUT_FORMAT" environment variable contains the output MIME media type, and the "PPD" environment variable contains the PPD filename as specified with the "-P" option. +
+Unless they communicate directly with a printer, print commands send printer-ready data to the standard output. +
+Print commands can send messages back to +ippeveprinter +on the standard error with one of the following prefixes: +
+ATTR: attribute=value[ attribute=value]
+Sets the named attribute(s) to the given values.
+Currently only the "job-impressions" and "job-impressions-completed" Job Status attributes and the "marker-xxx", "printer-alert", "printer-alert-description", "printer-supply", and "printer-supply-description" Printer Status attributes can be set.
+
DEBUG: Debugging message
+Logs a debugging message if at least two -v's have been specified.
+
ERROR: Error message
+Logs an error message and copies the message to the "job-state-message" attribute.
+
INFO: Informational message
+Logs an informational/progress message if -v has been specified and copies the message to the "job-state-message" attribute unless an error has been reported.
+
STATE: keyword[,keyword,...]
+Sets the printer's "printer-state-reasons" attribute to the listed keywords.
+
STATE: -keyword[,keyword,...]
+Removes the listed keywords from the printer's "printer-state-reasons" attribute.
+
STATE: +keyword[,keyword,...]
+Adds the listed keywords to the printer's "printer-state-reasons" attribute.
+
Run +ippeveprinter +with a service name of My Cool Printer: +
++ ippeveprinter "My Cool Printer" ++
Run the +file(1) + +command whenever a job is sent to the server: +
++ ippeveprinter -c /usr/bin/file "My Cool Printer" ++
ippevepcl(1), + +ippeveps(1), + +ipptransform(1), + +PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp) +
+Copyright © 2021-2023 by OpenPrinting. + + diff --git a/libcups/ippfind.html b/libcups/ippfind.html new file mode 100644 index 0000000000..62fbdf0ae6 --- /dev/null +++ b/libcups/ippfind.html @@ -0,0 +1,334 @@ + + +
+ + +ippfind - find internet printing protocol printers +
+ippfind
+[
+options
+] regtype[,subtype][.domain.] ... [
+expression
+ ... ]
+
+ippfind
+[
+options
+] name[.regtype[.domain.]] ... [
+expression
+ ... ]
+
+ippfind
+--help
+
+ippfind
+--version
+
ippfind finds services registered with a DNS server or available through local devices. +Its primary purpose is to find IPP printers and show their URIs, show their current status, or run commands. +
+ippfind supports the following registration types: +
+_http._tcp
+HyperText Transport Protocol (HTTP, RFC 2616)
+
_https._tcp
+Secure HyperText Transport Protocol (HTTPS, RFC 2818)
+
_ipp._tcp
+Internet Printing Protocol (IPP, RFC 2911)
+
_ipps._tcp
+Secure Internet Printing Protocol (IPPS, draft)
+
_printer._tcp
+Line Printer Daemon (LPD, RFC 1179)
+
ippfind supports expressions much like the +find(1) + +utility. +However, unlike +find(1), + +ippfind uses POSIX regular expressions instead of shell filename matching patterns. +If --exec, -l, --ls, -p, --print, --print-name, -q, --quiet, -s, or -x is not specified, ippfind adds --print to print the service URI of anything it finds. +The following expressions are supported: +
+-d regex
+
--domain regex
+True if the domain matches the given regular expression.
+
--false
+Always false.
+
-h regex
+
--host regex
+True is the hostname matches the given regular expression.
+
-l
+
--ls
+Lists attributes returned by Get-Printer-Attributes for IPP printers and traditional find "-ls" output for HTTP URLs.
+The result is true if the URI is accessible, false otherwise.
+
--local
+True if the service is local to this computer.
+
-N name
+
--literal-name name
+True if the service instance name matches the given name.
+
-n regex
+
--name regex
+True if the service instance name matches the given regular expression.
+
--path regex
+True if the URI resource path matches the given regular expression.
+
-P number[-number]
+
--port number[-number]
+True if the port matches the given number or range.
+
-p
+
--print
+Prints the URI if the result of previous expressions is true.
+The result is always true.
+
-q
+
--quiet
+Quiet mode - just returns the exit codes below.
+
-r
+
--remote
+True if the service is not local to this computer.
+
-s
+
--print-name
+Prints the service instance name if the result of previous expressions is true.
+The result is always true.
+
--true
+Always true.
+
-t key
+
--txt key
+True if the TXT record contains the named key.
+
--txt-key regex
+True if the TXT record contains the named key and matches the given regular expression.
+
-u regex
+
--uri regex
+True if the URI matches the given regular expression.
+
-x utility [ argument ... ] ;
+
--exec utility [ argument ... ] ;
+Executes the specified program if the current result is true.
+"{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below.
+
Expressions may also contain modifiers: +
+( expression )
+Group the result of expressions.
+
! expression
+
--not expression
+Unary NOT of the expression.
+
expression expression
+
expression --and expression
+Logical AND of expressions.
+
expression --or expression
+Logical OR of expressions.
+
The substitutions for "{foo}" in -e and --exec are: +
+{service_domain}
+Domain name, e.g., "example.com.", "local.", etc.
+
{service_hostname}
+Fully-qualified domain name, e.g., "printer.example.com.", "printer.local.", etc.
+
{service_name}
+Service instance name, e.g., "My Fine Printer".
+
{service_port}
+Port number for server, typically 631 for IPP and 80 for HTTP.
+
{service_regtype}
+DNS-SD registration type, e.g., "_ipp._tcp", "_http._tcp", etc.
+
{service_scheme}
+URI scheme for DNS-SD registration type, e.g., "ipp", "http", etc.
+
{}
+
{service_uri}
+URI for service, e.g., "ipp://printer.local./ipp/print", "http://printer.local./", etc.
+
{txt_key}
+Value of TXT record key (lowercase).
+
ippfind supports the following options: +
+--help
+Show program help.
+
--version
+Show program version.
+
-4
+Use IPv4 when listing.
+
-6
+Use IPv6 when listing.
+
-T seconds
+Specify find timeout in seconds.
+If 1 or less, ippfind stops as soon as it thinks it has found everything.
+The default timeout is 1 second.
+
-V version
+Specifies the IPP version when listing.
+Supported values are "1.1", "2.0", "2.1", and "2.2".
+
ippfind returns 0 if the result for all processed expressions is true, 1 if the result of any processed expression is false, 2 if browsing or any query or resolution failed, 3 if an undefined option or invalid expression was specified, and 4 if it ran out of memory. +
+When executing a program, ippfind sets the following environment variables for the matching service registration: +
+IPPFIND_SERVICE_DOMAIN
+Domain name, e.g., "example.com.", "local.", etc.
+
IPPFIND_SERVICE_HOSTNAME
+Fully-qualified domain name, e.g., "printer.example.com.", "printer.local.", etc.
+
IPPFIND_SERVICE_NAME
+Service instance name, e.g., "My Fine Printer".
+
IPPFIND_SERVICE_PORT
+Port number for server, typically 631 for IPP and 80 for HTTP.
+
IPPFIND_SERVICE_REGTYPE
+DNS-SD registration type, e.g., "_ipp._tcp", "_http._tcp", etc.
+
IPPFIND_SERVICE_SCHEME
+URI scheme for DNS-SD registration type, e.g., "ipp", "http", etc.
+
IPPFIND_SERVICE_URI
+URI for service, e.g., "ipp://printer.local./ipp/print", "http://printer.local./", etc.
+
IPPFIND_TXT_KEY
+Values of TXT record KEY (uppercase).
+
To show the status of all registered IPP printers on your network, run: +
++ ippfind --ls + ++
Similarly, to send a PostScript test page to every PostScript printer, run: +
+
+ ippfind --txt-pdl application/postscript --exec ipptool
+ -f onepage-letter.ps '{}' print-job.test \;
+
+ ipptool(1)
+ + +Copyright © 2021-2023 by OpenPrinting. + + diff --git a/libcups/ipptool.html b/libcups/ipptool.html new file mode 100644 index 0000000000..94bcb17fb7 --- /dev/null +++ b/libcups/ipptool.html @@ -0,0 +1,338 @@ + + +
+ + +ipptool - perform internet printing protocol requests +
+ipptool +[ +--help +] [ +--ippserver +filename +] [ +--stop-after-include-error +] [ +--version +] [ +-4 +] [ +-6 +] [ +-C +] [ +-E +] [ +-I +] [ +-L +] [ +-P +filename.plist +] [ +-S +] [ +-T +seconds +] [ +-V +version +] [ +-X +] [ +-c +] [ +-d +name=value +] [ +-f +filename +] [ +-h +] [ +-i +seconds +] [ +-j +] [ +-n +repeat-count +] [ +-q +] [ +-t +] [ +-v ] +printer-uri +testfile +[ ... +testfile +] +
+ipptool +sends IPP requests to the specified +printer-uri +and tests and/or displays the results. +Each named +testfile +defines one or more requests, including the expected response status, attributes, and values. +Output is either a plain text, formatted text, CSV, or XML report on the standard output, with a non-zero exit status indicating that one or more tests have failed. +The +testfile +format is described in +ipptoolfile(5). + +
+The following options are recognized by +ipptool: +
+--help
+Shows program help.
+
--ippserver filename
+Specifies that the test results should be written to the named
+ippserver
+attributes file.
+
--stop-after-include-error
+Tells
+ipptool
+to stop if an error occurs in an included file. Normally
+ipptool
+will continue with subsequent tests after the INCLUDE directive.
+
--version
+Shows the version of
+ipptool
+being used.
+
-4
+Specifies that
+ipptool
+must connect to the printer or server using IPv4.
+
-6
+Specifies that
+ipptool
+must connect to the printer or server using IPv6.
+
-C
+Specifies that requests should be sent using the HTTP/1.1 "Transfer-Encoding: chunked" header, which is required for conformance by all versions of IPP.
+The default is to use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files.
+
-E
+Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
+
-I
+Specifies that
+ipptool
+will continue past errors.
+
-L
+Specifies that requests should be sent using the HTTP/1.0 "Content-Length:" header, which is required for conformance by all versions of IPP.
+The default is to use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files.
+
-P filename.plist
+
+Specifies that the test results should be written to the named XML (Apple plist) file in addition to the regular test report (-t).
+This option is incompatible with the -i (interval) and -n (repeat-count) options.
+
-S
+Forces (dedicated) TLS encryption when connecting to the server.
+
-T seconds
+
+Specifies a timeout for IPP requests in seconds.
+
-V version
+
+Specifies the default IPP version to use: 1.0, 1.1, 2.0, 2.1, or 2.2. If not specified, version 1.1 is used.
+
-X
+Specifies that XML (Apple plist) output is desired instead of the plain text report.
+This option is incompatible with the -i (interval) and -n (repeat-count) options.
+
-c
+Specifies that CSV (comma-separated values) output is desired instead of the plain text output.
+
-d name=value
+
+Defines the named variable.
+
-f filename
+
+Defines the default request filename for tests.
+
-h
+Validate HTTP response headers.
+
-i seconds
+
+Specifies that the (last)
+testfile
+should be repeated at the specified interval.
+This option is incompatible with the -X (XML plist output) option.
+
-j
+Specifies that
+ipptool
+will produce JSON output.
+
-l
+Specifies that plain text output is desired.
+
-n repeat-count
+
+Specifies that the (last)
+testfile
+should be repeated the specified number of times.
+This option is incompatible with the -X (XML plist output) option.
+
-q
+Be quiet and produce no output.
+
-t
+Specifies that CUPS test report output is desired instead of the plain text output.
+
-v
+Specifies that all request and response attributes should be output in CUPS test mode (-t).
+This is the default for XML output.
+
The +ipptool +program returns 0 if all tests were successful and 1 otherwise. +
+The following standard files are available: +
++ color.jpg + create-printer-subscription.test + document-a4.pdf + document-a4.ps + document-letter.pdf + document-letter.ps + get-completed-jobs.test + get-jobs.test + get-notifications.test + get-printer-attributes.test + get-subscriptions.test + gray.jpg + ipp-1.1.test + ipp-2.0.test + ipp-2.1.test + ipp-2.2.test + ipp-everywhere.test + onepage-a4.pdf + onepage-a4.ps + onepage-letter.pdf + onepage-letter.ps + print-job.test + print-job-deflate.test + print-job-gzip.test + testfile.jpg + testfile.pcl + testfile.pdf + testfile.ps + testfile.txt + validate-job.test ++
The +ipptool +program is unique to CUPS and conforms to the Internet Printing Protocol up to version 2.2. +
+Get a list of completed jobs for "myprinter": +
++ ipptool ipp://localhost/printers/myprinter get-completed-jobs.test ++
Send email notifications to "user@example.com" when "myprinter" changes: +
++ ipptool -d recipient=mailto:user@example.com \ + ipp://localhost/printers/myprinter create-printer-subscription.test ++
ipptoolfile(5),
+ +IANA IPP Registry (https://www.iana.org/assignments/ipp-registrations), +PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp), +RFC 8011 (https://datatracker.ietf.org/doc/html/rfc8011) + +Copyright © 2021-2023 by OpenPrinting. + + diff --git a/libcups/ipptoolfile.html b/libcups/ipptoolfile.html new file mode 100644 index 0000000000..66542b5cf6 --- /dev/null +++ b/libcups/ipptoolfile.html @@ -0,0 +1,978 @@ + + +
+ + +ipptoolfile - ipptool file format +
+The +ipptool(1) + +program accepts free-form plain text files that describe one or more IPP requests. +Comments start with the "#" character and continue to the end of the line. +Each request is enclosed by curly braces, for example: +
+
+ # This is a comment
+ {
+ # The name of the test
+ NAME "Print PDF File"
+
+ # The request to send
+ OPERATION Print-Job
+
+ GROUP operation-attributes-tag
+ ATTR charset attributes-charset utf-8
+ ATTR language attributes-natural-language en
+ ATTR uri printer-uri $uri
+ ATTR name requesting-user-name $user
+ ATTR mimeMediaType document-format application/pdf
+
+ GROUP job-attributes-tag
+ ATTR collection media-col {
+ # US Letter plain paper from the "main" tray
+ MEMBER collection media-size {
+ MEMBER integer x-dimension 21590
+ MEMBER integer y-dimension 27940
+ }
+ MEMBER integer media-top-margin 423
+ MEMBER integer media-bottom-margin 423
+ MEMBER integer media-left-margin 423
+ MEMBER integer media-right-margin 423
+ MEMBER keyword media-source "main"
+ MEMBER keyword media-type "stationery"
+ }
+
+ FILE testfile.pdf
+
+ # The response to expect
+ STATUS successful-ok
+ EXPECT job-id OF-TYPE integer WITH-VALUE >0
+ EXPECT job-uri OF-TYPE uri
+ }
+ {
+ # The name of the test
+ NAME "Wait for Job to Complete"
+
+ # The request to send
+ OPERATION Get-Job-Attributes
+
+ GROUP operation-attributes-tag
+ ATTR charset attributes-charset utf-8
+ ATTR language attributes-natural-language en
+ ATTR uri printer-uri $uri
+ ATTR integer job-id $job-id
+ ATTR name requesting-user-name $user
+
+ # The response to expect
+ STATUS successful-ok
+ EXPECT job-id OF-TYPE integer WITH-VALUE $job-id
+ EXPECT job-uri OF-TYPE uri
+ EXPECT job-state OF-TYPE enum WITH-VALUE >5 REPEAT-NO-MATCH
+ EXPECT job-originating-user-name OF-TYPE name WITH-VALUE "$user"
+
+ # Show the job state until completed...
+ DISPLAY job-state
+ DISPLAY job-state-reasons
+ }
+
+ The following directives can be used outside of a test: +
+{ test }
+Defines a test.
+
DEFINE variable-name value
+Defines the named variable to the given value. This is equivalent to specifying -d variable-name=value on the
+ipptool(8)
+
+command-line.
+
DEFINE-DEFAULT variable-name value
+Defines the named variable to the given value if it does not already have a value.
+
FILE-ID "identifier"
+Specifies an identifier string for the current file.
+
IGNORE-ERRORS yes
+
IGNORE-ERRORS no
+Specifies whether, by default,
+ipptool(8)
+
+will ignore errors and continue with subsequent tests.
+
INCLUDE "filename"
+
INCLUDE <filename>
+Includes another test file. The first form includes a file relative to the current test file, while the second form includes a file from the
+ipptool(8)
+
+include directory.
+
INCLUDE-IF-DEFINED name "filename"
+
INCLUDE-IF-DEFINED name <filename>
+Includes another test file if the named variable is defined. The first form includes a file relative to the current test file, while the second form includes a file from the
+ipptool(8)
+
+include directory.
+
INCLUDE-IF-NOT-DEFINED name "filename"
+
INCLUDE-IF-NOT-DEFINED name <filename>
+Includes another test file if the named variable is not defined. The first form includes a file relative to the current test file, while the second form includes a file from the
+ipptool(8)
+
+include directory.
+
SKIP-IF-DEFINED variable-name
+
SKIP-IF-NOT-DEFINED variable-name
+Specifies that the remainder of the test file should be skipped when the variable is or is not defined.
+
STOP-AFTER-INCLUDE-ERROR no
+
STOP-AFTER-INCLUDE-ERROR yes
+Specifies whether tests will be stopped after an error in an included file.
+
TRANSFER auto
+Specifies that tests will, by default, use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files.
+
TRANSFER chunked
+Specifies that tests will, by default, use the HTTP/1.1 "Transfer-Encoding: chunked" header. This is the default and is equivalent to specifying -c on the
+ipptool(8)
+
+command-line. Support for chunked requests is required for conformance with all versions of IPP.
+
TRANSFER length
+Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:" header. This is equivalent to specifying -l on the
+ipptool(8)
+
+command-line. Support for content length requests is required for conformance with all versions of IPP.
+
VERSION 1.0
+
VERSION 1.1
+
VERSION 2.0
+
VERSION 2.1
+
VERSION 2.2
+Specifies the default IPP version number to use for the tests that follow.
+
The following directives are understood within a test: +
+ATTR out-of-band-tag attribute-name
+
ATTR tag attribute-name value(s)
+Adds an attribute to the test request.
+Out-of-band tags (admin-define, delete-attribute, no-value, not-settable, unknown, unsupported) have no value.
+Values for other tags are delimited by the comma (",") character - escape commas using the "\" character.
+Common attributes and values are listed in the IANA IPP registry - see references below.
+
ATTR collection attribute-name { MEMBER tag member-name value(s) ... } [ ... ,{ ... } ]
+Adds a collection attribute to the test request.
+Member attributes follow the same syntax as regular attributes and can themselves be nested collections.
+Multiple collection values can be supplied as needed, separated by commas.
+
COMPRESSION deflate
+
COMPRESSION gzip
+
COMPRESSION none
+Uses the specified compression on the document data following the attributes in a Print-Job or Send-Document request.
+
DELAY seconds[,repeat-seconds]
+Specifies a delay in seconds before this test will be run.
+If two values are specified, the second value is used as the delay between repeated tests.
+
DISPLAY attribute-name
+Specifies that value of the named attribute should be output as part of the
+test report.
+
EXPECT attribute-name [ predicate(s) ]
+
EXPECT ?attribute-name predicate(s)
+
EXPECT !attribute-name
+Specifies that the response must/may/must not include the named attribute. Additional requirements can be added as predicates - see the "EXPECT PREDICATES" section for more information on predicates. Attribute names can specify member attributes by separating the attribute and member names with the forward slash, for example "media-col/media-size/x-dimension".
+
EXPECT-ALL attribute-name [ predicate(s) ]
+
EXPECT-ALL ?attribute-name predicate(s)
+Specifies that the response must/may include the named attribute and that all occurrences of that attribute must match the given predicates.
+
FILE filename
+Specifies a file to include at the end of the request. This is typically used when sending a test print file.
+
GENERATE-FILE { parameters }
+Specifies that
+ipptool
+should generate PWG or Apple raster data for the printer.
+See the "GENERATE-FILE PARAMETERS" section for information on the parameters you can specify.
+
GROUP tag
+Specifies the group tag for subsequent attributes in the request.
+
IGNORE-ERRORS yes
+
IGNORE-ERRORS no
+Specifies whether
+ipptool(8)
+
+will ignore errors and continue with subsequent tests.
+
MONITOR-PRINTER-STATE [ printer-uri ] { EXPECT attribute-name [ predicate(s) ] }
+Specifies printer state monitoring tests to run in parallel with the test operation.
+The monitoring tests will run until all of the EXPECT conditions are satisfied or the primary test operation has completed, whichever occurs first.
+
NAME "literal string"
+Specifies the human-readable name of the test.
+
OPERATION operation-code
+Specifies the operation to be performed.
+
PASS-IF-DEFINED variable-name
+
PASS-IF-NOT-DEFINED variable-name
+Specifies that the current test should be passed automatically when the variable is or is not defined.
+
PAUSE "message"
+Displays the provided message and waits for the user to press a key to continue.
+
REQUEST-ID number
+
REQUEST-ID random
+Specifies the request-id value to use in the request, either an integer or the word "random" to use a randomly generated value (the default).
+
RESOURCE path
+Specifies an alternate resource path that is used for the HTTP POST request. The default is the resource from the URI provided to the
+ipptool(8)
+
+program.
+
SKIP-IF-DEFINED variable-name
+
SKIP-IF-NOT-DEFINED variable-name
+Specifies that the current test should be skipped when the variable is or is not defined.
+
SKIP-PREVIOUS-ERROR yes
+
SKIP-PREVIOUS-ERROR no
+Specifies whether
+ipptool(8)
+
+will skip the current test if the previous test resulted in an error/failure.
+
STATUS status-code [ predicate ]
+Specifies an expected response status-code value. Additional requirements can be added as predicates - see the "STATUS PREDICATES" section for more information on predicates.
+
TEST-ID "identifier"
+Specifies an identifier string for the current test.
+
TRANSFER auto
+Specifies that this test will use "Transfer-Encoding: chunked" if it has an attached file or "Content-Length:" otherwise.
+
TRANSFER chunked
+Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked" header.
+
TRANSFER length
+Specifies that this test will use the HTTP/1.0 "Content-Length:" header.
+
VERSION 1.0
+
VERSION 1.1
+
VERSION 2.0
+
VERSION 2.1
+
VERSION 2.2
+Specifies the IPP version number to use for this test.
+
The following predicates are understood following the EXPECT test directive: +
+COUNT number
+Requires the EXPECT attribute to have the specified number of values.
+
DEFINE-MATCH variable-name
+Defines the variable to "1" when the EXPECT condition matches.
+A side-effect of this predicate is that this EXPECT will never fail a test.
+
DEFINE-NO-MATCH variable-name
+Defines the variable to "1" when the EXPECT condition does not match.
+A side-effect of this predicate is that this EXPECT will never fail a test.
+
DEFINE-VALUE variable-name
+Defines the variable to the value of the attribute when the EXPECT condition matches.
+A side-effect of this predicate is that this EXPECT will never fail a test.
+
DISPLAY-MATCH "message"
+Displays the specified message when the EXPECT condition matches.
+
IF-DEFINED variable-name
+Makes the EXPECT conditions apply only if the specified variable is defined.
+
IF-NOT-DEFINED variable-name
+Makes the EXPECT conditions apply only if the specified variable is not defined.
+
IN-GROUP tag
+Requires the EXPECT attribute to be in the specified group tag.
+
OF-TYPE tag[(limits)|tag|...]
+Requires the EXPECT attribute to use one of the specified value tag(s).
+Most value tags also support the specification of limits in parenthesis, for example "name(42)" would allow nameWith/WithoutLanguage strings up to 42 octets in length, "name(4:MAX)" would allow nameWith/WithoutLanguage strings between 4 and 255 octets in length, and "integer(-273:MAX)" would allow integers between -273 and 2147483647.
+
REPEAT-LIMIT number
+
+Specifies the maximum number of times to repeat if the REPEAT-MATCH or REPEAT-NO-MATCH predicate is specified. The default value is 1000.
+
REPEAT-MATCH
+
REPEAT-NO-MATCH
+Specifies that the current test should be repeated when the EXPECT condition matches or does not match.
+
SAME-COUNT-AS attribute-name
+Requires the EXPECT attribute to have the same number of values as the specified parallel attribute.
+
SAVE-CONTENT filespec
+
SAVE-ALL-CONTENT filespec
+Saves all "http" or "https" URI values to the specified location.
+The filespec value is a filename or directory path and can contain the special strings "%basename%" to insert the base filename from the URI, "%ext%" to insert the extension from the URI, and "%index%" to insert the value number starting at 1.
+
WITH-ALL-CONTENT available
+
WITH-CONTENT available
+Requires that all URI values be accessible.
+A "http" or "https" URI must respond to a GET request while a "ipp" or "ipps" URI must respond to a HEAD request.
+
WITH-ALL-CONTENT valid
+
WITH-CONTENT valid
+Requires that all "http" and "https" URI values be accessible and provide valid content.
+
WITH-ALL-CONTENT valid-icon
+
WITH-CONTENT valid-icon
+Requires that all "http" and "https" URI values be accessible and provide valid PNG images for icons - 48x48, 128x128, or 512x512 in size with transparency.
+
WITH-ALL-HOSTNAMES "literal string"
+
WITH-ALL-HOSTNAMES "/regular expression/"
+Requires that all URI values contain a matching hostname.
+
WITH-ALL-MIME-TYPES mime/type[,...,mime/type]
+
WITH-MIME-TYPES mime/type[,...,mime/type]
+Requires that all URI values provide one of the listed MIME media types.
+For non-content tests, the target Printer must respond to HTTP HEAD requests with the MIME media type that would be returned by a GET or POST requests.
+For "http" and "https" content tests,
+ipptool
+sends a HTTP GET request.
+For "ipp" and "ipps" content tests,
+ipptool
+sends an IPP Get-Printer-Attributes request.
+
WITH-ALL-RESOURCES "literal string"
+
WITH-ALL-RESOURCES "/regular expression/"
+Requires that all URI values contain a matching resource (including leading /).
+
WITH-ALL-SCHEMES "literal string"
+
WITH-ALL-SCHEMES "/regular expression/"
+Requires that all URI values contain a matching scheme.
+
WITH-ALL-VALUES "literal string"
+Requires that all values of the EXPECT attribute match the literal string. Comparisons are case-sensitive.
+
WITH-ALL-VALUES <number
+
WITH-ALL-VALUES =number
+
WITH-ALL-VALUES >number
+
WITH-ALL-VALUES number[,...,number]
+Requires that all values of the EXPECT attribute match the number(s) or numeric comparison. When comparing rangeOfInteger values, the "<" and ">" operators only check the upper bound of the range.
+
WITH-ALL-VALUES "false"
+
WITH-ALL-VALUES "true"
+Requires that all values of the EXPECT attribute match the boolean value given.
+
WITH-ALL-VALUES "/regular expression/"
+Requires that all values of the EXPECT attribute match the regular expression, which must conform to the POSIX regular expression syntax.
+Comparisons are case-sensitive.
+
WITH-ALL-VALUES-FROM attribute-name
+Requires that all value(s) of the EXPECT attribute matches the value(s) in the specified attribute.
+For example, "EXPECT-ALL media-col-database/media-source WITH-ALL-VALUES-FROM media-source-supported" requires that all the "media-source" values are listed as a value of the "media-source-supported" attribute.
+
WITH-DISTINCT-VALUES
+Requires that all values of the EXPECT attribute are unique.
+Comparisons are case-sensitive.
+Only charset, collection, enum, integer, keyword, mimeMediaType, naturalLanguage, rangeOfInteger, resolution, uriScheme attributes support this predicate.
+
WITH-HOSTNAME "literal string"
+
WITH-HOSTNAME "/regular expression/"
+Requires that at least one URI value contains a matching hostname.
+
WITH-RESOURCE "literal string"
+
WITH-RESOURCE "/regular expression/"
+Requires that at least one URI value contains a matching resource (including leading /).
+
WITH-SCHEME "literal string"
+
WITH-SCHEME "/regular expression/"
+Requires that at least one URI value contains a matching scheme.
+
WITH-VALUE "literal string"
+Requires that at least one value of the EXPECT attribute matches the literal string. Comparisons are case-sensitive.
+
WITH-VALUE <number
+
WITH-VALUE =number
+
WITH-VALUE >number
+
WITH-VALUE number[,...,number]
+Requires that at least one value of the EXPECT attribute matches the number(s) or numeric comparison. When comparing rangeOfInteger values, the "<" and ">" operators only check the upper bound of the range.
+
WITH-VALUE "false"
+
WITH-VALUE "true"
+Requires that at least one value of the EXPECT attribute matches the boolean value given.
+
WITH-VALUE "/regular expression/"
+Requires that at least one value of the EXPECT attribute matches the regular expression, which must conform to the POSIX regular expression syntax. Comparisons are case-sensitive.
+
WITH-VALUE-FROM attribute-name
+Requires that the value(s) of the EXPECT attribute matches the value(s) in the specified attribute.
+For example, "EXPECT job-sheets WITH-VALUE-FROM job-sheets-supported" requires that the "job-sheets" value is listed as a value of the "job-sheets-supported" attribute.
+
The following predicates are understood following the STATUS test directive: +
+DEFINE-MATCH variable-name
+Defines the variable to "1" when the STATUS matches. A side-effect of this predicate is that this STATUS will never fail a test.
+
DEFINE-NO-MATCH variable-name
+Defines the variable to "1" when the STATUS does not match. A side-effect of this predicate is that this STATUS will never fail a test.
+
IF-DEFINED variable-name
+Makes the STATUS apply only if the specified variable is defined.
+
IF-NOT-DEFINED variable-name
+Makes the STATUS apply only if the specified variable is not defined.
+
REPEAT-LIMIT number
+
+Specifies the maximum number of times to repeat. The default value is 1000.
+
REPEAT-MATCH
+
REPEAT-NO-MATCH
+Specifies that the current test should be repeated when the response status-code matches or does not match the value specified by the STATUS directive.
+
Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC 8011 and other IPP extension specifications. Here is a complete list of names supported by +ipptool(8): + +
++ Acknowledge-Document + Acknowledge-Identify-Printer + Acknowledge-Job + Activate-Printer + Add-Document-Images + Allocate-Printer-Resources + Cancel-Current-Job + Cancel-Job + Cancel-Jobs + Cancel-My-Jobs + Cancel-Resource + Cancel-Subscription + Close-Job + Create-Job + Create-Job-Subscriptions + Create-Printer + Create-Printer-Subscriptions + Create-Resource + Create-Resource-Subscriptions + Create-System-Subscriptions + CUPS-Accept-Jobs + CUPS-Accept-Jobs + CUPS-Add-Modify-Class + CUPS-Add-Modify-Printer + CUPS-Authenticate-Job + CUPS-Create-Local-Printer + CUPS-Delete-Class + CUPS-Delete-Printer + CUPS-Get-Classes + CUPS-Get-Default + CUPS-Get-Devices + CUPS-Get-Document + CUPS-Get-PPD + CUPS-Get-PPDs + CUPS-Get-Printers + CUPS-Move-Job + CUPS-Reject-Jobs + CUPS-Set-Default + Deactivate-Printer + Deallocate-Printer-Resources + Delete-Printer + Deregister-Output-Device + Disable-All-Printers + Disable-Printer + Enable-All-Printers + Enable-Printer + Fetch-Document + Fetch-Job + Get-Job-Attributes + Get-Jobs + Get-Next-Document-Data + Get-Notifications + Get-Output-Device-Attributes + Get-Printer-Attributes + Get-Printer-Support-Files + Get-Printer-Supported-Values + Get-Printers + Get-Subscription-Attributes + Get-Subscriptions + Get-System-Attributes + Get-System-Supported-Values + Hold-Job + Hold-New-Jobs + Identify-Printer + Install-Resource + Pause-All-Printers + Pause-All-Printers-After-Current-Job + Pause-Printer + Pause-Printer-After-Current-Job + Print-Job + Print-URI + Promote-Job + Purge-Jobs + Register-Output-Device + Release-Held-New-Jobs + Release-Job + Renew-Subscription + Reprocess-Job + Restart-Job + Restart-Printer + Restart-System + Resubmit-Job + Resume-All-Printers + Resume-Job + Resume-Printer + Schedule-Job-After + Send-Document + Send-Hardcopy-Document + Send-Notifications + Send-Resource-Data + Send-URI + Set-Job-Attributes + Set-Printer-Attributes + Set-Resource-Attributes + Set-System-Attributes + Shutdown-All-Printers + Shutdown-One-Printer + Shutdown-Printer + Startup-All-Printers + Startup-One-Printer + Startup-Printer + Suspend-Current-Job + Update-Active-Jobs + Update-Document-Status + Update-Job-Status + Update-Output-Device-Attributes + Validate-Document + Validate-Job ++
Status codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC 8011 and other IPP extension specifications. Here is a complete list of the names supported by +ipptool(8): + +
++ client-error-account-authorization-failed + client-error-account-closed + client-error-account-info-needed + client-error-account-limit-reached + client-error-attributes-not-settable + client-error-attributes-or-values-not-supported + client-error-bad-request + client-error-charset-not-supported + client-error-compression-error + client-error-compression-not-supported + client-error-conflicting-attributes + client-error-document-access-error + client-error-document-format-error + client-error-document-format-not-supported + client-error-document-password-error + client-error-document-permission-error + client-error-document-security-error + client-error-document-unprintable-error + client-error-forbidden + client-error-gone + client-error-ignored-all-notifications + client-error-ignored-all-subscriptions + client-error-not-authenticated + client-error-not-authorized + client-error-not-fetchable + client-error-not-found + client-error-not-possible + client-error-print-support-file-not-found + client-error-request-entity-too-large + client-error-request-value-too-long + client-error-timeout + client-error-too-many-subscriptions + client-error-uri-scheme-not-supported + cups-error-account-authorization-failed + cups-error-account-closed + cups-error-account-info-needed + cups-error-account-limit-reached + cups-see-other + redirection-other-site + server-error-busy + server-error-device-error + server-error-internal-error + server-error-job-canceled + server-error-multiple-document-jobs-not-supported + server-error-not-accepting-jobs + server-error-operation-not-supported + server-error-printer-is-deactivated + server-error-service-unavailable + server-error-temporary-error + server-error-version-not-supported + successful-ok + successful-ok-but-cancel-subscription + successful-ok-conflicting-attributes + successful-ok-events-complete + successful-ok-ignored-notifications + successful-ok-ignored-or-substituted-attributes + successful-ok-ignored-subscriptions + successful-ok-too-many-events ++
Value and group tags correspond to the names from RFC 8011 and other IPP extension specifications. Here are the group tags: +
++ document-attributes-tag + event-notification-attributes-tag + job | job-attributes-tag + operation | operation-attributes-tag + printer | printer-attributes-tag + resource-attributes-tag + subscription-attributes-tag + system-attributes-tag + unsupported-attributes-tag ++
Here are the value tags: +
++ admin-define + boolean + charset + collection | begCollection + dateTime + default + delete-attribute + enum + integer + keyword + language | naturalLanguage + mimetype | mimeMediaType + name | nameWithLanguage | nameWithoutLanguage + no-value + not-settable + octetString + rangeOfInteger + resolution + text | textWithLanguage | textWithoutLanguage + unknown + unsupported + uri + uriScheme ++
The +ipptool(8) + +program maintains a list of variables that can be used in any literal string or attribute value by specifying "$variable-name". Aside from variables defined using the -d option or DEFINE directive, the following pre-defined variables are available: +
+$$
+Inserts a single "$" character.
+
$ENV[name]
+Inserts the value of the named environment variable, or an empty string if the environment variable is not defined.
+
$basename
+Inserts the base filename (without directory path) of the path provided to
+ipptool(8)
+
+with the -f option.
+
$date-current
+Inserts the current date and time using the ISO-8601 format ("yyyy-mm-ddThh:mm:ssZ").
+
$date-start
+Inserts the starting date and time using the ISO-8601 format ("yyyy-mm-ddThh:mm:ssZ").
+
$filename
+Inserts the filename provided to
+ipptool(8)
+
+with the -f option.
+
$filetype
+Inserts the MIME media type for the filename provided to
+ipptool(8)
+
+with the -f option.
+
$hostname
+Inserts the hostname from the URI provided to
+ipptool(8).
+
+
$job-id
+Inserts the last "job-id" attribute value returned in a test response or 0 if no "job-id" attribute has been seen.
+
$job-uri
+Inserts the last "job-uri" attribute value returned in a test response or an empty string if no "job-uri" attribute has been seen.
+
$notify-subscription-id
+Inserts the last "notify-subscription-id" attribute value returned in a test response or 0 if no "notify-subscription-id" attribute has been seen.
+
$port
+Inserts the port number from the URI provided to
+ipptool(8).
+
+
$resource
+Inserts the resource path from the URI provided to
+ipptool(8).
+
+
$scheme
+Inserts the scheme from the URI provided to
+ipptool(8).
+
+
$uri
+Inserts the URI provided to
+ipptool(8).
+
+
$uriuser
+Inserts the username from the URI provided to
+ipptool(8),
+
+if any.
+
$user
+Inserts the current user's login name.
+
The +GENERATE-FILE +directive dynamically generates raster pages for the destination printer. +Each page consists of a black border and the text "TEST-PAGE ####" repeated in the interior in several shades of gray and colors. +The following parameters are supported: +
+COLORSPACE auto
+
COLORSPACE bi-level
+
COLORSPACE color
+
COLORSPACE monochrome
+
COLORSPACE colorspace_bits
+Specifies the output color space and bit depth.
+"auto" chooses an available combination with preference for full color, "bi-level" chooses a B&W (bitmap) color space, "color" chooses a full color combination, and "monochrome" chooses a grayscale combination.
+Otherwise, the value must be one of the registered IPP "pwg-raster-document-type-supported" keywords.
+NOTE: The "device N" color spaces are not current supported.
+
FORMAT image/pwg-raster
+
FORMAT image/urf
+Specifies the raster format to use, either "image/pwg-raster" (PWG Raster) or "image/urf" (Apple Raster).
+The default is "image/urf" if supported, "image/pwg-raster" otherwise.
+
MEDIA default
+
MEDIA ready
+
MEDIA media-size-name
+Specifies the output media size.
+"default" uses the printer's default media size while "ready" uses the first ready (loaded) media reported by the printer.
+Other media size names must conform the PWG self-describing media size format.
+
NUM-COPIES copies
+Specifies the number of copies to produce.
+The default is 1 copy.
+
NUM-PAGES pages
+Specifies the number of pages to produce.
+The default is 1 page for single-sided output and 2 pages for double-sided output.
+
ORIENTATION landscape
+
ORIENTATION portrait
+
ORIENTATION reverse-landscape
+
ORIENTATION reverse-portrait
+Specifies the orientation of the output.
+The default is "portrait".
+
RESOLUTION default
+
RESOLUTION max
+
RESOLUTION min
+
RESOLUTION resolutiondpcm
+
RESOLUTION horzontalxverticaldpcm
+
RESOLUTION resolutiondpi
+
RESOLUTION horizontalxverticaldpi
+Specifies the output resolution using the printer's supported resolutions or as specified in dots per inch or dots per centimeter.
+"default" uses the median resolution of the printer and is the default, "min" uses the lowest resolution of the printer, and "max" uses the highest resolution of the printer.
+
SIDES one-sided
+
SIDES two-sided-long-edge
+
SIDES two-sided-short-edge
+Specifies whether to print on one or both sides of the media.
+The default is "two-sided-long-edge" for portrait output and "two-sided-short-edge" for landscape output when supported by the printer, otherwise "one-sided" is used.
+
Query the "foo-default" and "foo-supported" Printer Description attributes and validate that all of its values are 'bar', 'baz', or 'none': +
+{
+ NAME "Validate 'foo' Attribute"
+ OPERATION Get-Printer-Attributes
+ GROUP operation-attributes-tag
+ ATTR charset attributes-charset utf-8
+ ATTR language attributes-natural-language en
+ ATTR uri printer-uri $uri
+ ATTR keyword requested-attributes foo-default,foo-supported
+ EXPECT foo-default OF-TYPE keyword IN-GROUP printer-attributes-tag
+ COUNT 1 WITH-VALUE "/^(bar|baz|none)$$/"
+ EXPECT foo-supported OF-TYPE keyword IN-GROUP printer-attributes-tag
+ WITH-ALL-VALUES "/^(bar|baz|none)$$/"
+}
+
+Query the "media-col-ready" Printer Status attribute and validate that the collection values contain "media-size" and "media-source" member attributes: +
+{
+ NAME "Validate 'foo' Attribute"
+ OPERATION Get-Printer-Attributes
+ GROUP operation-attributes-tag
+ ATTR charset attributes-charset utf-8
+ ATTR language attributes-natural-language en
+ ATTR uri printer-uri $uri
+ ATTR keyword requested-attributes media-col-ready
+ EXPECT media-col-ready OF-TYPE collection IN-GROUP printer-attributes-tag
+ EXPECT-ALL media-col-ready/media-size OF-TYPE collection COUNT 1
+ EXPECT-ALL media-col-ready/media-size/x-dimension OF-TYPE integer(1:MAX) COUNT 1
+ EXPECT-ALL media-col-ready/media-size/y-dimension OF-TYPE integer(0:MAX) COUNT 1
+ EXPECT-ALL media-col-ready/media-source OF-TYPE keyword|name COUNT 1
+}
+
+ ipptool(1)
+ + +IANA IPP Registry (https://www.iana.org/assignments/ipp-registrations) +
+PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp) +
+PWG 5101.1-2023: PWG Media Standardized Names v2.1 (https://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn21-20230915-5101.1.pdf) +
+RFC 8011 (https://datatracker.ietf.org/doc/html/rfc8011) +
+Copyright © 2021-2023 by OpenPrinting. + + diff --git a/libcups/ipptransform.html b/libcups/ipptransform.html new file mode 100644 index 0000000000..f35e8c3111 --- /dev/null +++ b/libcups/ipptransform.html @@ -0,0 +1,279 @@ + + +
+ + +ipptransform - convert document data to alternate formats
+
+ippevepcl - convert document data to hp pcl
+
+ippeveps - convert document data to postscript
+
ipptransform +[ +--help +] [ +-d +device-uri +] [ +-f +output-filename +] [ +-i +input/format +] [ +-m +output/format +] [ +-o +"name=value [... name=value]" +] [ +-r +resolution[,...,resolution] +] [ +-s +{flipped|manual-tumble|normal|rotated} +] [ +-t +type[,...,type] +] [ +-v +] +filename +
+ipptransform +converts the input file into the output format and optionally sends the output to a network printer. +
+The following options are recognized by +ipptransform: +
+--help
+Shows program help.
+
-d device-uri
+
+Specifies an output device as a URI.
+Currently only the "ipp", "ipps", and "socket" URI schemes are supported, for example "socket://10.0.1.42" to send print data to an AppSocket printer at IP address 10.0.1.42.
+
-i input/format
+
+Specifies the MIME media type of the input file.
+Currently the "application/pdf" (PDF) and "image/jpeg" (JPEG) MIME media types are supported.
+
-m output/format
+
+Specifies the MIME media type of the output file.
+Current the "application/vnd.hp-pcl" (HP PCL) and "image/pwg-raster" (PWG Raster) MIME media types are supported.
+
-o "name=value[...name=value]"
+
+Specifies one or more named options for the conversion.
+Currently the "copies", "media", "media-col", "page-ranges", "print-color-mode", "print-quality", "printer-resolution", and "sides" options are supported.
+See the NAMED OPTIONS section for more information.
+
-r resolution[,...,resolution]
+
+Specifies the supported resolutions.
+Resolutions are of the form "NNNdpi" or "NNNxNNNdpi", for example "300dpi" or "600x300dpi".
+HP PCL output only supports resolutions of "300dpi" and "600dpi".
+
-s {flipped|manual-tumble|normal|rotated}
+
+Specifies the coordinate system for the back side of duplex sheets.
+
-t type[,...,type]
+
+Specifies the output color spaces and bit depths, separated by commas.
+Types include "adobe-rgb_8" and "adobe-rgb_16" for 8-bit and 16-bit AdobeRGB, "black_1" and "black_8" for 1-bit and 8-bit black, "cmyk_8" for 8-bit CMYK, "sgray_1" and "sgray_8" for 1-bit and 8-bit grayscale with a 2.2 gamma correction, and "srgb_8" for 8-bit sRGB color.
+Run
+ipptransform
+with the
+--help
+option to see the list of supported color spaces and bit depths.
+
-v
+Increases the verbosity for any diagnostics.
+
The following named options are supported: +
+copies
+Specifies the number of copies to produce.
+
media
+Specifies the media size as a PWG standardized media size name.
+For example, US Letter (8.5x11in) is "na_letter_8.5x11in" and ISO A4 is "iso_a4_210x297mm".
+
media-col
+Specifies the media size as a collection.
+Both the "media-size" and "media-size-name" members can be used to specify the size.
+For example, both "media-col={media-size={x-dimension=21000 y-dimension=29700}}" and "media-col={media-size-name=iso_a4_210x297mm}" specify ISO A4 media.
+
page-ranges
+Selects a single range of pages to print.
+For example, the value "5-12" selects pages 5 through 12.
+
print-color-mode
+Specifies the color mode as "auto" (automatic), "monochrome" (grayscale), or "color".
+
print-quality
+Specifies the print quality with value 3 (draft), 4 (normal), or 5 (high/best).
+
print-scaling
+Specifies the scaling to use when converting image files.
+The values "auto", "fit", and "fill" are supported.
+
printer-resolution
+Specifies the print resolution using one of the supported print resolutions.
+
sides
+Specifies whether to do 1-sided printing ("one-sided") or 2-sided printing ("two-sided-long-edge" for portrait and "two-sided-short-edge" for landscape).
+
ipptransform +sends all messages to the standard error. +Each message is prefixed with "ERROR", "INFO", or "DEBUG" depending on the level of verbosity. +
+The +ipptransform +program returns 0 if the input file is converted successfully and 1 otherwise. +
+ipptransform +recognizes the following environment variables: +
+CONTENT_TYPE
+Specifies the MIME media type of the input file.
+
DEVICE_URI
+Specifies the output device as a URI.
+
DOCUMENT_NAME
+Specifies the title of the input file.
+
IPP_xxx
+Specifies the value of the "xxx" Job Template attribute, where "xxx" is converted to uppercase.
+For example, the "media" Job Template attribute is stored as the "IPP_MEDIA" environment variable.
+
IPP_xxx_DEFAULT
+Specifies the default value of the corresponding "xxx-default" Printer Description attribute, where "xxx" is converted to uppercase.
+For example, the "media-default" Printer Description attribute is stored as the "IPP_MEDIA_DEFAULT" environment variable.
+
IPP_PWG_RASTER_DOCUMENT_RESOLUTION_SUPPORTED
+Lists the supported output resolutions.
+
IPP_PWG_RASTER_DOCUMENT_SHEET_BACK
+Specifies the coordinate system of the back side of duplex sheets.
+
IPP_PWG_RASTER_DOCUMENT_TYPE_SUPPORTED
+Lists the supported output color spaces and bit depths.
+
IPPTRANSFORM_MAX_RASTER
+Specifies the maximum number of bytes to use when generating raster data.
+The default is 16MB.
+
OUTPUT_TYPE
+Specifies the MIME media type of the output file.
+
SERVER_LOGLEVEL
+Specifies the log level (verbosity) as "error", "info", or "debug".
+
Print a PDF file to a PCL printer at 10.0.1.42: +
++ ipptransform -d socket://10.0.1.42 -m application/vnd.hp-pcl \ + filename.pdf ++
Print a PDF file to an IPP Everywhere printer at 10.0.1.42: +
++ ipptransform -d ipp://10.0.1.42/ipp/print -m image/pwg-raster \ + filename.pdf ++
Convert a JPEG file to sRGB PWG Raster at 600dpi: +
++ ipptransform -m image/pwg-raster -r 600dpi -t sgray_8,srgb_8 \ + filename.jpg >filename.ras ++
ipptool(1),
+ + +Copyright © 2023 by OpenPrinting. +Copyright © 2016-2019 by the Printer Working Group. +Copyright © 2016-2019 by Apple Inc. + + diff --git a/libcups/raster-organization.png b/libcups/raster-organization.png new file mode 100644 index 0000000000..c6af40809e Binary files /dev/null and b/libcups/raster-organization.png differ diff --git a/libcups/raster.png b/libcups/raster.png new file mode 100644 index 0000000000..6af212a6d7 Binary files /dev/null and b/libcups/raster.png differ diff --git a/libcups/sample-image.png b/libcups/sample-image.png new file mode 100644 index 0000000000..c22b8cd03e Binary files /dev/null and b/libcups/sample-image.png differ diff --git a/libcups/spec-ipp.html b/libcups/spec-ipp.html new file mode 100644 index 0000000000..8927d2d68d --- /dev/null +++ b/libcups/spec-ipp.html @@ -0,0 +1,1472 @@ + + + +
+ +Last Updated October 12, 2023
+ + +CUPS implements the following Internet Printing Protocol standards:
+CUPS also provides 17 new operations and many new attributes to support multiple IPP printers and printer classes on a single host.
+ +CUPS supports the "ipp" and "ipps" schemes. The following resource names are used:
+So a typical printer URI would be "ipp://foo.example.com/ipp/print/LaserJet".
+ + +CUPS provides 17 vendor extension operations in addition to most of the standard IPP and registered extension operations:
+| Operation Name | +CUPS | +Code | +Brief Description | +
|---|---|---|---|
| Print-Job | +1.0 | +0x0002 | +Print a file. | +
| Validate-Job | +1.0 | +0x0004 | +Validate job attributes. | +
| Create-Job | +1.1 | +0x0005 | +Create a print job. | +
| Send-Document | +1.1 | +0x0006 | +Send a file for a print job. | +
| Cancel-Job | +1.0 | +0x0008 | +Cancel a print job. | +
| Get-Job-Attributes | +1.0 | +0x0009 | +Get job attributes. | +
| Get-Jobs | +1.0 | +0x000A | +Get all jobs. | +
| Get-Printer-Attributes | +1.0 | +0x000B | +Get printer attributes. | +
| Hold-Job | +1.1 | +0x000C | +Hold a job for printing. | +
| Release-Job | +1.1 | +0x000D | +Release a job for printing. | +
| Restart-Job | +1.1 | +0x000E | +Restarts a print job. | +
| Pause-Printer | +1.0 | +0x0010 | +Pause printing on a printer. | +
| Resume-Printer | +1.0 | +0x0011 | +Resume printing on a printer. | +
| Purge-Jobs | +1.0 | +0x0012 | +Purge all jobs. | +
| Set-Printer-Attributes | +1.4 | +0x0013 | +Set attributes for a printer. | +
| Set-Job-Attributes | +1.1 | +0x0014 | +Set attributes for a pending or held job. | +
| Create-Printer-Subscriptions | +1.2 | +0x0016 | +Creates subscription(s) associated with a printer or the server. | +
| Create-Job-Subscriptions | +1.2 | +0x0017 | +Creates subscriptions associated with a job. | +
| Get-Subscription-Attributes | +1.2 | +0x0018 | +Gets the attributes for a subscription. | +
| Get-Subscriptions | +1.2 | +0x0019 | +Gets the attributes for zero or more subscriptions. | +
| Renew-Subscription | +1.2 | +0x001A | +Renews a subscription. | +
| Cancel-Subscription | +1.2 | +0x001B | +Cancels a subscription. | +
| Get-Notifications | +1.2 | +0x001C | +Get notification events for ippget subscriptions. | +
| Enable-Printer | +1.2 | +0x0022 | +Accepts jobs on a printer. | +
| Disable-Printer | +1.2 | +0x0023 | +Rejects jobs on a printer. | +
| Hold-New-Jobs | +1.4 | +0x0025 | +Hold new jobs by default. | +
| Release-Held-New-Jobs | +1.4 | +0x0026 | +Releases all jobs that were previously held. | +
| Cancel-Jobs | +1.5 | +0x0038 | +Cancel all jobs (administrator). | +
| Cancel-My-Jobs | +1.5 | +0x0039 | +Cancel all jobs (user). | +
| Close-Job | +1.5 | +0x003b | +Close a created job. | +
| CUPS-Get-Default | +1.0 | +0x4001 | +Get the default destination. | +
| CUPS-Get-Printers | +1.0 | +0x4002 | +Get all of the available printers. | +
| CUPS-Add-Modify-Printer | +1.0 | +0x4003 | +Add or modify a printer. | +
| CUPS-Delete-Printer | +1.0 | +0x4004 | +Delete a printer. | +
| CUPS-Get-Classes | +1.0 | +0x4005 | +Get all of the available printer classes. | +
| CUPS-Add-Modify-Class | +1.0 | +0x4006 | +Add or modify a printer class. | +
| CUPS-Delete-Class | +1.0 | +0x4007 | +Delete a printer class. | +
| CUPS-Accept-Jobs | +1.0 | +0x4008 | +Accept jobs on a printer or printer class. This operation is deprecated - use the Enable-Printer operation instead. | +
| CUPS-Reject-Jobs | +1.0 | +0x4009 | +Reject jobs on a printer or printer class. This operation is deprecated - use the Disable-Printer operation instead. | +
| CUPS-Set-Default | +1.0 | +0x400A | +Set the default destination. | +
| CUPS-Get-Devices | +1.1 | +0x400B | +Get all of the available devices. | +
| CUPS-Get-PPDs | +1.1 | +0x400C | +Get all of the available PPDs. | +
| CUPS-Move-Job | +1.1 | +0x400D | +Move a job to a different printer. | +
| CUPS-Authenticate-Job | +1.2 | +0x400E | +Authenticate a job for printing. | +
| CUPS-Get-PPD | +1.3 | +0x400F | +Get a PPD file. | +
| CUPS-Get-Document | +1.4 | +0x4027 | +Get a document file from a job. | +
| CUPS-Create-Local-Printer | +2.2 | +0x4028 | +Creates a local (temporary) print queue pointing to a remote IPP Everywhere printer. | +
The following sections describe the operations supported by CUPS. In the interest of brevity, operations which use only the standard IPP attributes are not described. + + +
The Cancel-Job operation (0x0008) cancels the specified job. CUPS 1.4 added support for the purge-job (boolean) operation attribute that (if 'true') removes all history and document files for the job as well.
+ + +The Purge-Jobs operation (0x0012) cancels all of the jobs on a given destination and optionally removes all history and document files for the jobs as well. CUPS 1.2 added support for the purge-job (boolean) operation attribute that (if 'false') retains all history and document files for the canceled jobs.
+Note: ++ + +The Cancel-Jobs and Cancel-My-Jobs operations should be used instead of Purge-Jobs.
+
The Create-Printer-Subscriptions operation (0x0016) creates one or more subscriptions for printer or server event notifications. CUPS provides several additional events in addition to the standard events in the IPP notifications specification. CUPS adds the following notify-events (1setOf type2 keyword) values:
+
The CUPS-Get-Default operation (0x4001) returns the default printer URI and attributes. + +
The following groups of attributes are supplied as part of the CUPS-Get-Default request: +
Group 1: Operation Attributes +
The following groups of attributes are send as part of the CUPS-Get-Default Response: +
Group 1: Operation Attributes +
Group 2: Printer Object Attributes +
The CUPS-Get-Printers operation (0x4002) returns the printer attributes for every printer known to the system. This may include printers that are not served directly by the server. + +
The following groups of attributes are supplied as part of the CUPS-Get-Printers request: +
Group 1: Operation Attributes +
The following groups of attributes are send as part of the CUPS-Get-Printers Response: +
Group 1: Operation Attributes +
Group 2: Printer Object Attributes +
The CUPS-Add-Modify-Printer operation (0x4003) adds a new printer or modifies an existing printer on the system. + +
The following groups of attributes are supplied as part of the CUPS-Add-Modify-Printer request: +
Group 1: Operation Attributes +
Group 2: Printer Object Attributes +
The CUPS-Add-Modify-Printer request can optionally be followed by a PPD file to be used for the printer. The "ppd-name" attribute overrides any file that is attached to the end of the request with a local CUPS PPD file. + +
The following groups of attributes are send as part of the CUPS-Add-Modify-Printer Response: +
Group 1: Operation Attributes +
The CUPS-Delete-Printer operation (0x4004) removes an existing printer from the system. + +
The following groups of attributes are supplied as part of the CUPS-Delete-Printer request: +
Group 1: Operation Attributes +
The following groups of attributes are send as part of the CUPS-Delete-Printer Response: +
Group 1: Operation Attributes +
The CUPS-Get-Classes operation (0x4005) returns the printer attributes for every printer class known to the system. This may include printer classes that are not served directly by the server. + +
The following groups of attributes are supplied as part of the CUPS-Get-Classes request: +
Group 1: Operation Attributes +
The following groups of attributes are send as part of the CUPS-Get-Classes Response: +
Group 1: Operation Attributes +
Group 2: Printer Class Object Attributes +
The CUPS-Add-Modify-Class operation (0x4006) adds a new printer class or modifies and existing printer class on the system. + +
The following groups of attributes are supplied as part of the CUPS-Add-Modify-Class request: +
Group 1: Operation Attributes +
Group 2: Printer Object Attributes +
The following groups of attributes are send as part of the CUPS-Add-Modify-Class Response: +
Group 1: Operation Attributes +
The CUPS-Delete-Class operation (0x4007) removes an existing printer class from the system. + +
The following groups of attributes are supplied as part of the CUPS-Delete-Class request: +
Group 1: Operation Attributes +
The following groups of attributes are send as part of the CUPS-Delete-Class Response: +
Group 1: Operation Attributes +
The CUPS-Set-Default operation (0x400A) sets the default printer destination for all clients when a resource name of "/printers" is specified. + +
The following groups of attributes are supplied as part of the CUPS-Set-Default request: +
Group 1: Operation Attributes +
The following groups of attributes are send as part of the CUPS-Set-Default Response: +
Group 1: Operation Attributes +
The CUPS-Get-Devices operation (0x400B) returns all of the supported device-uri's for the server.
+ +The following groups of attributes are supplied as part of the CUPS-Get-Devices request: +
Group 1: Operation Attributes +
The following groups of attributes are send as part of the CUPS-Get-Devices Response: +
Group 1: Operation Attributes +
Groups 2-N: Device Object Attributes (using printer-attributes-tag group) +
The CUPS-Get-PPDs operation (0x400C) returns all of the locally available PPD files on the system.
+ +The following groups of attributes are supplied as part of the CUPS-Get-PPDs request: +
Group 1: Operation Attributes +
The following groups of attributes are send as part of the + CUPS-Get-PPDs Response: +
Group 1: Operation Attributes +
Groups 2-N: PPD Attributes (using printer-attributes-tag group) +
The CUPS-Move-Job operation (0x400D) moves an active print job or all print jobs for a printer to a different printer.
+ +The following groups of attributes are supplied as part of the CUPS-Move-Job request: +
Group 1: Operation Attributes +
Group 2: Job Template Attributes +
The following groups of attributes are send as part of the CUPS-Move-Job Response: +
Group 1: Operation Attributes +
The CUPS-Authenticate-Job operation (0x400E) authenticates a print job for printing, releasing the job if it is held. Typically this is used when printing to a remote server. The authentication information is passed in the HTTP request; the HTTP connection is normally encrypted for this type of request.
+ +The following groups of attributes are supplied as part of the CUPS-Authenticate-Job request: +
Group 1: Operation Attributes +
Group 2: Job Attributes +
The following groups of attributes are send as part of the CUPS-Authenticate-Job Response: +
Group 1: Operation Attributes +
Group 2: Unsupported Attributes (status=client-eror-attributes-or-values-not-supported) +
The CUPS-Get-PPD operation (0x400F) gets a PPD file from the server. The PPD file can be specified using a ppd-name returned by CUPS-Get-PPDs or using the printer-uri for a queue.
+If the PPD file is found, successful-ok is returned with the PPD file following the response data.
+If the PPD file cannot be served by the local server because the printer-uri attribute points to an external printer, a cups-see-other status is returned with the correct URI to use.
+If the PPD file does not exist, client-error-not-found is returned.
+ +The following group of attributes is supplied as part of the CUPS-Get-PPD request: +
Group 1: Operation Attributes +
The following group of attributes is sent as part of the CUPS-Get-PPD Response: +
Group 1: Operation Attributes +
If the status code is successful-ok, the PPD file follows the end of the IPP response.
+ + +The CUPS-Get-Document operation (0x4027) gets a document file from a job on the server. The document file is specified using the document-number and either the job-uri or printer-uri and job-id identifying the job.
+If the document file is found, successful-ok is returned with the document file following the response data.
+If the document file does not exist, client-error-not-found is returned.
+If the requesting user does not have access to the document file, client-error-not-authorized is returned. + +
The following group of attributes is supplied as part of the CUPS-Get-Document request: +
Group 1: Operation Attributes +
The following group of attributes is sent as part of the CUPS-Get-Document Response: +
Group 1: Operation Attributes +
If the status code is successful-ok, the document file follows the end of the IPP response.
+ + +The CUPS-Create-Local-Printer operation (0x4028) creates a local (temporary) print queue pointing to a remote IPP Everywhere Printer. The queue will remain until the scheduler idle exits, is restarted, or the system is restarted or shutdown. Temporary print queues can be made permanent by an administrator by setting the "printer-is-shared" attribute to 'true'.
+At a minimum, the scheduler requires a name and URI for the Printer to add. When successful, the local "printer-uri" values are returned and may be used by the Client to submit Job Creation Requests, monitor for state changes, and so forth.
+If the named printer already exists, the scheduler will reject the request with the 'client-error-not-possible' status code.
+Access Rights: The authenticated user performing this operation MUST be a Local User of the system, and the request MUST be made over a local (domain socket or loopback interface) address. Otherwise, the request will be rejected with the 'client-error-forbidden' status code.
+ +The following group of attributes is supplied as part of the CUPS-Create-Local-Printer request: +
Group 1: Operation Attributes +
Group 2: Printer Attributes +
The following group of attributes is sent as part of the CUPS-Create-Local-Printer Response: +
Group 1: Operation Attributes +
Group 2: Printer Attributes +
CUPS provides many extension attributes to support multiple devices, PPD files, standard job filters, printers, and printer classes.
+ + +Device attributes are returned by the CUPS-Get-Devices operation and enumerate all of the available hardware devices and network protocols that are supported by the server. Device attributes are reported in the printer-attributes-tag group.
+ +The "device-class" attribute provides the class of device and can be one of the following: +
The "device-id" attribute provides the IEEE-1284 device ID string for the device.
+ +The "device-info" attribute specifies a human-readable string describing the device, e.g., 'Parallel Port #1'. + +
The "device-location" attribute specifies the physical location of the printer, e.g., '2nd Floor Computer Lab'. + +
The "device-make-and-model" attribute specifies a device identification string provided by the printer connected to the device. If the device or printer does not support identification then this attribute contains the string 'unknown'. + +
The "device-uri" attribute specifies a unique identifier for the device. The actual format of the "device-uri" string depends on the value of the "device-class" attribute: +
The URI returned by CUPS-Get-Devices will contain the maximum baud rate supported by the device and the best type of flow control available ("soft" or "hard"). +
The URI returned by CUPS-Get-Devices MAY only contain the scheme name ('scheme'). It is up to the client application to add the appropriate host and other information when adding a new printer. +
The URI returned by Get-Printer-Attributes and CUPS-Get-Printers has any username and password information stripped; the information is still stored and used by the server internally to perform any needed authentication. +
The "auth-info" attribute specifies the authentication information to use when printing to a remote device. The order and content of each text value is specifed by the auth-info-required printer attribute. + +
The "job-cancel-after" attribute provides the maximum number of seconds that are allowed for processing a job.
+ +The "job-hold-until" attribute specifies a hold time. In addition to the standard IPP/1.1 keyword names, CUPS supports name values of the form "HH:MM" and "HH:MM:SS" that specify a hold time. The hold time is in Universal Coordinated Time (UTC) and not in the local time zone. If the specified time is less than the current time, the job is held until the next day. + +
The "job-media-progress" status attribute specifies the percentage of completion of the current page. It is only valid when the "job-state" attribute has the 'processing(5)' value.
+ +The "job-printer-state-message" status attribute provides the last known value of the "printer-state-message" attribute for the printer that processed (or is processing) the job.
+ +The "job-printer-state-reasons" status attribute provides the last known value of the "printer-state-reasons" attribute for the printer that processed (or is processing) the job.
+ +The "job-sheets" attribute specifies one or two banner files that are printed before and after a job. The reserved value of "none" disables banner printing. The default value is stored in the "job-sheets-default" attribute. +
If only one value is supplied, the banner file is printed before the job. If two values are supplied, the first value is used as the starting banner file and the second as the ending banner file. + +
The "job-originating-host-name" status attribute specifies the host from which the job was queued. The value will be the hostname or IP address of the client depending on whether hostname resolution is enabled. The localhost address (127.0.0.1) is always resolved to the name "localhost". +
This attribute is read-only. + +
The "page-border" attribute specifies whether a border is draw around each page. The following keywords are presently defined: +
The "page-set" attribute specifies which pages to print in a file. The supported keywords are 'all', 'even', and 'odd'. The default value is 'all'. + + +
PPD attributes are returned in the printer-attributes-tag group. + +
The "ppd-device-id" attribute specifies the IEEE-1284 device ID string for the device described by the PPD file.
+ +The "ppd-make" attribute specifies the manufacturer of the printer (the Manufacturer attribute in the PPD file). If the manufacturer is not specified in the PPD file then an educated guess is made using the NickName attribute in the PPD file. + +
The "ppd-make-and-model" attribute specifies the manufacturer and model name of the PPD file (the NickName attribute in the PPD file). If the make and model is not specified in the PPD file then the ModelName or ShortNickName attributes are used instead. + +
The "ppd-model-number" attribute provides the cupsModelNumber value from the PPD file. + +
The "ppd-name" attribute specifies either the PPD filename on the server relative to the model directory or a URI that maps to a specific driver interface in the driver directory. The forward slash (/) is used to delineate directories. + +
The "ppd-natural-language" attribute specifies the language encoding of the PPD file (the LanguageVersion attribute in the PPD file). If the language is unknown or undefined then "en" (English) is assumed. + +
The "ppd-product" attribute specifies the Product attribute values in the PPD file. + +
The "ppd-product" attribute specifies the PSVersion attribute values in the PPD file. + +
The "ppd-type" attribute specifies the type of driver described by the PPD file:
+The "auth-info-required" attribute specifies the authentication information that is required for printing a job. The following keywords are recognized:
+The "job-k-limit" attribute specifies the maximum number of kilobytes that may be printed by a user, including banner files. The default value of 0 specifies that there is no limit. + +
The "job-page-limit" attribute specifies the maximum number of pages that may be printed by a user, including banner files. The default value of 0 specifies that there is no limit. + +
The "job-quota-period" attribute specifies the time period used for quota calculations, in seconds. The default value of 0 specifies that the limits apply to all jobs that have been printed by a user that are still known to the system. + +
The "marker-change-time" status attribute specifies the "printer-up-time" value when the last change to the marker-colors, marker-levels, marker-message, marker-names, or marker-types attributes was made.
+ +The "marker-colors" status attribute specifies the color(s) for each supply in the printer. It is only available when the driver provides supply levels. The color is either 'none' or one or more hex-encoded sRGB colors of the form '#RRGGBB'.
+ +The "marker-high-levels" status attribute specifies the supply levels that indicate a near-full condition. A value of 100 should be used for supplies that are consumed/emptied, e.g. ink cartridges.
+ +The "marker-levels" status attribute specifies the current supply levels for the printer. It is only available when the driver provides supply levels. A value of -1 indicates the level is unavailable, -2 indicates unknown, and -3 indicates the level is unknown but has not yet reached capacity. Values from 0 to 100 indicate the corresponding percentage.
+ +The "marker-low-levels" status attribute specifies the supply levels that indicate a near-empty condition. A value of 0 should be used for supplies that are filled, e.g. waste ink tanks.
+ +The "marker-message" status attribute provides a human-readable status message for the current supply levels, e.g. "12 pages of ink remaining." It is only available when the driver provides supply levels.
+ +The "marker-names" status attribute specifies the name(s) for each supply in the printer. It is only available when the driver provides supply levels.
+ +The "marker-types" status attribute specifies the type(s) of each supply in the printer. It is only available when the driver provides supply levels. The following (RFC 3805) types are currently supported:
+The "port-monitor" attribute specifies the port monitor to use when printing to this printer. The default port monitor is 'none'. + +
The "port-monitor-supported" attribute specifies the available port monitors. + +
The "printer-commands" attribute specifies the commands that are supported by the CUPS command file filter. The keyword 'none' indicates that no commands are supported.
+ +The "printer-type" status attribute specifies printer type and capability bits for the printer or class. The default value is computed from internal state information and the PPD file for the printer. The following bits are defined:
+| Bit | +Description | +
|---|---|
| 0x00000001 | +Is a printer class. | +
| 0x00000002 | +Is a remote destination. | +
| 0x00000004 | +Can print in black. | +
| 0x00000008 | +Can print in color. | +
| 0x00000010 | +Can print on both sides of the page in hardware. | +
| 0x00000020 | +Can staple output. | +
| 0x00000040 | +Can do fast copies in hardware. | +
| 0x00000080 | +Can do fast copy collation in hardware. | +
| 0x00000100 | +Can punch output. | +
| 0x00000200 | +Can cover output. | +
| 0x00000400 | +Can bind output. | +
| 0x00000800 | +Can sort output. | +
| 0x00001000 | +Can handle media up to US-Legal/A4. | +
| 0x00002000 | +Can handle media from US-Legal/A4 to ISO-C/A2. | +
| 0x00004000 | +Can handle media larger than ISO-C/A2. | +
| 0x00008000 | +Can handle user-defined media sizes. | +
| 0x00010000 | +Is an implicit (server-generated) class. | +
| 0x00020000 | +Is the a default printer on the network. | +
| 0x00040000 | +Is a facsimile device. | +
| 0x00080000 | +Is rejecting jobs. | +
| 0x00100000 | +Delete this queue. | +
| 0x00200000 | +Queue is not shared. | +
| 0x00400000 | +Queue requires authentication. | +
| 0x00800000 | +Queue supports CUPS command files. | +
| 0x01000000 | +Queue was automatically discovered and added. | +
| 0x02000000 | +Queue is a scanner with no printing capabilities. | +
| 0x04000000 | +Queue is a printer with scanning capabilities. | +
The "printer-type-mask" attribute is used to choose printers or classes with the CUPS-Get-Printers and CUPS-Get-Classes operations. The bits are defined identically to the printer-type attribute and default to all 1's. + +
The "requesting-user-name-allowed" attribute lists all of the users that are allowed to access a printer or class. Either this attribute or the "requesting-user-name-denied" attribute will be defined, but not both. + +
The "requesting-user-name-denied" attribute lists all of the users that are not allowed to access a printer or class. Either this attribute or the "requesting-user-name-allowed" attribute will be defined, but not both. + + +
Printer class attributes are placed in the printer-attributes-tag group.
+ +The "member-names" attribute specifies the "printer-name" attributes for each the member printer and class. Each name corresponds to the same element of the "member-uris" attribute. + +
The "member-uris" attribute specifies the "printer-uri-supported" values for each member printer and class. Each URI corresponds to the same element of the "member-names" attribute. + + diff --git a/libcups/spec-raster.html b/libcups/spec-raster.html new file mode 100644 index 0000000000..65ec96f851 --- /dev/null +++ b/libcups/spec-raster.html @@ -0,0 +1,799 @@ + + + +
+ +Last Updated October 4, 2023
+ + +CUPS Raster files are device-dependent raster image files that contain a PostScript page device dictionary and device-dependent raster imagery for each page in the document. These files are used to transfer raster data from the PostScript and image file RIPs to device-dependent filters that convert the raster data to a printable format.
+CUPS 1.0 and 1.1 used version 1 of the raster format. CUPS 1.2 and later use version 2 (compressed) and version 3 (uncompressed) that are a superset of the version 1 raster format. All three versions of CUPS Raster are streamable formats, and applications using the CUPS Imaging API (the cupsRaster* functions) can read all formats without code changes.
+The registered MIME media type for CUPS Raster files is application/vnd.cups-raster.
Figure 1, "Raster Organization", shows the general organization of all CUPS Raster files. Each file begins with a 32-bit synchronization word followed by zero or more pages. Each page consists of a header (the PostScript page device dictionary and raster-specific values) followed by the bitmap image for the page.
+ + |
+
Each page bitmap is stored as described by the cupsBitsPerColor, cupsBytesPerLine, cupsColorOrder, cupsColorSpace, cupsHeight, and cupsWidth values in the page header. Pixels for the front side of a sheet are always stored left-to-right, top-to-bottom. When doing duplex printing, pixels for the back side of a sheet may be stored differently depending on the value of the cupsBackSide keyword ("Normal", "ManualTumble", "Rotated", or "Flipped") in the PPD file and the Tumble value ("true" or "false") in the page header. Figure 2, "Page Bitmaps", shows the pixel order for each combination.
 |
+
A version 1 raster file begins with a 32-bit synchronization word: 0x52615374 ("RaSt") for big-endian architectures or 0x74536152 ("tSaR") for little-endian architectures. The writer of the raster file will use the native word order, and the reader is responsible for detecting a reversed word order file and swapping bytes as needed. The CUPS Imaging API raster functions perform this function automatically.
+ +Following the synchronization word are a series of raster pages. Each page starts with a page device dictionary header and is followed immediately by the (uncompressed/raw) raster data for that page.
+ +| Bytes | +Type | +Description | +Values | +
|---|---|---|---|
| 0-63 | +C String | +MediaClass | +Media class string | +
| 64-127 | +C String | +MediaColor | +Media color string | +
| 128-191 | +C String | +MediaType | +Media type string | +
| 192-255 | +C String | +OutputType | +Output type string | +
| 256-259 | +Unsigned Integer | +AdvanceDistance | +0 to 232 - 1 points | +
| 260-263 | +Unsigned Integer | +AdvanceMedia | +0 = Never advance roll + 1 = Advance roll after file + 2 = Advance roll after job + 3 = Advance roll after set + 4 = Advance roll after page |
+
| 264-267 | +Unsigned Integer | +Collate | +0 = do not collate copies + 1 = collate copies |
+
| 268-271 | +Unsigned Integer | +CutMedia | +0 = Never cut media + 1 = Cut roll after file + 2 = Cut roll after job + 3 = Cut roll after set + 4 = Cut roll after page |
+
| 272-275 | +Unsigned Integer | +Duplex | +0 = Print single-sided + 1 = Print double-sided |
+
| 276-283 | +Unsigned Integers (2) | +HWResolution | +Horizontal and vertical resolution in dots-per-inch. | +
| 284-299 | +Unsigned Integers (4) | +ImagingBoundingBox | +Four integers giving the left, bottom, right, and top positions of the page bounding box in points | +
| 300-303 | +Unsigned Integer | +InsertSheet | +0 = Do not insert separator sheets + 1 = Insert separator sheets |
+
| 304-307 | +Unsigned Integer | +Jog | +0 = Do no jog pages + 1 = Jog pages after file + 2 = Jog pages after job + 3 = Jog pages after set |
+
| 308-311 | +Unsigned Integer | +LeadingEdge | +0 = Top edge is first + 1 = Right edge is first + 2 = Bottom edge is first + 3 = Left edge is first |
+
| 312-319 | +Unsigned Integers (2) | +Margins | +Left and bottom origin of image in points | +
| 320-323 | +Unsigned Integer | +ManualFeed | +0 = Do not manually feed media + 1 = Manually feed media |
+
| 324-327 | +Unsigned Integer | +MediaPosition | +Input slot position from 0 to N | +
| 328-331 | +Unsigned Integer | +MediaWeight | +Media weight in grams per meter squared, 0 = printer default | +
| 332-335 | +Unsigned Integer | +MirrorPrint | +0 = Do not mirror prints + 1 = Mirror prints |
+
| 336-339 | +Unsigned Integer | +NegativePrint | +0 = Do not invert prints + 1 = Invert prints |
+
| 340-343 | +Unsigned Integer | +NumCopies | +0 to 232 - 1, 0 = printer default | +
| 344-347 | +Unsigned Integer | +Orientation | +0 = Do not rotate page + 1 = Rotate page counter-clockwise + 2 = Turn page upside down + 3 = Rotate page clockwise |
+
| 348-351 | +Unsigned Integer | +OutputFaceUp | +0 = Output face down + 1 = Output face up |
+
| 352-359 | +Unsigned Integers (2) | +PageSize | +Width and length in points | +
| 360-363 | +Unsigned Integer | +Separations | +0 = Print composite image + 1 = Print color separations |
+
| 364-367 | +Unsigned Integer | +TraySwitch | +0 = Do not change trays if selected tray is empty + 1 = Change trays if selected tray is empty |
+
| 368-371 | +Unsigned Integer | +Tumble | +0 = Do not rotate even pages when duplexing + 1 = Rotate even pages when duplexing |
+
| 372-375 | +Unsigned Integer | +cupsWidth | +Width of page image in pixels | +
| 376-379 | +Unsigned Integer | +cupsHeight | +Height of page image in pixels | +
| 380-383 | +Unsigned Integer | +cupsMediaType | +Driver-specific 0 to 232 - 1 | +
| 384-387 | +Unsigned Integer | +cupsBitsPerColor | +1, 2, 4, 8 bits for version 1 raster files + 1, 2, 4, 8, and 16 bits for version 2/3 raster files |
+
| 388-391 | +Unsigned Integer | +cupsBitsPerPixel | +1 to 32 bits for version 1 raster files + 1 to 240 bits for version 2/3 raster files |
+
| 392-395 | +Unsigned Integer | +cupsBytesPerLine | +1 to 232 - 1 bytes | +
| 396-399 | +Unsigned Integer | +cupsColorOrder | +0 = chunky pixels (CMYK CMYK CMYK) + 1 = banded pixels (CCC MMM YYY KKK) + 2 = planar pixels (CCC... MMM... YYY... KKK...) |
+
| 400-403 | +Unsigned Integer | +cupsColorSpace | +0 = gray (device, typically sRGB-based) + 1 = RGB (device, typically sRGB) + 2 = RGBA (device, typically sRGB) + 3 = black + 4 = CMY + 5 = YMC + 6 = CMYK + 7 = YMCK + 8 = KCMY + 9 = KCMYcm + 10 = GMCK + 11 = GMCS + 12 = WHITE + 13 = GOLD + 14 = SILVER + 15 = CIE XYZ + 16 = CIE Lab + 17 = RGBW (sRGB) + 18 = sGray (gray using sRGB gamma/white point) + 19 = sRGB + 20 = AdobeRGB + 32 = ICC1 (CIE Lab with hint for 1 color) + 33 = ICC2 (CIE Lab with hint for 2 colors) + 34 = ICC3 (CIE Lab with hint for 3 colors) + 35 = ICC4 (CIE Lab with hint for 4 colors) + 36 = ICC5 (CIE Lab with hint for 5 colors) + 37 = ICC6 (CIE Lab with hint for 6 colors) + 38 = ICC7 (CIE Lab with hint for 7 colors) + 39 = ICC8 (CIE Lab with hint for 8 colors) + 40 = ICC9 (CIE Lab with hint for 9 colors) + 41 = ICCA (CIE Lab with hint for 10 colors) + 42 = ICCB (CIE Lab with hint for 11 colors) + 43 = ICCC (CIE Lab with hint for 12 colors) + 44 = ICCD (CIE Lab with hint for 13 colors) + 45 = ICCE (CIE Lab with hint for 14 colors) + 46 = ICCF (CIE Lab with hint for 15 colors) + 48 = Device1 (DeviceN for 1 color) + 49 = Device2 (DeviceN for 2 colors) + 50 = Device3 (DeviceN for 3 colors) + 51 = Device4 (DeviceN for 4 colors) + 52 = Device5 (DeviceN for 5 colors) + 53 = Device6 (DeviceN for 6 colors) + 54 = Device7 (DeviceN for 7 colors) + 55 = Device8 (DeviceN for 8 colors) + 56 = Device9 (DeviceN for 9 colors) + 57 = DeviceA (DeviceN for 10 colors) + 58 = DeviceB (DeviceN for 11 colors) + 59 = DeviceC (DeviceN for 12 colors) + 60 = DeviceD (DeviceN for 13 colors) + 61 = DeviceE (DeviceN for 14 colors) + 62 = DeviceF (DeviceN for 15 colors) + |
+
| 404-407 | +Unsigned Integer | +cupsCompression | +Driver-specific 0 to 232 - 1 | +
| 408-411 | +Unsigned Integer | +cupsRowCount | +Driver-specific 0 to 232 - 1 | +
| 412-415 | +Unsigned Integer | +cupsRowFeed | +Driver-specific 0 to 232 - 1 | +
| 416-419 | +Unsigned Integer | +cupsRowStep | +Driver-specific 0 to 232 - 1 | +
A version 2 raster file begins with a 32-bit synchronization word: 0x52615332 ("RaS2") for big-endian architectures or 0x32536152 ("2SaR") for little-endian architectures. The writer of the raster file will use the native word order, and the reader is responsible for detecting a reversed word order file and swapping bytes as needed. The CUPS Imaging API raster functions perform this function automatically.
+ +Following the synchronization word are a series of raster pages. Each page starts with a version 2 page device dictionary header and is followed immediately by the compressed raster data for that page.
+ +| Bytes | +Type | +Description | +Values | +
|---|---|---|---|
| 0-419 | +Version 1 header data | +See Table 1 | +|
| 420-423 | +Unsigned Integer | +cupsNumColors | +1 to 15 colors | +
| 424-427 | +IEEE Single Precision | +cupsBorderlessScalingFactor | +0.0 or 1.0 or greater | +
| 428-435 | +IEEE Single Precision (2) | +cupsPageSize | +Width and length in points | +
| 436-451 | +IEEE Single Precision (4) | +cupsImagingBBox | +Four floating point numbers giving the left, bottom, right, and top positions of the page bounding box in points | +
| 452-515 | +Unsigned Integers (16) | +cupsInteger | +16 driver-defined integer values | +
| 516-579 | +IEEE Single Precision (16) | +cupsReal | +16 driver-defined floating point values | +
| 580-1603 | +C Strings (16x64) | +cupsString | +16 driver-defined strings | +
| 1604-1667 | +C String | +cupsMarkerType | +Ink/toner type string | +
| 1668-1731 | +C String | +cupsRenderingIntent | +Color rendering intent string | +
| 1732-1795 | +C String | +cupsPageSizeName | +Page size name/keyword string from PPD | +
The version 2 raster data is compressed using a PackBits-like algorithm. Lines are grouped into an integral number of color values based upon the cupsColorOrder setting:
| cupsColorOrder | +Bytes per color value | +
|---|---|
| 0 (chunky) | +(cupsBitsPerPixel + 7) / 8 |
+
| 1 (banded) | +(cupsBitsPerColor + 7) / 8 |
+
| 2 (planar) | +(cupsBitsPerColor + 7) / 8 |
+
Each line of raster data begins with a repetition count from 1 to 256 that is encoded using a single byte of "count - 1".
+ +After the repetition count, whole color values for that line are run-length encoded using a PackBits-like run-length encoding algorithm: 1 to 128 repeated colors are encoded using an initial byte of "count - 1" followed by the color value byte(s) while 2 to 128 non-repeating colors are encoded using an initial byte of "257 - count" followed by the color value bytes.
+ +For example, the 8x8 24-bit sRGB image shown in Figure 3, "Sample Image", would be encoded as the following 89 octets:
+ ++ %x00 %x00.FF.FF.FF %x02.FF.FF.00 %x03.FF.FF.FF + %x00 %xFE.FF.FF.00.00.00.FF.FF.FF.00 %x02.FF.FF.FF %x00.00.FF.00 %x00.FF.FF.FF + %x00 %x01.FF.FF.00 %x02.FF.FF.FF %x02.00.FF.00 + %x00 %x02.FF.FF.00 %x02.FF.FF.FF %x00.00.FF.00 %x00.FF.FF.FF + %x00 %x00.FF.FF.FF %x02.FF.FF.00 %x03.FF.FF.FF + %x00 %x07.FF.FF.FF + %x01 %x07.FF.00.00 ++ +
The first line (%x00) contains 1 white pixel (%x00.FF.FF.FF), 3 yellow pixels (%x02.FF.FF.00), and 4 white pixels (%x03.FF.FF.FF).
+ +The second line (%x00) contains a sequence of yellow + blue + yellow pixels (%xFE.FF.FF.00.00.00.FF.FF.FF.00), 3 white pixels (%x02.FF.FF.FF), 1 green pixel (%x00.00.FF.00), and 1 white pixel (%x00.FF.FF.FF).
+ +The third line (%x00) contains 2 yellow pixels (%x01.FF.FF.00), 3 white pixels (%x02.FF.FF.FF), and 3 green pixels (%x02.00.FF.00)
+ +The fourth line (%x00) contains 3 yellow pixels (%x02.FF.FF.00), 3 white pixels (%x02.FF.FF.FF), 1 green pixel (%x00.00.FF.00), and 1 white pixel (%x00.FF.FF.FF).
+ +The fifth line (%x00) contains 1 white pixel (%x00.FF.FF.FF), 3 yellow pixels (%x02.FF.FF.00), and 4 white pixels (%x03.FF.FF.FF).
+ +The sixth line (%x00) contains 8 white pixels (%x07.FF.FF.FF).
+ +The seventh and eighth lines (%x01) contain 8 red pixels (%x07.FF.00.00).
+ + |
+
A version 3 raster file begins with a 32-bit synchronization word: 0x52615333 ("RaS3") for big-endian architectures and 0x33536152 ("3SaR") for little-endian architectures. The writer of the raster file will use the native word order, and the reader is responsible for detecting a reversed word order file and swapping bytes as needed. The CUPS Imaging API raster functions perform this function automatically.
+ +Following the synchronization word are a series of raster pages. Each page starts with a version 2 page device dictionary header and is followed immediately by the uncompressed/raw raster data for that page.
+ + +The following sections describe the encoding and decoding of the color values in a CUPS Raster file. In general, colors are packed into the minimum number of bytes, with special consideration provided for efficiency of encoding and access. Multi-byte values are stored in the native byte order and automatically swapped as needed when reading them using the CUPS imaging API.
+ +The chunked order provides the pixel value packed in a single place. Pixel values with 8 or more bits per color are stored as an array of colors in order, e.g. for CUPS_CSPACE_RGB you will see 8/16-bits of red, then blue, then green, then red, green, blue, etc. Pixel values with less than 8 bits per color are packed together as shown in Table 4. Multi-byte pixel values are stored in the native word order, just as for 16-bit color values.
| Bits | +1-color | +3-color | +4-color | +6-color | +
|---|---|---|---|---|
| 1 | +W/W/W/W/W/W/W/W | +0RGB/0RGB | +CMYK/CMYK | +00KCMYcm | +
| 2 | +WW/WW/WW/WW | +00RRGGBB | +CCMMYYKK | +N/A | +
| 4 | +WWWW/WWWW | +0000RRRRGGGGBBBB + (multi-byte) |
+ CCCCMMMMYYYYKKKK + (multi-byte) |
+ N/A | +
The banded order provides each color as a separate line of data. Each color plane for a line is written in sequence, e.g. for the CUPS_CSPACE_CMYK color space you would see all of the cyan pixels for a line followed by the magenta, yellow, and black pixels for that line. This is repeated for all of the lines on the page. Color values are packed starting with the most-significant bit (MSB) first.
The planar order provides each color as a separate page of data using a shared page header. Each color plane for a page is written in sequence, e.g. for the CUPS_CSPACE_CMYK color space you would see all of the cyan pixels for a page followed by the magenta, yellow, and black pixels for that page. Color values are packed starting with the most-significant bit (MSB) first. Each line starts on an 8-bit boundary.
This color space provides a dedicated black text channel and uses the sRGB color space definition and white point for the RGB color channels. The white channel is 0 for text (or "true") black, otherwise it must contain the maximum color value: 1 for 1-bit, 3 for 2-bit, 15 for 4-bit, 255 for 8-bit, or 65535 for 16-bit.
+ + +When cupsBitsPerColor is 1, 6 color planes are provided - black, cyan, magenta, yellow, light cyan, and light magenta. When cupsBitsPerColor is greater than 1, 4 color planes are provided using the CUPS_CSPACE_KCMY color space instead.
When cupsColorOrder is CUPS_ORDER_CHUNKED, bit 5 corresponds to black and bit 0 corresponds to light magenta. For CUPS_ORDER_BANDED and CUPS_ORDER_PLANAR, each color plane is encoded separately.
These color spaces map a CIE Lab color value with a D65 white point to either a 8- or 16-bit per color chunked (CUPS_ORDER_CHUNKED) format; the banded (CUPS_ORDER_BANDED) and planar (CUPS_ORDER_PLANAR) color orders are not supported.
The values are encoded and decoded using the following formulas:
+ +These color spaces map a CIE XYZ color value with a D65 white point to either a 8- or 16-bit per color chunked (CUPS_ORDER_CHUNKED) format; the banded (CUPS_ORDER_BANDED) and planar (CUPS_ORDER_PLANAR) color orders are not supported.
The values are encoded and decoded using the following formulas:
+ +The scaling factor for XYZ values is 1/1.1, or 231.8181 for 8-bit values and 59577.2727 for 16-bit values. This allows for a slight overflow of XYZ values when converting from RGB, improving accuracy.
+ + +