1ipptoolfile(5)                    Apple Inc.                    ipptoolfile(5)
2
3
4

NAME

6       ipptoolfile - ipptool file format
7

DESCRIPTION

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
14           # This is a comment
15           {
16             # The name of the test
17             NAME "Print PDF File"
18
19             # The request to send
20             OPERATION Print-Job
21
22             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
29             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
44             FILE testfile.pdf
45
46             # 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
55             # The request to send
56             OPERATION Get-Job-Attributes
57
58             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
65             # 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
72             # Show the job state until completed...
73             DISPLAY job-state
74             DISPLAY job-state-reasons
75           }
76
77   TOP-LEVEL DIRECTIVES
78       The following directives can be used outside of a test:
79
80       { test }
81            Defines a test.
82
83       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
88       DEFINE-DEFAULT variable-name value
89            Defines the named variable to the  given  value  if  it  does  not
90            already have a value.
91
92       FILE-ID "identifier"
93            Specifies an identifier string for the current file.
94
95       IGNORE-ERRORS yes
96
97       IGNORE-ERRORS no
98            Specifies  whether,  by default, ipptool(8) will ignore errors and
99            continue with subsequent tests.
100
101       INCLUDE "filename"
102
103       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
108       INCLUDE-IF-DEFINED name "filename"
109
110       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
116       INCLUDE-IF-NOT-DEFINED name "filename"
117
118       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
124       SKIP-IF-DEFINED variable-name
125
126       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
130       STOP-AFTER-INCLUDE-ERROR no
131
132       STOP-AFTER-INCLUDE-ERROR yes
133            Specifies  whether  tests  will  be  stopped  after an error in an
134            included file.
135
136       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
141       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
147       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
153       VERSION 1.0
154
155       VERSION 1.1
156
157       VERSION 2.0
158
159       VERSION 2.1
160
161       VERSION 2.2
162            Specifies the default IPP version number to use for the tests that
163            follow.
164
165   TEST DIRECTIVES
166       The following directives are understood within a test:
167
168       ATTR out-of-band-tag attribute-name
169
170       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 separated by the
174            comma  (",")  character  -  escape  commas  using  the  "   Common
175            attributes  and  values  are listed in the IANA IPP registry - see
176            references below.
177
178       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
185       COMPRESSION deflate
186
187       COMPRESSION gzip
188
189       COMPRESSION none
190            Uses the specified compression on the document data following  the
191            attributes in a Print-Job or Send-Document request.
192
193       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
198       DISPLAY attribute-name
199            Specifies  that  value  of the named attribute should be output as
200            part of the test report.
201
202       EXPECT attribute-name [ predicate(s) ]
203
204       EXPECT ?attribute-name predicate(s)
205
206       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
214       EXPECT-ALL attribute-name [ predicate(s) ]
215
216       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
221       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
225       GROUP tag
226            Specifies the group tag for subsequent attributes in the request.
227
228       IGNORE-ERRORS yes
229
230       IGNORE-ERRORS no
231            Specifies whether ipptool(8) will ignore errors and continue  with
232            subsequent tests.
233
234       NAME "literal string"
235            Specifies the human-readable name of the test.
236
237       OPERATION operation-code
238            Specifies the operation to be performed.
239
240       PAUSE "message"
241            Displays  the  provided  message and waits for the user to press a
242            key to continue.
243
244       REQUEST-ID number
245
246       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
251       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
256       SKIP-IF-DEFINED variable-name
257
258       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
262       SKIP-PREVIOUS-ERROR yes
263
264       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
268       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
273       TEST-ID "identifier"
274            Specifies an identifier string for the current test.
275
276       TRANSFER auto
277            Specifies that this test will use "Transfer-Encoding: chunked"  if
278            it has an attached file or "Content-Length:" otherwise.
279
280       TRANSFER chunked
281            Specifies that this test will use the HTTP/1.1 "Transfer-Encoding:
282            chunked" header.
283
284       TRANSFER length
285            Specifies that this test will use the  HTTP/1.0  "Content-Length:"
286            header.
287
288       VERSION 1.0
289
290       VERSION 1.1
291
292       VERSION 2.0
293
294       VERSION 2.1
295
296       VERSION 2.2
297            Specifies the IPP version number to use for this test.
298
299   EXPECT PREDICATES
300       The  following  predicates  are  understood  following  the EXPECT test
301       directive:
302
303       COUNT number
304            Requires the EXPECT attribute to have the specified number of val‐
305            ues.
306
307       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
312       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
317       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
322       IF-DEFINED variable-name
323            Makes  the  EXPECT conditions apply only if the specified variable
324            is defined.
325
326       IF-NOT-DEFINED variable-name
327            Makes the EXPECT conditions apply only if the  specified  variable
328            is not defined.
329
330       IN-GROUP tag
331            Requires the EXPECT attribute to be in the specified group tag.
332
333       OF-TYPE tag[|tag,...]
334            Requires  the  EXPECT  attribute to use one of the specified value
335            tag(s).
336
337       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
342       REPEAT-MATCH
343
344       REPEAT-NO-MATCH
345            Specifies that the current test should be repeated when the EXPECT
346            condition matches or does not match.
347
348       SAME-COUNT-AS attribute-name
349            Requires the EXPECT attribute to have the same number of values as
350            the specified parallel attribute.
351
352       WITH-ALL-HOSTNAMES "literal string"
353
354       WITH-ALL-HOSTNAMES "/regular expression/"
355            Requires that all URI values contain a matching hostname.
356
357       WITH-ALL-RESOURCES "literal string"
358
359       WITH-ALL-RESOURCES "/regular expression/"
360            Requires that all URI values contain a matching resource  (includ‐
361            ing leading /).
362
363       WITH-ALL-SCHEMES "literal string"
364
365       WITH-ALL-SCHEMES "/regular expression/"
366            Requires that all URI values contain a matching scheme.
367
368       WITH-ALL-VALUES "literal string"
369            Requires that all values of the EXPECT attribute match the literal
370            string. Comparisons are case-sensitive.
371
372       WITH-ALL-VALUES <number
373
374       WITH-ALL-VALUES =number
375
376       WITH-ALL-VALUES >number
377
378       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
384       WITH-ALL-VALUES "false"
385
386       WITH-ALL-VALUES "true"
387            Requires that all values of the EXPECT attribute match the boolean
388            value given.
389
390       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
395       WITH-HOSTNAME "literal string"
396
397       WITH-HOSTNAME "/regular expression/"
398            Requires that at least one URI value contains a matching hostname.
399
400       WITH-RESOURCE "literal string"
401
402       WITH-RESOURCE "/regular expression/"
403            Requires that at least one URI value contains a matching  resource
404            (including leading /).
405
406       WITH-SCHEME "literal string"
407
408       WITH-SCHEME "/regular expression/"
409            Requires that at least one URI value contains a matching scheme.
410
411       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
415       WITH-VALUE <number
416
417       WITH-VALUE =number
418
419       WITH-VALUE >number
420
421       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
427       WITH-VALUE "false"
428
429       WITH-VALUE "true"
430            Requires  that  at least one value of the EXPECT attribute matches
431            the boolean value given.
432
433       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
438       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
445   STATUS PREDICATES
446       The following predicates  are  understood  following  the  STATUS  test
447       directive:
448
449       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
453       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
458       IF-DEFINED variable-name
459            Makes the STATUS apply only if the specified variable is defined.
460
461       IF-NOT-DEFINED variable-name
462            Makes the STATUS apply only  if  the  specified  variable  is  not
463            defined.
464
465       REPEAT-LIMIT number
466            Specifies the maximum number of times to repeat. The default value
467            is 1000.
468
469       REPEAT-MATCH
470
471       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
476   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
481           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
549   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
554           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
612   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
616           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
624       Here are the value tags:
625
626           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
652   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
658       $$   Inserts a single "$" character.
659
660       $ENV[name]
661            Inserts the value of the named environment variable, or  an  empty
662            string if the environment variable is not defined.
663
664       $filename
665            Inserts the filename provided to ipptool(8) with the -f option.
666
667       $filetype
668            Inserts  the  MIME  media  type  for the filename provided to ipp‐
669            tool(8) with the -f option.
670
671       $hostname
672            Inserts the hostname from the URI provided to ipptool(8).
673
674       $job-id
675            Inserts the last "job-id"  attribute  value  returned  in  a  test
676            response or 0 if no "job-id" attribute has been seen.
677
678       $job-uri
679            Inserts  the  last  "job-uri"  attribute  value returned in a test
680            response or an empty string if no  "job-uri"  attribute  has  been
681            seen.
682
683       $notify-subscription-id
684            Inserts the last "notify-subscription-id" attribute value returned
685            in a test response or 0 if no  "notify-subscription-id"  attribute
686            has been seen.
687
688       $port
689            Inserts the port number from the URI provided to ipptool(8).
690
691       $resource
692            Inserts the resource path from the URI provided to ipptool(8).
693
694       $scheme
695            Inserts the scheme from the URI provided to ipptool(8).
696
697       $uri Inserts the URI provided to ipptool(8).
698
699       $uriuser
700            Inserts the username from the URI provided to ipptool(8), if any.
701
702       $user
703            Inserts the current user's login name.
704

SEE ALSO

706       ipptool(1), IANA IPP Registry (http://www.iana.org/assignments/ipp-reg
707       istrations),    PWG    Internet     Printing     Protocol     Workgroup
708       (http://www.pwg.org/ipp), RFC 8011 (http://tools.ietf.org/html/rfc8011)
709
711       Copyright © 2007-2019 by Apple Inc.
712
713
714
7155 August 2019                        CUPS                       ipptoolfile(5)
Impressum