1ipptoolfile(5) OpenPrinting ipptoolfile(5)
2
6 ipptoolfile - ipptool file format
7
9 The ipptool(1) program accepts free-form plain text files that describe
10 one or more IPP requests. Comments start with the "#" character and
11 continue to the end of the line. Each request is enclosed by curly
12 braces, for example:
13 # This is a comment
15 {
16 # The name of the test
17 NAME "Print PDF File"
18 # The request to send
20 OPERATION Print-Job
21 GROUP operation-attributes-tag
23 ATTR charset attributes-charset utf-8
24 ATTR language attributes-natural-language en
25 ATTR uri printer-uri $uri
26 ATTR name requesting-user-name $user
27 ATTR mimeMediaType document-format application/pdf
28 GROUP job-attributes-tag
30 ATTR collection media-col {
31 # US Letter plain paper from the "main" tray
32 MEMBER collection media-size {
33 MEMBER integer x-dimension 21590
34 MEMBER integer y-dimension 27940
35 }
36 MEMBER integer media-top-margin 423
37 MEMBER integer media-bottom-margin 423
38 MEMBER integer media-left-margin 423
39 MEMBER integer media-right-margin 423
40 MEMBER keyword media-source "main"
41 MEMBER keyword media-type "stationery"
42 }
43 FILE testfile.pdf
45 # The response to expect
47 STATUS successful-ok
48 EXPECT job-id OF-TYPE integer WITH-VALUE >0
49 EXPECT job-uri OF-TYPE uri
50 }
51 {
52 # The name of the test
53 NAME "Wait for Job to Complete"
54 # The request to send
56 OPERATION Get-Job-Attributes
57 GROUP operation-attributes-tag
59 ATTR charset attributes-charset utf-8
60 ATTR language attributes-natural-language en
61 ATTR uri printer-uri $uri
62 ATTR integer job-id $job-id
63 ATTR name requesting-user-name $user
64 # The response to expect
66 STATUS successful-ok
67 EXPECT job-id OF-TYPE integer WITH-VALUE $job-id
68 EXPECT job-uri OF-TYPE uri
69 EXPECT job-state OF-TYPE enum WITH-VALUE >5 REPEAT-NO-MATCH
70 EXPECT job-originating-user-name OF-TYPE name WITH-VALUE "$user"
71 # Show the job state until completed...
73 DISPLAY job-state
74 DISPLAY job-state-reasons
75 }
76 TOP-LEVEL DIRECTIVES
78 The following directives can be used outside of a test:
79 { test }
81 Defines a test.
82 DEFINE variable-name value
84 Defines the named variable to the given value. This is equivalent
85 to specifying -d variable-name=value on the ipptool(8) command-
86 line.
87 DEFINE-DEFAULT variable-name value
89 Defines the named variable to the given value if it does not al‐
90 ready have a value.
91 FILE-ID "identifier"
93 Specifies an identifier string for the current file.
94 IGNORE-ERRORS yes
96 IGNORE-ERRORS no
98 Specifies whether, by default, ipptool(8) will ignore errors and
99 continue with subsequent tests.
100 INCLUDE "filename"
102 INCLUDE <filename>
104 Includes another test file. The first form includes a file rela‐
105 tive to the current test file, while the second form includes a
106 file from the ipptool(8) include directory.
107 INCLUDE-IF-DEFINED name "filename"
109 INCLUDE-IF-DEFINED name <filename>
111 Includes another test file if the named variable is defined. The
112 first form includes a file relative to the current test file,
113 while the second form includes a file from the ipptool(8) include
114 directory.
115 INCLUDE-IF-NOT-DEFINED name "filename"
117 INCLUDE-IF-NOT-DEFINED name <filename>
119 Includes another test file if the named variable is not defined.
120 The first form includes a file relative to the current test file,
121 while the second form includes a file from the ipptool(8) include
122 directory.
123 SKIP-IF-DEFINED variable-name
125 SKIP-IF-NOT-DEFINED variable-name
127 Specifies that the remainder of the test file should be skipped
128 when the variable is or is not defined.
129 STOP-AFTER-INCLUDE-ERROR no
131 STOP-AFTER-INCLUDE-ERROR yes
133 Specifies whether tests will be stopped after an error in an in‐
134 cluded file.
135 TRANSFER auto
137 Specifies that tests will, by default, use "Transfer-Encoding:
138 chunked" for requests with attached files and "Content-Length:"
139 for requests without attached files.
140 TRANSFER chunked
142 Specifies that tests will, by default, use the HTTP/1.1 "Transfer-
143 Encoding: chunked" header. This is the default and is equivalent
144 to specifying -c on the ipptool(8) command-line. Support for chun‐
145 ked requests is required for conformance with all versions of IPP.
146 TRANSFER length
148 Specifies that tests will, by default, use the HTTP/1.0 "Content-
149 Length:" header. This is equivalent to specifying -l on the ipp‐
150 tool(8) command-line. Support for content length requests is re‐
151 quired for conformance with all versions of IPP.
152 VERSION 1.0
154 VERSION 1.1
156 VERSION 2.0
158 VERSION 2.1
160 VERSION 2.2
162 Specifies the default IPP version number to use for the tests that
163 follow.
164 TEST DIRECTIVES
166 The following directives are understood within a test:
167 ATTR out-of-band-tag attribute-name
169 ATTR tag attribute-name value(s)
171 Adds an attribute to the test request. Out-of-band tags (admin-
172 define, delete-attribute, no-value, not-settable, unknown, unsup‐
173 ported) have no value. Values for other tags are delimited by the
174 comma (",") character - escape commas using the "\" character.
175 Common attributes and values are listed in the IANA IPP registry -
176 see references below.
177 ATTR collection attribute-name { MEMBER tag member-name value(s) ... }
179 [ ... ,{ ... } ]
180 Adds a collection attribute to the test request. Member at‐
181 tributes follow the same syntax as regular attributes and can
182 themselves be nested collections. Multiple collection values can
183 be supplied as needed, separated by commas.
184 COMPRESSION deflate
186 COMPRESSION gzip
188 COMPRESSION none
190 Uses the specified compression on the document data following the
191 attributes in a Print-Job or Send-Document request.
192 DELAY seconds[,repeat-seconds]
194 Specifies a delay in seconds before this test will be run. If two
195 values are specified, the second value is used as the delay be‐
196 tween repeated tests.
197 DISPLAY attribute-name
199 Specifies that value of the named attribute should be output as
200 part of the test report.
201 EXPECT attribute-name [ predicate(s) ]
203 EXPECT ?attribute-name predicate(s)
205 EXPECT !attribute-name
207 Specifies that the response must/may/must not include the named
208 attribute. Additional requirements can be added as predicates -
209 see the "EXPECT PREDICATES" section for more information on predi‐
210 cates. Attribute names can specify member attributes by separating
211 the attribute and member names with the forward slash, for example
212 "media-col/media-size/x-dimension".
213 EXPECT-ALL attribute-name [ predicate(s) ]
215 EXPECT-ALL ?attribute-name predicate(s)
217 Specifies that the response must/may include the named attribute
218 and that all occurrences of that attribute must match the given
219 predicates.
220 FILE filename
222 Specifies a file to include at the end of the request. This is
223 typically used when sending a test print file.
224 GROUP tag
226 Specifies the group tag for subsequent attributes in the request.
227 IGNORE-ERRORS yes
229 IGNORE-ERRORS no
231 Specifies whether ipptool(8) will ignore errors and continue with
232 subsequent tests.
233 MONITOR-PRINTER-STATE [ printer-uri ] { EXPECT attribute-name [ predi‐
235 cate(s) ] }
236 Specifies printer state monitoring tests to run in parallel with
237 the test operation. The monitoring tests will run until all of
238 the EXPECT conditions are satisfied or the primary test operation
239 has completed, whichever occurs first.
240 NAME "literal string"
242 Specifies the human-readable name of the test.
243 OPERATION operation-code
245 Specifies the operation to be performed.
246 PASS-IF-DEFINED variable-name
248 PASS-IF-NOT-DEFINED variable-name
250 Specifies that the current test should be passed automatically
251 when the variable is or is not defined.
252 PAUSE "message"
254 Displays the provided message and waits for the user to press a
255 key to continue.
256 REQUEST-ID number
258 REQUEST-ID random
260 Specifies the request-id value to use in the request, either an
261 integer or the word "random" to use a randomly generated value
262 (the default).
263 RESOURCE path
265 Specifies an alternate resource path that is used for the HTTP
266 POST request. The default is the resource from the URI provided to
267 the ipptool(8) program.
268 SKIP-IF-DEFINED variable-name
270 SKIP-IF-NOT-DEFINED variable-name
272 Specifies that the current test should be skipped when the vari‐
273 able is or is not defined.
274 SKIP-PREVIOUS-ERROR yes
276 SKIP-PREVIOUS-ERROR no
278 Specifies whether ipptool(8) will skip the current test if the
279 previous test resulted in an error/failure.
280 STATUS status-code [ predicate ]
282 Specifies an expected response status-code value. Additional re‐
283 quirements can be added as predicates - see the "STATUS PREDI‐
284 CATES" section for more information on predicates.
285 TEST-ID "identifier"
287 Specifies an identifier string for the current test.
288 TRANSFER auto
290 Specifies that this test will use "Transfer-Encoding: chunked" if
291 it has an attached file or "Content-Length:" otherwise.
292 TRANSFER chunked
294 Specifies that this test will use the HTTP/1.1 "Transfer-Encoding:
295 chunked" header.
296 TRANSFER length
298 Specifies that this test will use the HTTP/1.0 "Content-Length:"
299 header.
300 VERSION 1.0
302 VERSION 1.1
304 VERSION 2.0
306 VERSION 2.1
308 VERSION 2.2
310 Specifies the IPP version number to use for this test.
311 EXPECT PREDICATES
313 The following predicates are understood following the EXPECT test di‐
314 rective:
315 COUNT number
317 Requires the EXPECT attribute to have the specified number of val‐
318 ues.
319 DEFINE-MATCH variable-name
321 Defines the variable to "1" when the EXPECT condition matches. A
322 side-effect of this predicate is that this EXPECT will never fail
323 a test.
324 DEFINE-NO-MATCH variable-name
326 Defines the variable to "1" when the EXPECT condition does not
327 match. A side-effect of this predicate is that this EXPECT will
328 never fail a test.
329 DEFINE-VALUE variable-name
331 Defines the variable to the value of the attribute when the EXPECT
332 condition matches. A side-effect of this predicate is that this
333 EXPECT will never fail a test.
334 DISPLAY-MATCH "message"
336 Displays the specified message when the EXPECT condition matches.
337 IF-DEFINED variable-name
339 Makes the EXPECT conditions apply only if the specified variable
340 is defined.
341 IF-NOT-DEFINED variable-name
343 Makes the EXPECT conditions apply only if the specified variable
344 is not defined.
345 IN-GROUP tag
347 Requires the EXPECT attribute to be in the specified group tag.
348 OF-TYPE tag[(limits)|tag|...]
350 Requires the EXPECT attribute to use one of the specified value
351 tag(s). Most value tags also support the specification of limits
352 in parenthesis, for example "name(42)" would allow nameWith/With‐
353 outLanguage strings up to 42 octets in length, "name(4:MAX)" would
354 allow nameWith/WithoutLanguage strings between 4 and 255 octets in
355 length, and "integer(-273:MAX)" would allow integers between -273
356 and 2147483647.
357 REPEAT-LIMIT number
359 Specifies the maximum number of times to repeat if the REPEAT-
360 MATCH or REPEAT-NO-MATCH predicate is specified. The default value
361 is 1000.
362 REPEAT-MATCH
364 REPEAT-NO-MATCH
366 Specifies that the current test should be repeated when the EXPECT
367 condition matches or does not match.
368 SAME-COUNT-AS attribute-name
370 Requires the EXPECT attribute to have the same number of values as
371 the specified parallel attribute.
372 WITH-ALL-HOSTNAMES "literal string"
374 WITH-ALL-HOSTNAMES "/regular expression/"
376 Requires that all URI values contain a matching hostname.
377 WITH-ALL-RESOURCES "literal string"
379 WITH-ALL-RESOURCES "/regular expression/"
381 Requires that all URI values contain a matching resource (includ‐
382 ing leading /).
383 WITH-ALL-SCHEMES "literal string"
385 WITH-ALL-SCHEMES "/regular expression/"
387 Requires that all URI values contain a matching scheme.
388 WITH-ALL-VALUES "literal string"
390 Requires that all values of the EXPECT attribute match the literal
391 string. Comparisons are case-sensitive.
392 WITH-ALL-VALUES <number
394 WITH-ALL-VALUES =number
396 WITH-ALL-VALUES >number
398 WITH-ALL-VALUES number[,...,number]
400 Requires that all values of the EXPECT attribute match the num‐
401 ber(s) or numeric comparison. When comparing rangeOfInteger val‐
402 ues, the "<" and ">" operators only check the upper bound of the
403 range.
404 WITH-ALL-VALUES "false"
406 WITH-ALL-VALUES "true"
408 Requires that all values of the EXPECT attribute match the boolean
409 value given.
410 WITH-ALL-VALUES "/regular expression/"
412 Requires that all values of the EXPECT attribute match the regular
413 expression, which must conform to the POSIX regular expression
414 syntax. Comparisons are case-sensitive.
415 WITH-DISTINCT-VALUES
417 Requires that all values of the EXPECT attribute are unique. Com‐
418 parisons are case-sensitive. Only charset, collection, enum, in‐
419 teger, keyword, mimeMediaType, naturalLanguage, rangeOfInteger,
420 resolution, uriScheme attributes support this predicate.
421 WITH-HOSTNAME "literal string"
423 WITH-HOSTNAME "/regular expression/"
425 Requires that at least one URI value contains a matching hostname.
426 WITH-RESOURCE "literal string"
428 WITH-RESOURCE "/regular expression/"
430 Requires that at least one URI value contains a matching resource
431 (including leading /).
432 WITH-SCHEME "literal string"
434 WITH-SCHEME "/regular expression/"
436 Requires that at least one URI value contains a matching scheme.
437 WITH-VALUE "literal string"
439 Requires that at least one value of the EXPECT attribute matches
440 the literal string. Comparisons are case-sensitive.
441 WITH-VALUE <number
443 WITH-VALUE =number
445 WITH-VALUE >number
447 WITH-VALUE number[,...,number]
449 Requires that at least one value of the EXPECT attribute matches
450 the number(s) or numeric comparison. When comparing rangeOfInteger
451 values, the "<" and ">" operators only check the upper bound of
452 the range.
453 WITH-VALUE "false"
455 WITH-VALUE "true"
457 Requires that at least one value of the EXPECT attribute matches
458 the boolean value given.
459 WITH-VALUE "/regular expression/"
461 Requires that at least one value of the EXPECT attribute matches
462 the regular expression, which must conform to the POSIX regular
463 expression syntax. Comparisons are case-sensitive.
464 WITH-VALUE-FROM attribute-name
466 Requires that the value(s) of the EXPECT attribute matches the
467 value(s) in the specified attribute. For example, "EXPECT
468 job-sheets WITH-VALUE-FROM job-sheets-supported" requires that the
469 "job-sheets" value is listed as a value of the "job-sheets-sup‐
470 ported" attribute.
471 STATUS PREDICATES
473 The following predicates are understood following the STATUS test di‐
474 rective:
475 DEFINE-MATCH variable-name
477 Defines the variable to "1" when the STATUS matches. A side-effect
478 of this predicate is that this STATUS will never fail a test.
479 DEFINE-NO-MATCH variable-name
481 Defines the variable to "1" when the STATUS does not match. A
482 side-effect of this predicate is that this STATUS will never fail
483 a test.
484 IF-DEFINED variable-name
486 Makes the STATUS apply only if the specified variable is defined.
487 IF-NOT-DEFINED variable-name
489 Makes the STATUS apply only if the specified variable is not de‐
490 fined.
491 REPEAT-LIMIT number
493 Specifies the maximum number of times to repeat. The default value
494 is 1000.
495 REPEAT-MATCH
497 REPEAT-NO-MATCH
499 Specifies that the current test should be repeated when the re‐
500 sponse status-code matches or does not match the value specified
501 by the STATUS directive.
502 OPERATION CODES
504 Operation codes correspond to the hexadecimal numbers (0xHHHH) and
505 names from RFC 8011 and other IPP extension specifications. Here is a
506 complete list of names supported by ipptool(8):
507 Acknowledge-Document
509 Acknowledge-Identify-Printer
510 Acknowledge-Job
511 Activate-Printer
512 Add-Document-Images
513 Allocate-Printer-Resources
514 Cancel-Current-Job
515 Cancel-Job
516 Cancel-Jobs
517 Cancel-My-Jobs
518 Cancel-Resource
519 Cancel-Subscription
520 Close-Job
521 Create-Job
522 Create-Job-Subscriptions
523 Create-Printer
524 Create-Printer-Subscriptions
525 Create-Resource
526 Create-Resource-Subscriptions
527 Create-System-Subscriptions
528 CUPS-Accept-Jobs
529 CUPS-Accept-Jobs
530 CUPS-Add-Modify-Class
531 CUPS-Add-Modify-Printer
532 CUPS-Authenticate-Job
533 CUPS-Create-Local-Printer
534 CUPS-Delete-Class
535 CUPS-Delete-Printer
536 CUPS-Get-Classes
537 CUPS-Get-Default
538 CUPS-Get-Devices
539 CUPS-Get-Document
540 CUPS-Get-PPD
541 CUPS-Get-PPDs
542 CUPS-Get-Printers
543 CUPS-Move-Job
544 CUPS-Reject-Jobs
545 CUPS-Set-Default
546 Deactivate-Printer
547 Deallocate-Printer-Resources
548 Delete-Printer
549 Deregister-Output-Device
550 Disable-All-Printers
551 Disable-Printer
552 Enable-All-Printers
553 Enable-Printer
554 Fetch-Document
555 Fetch-Job
556 Get-Job-Attributes
557 Get-Jobs
558 Get-Next-Document-Data
559 Get-Notifications
560 Get-Output-Device-Attributes
561 Get-Printer-Attributes
562 Get-Printer-Support-Files
563 Get-Printer-Supported-Values
564 Get-Printers
565 Get-Subscription-Attributes
566 Get-Subscriptions
567 Get-System-Attributes
568 Get-System-Supported-Values
569 Hold-Job
570 Hold-New-Jobs
571 Identify-Printer
572 Install-Resource
573 Pause-All-Printers
574 Pause-All-Printers-After-Current-Job
575 Pause-Printer
576 Pause-Printer-After-Current-Job
577 Print-Job
578 Print-URI
579 Promote-Job
580 Purge-Jobs
581 Register-Output-Device
582 Release-Held-New-Jobs
583 Release-Job
584 Renew-Subscription
585 Reprocess-Job
586 Restart-Job
587 Restart-Printer
588 Restart-System
589 Resubmit-Job
590 Resume-All-Printers
591 Resume-Job
592 Resume-Printer
593 Schedule-Job-After
594 Send-Document
595 Send-Hardcopy-Document
596 Send-Notifications
597 Send-Resource-Data
598 Send-URI
599 Set-Job-Attributes
600 Set-Printer-Attributes
601 Set-Resource-Attributes
602 Set-System-Attributes
603 Shutdown-All-Printers
604 Shutdown-One-Printer
605 Shutdown-Printer
606 Startup-All-Printers
607 Startup-One-Printer
608 Startup-Printer
609 Suspend-Current-Job
610 Update-Active-Jobs
611 Update-Document-Status
612 Update-Job-Status
613 Update-Output-Device-Attributes
614 Validate-Document
615 Validate-Job
616 STATUS CODES
618 Status codes correspond to the hexadecimal numbers (0xHHHH) and names
619 from RFC 8011 and other IPP extension specifications. Here is a com‐
620 plete list of the names supported by ipptool(8):
621 client-error-account-authorization-failed
623 client-error-account-closed
624 client-error-account-info-needed
625 client-error-account-limit-reached
626 client-error-attributes-not-settable
627 client-error-attributes-or-values-not-supported
628 client-error-bad-request
629 client-error-charset-not-supported
630 client-error-compression-error
631 client-error-compression-not-supported
632 client-error-conflicting-attributes
633 client-error-document-access-error
634 client-error-document-format-error
635 client-error-document-format-not-supported
636 client-error-document-password-error
637 client-error-document-permission-error
638 client-error-document-security-error
639 client-error-document-unprintable-error
640 client-error-forbidden
641 client-error-gone
642 client-error-ignored-all-notifications
643 client-error-ignored-all-subscriptions
644 client-error-not-authenticated
645 client-error-not-authorized
646 client-error-not-fetchable
647 client-error-not-found
648 client-error-not-possible
649 client-error-print-support-file-not-found
650 client-error-request-entity-too-large
651 client-error-request-value-too-long
652 client-error-timeout
653 client-error-too-many-subscriptions
654 client-error-uri-scheme-not-supported
655 cups-error-account-authorization-failed
656 cups-error-account-closed
657 cups-error-account-info-needed
658 cups-error-account-limit-reached
659 cups-see-other
660 redirection-other-site
661 server-error-busy
662 server-error-device-error
663 server-error-internal-error
664 server-error-job-canceled
665 server-error-multiple-document-jobs-not-supported
666 server-error-not-accepting-jobs
667 server-error-operation-not-supported
668 server-error-printer-is-deactivated
669 server-error-service-unavailable
670 server-error-temporary-error
671 server-error-version-not-supported
672 successful-ok
673 successful-ok-but-cancel-subscription
674 successful-ok-conflicting-attributes
675 successful-ok-events-complete
676 successful-ok-ignored-notifications
677 successful-ok-ignored-or-substituted-attributes
678 successful-ok-ignored-subscriptions
679 successful-ok-too-many-events
680 TAGS
682 Value and group tags correspond to the names from RFC 8011 and other
683 IPP extension specifications. Here are the group tags:
684 document-attributes-tag
686 event-notification-attributes-tag
687 job | job-attributes-tag
688 operation | operation-attributes-tag
689 printer | printer-attributes-tag
690 resource-attributes-tag
691 subscription-attributes-tag
692 system-attributes-tag
693 unsupported-attributes-tag
694 Here are the value tags:
696 admin-define
698 boolean
699 charset
700 collection | begCollection
701 dateTime
702 default
703 delete-attribute
704 enum
705 integer
706 keyword
707 language | naturalLanguage
708 mimetype | mimeMediaType
709 name | nameWithLanguage | nameWithoutLanguage
710 no-value
711 not-settable
712 octetString
713 rangeOfInteger
714 resolution
715 text | textWithLanguage | textWithoutLanguage
716 unknown
717 unsupported
718 uri
719 uriScheme
720 VARIABLES
722 The ipptool(8) program maintains a list of variables that can be used
723 in any literal string or attribute value by specifying "$variable-
724 name". Aside from variables defined using the -d option or DEFINE di‐
725 rective, the following pre-defined variables are available:
726 $$ Inserts a single "$" character.
728 $ENV[name]
730 Inserts the value of the named environment variable, or an empty
731 string if the environment variable is not defined.
732 $date-current
734 Inserts the current date and time using the ISO-8601 format
735 ("yyyy-mm-ddThh:mm:ssZ").
736 $date-start
738 Inserts the starting date and time using the ISO-8601 format
739 ("yyyy-mm-ddThh:mm:ssZ").
740 $filename
742 Inserts the filename provided to ipptool(8) with the -f option.
743 $filetype
745 Inserts the MIME media type for the filename provided to ipp‐
746 tool(8) with the -f option.
747 $hostname
749 Inserts the hostname from the URI provided to ipptool(8).
750 $job-id
752 Inserts the last "job-id" attribute value returned in a test re‐
753 sponse or 0 if no "job-id" attribute has been seen.
754 $job-uri
756 Inserts the last "job-uri" attribute value returned in a test re‐
757 sponse or an empty string if no "job-uri" attribute has been seen.
758 $notify-subscription-id
760 Inserts the last "notify-subscription-id" attribute value returned
761 in a test response or 0 if no "notify-subscription-id" attribute
762 has been seen.
763 $port
765 Inserts the port number from the URI provided to ipptool(8).
766 $resource
768 Inserts the resource path from the URI provided to ipptool(8).
769 $scheme
771 Inserts the scheme from the URI provided to ipptool(8).
772 $uri Inserts the URI provided to ipptool(8).
774 $uriuser
776 Inserts the username from the URI provided to ipptool(8), if any.
777 $user
779 Inserts the current user's login name.
780
782 ipptool(1), IANA IPP Registry (https://www.iana.org/assignments/ipp-
783 registrations), PWG Internet Printing Protocol Workgroup
784 (https://www.pwg.org/ipp), RFC 8011 (https://data‐
785 tracker.ietf.org/doc/html/rfc8011)
786
788 Copyright © 2021-2022 by OpenPrinting.
7892021-09-20 CUPS ipptoolfile(5)