[
<strong>--help</strong>
] [
-<strong>--ippserver</strong>
-<em>filename</em>
+<strong>--ippfile</strong>
+<em>FILENAME</em>
] [
<strong>--stop-after-include-error</strong>
] [
] [
<strong>-6</strong>
] [
+<strong>-c</strong>
+] [
<strong>-C</strong>
] [
-<strong>-E</strong>
+<strong>-d</strong>
+<em>NAME=VALUE</em>
] [
-<strong>-I</strong>
+<strong>-E</strong>
] [
-<strong>-L</strong>
+<strong>-f</strong>
+<em>FILENAME</em>
] [
-<strong>-P</strong>
-<em>filename.plist</em>
+<strong>-h</strong>
] [
-<strong>-S</strong>
+<strong>-i</strong>
+<em>SECONDS</em>
] [
-<strong>-T</strong>
-<em>seconds</em>
+<strong>-I</strong>
] [
-<strong>-V</strong>
-<em>version</em>
+<strong>-j</strong>
] [
-<strong>-X</strong>
+<strong>-L</strong>
] [
-<strong>-c</strong>
+<strong>-n</strong>
+<em>REPEAT-COUNT</em>
] [
-<strong>-d</strong>
-<em>name=value</em>
+<strong>-P</strong>
+<em>FILENAME.plist</em>
] [
-<strong>-f</strong>
-<em>filename</em>
+<strong>-q</strong>
] [
-<strong>-h</strong>
+<strong>-R</strong>
] [
-<strong>-i</strong>
-<em>seconds</em>
+<strong>-S</strong>
] [
-<strong>-j</strong>
+<strong>-t</strong>
] [
-<strong>-n</strong>
-<em>repeat-count</em>
+<strong>-T</strong>
+<em>SECONDS</em>
] [
-<strong>-q</strong>
+<strong>-v</strong>
] [
-<strong>-t</strong>
+<strong>-V</strong>
+<em>VERSION</em>
] [
-<strong>-v ]</strong>
-<em>printer-uri</em>
-<em>testfile</em>
+<strong>-X</strong>
+]
+<em>PRINTER-URI</em>
+<em>TESTFILE</em>
[ ...
-<em>testfile</em>
+<em>TESTFILE</em>
]
</p>
<h2 id="ipptool-1.description">Description</h2>
Each named
<em>testfile</em>
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.
+Output is either a plain text, formatted text, CSV, JSON, or XML report on the standard output, with a non-zero exit status indicating that one or more tests have failed.
The
<em>testfile</em>
format is described in
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--help</strong><br>
Shows program help.
</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--ippserver </strong><em>filename</em><br>
-Specifies that the test results should be written to the named
-<strong>ippserver</strong>
-attributes file.
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--ippfile </strong><em>FILENAME</em><br>
+Specifies that the test results should be written to the named IPP file.
+These files can be used with programs like
+<strong>ippeveprinter</strong>(1).
+
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--stop-after-include-error</strong><br>
Tells
Specifies that
<strong>ipptool</strong>
must connect to the printer or server using IPv6.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-c</strong><br>
+Specifies that CSV (comma-separated values) output is desired instead of the plain text output.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-C</strong><br>
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.
</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-E</strong><br>
-Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
-</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-I</strong><br>
-Specifies that
-<strong>ipptool</strong>
-will continue past errors.
-</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-L</strong><br>
-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>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-P</strong><em> filename.plist</em>
-<br>
-Specifies that the test results should be written to the named XML (Apple plist) file in addition to the regular test report (<strong>-t</strong>).
-This option is incompatible with the <strong>-i</strong> (interval) and <strong>-n</strong> (repeat-count) options.
-</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-S</strong><br>
-Forces (dedicated) TLS encryption when connecting to the server.
-</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-T</strong><em> seconds</em>
-<br>
-Specifies a timeout for IPP requests in seconds.
-</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-V</strong><em> version</em>
-<br>
-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.
-</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-X</strong><br>
-Specifies that XML (Apple plist) output is desired instead of the plain text report.
-This option is incompatible with the <strong>-i</strong> (interval) and <strong>-n</strong> (repeat-count) options.
-</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-c</strong><br>
-Specifies that CSV (comma-separated values) output is desired instead of the plain text output.
-</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-d</strong><em> name=value</em>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-d</strong><em> NAME=VALUE</em>
<br>
Defines the named variable.
</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-f</strong><em> filename</em>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-E</strong><br>
+Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-f</strong><em> FILENAME</em>
<br>
Defines the default request filename for tests.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-h</strong><br>
Validate HTTP response headers.
</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-i</strong><em> seconds</em>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-i</strong><em> SECONDS</em>
<br>
Specifies that the (last)
<em>testfile</em>
should be repeated at the specified interval.
-This option is incompatible with the <strong>-X</strong> (XML plist output) option.
+This option is incompatible with the <strong>--ippfile</strong> (IPP file output) and <em>-P</em> or <strong>-X</strong> (XML plist output) options.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-I</strong><br>
+Specifies that
+<strong>ipptool</strong>
+will continue past errors.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-j</strong><br>
Specifies that
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-l</strong><br>
Specifies that plain text output is desired.
</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-n</strong><em> repeat-count</em>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-L</strong><br>
+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>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-n</strong><em> REPEAT-COUNT</em>
<br>
Specifies that the (last)
<em>testfile</em>
should be repeated the specified number of times.
-This option is incompatible with the <em>-X</em> (XML plist output) option.
+This option is incompatible with the <em>--ippfile</em> (IPP file output) and <em>-P</em> or <em>-X</em> (XML plist output) options.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-P</strong><em> FILENAME.plist</em>
+<br>
+Specifies that the test results should be written to the named XML (Apple plist) file in addition to the regular test report (<strong>-t</strong>).
+This option is incompatible with the <strong>-i</strong> (interval) and <strong>-n</strong> (repeat-count) options.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-q</strong><br>
Be quiet and produce no output.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-S</strong><br>
+Forces (dedicated) TLS encryption when connecting to the server.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-t</strong><br>
Specifies that CUPS test report output is desired instead of the plain text output.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-T</strong><em> SECONDS</em>
+<br>
+Specifies a timeout for IPP requests in SECONDS.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-v</strong><br>
Specifies that all request and response attributes should be output in CUPS test mode (<strong>-t</strong>).
-This is the default for XML output.
+This is the default for CSV, JSON, and XML output.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-V</strong><em> VERSION</em>
+<br>
+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.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-X</strong><br>
+Specifies that XML (Apple plist) output is desired instead of the plain text report.
+This option is incompatible with the <strong>-i</strong> (interval) and <strong>-n</strong> (repeat-count) options.
</p>
<h2 id="ipptool-1.exit-status">Exit Status</h2>
<p>The
program returns 0 if all tests were successful and 1 otherwise.
</p>
<h2 id="ipptool-1.files">Files</h2>
-<p>The following standard files are available:
+<p>The following standard test files are available:
+</p>
+ <pre>
+ cancel-current-job.test - Cancel the current job
+ create-job.test - Create a job and send a document
+ create-job-sheets.test - "" with banner
+ create-job-timeout.test - "" with timeout
+ create-printer-subscription.test - Create a printer subscription
+ cups-create-local-printer.test - Create a local print queue
+ fax-job.test - Fax a file (for fax queues)
+ get-completed-jobs.test - Get a list of completed jobs
+ get-job-attributes.test - Get attributes for a job
+ get-job-template-attributes.test - Get job ticket attributes for a printer
+ get-jobs.test - Get a list of not-completed jobs
+ get-notifications.test - Get notifications for a subscription
+ get-printer-attributes.test - Get attributes for a printer
+ get-printer-attributes-suite.test - Test Get-Printer-Attributes conformance
+ get-printers.test - Get a list of printers
+ get-subscriptions.test - Get a list of subscriptions
+ identify-printer.test - Identify a printer
+ identify-printer-display.test - Identify a printer via the display
+ ipp-1.1.test - Run IPP/1.1 conformance tests
+ ipp-2.0.test - Run IPP/2.0 conformance tests
+ ipp-2.1.test - Run IPP/2.1 conformance tests
+ ipp-2.2.test - Run IPP/2.2 conformance tests
+ print-job.test - Print a file
+ print-job-and-wait.test - Print a file and wait for completion
+ print-job-deflate.test - Print a file with deflate compression
+ print-job-gzip.test - Print a file with gzip compression
+ print-job-hold.test - Print a file and hold
+ print-job-letter.test - Print a file on US Letter media
+ print-job-manual.test - Print a file with manual feed
+ print-job-media-col.test - Print a file using "media-col"
+ print-job-media-needed.test - Print a file and test for "media-needed"
+ print-job-password.test - Print a file with a password/PIN
+ print-job-raster.test - Print a generated raster file
+ print-uri.test - Print a URI/URL
+ set-attrs-hold.test - Test setting job-hold-until to hold a job
+ validate-job.test - Validate a job ticket
+</pre>
+ <p>The following standard document files are available:
</p>
<pre>
- 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
+ color.jpg - A color photo of a flower
+ document-a4.pdf - A 4-page A4 PDF document
+ document-a4.ps - A 4-page A4 PostScript document
+ document-letter.pdf - A 4-page US Letter PDF document
+ document-letter.ps - A 4-page US Letter PostScript document
+ gray.jpg - A grayscale photo of an Alcatraz doorway
+ onepage-a4-300-black-1.pwg - A one page A4 PWG Raster document
+ onepage-a4.pdf - A one page A4 PDF document
+ onepage-a4.ps - A one page A4 PostScript document
+ onepage-letter-300-black-1.pwg - A one page US Letter PWG Raster document
+ onepage-letter.pdf - A one page US Letter PDF document
+ onepage-letter.ps - A one page US Letter PostScript document
+ testfile.jpg - A color photo collage
+ testfile.pcl - A HP-PCL homage to "The Shining"
+ testfile.pdf - A historical CUPS PDF document
+ testfile.ps - A historical CUPS PostScript document
+ testfile.txt - A plain text homage to "The Shining"
</pre>
<h2 id="ipptool-1.conforming-to">Conforming To</h2>
<p>The
<p><strong>ipptoolfile</strong>(5),
IANA IPP Registry (<a href="https://www.iana.org/assignments/ipp-registrations">https://www.iana.org/assignments/ipp-registrations</a>),
-PWG Internet Printing Protocol Workgroup (<a href="https://www.pwg.org/ipp">https://www.pwg.org/ipp</a>)
-RFC 8011 (<a href="https://datatracker.ietf.org/doc/html/rfc8011">https://datatracker.ietf.org/doc/html/rfc8011</a>),
+PWG Internet Printing Protocol Workgroup (<a href="https://www.pwg.org/ipp">https://www.pwg.org/ipp</a>),
+RFC 8011 (<a href="https://datatracker.ietf.org/doc/html/rfc8011">https://datatracker.ietf.org/doc/html/rfc8011</a>)
</p>
<h2 id="ipptool-1.copyright">Copyright</h2>
-<p>Copyright © 2020-2024 by OpenPrinting.
+<p>Copyright © 2021-2024 by OpenPrinting.
</body>
</html>
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ATTR </strong><em>out-of-band-tag attribute-name</em><br>
</p>
- <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ATTR </strong><em>tag attribute-name value(s)</em><br>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ATTR </strong><em>tag attribute-name value[,...,value]</em><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ATTR </strong><em>tag attribute-name "value"[,...,"value"]</em><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ATTR </strong><em>tag attribute-name <hex-value>[,...,<hex-value>]</em><br>
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.
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>DELAY </strong><em>seconds</em>[<em>,repeat-seconds</em>]<br>
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.
-A default repeat interval of 5 seconds is used if this directive is not provided.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>DISPLAY </strong><em>attribute-name</em><br>
Specifies that value of the named attribute should be output as part of the
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>FILE filename</strong><br>
Specifies a file to include at the end of the request. This is typically used when sending a test print file.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>GENERATE-FILE { </strong><em>parameters</em><strong> }</strong><br>
+Specifies that
+<strong>ipptool</strong>
+should generate PWG or Apple raster data for the printer.
+See the "GENERATE-FILE PARAMETERS" section for information on the parameters you can specify.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>GROUP tag</strong><br>
Specifies the group tag for subsequent attributes in the request.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>SAME-COUNT-AS </strong><em>attribute-name</em><br>
Requires the <strong>EXPECT</strong> attribute to have the same number of values as the specified parallel attribute.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>SAVE-CONTENT </strong><em>filespec</em><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>SAVE-ALL-CONTENT </strong><em>filespec</em><br>
+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.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-ALL-CONTENT available</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-CONTENT available</strong><br>
+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.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-ALL-CONTENT valid</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-CONTENT valid</strong><br>
+Requires that all "http" and "https" URI values be accessible and provide valid content.
+Currently
+<strong>ipptool</strong>
+is able to validate CSS, HTML, ICC, IPP, JPEG, PDF, PNG, and Apple .strings files.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-ALL-CONTENT valid-icon</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-CONTENT valid-icon</strong><br>
+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.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-ALL-HOSTNAMES "</strong><em>literal string</em><strong>"</strong><br>
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-ALL-HOSTNAMES "/</strong><em>regular expression</em><strong>/"</strong><br>
Requires that all URI values contain a matching hostname.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-ALL-MIME-TYPES </strong><em>mime/type[,...,mime/type]</em><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-MIME-TYPES </strong><em>mime/type[,...,mime/type]</em><br>
+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,
+<strong>ipptool</strong>
+sends a HTTP GET request.
+For "ipp" and "ipps" content tests,
+<strong>ipptool</strong>
+sends an IPP Get-Printer-Attributes request.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-ALL-RESOURCES "</strong><em>literal string</em><strong>"</strong><br>
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-ALL-VALUES "/</strong><em>regular expression</em><strong>/"</strong><br>
Requires that all values of the <strong>EXPECT</strong> attribute match the regular expression, which must conform to the POSIX regular expression syntax.
Comparisons are case-sensitive.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-ALL-VALUES-FROM </strong><em>attribute-name</em><br>
+Requires that all value(s) of the <strong>EXPECT</strong> 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.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>WITH-DISTINCT-VALUES</strong><br>
Requires that all values of the <strong>EXPECT</strong> attribute are unique.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>$ENV[</strong><em>name</em><strong>]</strong><br>
Inserts the value of the named environment variable, or an empty string if the environment variable is not defined.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>$basename</strong><br>
+Inserts the base filename (without directory path) of the path provided to
+<strong>ipptool</strong>(8)
+
+with the <em>-f</em> option.
</p>
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>$date-current</strong><br>
Inserts the current date and time using the ISO-8601 format ("yyyy-mm-ddThh:mm:ssZ").
<p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>$user</strong><br>
Inserts the current user's login name.
</p>
+ <h2 id="ipptoolfile-5.generate-file-parameters">Generate-File Parameters</h2>
+<p>The
+<strong>GENERATE-FILE</strong>
+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:
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>COLORSPACE auto</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>COLORSPACE bi-level</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>COLORSPACE color</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>COLORSPACE monochrome</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>COLORSPACE </strong><em>colorspace_bits</em><br>
+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.
+<em>NOTE:</em> The "device N" color spaces are not current supported.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>FORMAT image/pwg-raster</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>FORMAT image/urf</strong><br>
+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.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>MEDIA default</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>MEDIA ready</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>MEDIA </strong><em>media-size-name</em><br>
+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.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>NUM-COPIES </strong><em>copies</em><br>
+Specifies the number of copies to produce.
+The default is 1 copy.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>NUM-PAGES </strong><em>pages</em><br>
+Specifies the number of pages to produce.
+The default is 1 page for single-sided output and 2 pages for double-sided output.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ORIENTATION landscape</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ORIENTATION portrait</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ORIENTATION reverse-landscape</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ORIENTATION reverse-portrait</strong><br>
+Specifies the orientation of the output.
+The default is "portrait".
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>RESOLUTION default</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>RESOLUTION max</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>RESOLUTION min</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>RESOLUTION </strong><em>resolution</em><strong>dpcm</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>RESOLUTION </strong><em>horzontal</em><strong>x</strong><em>vertical</em><strong>dpcm</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>RESOLUTION </strong><em>resolution</em><strong>dpi</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>RESOLUTION </strong><em>horizontal</em><strong>x</strong><em>vertical</em><strong>dpi</strong><br>
+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.
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong> SIDES one-sided</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong> SIDES two-sided-long-edge</strong><br>
+</p>
+ <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong> SIDES two-sided-short-edge</strong><br>
+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.
+</p>
+ <h2 id="ipptoolfile-5.examples">Examples</h2>
+<p>Query the "foo-default" and "foo-supported" Printer Description attributes and validate that all of its values are 'bar', 'baz', or 'none':
+</p>
+ <pre>{
+ 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)$$/"
+}
+</pre>
+<p>Query the "media-col-ready" Printer Status attribute and validate that the collection values contain "media-size" and "media-source" member attributes:
+</p>
+ <pre>{
+ 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
+}
+</pre>
<h2 id="ipptoolfile-5.see-also">See Also</h2>
-<p><strong>ipptool</strong>(1),
+<p><strong>ipptool</strong>(1)
-IANA IPP Registry (<a href="https://www.iana.org/assignments/ipp-registrations">https://www.iana.org/assignments/ipp-registrations</a>),
-PWG Internet Printing Protocol Workgroup (<a href="https://www.pwg.org/ipp">https://www.pwg.org/ipp</a>),
-RFC 8011 (<a href="https://datatracker.ietf.org/doc/html/rfc8011">https://datatracker.ietf.org/doc/html/rfc8011</a>)
+</p>
+ <p>IANA IPP Registry (<a href="https://www.iana.org/assignments/ipp-registrations">https://www.iana.org/assignments/ipp-registrations</a>)
+</p>
+ <p>PWG Internet Printing Protocol Workgroup (<a href="https://www.pwg.org/ipp">https://www.pwg.org/ipp</a>)
+</p>
+ <p>PWG 5101.1-2023: PWG Media Standardized Names v2.1 (<a href="https://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn21-20230915-5101.1.pdf">https://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn21-20230915-5101.1.pdf</a>)
+</p>
+ <p>RFC 8011 (<a href="https://datatracker.ietf.org/doc/html/rfc8011">https://datatracker.ietf.org/doc/html/rfc8011</a>)
</p>
<h2 id="ipptoolfile-5.copyright">Copyright</h2>
-<p>Copyright © 2020-2024 by OpenPrinting.
+<p>Copyright © 2021-2024 by OpenPrinting.
</body>
</html>
.\"
.\" ipptool man page.
.\"
-.\" Copyright © 2020-2024 by OpenPrinting.
+.\" Copyright © 2021-2024 by OpenPrinting.
.\" Copyright © 2010-2019 by Apple Inc.
.\"
.\" Licensed under Apache License v2.0. See the file "LICENSE" for more
.\" information.
.\"
-.TH ipptool 1 "CUPS" "2021-10-20" "OpenPrinting"
+.TH ipptool 1 "CUPS" "2024-09-12" "OpenPrinting"
.SH NAME
ipptool \- perform internet printing protocol requests
.SH SYNOPSIS
[
.B \-\-help
] [
-.B \-\-ippserver
-.I filename
+.B \-\-ippfile
+.I FILENAME
] [
.B \-\-stop\-after\-include\-error
] [
] [
.B \-6
] [
+.B \-c
+] [
.B \-C
] [
-.B \-E
+.B \-d
+.I NAME=VALUE
] [
-.B \-I
+.B \-E
] [
-.B \-L
+.B \-f
+.I FILENAME
] [
-.B \-P
-.I filename.plist
+.B \-h
] [
-.B \-S
+.B \-i
+.I SECONDS
] [
-.B \-T
-.I seconds
+.B \-I
] [
-.B \-V
-.I version
+.B \-j
] [
-.B \-X
+.B \-L
] [
-.B \-c
+.B \-n
+.I REPEAT-COUNT
] [
-.B \-d
-.I name=value
+.B \-P
+.I FILENAME.plist
] [
-.B \-f
-.I filename
+.B \-q
] [
-.B \-h
+.B \-R
] [
-.B \-i
-.I seconds
+.B \-S
] [
-.B \-j
+.B \-t
] [
-.B \-n
-.I repeat-count
+.B \-T
+.I SECONDS
] [
-.B \-q
+.B \-v
] [
-.B \-t
+.B \-V
+.I VERSION
] [
-.B \-v ]
-.I printer-uri
-.I testfile
+.B \-X
+]
+.I PRINTER-URI
+.I TESTFILE
[ ...
-.I testfile
+.I TESTFILE
]
.SH DESCRIPTION
.B ipptool
Each named
.I 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.
+Output is either a plain text, formatted text, CSV, JSON, or XML report on the standard output, with a non-zero exit status indicating that one or more tests have failed.
The
.I testfile
format is described in
.B \-\-help
Shows program help.
.TP 5
-\fB\-\-ippserver \fIfilename\fR
-Specifies that the test results should be written to the named
-.B ippserver
-attributes file.
+\fB\-\-ippfile \fIFILENAME\fR
+Specifies that the test results should be written to the named IPP file.
+These files can be used with programs like
+.BR ippeveprinter (1).
.TP 5
.B \-\-stop-after-include-error
Tells
.B ipptool
must connect to the printer or server using IPv6.
.TP 5
+.B \-c
+Specifies that CSV (comma\-separated values) output is desired instead of the plain text output.
+.TP 5
.B \-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.
.TP 5
+.BI \-d \ NAME=VALUE
+Defines the named variable.
+.TP 5
.B \-E
Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
.TP 5
-.B \-I
-Specifies that
-.B ipptool
-will continue past errors.
-.TP 5
-.B \-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.
-.TP 5
-.BI \-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 (\fB\-t\fR).
-This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options.
-.TP 5
-.B \-S
-Forces (dedicated) TLS encryption when connecting to the server.
-.TP 5
-.BI \-T \ seconds
-Specifies a timeout for IPP requests in seconds.
-.TP 5
-.BI \-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.
-.TP 5
-.B \-X
-Specifies that XML (Apple plist) output is desired instead of the plain text report.
-This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options.
-.TP 5
-.B \-c
-Specifies that CSV (comma\-separated values) output is desired instead of the plain text output.
-.TP 5
-.BI \-d \ name=value
-Defines the named variable.
-.TP 5
-.BI \-f \ filename
+.BI \-f \ FILENAME
Defines the default request filename for tests.
.TP 5
.B \-h
Validate HTTP response headers.
.TP 5
-.BI \-i \ seconds
+.BI \-i \ SECONDS
Specifies that the (last)
.I testfile
should be repeated at the specified interval.
-This option is incompatible with the \fB\-X\fR (XML plist output) option.
+This option is incompatible with the \fB\-\-ippfile\fR (IPP file output) and \fI\-P\fR or \fB\-X\fR (XML plist output) options.
+.TP 5
+.B \-I
+Specifies that
+.B ipptool
+will continue past errors.
.TP 5
.B \-j
Specifies that
.B \-l
Specifies that plain text output is desired.
.TP 5
-.BI \-n \ repeat\-count
+.B \-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.
+.TP 5
+.BI \-n \ REPEAT\-COUNT
Specifies that the (last)
.I testfile
should be repeated the specified number of times.
-This option is incompatible with the \fI\-X\fR (XML plist output) option.
+This option is incompatible with the \fI\-\-ippfile\fR (IPP file output) and \fI\-P\fR or \fI\-X\fR (XML plist output) options.
+.TP 5
+.BI \-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 (\fB\-t\fR).
+This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat-count) options.
.TP 5
.B \-q
Be quiet and produce no output.
.TP 5
+.B \-S
+Forces (dedicated) TLS encryption when connecting to the server.
+.TP 5
.B \-t
Specifies that CUPS test report output is desired instead of the plain text output.
.TP 5
+.BI \-T \ SECONDS
+Specifies a timeout for IPP requests in SECONDS.
+.TP 5
.B \-v
Specifies that all request and response attributes should be output in CUPS test mode (\fB\-t\fR).
-This is the default for XML output.
+This is the default for CSV, JSON, and XML output.
+.TP 5
+.BI \-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.
+.TP 5
+.B \-X
+Specifies that XML (Apple plist) output is desired instead of the plain text report.
+This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options.
.SH EXIT STATUS
The
.B ipptool
program returns 0 if all tests were successful and 1 otherwise.
.SH FILES
-The following standard files are available:
+The following standard test files are available:
+.nf
+
+ cancel\-current\-job.test - Cancel the current job
+ create\-job.test - Create a job and send a document
+ create\-job\-sheets.test - "" with banner
+ create\-job\-timeout.test - "" with timeout
+ create\-printer\-subscription.test - Create a printer subscription
+ cups\-create\-local\-printer.test - Create a local print queue
+ fax\-job.test - Fax a file (for fax queues)
+ get\-completed\-jobs.test - Get a list of completed jobs
+ get\-job\-attributes.test - Get attributes for a job
+ get\-job\-template\-attributes.test - Get job ticket attributes for a printer
+ get\-jobs.test - Get a list of not-completed jobs
+ get\-notifications.test - Get notifications for a subscription
+ get\-printer\-attributes.test - Get attributes for a printer
+ get\-printer\-attributes\-suite.test - Test Get-Printer-Attributes conformance
+ get\-printers.test - Get a list of printers
+ get\-subscriptions.test - Get a list of subscriptions
+ identify\-printer.test - Identify a printer
+ identify\-printer\-display.test - Identify a printer via the display
+ ipp\-1.1.test - Run IPP/1.1 conformance tests
+ ipp\-2.0.test - Run IPP/2.0 conformance tests
+ ipp\-2.1.test - Run IPP/2.1 conformance tests
+ ipp\-2.2.test - Run IPP/2.2 conformance tests
+ print\-job.test - Print a file
+ print\-job\-and\-wait.test - Print a file and wait for completion
+ print\-job\-deflate.test - Print a file with deflate compression
+ print\-job\-gzip.test - Print a file with gzip compression
+ print\-job\-hold.test - Print a file and hold
+ print\-job\-letter.test - Print a file on US Letter media
+ print\-job\-manual.test - Print a file with manual feed
+ print\-job\-media\-col.test - Print a file using "media-col"
+ print\-job\-media\-needed.test - Print a file and test for "media-needed"
+ print\-job\-password.test - Print a file with a password/PIN
+ print\-job\-raster.test - Print a generated raster file
+ print\-uri.test - Print a URI/URL
+ set\-attrs\-hold.test - Test setting job-hold-until to hold a job
+ validate\-job.test - Validate a job ticket
+.fi
+.PP
+The following standard document files are available:
.nf
- 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
+ color.jpg - A color photo of a flower
+ document\-a4.pdf - A 4-page A4 PDF document
+ document\-a4.ps - A 4-page A4 PostScript document
+ document\-letter.pdf - A 4-page US Letter PDF document
+ document\-letter.ps - A 4-page US Letter PostScript document
+ gray.jpg - A grayscale photo of an Alcatraz doorway
+ onepage\-a4\-300\-black\-1.pwg - A one page A4 PWG Raster document
+ onepage\-a4.pdf - A one page A4 PDF document
+ onepage\-a4.ps - A one page A4 PostScript document
+ onepage\-letter\-300\-black\-1.pwg - A one page US Letter PWG Raster document
+ onepage\-letter.pdf - A one page US Letter PDF document
+ onepage\-letter.ps - A one page US Letter PostScript document
+ testfile.jpg - A color photo collage
+ testfile.pcl - A HP-PCL homage to "The Shining"
+ testfile.pdf - A historical CUPS PDF document
+ testfile.ps - A historical CUPS PostScript document
+ testfile.txt - A plain text homage to "The Shining"
.fi
.SH CONFORMING TO
The
.SH SEE ALSO
.BR 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),
+PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp),
+RFC 8011 (https://datatracker.ietf.org/doc/html/rfc8011)
.SH COPYRIGHT
-Copyright \[co] 2020-2024 by OpenPrinting.
+Copyright \[co] 2021-2024 by OpenPrinting.
.\"
.\" ipptoolfile man page.
.\"
-.\" Copyright © 2020-2024 by OpenPrinting.
+.\" Copyright © 2021-2024 by OpenPrinting.
.\" Copyright © 2010-2021 by Apple Inc.
.\"
.\" Licensed under Apache License v2.0. See the file "LICENSE" for more
.\" information.
.\"
-.TH ipptoolfile 5 "CUPS" "2021-09-20" "OpenPrinting"
+.TH ipptoolfile 5 "CUPS" "2024-09-12" "OpenPrinting"
.SH NAME
ipptoolfile \- ipptool file format
.SH DESCRIPTION
.TP 5
\fBATTR \fIout-of-band-tag attribute-name\fR
.TP 5
-\fBATTR \fItag attribute-name value(s)\fR
+\fBATTR \fItag attribute-name value[,...,value]\fR
+.TP 5
+\fBATTR \fItag attribute-name "value"[,...,"value"]\fR
+.TP 5
+\fBATTR \fItag attribute-name <hex-value>[,...,<hex-value>]\fR
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.
\fBDELAY \fIseconds\fR[\fI,repeat-seconds\fR]
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.
-A default repeat interval of 5 seconds is used if this directive is not provided.
.TP 5
\fBDISPLAY \fIattribute-name\fR
Specifies that value of the named attribute should be output as part of the
\fBFILE filename\fR
Specifies a file to include at the end of the request. This is typically used when sending a test print file.
.TP 5
+\fBGENERATE\-FILE { \fIparameters\fB }\fR
+Specifies that
+.B 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.
+.TP 5
\fBGROUP tag\fR
Specifies the group tag for subsequent attributes in the request.
.TP 5
\fBSAME\-COUNT\-AS \fIattribute-name\fR
Requires the \fBEXPECT\fR attribute to have the same number of values as the specified parallel attribute.
.TP 5
+\fBSAVE\-CONTENT \fIfilespec\fR
+.TP 5
+\fBSAVE\-ALL\-CONTENT \fIfilespec\fR
+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.
+.TP 5
+\fBWITH\-ALL\-CONTENT available\fR
+.TP 5
+\fBWITH\-CONTENT available\fR
+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.
+.TP 5
+\fBWITH\-ALL\-CONTENT valid\fR
+.TP 5
+\fBWITH\-CONTENT valid\fR
+Requires that all "http" and "https" URI values be accessible and provide valid content.
+Currently
+.B ipptool
+is able to validate CSS, HTML, ICC, IPP, JPEG, PDF, PNG, and Apple .strings files.
+.TP 5
+\fBWITH\-ALL\-CONTENT valid-icon\fR
+.TP 5
+\fBWITH\-CONTENT valid-icon\fR
+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.
+.TP 5
\fBWITH\-ALL\-HOSTNAMES "\fIliteral string\fB"\fR
.TP 5
\fBWITH\-ALL\-HOSTNAMES "/\fIregular expression\fB/"\fR
Requires that all URI values contain a matching hostname.
.TP 5
+\fBWITH\-ALL\-MIME\-TYPES \fImime/type[,...,mime/type]\fR
+.TP 5
+\fBWITH\-MIME\-TYPES \fImime/type[,...,mime/type]\fR
+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,
+.B ipptool
+sends a HTTP GET request.
+For "ipp" and "ipps" content tests,
+.B ipptool
+sends an IPP Get-Printer-Attributes request.
+.TP 5
\fBWITH\-ALL\-RESOURCES "\fIliteral string\fB"\fR
.TP 5
\fBWITH\-ALL\-RESOURCES "/\fIregular expression\fB/"\fR
.TP 5
\fBWITH\-ALL\-SCHEMES "\fIliteral string\fB"\fR
.TP 5
-\fBWITH\-ALL-SCHEMES "/\fIregular expression\fB/"\fR
+\fBWITH\-ALL\-SCHEMES "/\fIregular expression\fB/"\fR
Requires that all URI values contain a matching scheme.
.TP 5
\fBWITH\-ALL\-VALUES "\fIliteral string\fB"\fR
Requires that all values of the \fBEXPECT\fR attribute match the regular expression, which must conform to the POSIX regular expression syntax.
Comparisons are case-sensitive.
.TP 5
+\fBWITH\-ALL\-VALUES\-FROM \fIattribute-name\fR
+Requires that all value(s) of the \fBEXPECT\fR 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.
+.TP 5
\fBWITH\-DISTINCT\-VALUES\fR
Requires that all values of the \fBEXPECT\fR attribute are unique.
Comparisons are case-sensitive.
\fB$ENV[\fIname\fB]\fR
Inserts the value of the named environment variable, or an empty string if the environment variable is not defined.
.TP 5
+\fB$basename\fR
+Inserts the base filename (without directory path) of the path provided to
+.BR ipptool (8)
+with the \fI-f\fR option.
+.TP 5
\fB$date-current\fR
Inserts the current date and time using the ISO-8601 format ("yyyy-mm-ddThh:mm:ssZ").
.TP 5
.TP 5
\fB$user\fR
Inserts the current user's login name.
+.SH GENERATE\-FILE PARAMETERS
+The
+.B 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:
+.TP 5
+\fBCOLORSPACE auto\fR
+.TP 5
+\fBCOLORSPACE bi-level\fR
+.TP 5
+\fBCOLORSPACE color\fR
+.TP 5
+\fBCOLORSPACE monochrome\fR
+.TP 5
+\fBCOLORSPACE \fIcolorspace_bits\fR
+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.
+\fINOTE:\fR The "device N" color spaces are not current supported.
+.TP 5
+\fBFORMAT image/pwg-raster\fR
+.TP 5
+\fBFORMAT image/urf\fR
+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.
+.TP 5
+\fBMEDIA default\fR
+.TP 5
+\fBMEDIA ready\fR
+.TP 5
+\fBMEDIA \fImedia-size-name\fR
+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.
+.TP 5
+\fBNUM\-COPIES \fIcopies\fR
+Specifies the number of copies to produce.
+The default is 1 copy.
+.TP 5
+\fBNUM\-PAGES \fIpages\fR
+Specifies the number of pages to produce.
+The default is 1 page for single-sided output and 2 pages for double-sided output.
+.TP 5
+\fBORIENTATION landscape\fR
+.TP 5
+\fBORIENTATION portrait\fR
+.TP 5
+\fBORIENTATION reverse-landscape\fR
+.TP 5
+\fBORIENTATION reverse-portrait\fR
+Specifies the orientation of the output.
+The default is "portrait".
+.TP 5
+\fBRESOLUTION default\fR
+.TP 5
+\fBRESOLUTION max\fR
+.TP 5
+\fBRESOLUTION min\fR
+.TP 5
+\fBRESOLUTION \fIresolution\fBdpcm\fR
+.TP 5
+\fBRESOLUTION \fIhorzontal\fBx\fIvertical\fBdpcm\fR
+.TP 5
+\fBRESOLUTION \fIresolution\fBdpi\fR
+.TP 5
+\fBRESOLUTION \fIhorizontal\fBx\fIvertical\fBdpi\fR
+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.
+.TP 5
+\fB SIDES one-sided\fR
+.TP 5
+\fB SIDES two-sided-long-edge\fR
+.TP 5
+\fB SIDES two-sided-short-edge\fR
+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.
+.SH EXAMPLES
+Query the "foo-default" and "foo-supported" Printer Description attributes and validate that all of its values are 'bar', 'baz', or 'none':
+.nf
+{
+ 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)$$/"
+}
+.fi
+Query the "media-col-ready" Printer Status attribute and validate that the collection values contain "media-size" and "media-source" member attributes:
+.nf
+{
+ 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
+}
+.fi
.SH SEE ALSO
-.BR ipptool (1),
-IANA IPP Registry (https://www.iana.org/assignments/ipp-registrations),
-PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp),
+.BR ipptool (1)
+.PP
+IANA IPP Registry (https://www.iana.org/assignments/ipp-registrations)
+.PP
+PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp)
+.PP
+PWG 5101.1-2023: PWG Media Standardized Names v2.1 (https://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn21-20230915-5101.1.pdf)
+.PP
RFC 8011 (https://datatracker.ietf.org/doc/html/rfc8011)
.SH COPYRIGHT
-Copyright \[co] 2020-2024 by OpenPrinting.
+Copyright \[co] 2021-2024 by OpenPrinting.
char scheme[256], // Scheme
userpass[256], // Username:password (not used)
host[256], // Hostname
- resource[256]; // Resource path
+ resource[256], // Resource path
+ *resptr; // Pointer into resource
int port; // Port number
http_encryption_t encryption; // Encryption mode
http_uri_status_t uri_status; // URI decoding status
continue;
}
+ if ((resptr = strchr(resource, '#')) != NULL)
+ *resptr = '\0'; // Strip HTML target ("...#target")
+
if (strcmp(scheme, "http") && strcmp(scheme, "https") && strcmp(scheme, "ipp") && strcmp(scheme, "ipps"))
{
add_stringf(errors, "Unsupported URI scheme for '%s'.", uri);
if (status != HTTP_STATUS_OK)
{
- add_stringf(errors, "Got unexpected status %d for HEAD request to '%s'.", (int)status, uri);
+ add_stringf(errors, "Got unexpected status %d for GET request to '%s'.", (int)status, uri);
ret = false;
goto get_done;
}
}
else if (!_cups_strcasecmp(content_type, "image/jpeg") || !_cups_strcasecmp(content_type, "image/png"))
{
+ // Validate image content
if (!valid_image(filename, &width, &height, &depth))
{
- add_stringf(errors, "Unable to load image '%s'.", uri);
+ add_stringf(errors, "Unable to open image '%s'.", uri);
ret = false;
goto get_done;
}
}
- else if (!_cups_strcasecmp(content_type, "application/pdf") || !_cups_strcasecmp(content_type, "application/ipp") || !_cups_strcasecmp(content_type, "application/vnd.iccprofile") || !_cups_strcasecmp(content_type, "text/css") || !_cups_strcasecmp(content_type, "text/html") || !_cups_strcasecmp(content_type, "text/strings"))
+ else if (!_cups_strcasecmp(content_type, "application/ipp"))
+ {
+ ipp_t *ipp = ippNew(); // IPP message
+
+ if ((fd = open(filename, O_RDONLY | O_BINARY)) < 0)
+ {
+ add_stringf(errors, "Unable to open '%s': %s", uri, strerror(errno));
+ ippDelete(ipp);
+ ret = false;
+ goto get_done;
+ }
+ else if (ippReadFile(fd, ipp) != IPP_STATE_DATA)
+ {
+ add_stringf(errors, "Unable to read '%s': %s", uri, cupsGetErrorString());
+ ippDelete(ipp);
+ close(fd);
+ ret = false;
+ goto get_done;
+ }
+
+ ippDelete(ipp);
+ close(fd);
+ }
+ else if (!_cups_strcasecmp(content_type, "application/pdf") || !_cups_strcasecmp(content_type, "application/vnd.iccprofile") || !_cups_strcasecmp(content_type, "text/css") || !_cups_strcasecmp(content_type, "text/html") || !_cups_strncasecmp(content_type, "text/html;", 10) || !_cups_strcasecmp(content_type, "text/strings"))
{
// Just require these files to be non-empty for now, might add more checks in the future...
if (fileinfo.st_size == 0)
}
else
{
- add_stringf(errors, "Got unexpected Content-Type '%s' for HEAD request to '%s'.", content_type, uri);
+ add_stringf(errors, "Got unexpected Content-Type '%s' for GET request to '%s'.", content_type, uri);
ret = false;
goto get_done;
}
projects / thirdparty / cups.git / commitdiff
