1ipptoolfile(5) Apple Inc. 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
90 already 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
134 included 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
151 required 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
181 attributes 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
196 between 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 NAME "literal string"
235 Specifies the human-readable name of the test.
236 OPERATION operation-code
238 Specifies the operation to be performed.
239 PAUSE "message"
241 Displays the provided message and waits for the user to press a
242 key to continue.
243 REQUEST-ID number
245 REQUEST-ID random
247 Specifies the request-id value to use in the request, either an
248 integer or the word "random" to use a randomly generated value
249 (the default).
250 RESOURCE path
252 Specifies an alternate resource path that is used for the HTTP
253 POST request. The default is the resource from the URI provided to
254 the ipptool(8) program.
255 SKIP-IF-DEFINED variable-name
257 SKIP-IF-NOT-DEFINED variable-name
259 Specifies that the current test should be skipped when the vari‐
260 able is or is not defined.
261 SKIP-PREVIOUS-ERROR yes
263 SKIP-PREVIOUS-ERROR no
265 Specifies whether ipptool(8) will skip the current test if the
266 previous test resulted in an error/failure.
267 STATUS status-code [ predicate ]
269 Specifies an expected response status-code value. Additional
270 requirements can be added as predicates - see the "STATUS PREDI‐
271 CATES" section for more information on predicates.
272 TEST-ID "identifier"
274 Specifies an identifier string for the current test.
275 TRANSFER auto
277 Specifies that this test will use "Transfer-Encoding: chunked" if
278 it has an attached file or "Content-Length:" otherwise.
279 TRANSFER chunked
281 Specifies that this test will use the HTTP/1.1 "Transfer-Encoding:
282 chunked" header.
283 TRANSFER length
285 Specifies that this test will use the HTTP/1.0 "Content-Length:"
286 header.
287 VERSION 1.0
289 VERSION 1.1
291 VERSION 2.0
293 VERSION 2.1
295 VERSION 2.2
297 Specifies the IPP version number to use for this test.
298 EXPECT PREDICATES
300 The following predicates are understood following the EXPECT test
301 directive:
302 COUNT number
304 Requires the EXPECT attribute to have the specified number of val‐
305 ues.
306 DEFINE-MATCH variable-name
308 Defines the variable to "1" when the EXPECT condition matches. A
309 side-effect of this predicate is that this EXPECT will never fail
310 a test.
311 DEFINE-NO-MATCH variable-name
313 Defines the variable to "1" when the EXPECT condition does not
314 match. A side-effect of this predicate is that this EXPECT will
315 never fail a test.
316 DEFINE-VALUE variable-name
318 Defines the variable to the value of the attribute when the EXPECT
319 condition matches. A side-effect of this predicate is that this
320 EXPECT will never fail a test.
321 IF-DEFINED variable-name
323 Makes the EXPECT conditions apply only if the specified variable
324 is defined.
325 IF-NOT-DEFINED variable-name
327 Makes the EXPECT conditions apply only if the specified variable
328 is not defined.
329 IN-GROUP tag
331 Requires the EXPECT attribute to be in the specified group tag.
332 OF-TYPE tag[|tag,...]
334 Requires the EXPECT attribute to use one of the specified value
335 tag(s).
336 REPEAT-LIMIT number
338 Specifies the maximum number of times to repeat if the REPEAT-
339 MATCH or REPEAT-NO-MATCH predicate is specified. The default value
340 is 1000.
341 REPEAT-MATCH
343 REPEAT-NO-MATCH
345 Specifies that the current test should be repeated when the EXPECT
346 condition matches or does not match.
347 SAME-COUNT-AS attribute-name
349 Requires the EXPECT attribute to have the same number of values as
350 the specified parallel attribute.
351 WITH-ALL-HOSTNAMES "literal string"
353 WITH-ALL-HOSTNAMES "/regular expression/"
355 Requires that all URI values contain a matching hostname.
356 WITH-ALL-RESOURCES "literal string"
358 WITH-ALL-RESOURCES "/regular expression/"
360 Requires that all URI values contain a matching resource (includ‐
361 ing leading /).
362 WITH-ALL-SCHEMES "literal string"
364 WITH-ALL-SCHEMES "/regular expression/"
366 Requires that all URI values contain a matching scheme.
367 WITH-ALL-VALUES "literal string"
369 Requires that all values of the EXPECT attribute match the literal
370 string. Comparisons are case-sensitive.
371 WITH-ALL-VALUES <number
373 WITH-ALL-VALUES =number
375 WITH-ALL-VALUES >number
377 WITH-ALL-VALUES number[,...,number]
379 Requires that all values of the EXPECT attribute match the num‐
380 ber(s) or numeric comparison. When comparing rangeOfInteger val‐
381 ues, the "<" and ">" operators only check the upper bound of the
382 range.
383 WITH-ALL-VALUES "false"
385 WITH-ALL-VALUES "true"
387 Requires that all values of the EXPECT attribute match the boolean
388 value given.
389 WITH-ALL-VALUES "/regular expression/"
391 Requires that all values of the EXPECT attribute match the regular
392 expression, which must conform to the POSIX regular expression
393 syntax. Comparisons are case-sensitive.
394 WITH-HOSTNAME "literal string"
396 WITH-HOSTNAME "/regular expression/"
398 Requires that at least one URI value contains a matching hostname.
399 WITH-RESOURCE "literal string"
401 WITH-RESOURCE "/regular expression/"
403 Requires that at least one URI value contains a matching resource
404 (including leading /).
405 WITH-SCHEME "literal string"
407 WITH-SCHEME "/regular expression/"
409 Requires that at least one URI value contains a matching scheme.
410 WITH-VALUE "literal string"
412 Requires that at least one value of the EXPECT attribute matches
413 the literal string. Comparisons are case-sensitive.
414 WITH-VALUE <number
416 WITH-VALUE =number
418 WITH-VALUE >number
420 WITH-VALUE number[,...,number]
422 Requires that at least one value of the EXPECT attribute matches
423 the number(s) or numeric comparison. When comparing rangeOfInteger
424 values, the "<" and ">" operators only check the upper bound of
425 the range.
426 WITH-VALUE "false"
428 WITH-VALUE "true"
430 Requires that at least one value of the EXPECT attribute matches
431 the boolean value given.
432 WITH-VALUE "/regular expression/"
434 Requires that at least one value of the EXPECT attribute matches
435 the regular expression, which must conform to the POSIX regular
436 expression syntax. Comparisons are case-sensitive.
437 WITH-VALUE-FROM attribute-name
439 Requires that the value(s) of the EXPECT attribute matches the
440 value(s) in the specified attribute. For example, "EXPECT
441 job-sheets WITH-VALUE-FROM job-sheets-supported" requires that the
442 "job-sheets" value is listed as a value of the "job-sheets-sup‐
443 ported" attribute.
444 STATUS PREDICATES
446 The following predicates are understood following the STATUS test
447 directive:
448 DEFINE-MATCH variable-name
450 Defines the variable to "1" when the STATUS matches. A side-effect
451 of this predicate is that this STATUS will never fail a test.
452 DEFINE-NO-MATCH variable-name
454 Defines the variable to "1" when the STATUS does not match. A
455 side-effect of this predicate is that this STATUS will never fail
456 a test.
457 IF-DEFINED variable-name
459 Makes the STATUS apply only if the specified variable is defined.
460 IF-NOT-DEFINED variable-name
462 Makes the STATUS apply only if the specified variable is not
463 defined.
464 REPEAT-LIMIT number
466 Specifies the maximum number of times to repeat. The default value
467 is 1000.
468 REPEAT-MATCH
470 REPEAT-NO-MATCH
472 Specifies that the current test should be repeated when the
473 response status-code matches or does not match the value specified
474 by the STATUS directive.
475 OPERATION CODES
477 Operation codes correspond to the hexadecimal numbers (0xHHHH) and
478 names from RFC 8011 and other IPP extension specifications. Here is a
479 complete list of names supported by ipptool(8):
480 Activate-Printer
482 CUPS-Accept-Jobs
483 CUPS-Add-Modify-Class
484 CUPS-Add-Modify-Printer
485 CUPS-Authenticate-Job
486 CUPS-Delete-Class
487 CUPS-Delete-Printer
488 CUPS-Get-Classes
489 CUPS-Get-Default
490 CUPS-Get-Devices
491 CUPS-Get-Document
492 CUPS-Get-PPD
493 CUPS-Get-PPDs
494 CUPS-Get-Printers
495 CUPS-Move-Job
496 CUPS-Reject-Jobs
497 CUPS-Set-Default
498 Cancel-Current-Job
499 Cancel-Job
500 Cancel-Jobs
501 Cancel-My-Jobs
502 Cancel-Subscription
503 Close-Job
504 Create-Job
505 Create-Job-Subscriptions
506 Create-Printer-Subscriptions
507 Deactivate-Printer
508 Disable-Printer
509 Enable-Printer
510 Get-Job-Attributes
511 Get-Jobs
512 Get-Notifications
513 Get-Printer-Attributes
514 Get-Printer-Support-Files
515 Get-Printer-Supported-Values
516 Get-Subscription-Attributes
517 Get-Subscriptions
518 Hold-Job
519 Hold-New-Jobs
520 Identify-Printer
521 Pause-Printer
522 Pause-Printer-After-Current-Job
523 Print-Job
524 Print-URI
525 Promote-Job
526 Purge-Jobs
527 Release-Held-New-Jobs
528 Release-Job
529 Renew-Subscription
530 Reprocess-Job
531 Restart-Job
532 Restart-Printer
533 Resubmit-Job
534 Resume-Job
535 Resume-Printer
536 Schedule-Job-After
537 Send-Document
538 Send-Hardcopy-Document
539 Send-Notifications
540 Send-URI
541 Set-Job-Attributes
542 Set-Printer-Attributes
543 Shutdown-Printer
544 Startup-Printer
545 Suspend-Current-Job
546 Validate-Document
547 Validate-Job
548 STATUS CODES
550 Status codes correspond to the hexadecimal numbers (0xHHHH) and names
551 from RFC 8011 and other IPP extension specifications. Here is a com‐
552 plete list of the names supported by ipptool(8):
553 client-error-account-authorization-failed
555 client-error-account-closed
556 client-error-account-info-needed
557 client-error-account-limit-reached
558 client-error-attributes-not-settable
559 client-error-attributes-or-values-not-supported
560 client-error-bad-request
561 client-error-charset-not-supported
562 client-error-compression-error
563 client-error-compression-not-supported
564 client-error-conflicting-attributes
565 client-error-document-access-error
566 client-error-document-format-error
567 client-error-document-format-not-supported
568 client-error-document-password-error
569 client-error-document-permission-error
570 client-error-document-security-error
571 client-error-document-unprintable-error
572 client-error-forbidden
573 client-error-gone
574 client-error-ignored-all-notifications
575 client-error-ignored-all-subscriptions
576 client-error-not-authenticated
577 client-error-not-authorized
578 client-error-not-found
579 client-error-not-possible
580 client-error-print-support-file-not-found
581 client-error-request-entity-too-large
582 client-error-request-value-too-long
583 client-error-timeout
584 client-error-too-many-subscriptions
585 client-error-uri-scheme-not-supported
586 cups-error-account-authorization-failed
587 cups-error-account-closed
588 cups-error-account-info-needed
589 cups-error-account-limit-reached
590 cups-see-other
591 redirection-other-site
592 server-error-busy
593 server-error-device-error
594 server-error-internal-error
595 server-error-job-canceled
596 server-error-multiple-document-jobs-not-supported
597 server-error-not-accepting-jobs
598 server-error-operation-not-supported
599 server-error-printer-is-deactivated
600 server-error-service-unavailable
601 server-error-temporary-error
602 server-error-version-not-supported
603 successful-ok
604 successful-ok-but-cancel-subscription
605 successful-ok-conflicting-attributes
606 successful-ok-events-complete
607 successful-ok-ignored-notifications
608 successful-ok-ignored-or-substituted-attributes
609 successful-ok-ignored-subscriptions
610 successful-ok-too-many-events
611 TAGS
613 Value and group tags correspond to the names from RFC 8011 and other
614 IPP extension specifications. Here are the group tags:
615 document-attributes-tag
617 event-notification-attributes-tag
618 job-attributes-tag
619 operation-attributes-tag
620 printer-attributes-tag
621 subscription-attributes-tag
622 unsupported-attributes-tag
623 Here are the value tags:
625 admin-define
627 boolean
628 charset
629 collection
630 dateTime
631 default
632 delete-attribute
633 enum
634 integer
635 keyword
636 mimeMediaType
637 nameWithLanguage
638 nameWithoutLanguage
639 naturalLanguage
640 no-value
641 not-settable
642 octetString
643 rangeOfInteger
644 resolution
645 textWithLanguage
646 textWithoutLanguage
647 unknown
648 unsupported
649 uri
650 uriScheme
651 VARIABLES
653 The ipptool(8) program maintains a list of variables that can be used
654 in any literal string or attribute value by specifying "$variable-
655 name". Aside from variables defined using the -d option or DEFINE
656 directive, the following pre-defined variables are available:
657 $$ Inserts a single "$" character.
659 $ENV[name]
661 Inserts the value of the named environment variable, or an empty
662 string if the environment variable is not defined.
663 $date-current
665 Inserts the current date and time using the ISO-8601 format
666 ("yyyy-mm-ddThh:mm:ssZ").
667 $date-start
669 Inserts the starting date and time using the ISO-8601 format
670 ("yyyy-mm-ddThh:mm:ssZ").
671 $filename
673 Inserts the filename provided to ipptool(8) with the -f option.
674 $filetype
676 Inserts the MIME media type for the filename provided to ipp‐
677 tool(8) with the -f option.
678 $hostname
680 Inserts the hostname from the URI provided to ipptool(8).
681 $job-id
683 Inserts the last "job-id" attribute value returned in a test
684 response or 0 if no "job-id" attribute has been seen.
685 $job-uri
687 Inserts the last "job-uri" attribute value returned in a test
688 response or an empty string if no "job-uri" attribute has been
689 seen.
690 $notify-subscription-id
692 Inserts the last "notify-subscription-id" attribute value returned
693 in a test response or 0 if no "notify-subscription-id" attribute
694 has been seen.
695 $port
697 Inserts the port number from the URI provided to ipptool(8).
698 $resource
700 Inserts the resource path from the URI provided to ipptool(8).
701 $scheme
703 Inserts the scheme from the URI provided to ipptool(8).
704 $uri Inserts the URI provided to ipptool(8).
706 $uriuser
708 Inserts the username from the URI provided to ipptool(8), if any.
709 $user
711 Inserts the current user's login name.
712
714 ipptool(1), IANA IPP Registry (http://www.iana.org/assignments/ipp-reg‐
715 istrations), PWG Internet Printing Protocol Workgroup
716 (http://www.pwg.org/ipp), RFC 8011 (http://tools.ietf.org/html/rfc8011)
717
719 Copyright © 2007-2019 by Apple Inc.
72015 August 2019 CUPS ipptoolfile(5)