2 .\" ipptoolfile man page.
4 .\" Copyright 2010-2018 by Apple Inc.
6 .\" Licensed under Apache License v2.0. See the file "LICENSE" for more information.
8 .TH ipptoolfile 5 "CUPS" "15 June 2017" "Apple Inc."
10 ipptoolfile \- ipptool file format
14 program accepts free-form plain text files that describe one or more IPP requests.
15 Comments start with the "#" character and continue to the end of the line.
16 Each request is enclosed by curly braces, for example:
21 # The name of the test
27 GROUP operation\-attributes\-tag
28 ATTR charset attributes\-charset utf\-8
29 ATTR language attributes\-natural\-language en
30 ATTR uri printer\-uri $uri
31 ATTR name requesting\-user\-name $user
32 ATTR mimeMediaType document\-format application/pdf
34 GROUP job\-attributes\-tag
35 ATTR collection media\-col {
36 # US Letter plain paper from the "main" tray
37 MEMBER collection media\-size {
38 MEMBER integer x\-dimension 21590
39 MEMBER integer y\-dimension 27940
41 MEMBER integer media\-top\-margin 423
42 MEMBER integer media\-bottom\-margin 423
43 MEMBER integer media\-left\-margin 423
44 MEMBER integer media\-right\-margin 423
45 MEMBER keyword media\-source "main"
46 MEMBER keyword media\-type "stationery"
51 # The response to expect
53 EXPECT job\-id OF\-TYPE integer WITH\-VALUE >0
54 EXPECT job\-uri OF\-TYPE uri
57 # The name of the test
58 NAME "Wait for Job to Complete"
61 OPERATION Get\-Job\-Attributes
63 GROUP operation\-attributes\-tag
64 ATTR charset attributes\-charset utf\-8
65 ATTR language attributes\-natural\-language en
66 ATTR uri printer\-uri $uri
67 ATTR integer job\-id $job\-id
68 ATTR name requesting\-user\-name $user
70 # The response to expect
72 EXPECT job\-id OF\-TYPE integer WITH\-VALUE $job\-id
73 EXPECT job\-uri OF\-TYPE uri
74 EXPECT job\-state OF\-TYPE enum WITH\-VALUE >5 REPEAT\-NO\-MATCH
75 EXPECT job\-originating\-user\-name OF\-TYPE name WITH\-VALUE "$user"
77 # Show the job state until completed...
79 DISPLAY job-state-reasons
82 .SS TOP-LEVEL DIRECTIVES
83 The following directives can be used outside of a \fItest\fR:
88 \fBDEFINE \fIvariable-name value\fR
89 Defines the named variable to the given value. This is equivalent to specifying \fI\-d variable-name=value\fR on the
93 \fBDEFINE\-DEFAULT \fIvariable-name value\fR
94 Defines the named variable to the given value if it does not already have a value.
96 \fBFILE\-ID "\fIidentifier\fB"\fR
97 Specifies an identifier string for the current file.
99 \fBIGNORE\-ERRORS yes\fR
101 \fBIGNORE\-ERRORS no\fR
102 Specifies whether, by default,
104 will ignore errors and continue with subsequent tests.
106 \fBINCLUDE "\fIfilename\fB"\fR
108 \fBINCLUDE <\fIfilename\fB>\fR
109 Includes another test file. The first form includes a file relative to the current test file, while the second form includes a file from the
113 \fBINCLUDE\-IF\-DEFINED \fIname \fB"\fIfilename\fB"\fR
115 \fBINCLUDE\-IF\-DEFINED \fIname \fB<\fIfilename\fB>\fR
116 Includes another test file if the named variable is defined. The first form includes a file relative to the current test file, while the second form includes a file from the
120 \fBINCLUDE\-IF\-NOT\-DEFINED \fIname \fB"\fIfilename\fB"\fR
122 \fBINCLUDE\-IF\-NOT\-DEFINED \fIname \fB<\fIfilename\fB>\fR
123 Includes another test file if the named variable is not defined. The first form includes a file relative to the current test file, while the second form includes a file from the
127 \fBSKIP\-IF\-DEFINED \fIvariable-name\fR
129 \fBSKIP\-IF\-NOT\-DEFINED \fIvariable-name\fR
130 Specifies that the remainder of the test file should be skipped when the variable is or is not defined.
132 \fBSTOP\-AFTER\-INCLUDE\-ERROR no\fR
134 \fBSTOP\-AFTER\-INCLUDE\-ERROR yes\fR
135 Specifies whether tests will be stopped after an error in an included file.
138 Specifies that tests will, by default, use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files.
140 \fBTRANSFER chunked\fR
141 Specifies that tests will, by default, use the HTTP/1.1 "Transfer-Encoding: chunked" header. This is the default and is equivalent to specifying \fI\-c\fR on the
143 command-line. Support for chunked requests is required for conformance with all versions of IPP.
145 \fBTRANSFER length\fR
146 Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:" header. This is equivalent to specifying \fI\-l\fR on the
148 command-line. Support for content length requests is required for conformance with all versions of IPP.
159 Specifies the default IPP version number to use for the tests that follow.
161 The following directives are understood within a \fItest\fR:
163 \fBATTR \fIout-of-band-tag attribute-name\fR
165 \fBATTR \fItag attribute-name value(s)\fR
166 Adds an attribute to the test request.
167 Out-of-band tags (admin-define, delete-attribute, no-value, not-settable, unknown, unsupported) have no value.
168 Values for other tags are separated by the comma (",") character - escape commas using the "\" character.
169 Common attributes and values are listed in the IANA IPP registry - see references below.
171 \fBATTR collection \fIattribute-name \fB{ MEMBER \fItag member-name value(s) ... \fB}\fR [ \fI... \fB,{ \fI... \fB} \fR]
172 Adds a collection attribute to the test request.
173 Member attributes follow the same syntax as regular attributes and can themselves be nested collections.
174 Multiple collection values can be supplied as needed, separated by commas.
176 \fBCOMPRESSION deflate\fR
178 \fBCOMPRESSION gzip\fR
180 \fBCOMPRESSION none\fR
181 Uses the specified compression on the document data following the attributes in a Print-Job or Send-Document request.
183 \fBDELAY \fIseconds\fR[\fI,repeat-seconds\fR]
184 Specifies a delay in seconds before this test will be run.
185 If two values are specified, the second value is used as the delay between repeated tests.
187 \fBDISPLAY \fIattribute-name\fR
188 Specifies that value of the named attribute should be output as part of the
191 \fBEXPECT \fIattribute-name \fR[ \fIpredicate(s) \fR]
193 \fBEXPECT ?\fIattribute-name predicate(s)\fR
195 \fBEXPECT !\fIattribute-name\fR
196 Specifies that the response must/may/must not include the named attribute. Additional requirements can be added as predicates - see the "EXPECT PREDICATES" section for more information on predicates. Attribute names can specify member attributes by separating the attribute and member names with the forward slash, for example "media\-col/media\-size/x\-dimension".
198 \fBEXPECT-ALL \fIattribute-name \fR[ \fIpredicate(s) \fR]
200 \fBEXPECT-ALL ?\fIattribute-name predicate(s)\fR
201 Specifies that the response must/may include the named attribute and that all occurrences of that attribute must match the given predicates.
204 Specifies a file to include at the end of the request. This is typically used when sending a test print file.
207 Specifies the group tag for subsequent attributes in the request.
209 \fBIGNORE\-ERRORS yes\fR
211 \fBIGNORE\-ERRORS no\fR
214 will ignore errors and continue with subsequent tests.
216 \fBNAME "\fIliteral string\fB"\fR
217 Specifies the human-readable name of the test.
219 \fBOPERATION \fIoperation-code\fR
220 Specifies the operation to be performed.
222 \fBPAUSE "\fImessage\fB"\fR
223 Displays the provided message and waits for the user to press a key to continue.
225 \fBREQUEST\-ID \fInumber\fR\fR
227 \fBREQUEST\-ID random\fR
228 Specifies the request-id value to use in the request, either an integer or the word "random" to use a randomly generated value (the default).
230 \fBRESOURCE \fIpath\fR
231 Specifies an alternate resource path that is used for the HTTP POST request. The default is the resource from the URI provided to the
235 \fBSKIP\-IF\-DEFINED \fIvariable-name\fR
237 \fBSKIP\-IF\-NOT\-DEFINED \fIvariable-name\fR
238 Specifies that the current test should be skipped when the variable is or is not defined.
240 \fBSKIP\-PREVIOUS\-ERROR yes\fR
242 \fBSKIP\-PREVIOUS\-ERROR no\fR
245 will skip the current test if the previous test resulted in an error/failure.
247 \fBSTATUS \fIstatus-code \fR[ \fIpredicate\fR ]
248 Specifies an expected response status-code value. Additional requirements can be added as predicates - see the "STATUS PREDICATES" section for more information on predicates.
250 \fBTEST\-ID "\fIidentifier\fR"
251 Specifies an identifier string for the current test.
254 Specifies that this test will use "Transfer-Encoding: chunked" if it has an attached file or "Content-Length:" otherwise.
256 \fBTRANSFER chunked\fR
257 Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked" header.
259 \fBTRANSFER length\fR
260 Specifies that this test will use the HTTP/1.0 "Content-Length:" header.
271 Specifies the IPP version number to use for this test.
272 .SS EXPECT PREDICATES
273 The following predicates are understood following the \fBEXPECT\fR test directive:
275 \fBCOUNT \fInumber\fR
276 Requires the \fBEXPECT\fR attribute to have the specified number of values.
278 \fBDEFINE\-MATCH \fIvariable-name\fR
279 Defines the variable to "1" when the \fBEXPECT\fR condition matches. A side-effect of this predicate is that this \fBEXPECT\fR will never fail a test.
281 \fBDEFINE\-NO\-MATCH \fIvariable-name\fR
282 Defines the variable to "1" when the \fBEXPECT\fR condition does not match. A side-effect of this predicate is that this \fBEXPECT\fR will never fail a test.
284 \fBDEFINE\-VALUE \fIvariable-name\fR
285 Defines the variable to the value of the attribute when the \fBEXPECT\fR condition matches. A side-effect of this predicate is that this \fBEXPECT\fR will never fail a test.
287 \fBIF\-DEFINED \fIvariable-name\fR
288 Makes the \fBEXPECT\fR conditions apply only if the specified variable is defined.
290 \fBIF\-NOT\-DEFINED \fIvariable-name\fR
291 Makes the \fBEXPECT\fR conditions apply only if the specified variable is not defined.
293 \fBIN\-GROUP \fItag\fR
294 Requires the \fBEXPECT\fR attribute to be in the specified group tag.
296 \fBOF\-TYPE \fItag[,tag,...]\fR
297 Requires the \fBEXPECT\fR attribute to use one of the specified value tag(s).
299 \fBREPEAT\-LIMIT \fInumber\fR
301 Specifies the maximum number of times to repeat if the \fBREPEAT-MATCH\fR or \fBREPEAT-NO-MATCH\fR predicate is specified. The default value is 1000.
305 \fBREPEAT\-NO\-MATCH\fR
306 Specifies that the current test should be repeated when the \fBEXPECT\fR condition matches or does not match.
308 \fBSAME\-COUNT\-AS \fIattribute-name\fR
309 Requires the \fBEXPECT\fR attribute to have the same number of values as the specified parallel attribute.
311 \fBWITH\-ALL\-HOSTNAMES "\fIliteral string\fB"\fR
313 \fBWITH\-ALL\-HOSTNAMES "/\fIregular expression\fB/"\fR
314 Requires that all URI values contain a matching hostname.
316 \fBWITH\-ALL\-RESOURCES "\fIliteral string\fB"\fR
318 \fBWITH\-ALL\-RESOURCES "/\fIregular expression\fB/"\fR
319 Requires that all URI values contain a matching resource (including leading /).
321 \fBWITH\-ALL\-SCHEMES "\fIliteral string\fB"\fR
323 \fBWITH\-ALL-SCHEMES "/\fIregular expression\fB/"\fR
324 Requires that all URI values contain a matching scheme.
326 \fBWITH\-ALL\-VALUES "\fIliteral string\fB"\fR
327 Requires that all values of the \fBEXPECT\fR attribute match the literal string. Comparisons are case-sensitive.
329 \fBWITH\-ALL\-VALUES <\fInumber\fR
331 \fBWITH\-ALL\-VALUES =\fInumber\fR
333 \fBWITH\-ALL\-VALUES >\fInumber\fR
335 \fBWITH\-ALL\-VALUES \fInumber\fR[\fI,...,number\fR]
336 Requires that all values of the \fBEXPECT\fR attribute match the number(s) or numeric comparison. When comparing rangeOfInteger values, the "<" and ">" operators only check the upper bound of the range.
338 \fBWITH\-ALL\-VALUES "false"\fR
340 \fBWITH\-ALL\-VALUES "true"\fR
341 Requires that all values of the \fBEXPECT\fR attribute match the boolean value given.
343 \fBWITH\-ALL\-VALUES "/\fIregular expression\fB/"\fR
344 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.
346 \fBWITH\-HOSTNAME "\fIliteral string\fB"\fR
348 \fBWITH\-HOSTNAME "/\fIregular expression\fB/"\fR
349 Requires that at least one URI value contains a matching hostname.
351 \fBWITH\-RESOURCE "\fIliteral string\fB"\fR
353 \fBWITH\-RESOURCE "/\fIregular expression\fB/"\fR
354 Requires that at least one URI value contains a matching resource (including leading /).
356 \fBWITH\-SCHEME "\fIliteral string\fB"\fR
358 \fBWITH\-SCHEME "/\fIregular expression\fB/"\fR
359 Requires that at least one URI value contains a matching scheme.
361 \fBWITH\-VALUE "\fIliteral string\fB"\fR
362 Requires that at least one value of the \fBEXPECT\fR attribute matches the literal string. Comparisons are case-sensitive.
364 \fBWITH\-VALUE <\fInumber\fR
366 \fBWITH\-VALUE =\fInumber\fR
368 \fBWITH\-VALUE >\fInumber\fR
370 \fBWITH\-VALUE \fInumber\fR[\fI,...,number\fR]
371 Requires that at least one value of the \fBEXPECT\fR attribute matches the number(s) or numeric comparison. When comparing rangeOfInteger values, the "<" and ">" operators only check the upper bound of the range.
373 \fBWITH\-VALUE "false"\fR
375 \fBWITH\-VALUE "true"\fR
376 Requires that at least one value of the \fBEXPECT\fR attribute matches the boolean value given.
378 \fBWITH\-VALUE "/\fIregular expression\fB/"\fR
379 Requires that at least one value of the \fBEXPECT\fR attribute matches the regular expression, which must conform to the POSIX regular expression syntax. Comparisons are case-sensitive.
381 \fBWITH\-VALUE\-FROM \fIattribute-name\fR
382 Requires that the value(s) of the \fBEXPECT\fR attribute matches the value(s) in the specified attribute.
383 For example, "EXPECT job\-sheets WITH\-VALUE\-FROM job\-sheets\-supported" requires that the "job\-sheets" value is listed as a value of the "job\-sheets\-supported" attribute.
384 .SS STATUS PREDICATES
385 The following predicates are understood following the \fBSTATUS\fR test directive:
387 \fBDEFINE\-MATCH \fIvariable-name\fR
388 Defines the variable to "1" when the \fBSTATUS\fR matches. A side-effect of this predicate is that this \fBSTATUS\fR will never fail a test.
390 \fBDEFINE\-NO\-MATCH \fIvariable-name\fR
391 Defines the variable to "1" when the \fBSTATUS\fR does not match. A side-effect of this predicate is that this \fBSTATUS\fR will never fail a test.
393 \fBIF\-DEFINED \fIvariable-name\fR
394 Makes the \fBSTATUS\fR apply only if the specified variable is defined.
396 \fBIF\-NOT\-DEFINED \fIvariable-name\fR
397 Makes the \fBSTATUS\fR apply only if the specified variable is not defined.
399 \fBREPEAT\-LIMIT \fInumber\fR
401 Specifies the maximum number of times to repeat. The default value is 1000.
405 \fBREPEAT\-NO\-MATCH\fR
406 Specifies that the current test should be repeated when the response status-code matches or does not match the value specified by the STATUS directive.
408 Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC 8011 and other IPP extension specifications. Here is a complete list of names supported by
414 CUPS\-Add\-Modify\-Class
415 CUPS\-Add\-Modify\-Printer
416 CUPS\-Authenticate\-Job
418 CUPS\-Delete\-Printer
436 Create\-Job\-Subscriptions
437 Create\-Printer\-Subscriptions
444 Get\-Printer\-Attributes
445 Get\-Printer\-Support\-Files
446 Get\-Printer\-Supported\-Values
447 Get\-Subscription\-Attributes
453 Pause\-Printer\-After\-Current\-Job
458 Release\-Held\-New\-Jobs
469 Send\-Hardcopy\-Document
473 Set\-Printer\-Attributes
476 Suspend\-Current\-Job
481 Status codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC 8011 and other IPP extension specifications. Here is a complete list of the names supported by
485 client\-error\-account\-authorization\-failed
486 client\-error\-account\-closed
487 client\-error\-account\-info\-needed
488 client\-error\-account\-limit\-reached
489 client\-error\-attributes\-not\-settable
490 client\-error\-attributes\-or\-values\-not\-supported
491 client\-error\-bad\-request
492 client\-error\-charset\-not\-supported
493 client\-error\-compression\-error
494 client\-error\-compression\-not\-supported
495 client\-error\-conflicting\-attributes
496 client\-error\-document\-access\-error
497 client\-error\-document\-format\-error
498 client\-error\-document\-format\-not\-supported
499 client\-error\-document\-password\-error
500 client\-error\-document\-permission\-error
501 client\-error\-document\-security\-error
502 client\-error\-document\-unprintable\-error
503 client\-error\-forbidden
505 client\-error\-ignored\-all\-notifications
506 client\-error\-ignored\-all\-subscriptions
507 client\-error\-not\-authenticated
508 client\-error\-not\-authorized
509 client\-error\-not\-found
510 client\-error\-not\-possible
511 client\-error\-print\-support\-file\-not\-found
512 client\-error\-request\-entity\-too\-large
513 client\-error\-request\-value\-too\-long
514 client\-error\-timeout
515 client\-error\-too\-many\-subscriptions
516 client\-error\-uri\-scheme\-not\-supported
517 cups\-error\-account\-authorization\-failed
518 cups\-error\-account\-closed
519 cups\-error\-account\-info\-needed
520 cups\-error\-account\-limit\-reached
522 redirection\-other\-site
524 server\-error\-device\-error
525 server\-error\-internal\-error
526 server\-error\-job\-canceled
527 server\-error\-multiple\-document\-jobs\-not\-supported
528 server\-error\-not\-accepting\-jobs
529 server\-error\-operation\-not\-supported
530 server\-error\-printer\-is\-deactivated
531 server\-error\-service\-unavailable
532 server\-error\-temporary\-error
533 server\-error\-version\-not\-supported
535 successful\-ok\-but\-cancel\-subscription
536 successful\-ok\-conflicting\-attributes
537 successful\-ok\-events\-complete
538 successful\-ok\-ignored\-notifications
539 successful\-ok\-ignored\-or\-substituted\-attributes
540 successful\-ok\-ignored\-subscriptions
541 successful\-ok\-too\-many\-events
544 Value and group tags correspond to the names from RFC 8011 and other IPP extension specifications. Here are the group tags:
547 document\-attributes\-tag
548 event\-notification\-attributes\-tag
550 operation\-attributes\-tag
551 printer\-attributes\-tag
552 subscription\-attributes\-tag
553 unsupported\-attributes\-tag
556 Here are the value tags:
588 program maintains a list of variables that can be used in any literal string or attribute value by specifying "\fI$variable-name\fR". Aside from variables defined using the \fI-d\fR option or \fBDEFINE\fR directive, the following pre-defined variables are available:
591 Inserts a single "$" character.
593 \fB$ENV[\fIname\fB]\fR
594 Inserts the value of the named environment variable, or an empty string if the environment variable is not defined.
597 Inserts the filename provided to
599 with the \fI-f\fR option.
602 Inserts the MIME media type for the filename provided to
604 with the \fI-f\fR option.
607 Inserts the hostname from the URI provided to
611 Inserts the last "job\-id" attribute value returned in a test response or 0 if no "job\-id" attribute has been seen.
614 Inserts the last "job\-uri" attribute value returned in a test response or an empty string if no "job\-uri" attribute has been seen.
616 \fB$notify\-subscription\-id\fR
617 Inserts the last "notify\-subscription\-id" attribute value returned in a test response or 0 if no "notify\-subscription\-id" attribute has been seen.
620 Inserts the port number from the URI provided to
624 Inserts the resource path from the URI provided to
628 Inserts the scheme from the URI provided to
632 Inserts the URI provided to
636 Inserts the username from the URI provided to
641 Inserts the current user's login name.
644 IANA IPP Registry (http://www.iana.org/assignments/ipp-registrations),
645 PWG Internet Printing Protocol Workgroup (http://www.pwg.org/ipp),
646 RFC 8011 (http://tools.ietf.org/html/rfc8011)
648 Copyright \[co] 2007-2018 by Apple Inc.