2 .\" ipptoolfile man page.
4 .\" Copyright 2010-2017 by Apple Inc.
6 .\" These coded instructions, statements, and computer programs are the
7 .\" property of Apple Inc. and are protected by Federal copyright
8 .\" law. Distribution and use rights are outlined in the file "LICENSE.txt"
9 .\" which should have been included with this file. If this file is
10 .\" file is missing or damaged, see the license at "http://www.cups.org/".
12 .TH ipptoolfile 5 "CUPS" "15 June 2017" "Apple Inc."
14 ipptoolfile \- ipptool file format
18 program accepts free-form plain text files that describe one or more IPP requests.
19 Comments start with the "#" character and continue to the end of the line.
20 Each request is enclosed by curly braces, for example:
25 # The name of the test
31 GROUP operation\-attributes\-tag
32 ATTR charset attributes\-charset utf\-8
33 ATTR language attributes\-natural\-language en
34 ATTR uri printer\-uri $uri
35 ATTR name requesting\-user\-name $user
36 ATTR mimeMediaType document\-format application/pdf
38 GROUP job\-attributes\-tag
39 ATTR collection media\-col {
40 # US Letter plain paper from the "main" tray
41 MEMBER collection media\-size {
42 MEMBER integer x\-dimension 21590
43 MEMBER integer y\-dimension 27940
45 MEMBER integer media\-top\-margin 423
46 MEMBER integer media\-bottom\-margin 423
47 MEMBER integer media\-left\-margin 423
48 MEMBER integer media\-right\-margin 423
49 MEMBER keyword media\-source "main"
50 MEMBER keyword media\-type "stationery"
55 # The response to expect
57 EXPECT job\-id OF\-TYPE integer WITH\-VALUE >0
58 EXPECT job\-uri OF\-TYPE uri
61 # The name of the test
62 NAME "Wait for Job to Complete"
65 OPERATION Get\-Job\-Attributes
67 GROUP operation\-attributes\-tag
68 ATTR charset attributes\-charset utf\-8
69 ATTR language attributes\-natural\-language en
70 ATTR uri printer\-uri $uri
71 ATTR integer job\-id $job\-id
72 ATTR name requesting\-user\-name $user
74 # The response to expect
76 EXPECT job\-id OF\-TYPE integer WITH\-VALUE $job\-id
77 EXPECT job\-uri OF\-TYPE uri
78 EXPECT job\-state OF\-TYPE enum WITH\-VALUE >5 REPEAT\-NO\-MATCH
79 EXPECT job\-originating\-user\-name OF\-TYPE name WITH\-VALUE "$user"
81 # Show the job state until completed...
83 DISPLAY job-state-reasons
86 .SS TOP-LEVEL DIRECTIVES
87 The following directives can be used outside of a \fItest\fR:
92 \fBDEFINE \fIvariable-name value\fR
93 Defines the named variable to the given value. This is equivalent to specifying \fI\-d variable-name=value\fR on the
97 \fBDEFINE\-DEFAULT \fIvariable-name value\fR
98 Defines the named variable to the given value if it does not already have a value.
100 \fBFILE\-ID "\fIidentifier\fB"\fR
101 Specifies an identifier string for the current file.
103 \fBIGNORE\-ERRORS yes\fR
105 \fBIGNORE\-ERRORS no\fR
106 Specifies whether, by default,
108 will ignore errors and continue with subsequent tests.
110 \fBINCLUDE "\fIfilename\fB"\fR
112 \fBINCLUDE <\fIfilename\fB>\fR
113 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
117 \fBINCLUDE\-IF\-DEFINED \fIname \fB"\fIfilename\fB"\fR
119 \fBINCLUDE\-IF\-DEFINED \fIname \fB<\fIfilename\fB>\fR
120 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
124 \fBINCLUDE\-IF\-NOT\-DEFINED \fIname \fB"\fIfilename\fB"\fR
126 \fBINCLUDE\-IF\-NOT\-DEFINED \fIname \fB<\fIfilename\fB>\fR
127 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
131 \fBSKIP\-IF\-DEFINED \fIvariable-name\fR
133 \fBSKIP\-IF\-NOT\-DEFINED \fIvariable-name\fR
134 Specifies that the remainder of the test file should be skipped when the variable is or is not defined.
136 \fBSTOP\-AFTER\-INCLUDE\-ERROR no\fR
138 \fBSTOP\-AFTER\-INCLUDE\-ERROR yes\fR
139 Specifies whether tests will be stopped after an error in an included file.
142 Specifies that tests will, by default, use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files.
144 \fBTRANSFER chunked\fR
145 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
147 command-line. Support for chunked requests is required for conformance with all versions of IPP.
149 \fBTRANSFER length\fR
150 Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:" header. This is equivalent to specifying \fI\-l\fR on the
152 command-line. Support for content length requests is required for conformance with all versions of IPP.
163 Specifies the default IPP version number to use for the tests that follow.
165 The following directives are understood within a \fItest\fR:
167 \fBATTR \fIout-of-band-tag attribute-name\fR
169 \fBATTR \fItag attribute-name value(s)\fR
170 Adds an attribute to the test request.
171 Out-of-band tags (admin-define, delete-attribute, no-value, not-settable, unknown, unsupported) have no value.
172 Values for other tags are separated by the comma (",") character - escape commas using the "\" character.
173 Common attributes and values are listed in the IANA IPP registry - see references below.
175 \fBATTR collection \fIattribute-name \fB{ MEMBER \fItag member-name value(s) ... \fB}\fR [ \fI... \fB,{ \fI... \fB} \fR]
176 Adds a collection attribute to the test request.
177 Member attributes follow the same syntax as regular attributes and can themselves be nested collections.
178 Multiple collection values can be supplied as needed, separated by commas.
180 \fBCOMPRESSION deflate\fR
182 \fBCOMPRESSION gzip\fR
184 \fBCOMPRESSION none\fR
185 Uses the specified compression on the document data following the attributes in a Print-Job or Send-Document request.
187 \fBDELAY \fIseconds\fR[\fI,repeat-seconds\fR]
188 Specifies a delay in seconds before this test will be run.
189 If two values are specified, the second value is used as the delay between repeated tests.
191 \fBDISPLAY \fIattribute-name\fR
192 Specifies that value of the named attribute should be output as part of the
195 \fBEXPECT \fIattribute-name \fR[ \fIpredicate(s) \fR]
197 \fBEXPECT ?\fIattribute-name predicate(s)\fR
199 \fBEXPECT !\fIattribute-name\fR
200 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".
202 \fBEXPECT-ALL \fIattribute-name \fR[ \fIpredicate(s) \fR]
204 \fBEXPECT-ALL ?\fIattribute-name predicate(s)\fR
205 Specifies that the response must/may include the named attribute and that all occurrences of that attribute must match the given predicates.
208 Specifies a file to include at the end of the request. This is typically used when sending a test print file.
211 Specifies the group tag for subsequent attributes in the request.
213 \fBIGNORE\-ERRORS yes\fR
215 \fBIGNORE\-ERRORS no\fR
218 will ignore errors and continue with subsequent tests.
220 \fBNAME "\fIliteral string\fB"\fR
221 Specifies the human-readable name of the test.
223 \fBOPERATION \fIoperation-code\fR
224 Specifies the operation to be performed.
226 \fBPAUSE "\fImessage\fB"\fR
227 Displays the provided message and waits for the user to press a key to continue.
229 \fBREQUEST\-ID \fInumber\fR\fR
231 \fBREQUEST\-ID random\fR
232 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).
234 \fBRESOURCE \fIpath\fR
235 Specifies an alternate resource path that is used for the HTTP POST request. The default is the resource from the URI provided to the
239 \fBSKIP\-IF\-DEFINED \fIvariable-name\fR
241 \fBSKIP\-IF\-NOT\-DEFINED \fIvariable-name\fR
242 Specifies that the current test should be skipped when the variable is or is not defined.
244 \fBSKIP\-PREVIOUS\-ERROR yes\fR
246 \fBSKIP\-PREVIOUS\-ERROR no\fR
249 will skip the current test if the previous test resulted in an error/failure.
251 \fBSTATUS \fIstatus-code \fR[ \fIpredicate\fR ]
252 Specifies an expected response status-code value. Additional requirements can be added as predicates - see the "STATUS PREDICATES" section for more information on predicates.
254 \fBTEST\-ID "\fIidentifier\fR"
255 Specifies an identifier string for the current test.
258 Specifies that this test will use "Transfer-Encoding: chunked" if it has an attached file or "Content-Length:" otherwise.
260 \fBTRANSFER chunked\fR
261 Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked" header.
263 \fBTRANSFER length\fR
264 Specifies that this test will use the HTTP/1.0 "Content-Length:" header.
275 Specifies the IPP version number to use for this test.
276 .SS EXPECT PREDICATES
277 The following predicates are understood following the \fBEXPECT\fR test directive:
279 \fBCOUNT \fInumber\fR
280 Requires the \fBEXPECT\fR attribute to have the specified number of values.
282 \fBDEFINE\-MATCH \fIvariable-name\fR
283 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.
285 \fBDEFINE\-NO\-MATCH \fIvariable-name\fR
286 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.
288 \fBDEFINE\-VALUE \fIvariable-name\fR
289 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.
291 \fBIF\-DEFINED \fIvariable-name\fR
292 Makes the \fBEXPECT\fR conditions apply only if the specified variable is defined.
294 \fBIF\-NOT\-DEFINED \fIvariable-name\fR
295 Makes the \fBEXPECT\fR conditions apply only if the specified variable is not defined.
297 \fBIN\-GROUP \fItag\fR
298 Requires the \fBEXPECT\fR attribute to be in the specified group tag.
300 \fBOF\-TYPE \fItag[,tag,...]\fR
301 Requires the \fBEXPECT\fR attribute to use one of the specified value tag(s).
303 \fBREPEAT\-LIMIT \fInumber\fR
305 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.
309 \fBREPEAT\-NO\-MATCH\fR
310 Specifies that the current test should be repeated when the \fBEXPECT\fR condition matches or does not match.
312 \fBSAME\-COUNT\-AS \fIattribute-name\fR
313 Requires the \fBEXPECT\fR attribute to have the same number of values as the specified parallel attribute.
315 \fBWITH\-ALL\-HOSTNAMES "\fIliteral string\fB"\fR
317 \fBWITH\-ALL\-HOSTNAMES "/\fIregular expression\fB/"\fR
318 Requires that all URI values contain a matching hostname.
320 \fBWITH\-ALL\-RESOURCES "\fIliteral string\fB"\fR
322 \fBWITH\-ALL\-RESOURCES "/\fIregular expression\fB/"\fR
323 Requires that all URI values contain a matching resource (including leading /).
325 \fBWITH\-ALL\-SCHEMES "\fIliteral string\fB"\fR
327 \fBWITH\-ALL-SCHEMES "/\fIregular expression\fB/"\fR
328 Requires that all URI values contain a matching scheme.
330 \fBWITH\-ALL\-VALUES "\fIliteral string\fB"\fR
331 Requires that all values of the \fBEXPECT\fR attribute match the literal string. Comparisons are case-sensitive.
333 \fBWITH\-ALL\-VALUES <\fInumber\fR
335 \fBWITH\-ALL\-VALUES =\fInumber\fR
337 \fBWITH\-ALL\-VALUES >\fInumber\fR
339 \fBWITH\-ALL\-VALUES \fInumber\fR[\fI,...,number\fR]
340 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.
342 \fBWITH\-ALL\-VALUES "false"\fR
344 \fBWITH\-ALL\-VALUES "true"\fR
345 Requires that all values of the \fBEXPECT\fR attribute match the boolean value given.
347 \fBWITH\-ALL\-VALUES "/\fIregular expression\fB/"\fR
348 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.
350 \fBWITH\-HOSTNAME "\fIliteral string\fB"\fR
352 \fBWITH\-HOSTNAME "/\fIregular expression\fB/"\fR
353 Requires that at least one URI value contains a matching hostname.
355 \fBWITH\-RESOURCE "\fIliteral string\fB"\fR
357 \fBWITH\-RESOURCE "/\fIregular expression\fB/"\fR
358 Requires that at least one URI value contains a matching resource (including leading /).
360 \fBWITH\-SCHEME "\fIliteral string\fB"\fR
362 \fBWITH\-SCHEME "/\fIregular expression\fB/"\fR
363 Requires that at least one URI value contains a matching scheme.
365 \fBWITH\-VALUE "\fIliteral string\fB"\fR
366 Requires that at least one value of the \fBEXPECT\fR attribute matches the literal string. Comparisons are case-sensitive.
368 \fBWITH\-VALUE <\fInumber\fR
370 \fBWITH\-VALUE =\fInumber\fR
372 \fBWITH\-VALUE >\fInumber\fR
374 \fBWITH\-VALUE \fInumber\fR[\fI,...,number\fR]
375 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.
377 \fBWITH\-VALUE "false"\fR
379 \fBWITH\-VALUE "true"\fR
380 Requires that at least one value of the \fBEXPECT\fR attribute matches the boolean value given.
382 \fBWITH\-VALUE "/\fIregular expression\fB/"\fR
383 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.
385 \fBWITH\-VALUE\-FROM \fIattribute-name\fR
386 Requires that the value(s) of the \fBEXPECT\fR attribute matches the value(s) in the specified attribute.
387 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.
388 .SS STATUS PREDICATES
389 The following predicates are understood following the \fBSTATUS\fR test directive:
391 \fBDEFINE\-MATCH \fIvariable-name\fR
392 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.
394 \fBDEFINE\-NO\-MATCH \fIvariable-name\fR
395 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.
397 \fBIF\-DEFINED \fIvariable-name\fR
398 Makes the \fBSTATUS\fR apply only if the specified variable is defined.
400 \fBIF\-NOT\-DEFINED \fIvariable-name\fR
401 Makes the \fBSTATUS\fR apply only if the specified variable is not defined.
403 \fBREPEAT\-LIMIT \fInumber\fR
405 Specifies the maximum number of times to repeat. The default value is 1000.
409 \fBREPEAT\-NO\-MATCH\fR
410 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.
412 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
418 CUPS\-Add\-Modify\-Class
419 CUPS\-Add\-Modify\-Printer
420 CUPS\-Authenticate\-Job
422 CUPS\-Delete\-Printer
440 Create\-Job\-Subscriptions
441 Create\-Printer\-Subscriptions
448 Get\-Printer\-Attributes
449 Get\-Printer\-Support\-Files
450 Get\-Printer\-Supported\-Values
451 Get\-Subscription\-Attributes
457 Pause\-Printer\-After\-Current\-Job
462 Release\-Held\-New\-Jobs
473 Send\-Hardcopy\-Document
477 Set\-Printer\-Attributes
480 Suspend\-Current\-Job
485 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
489 client\-error\-account\-authorization\-failed
490 client\-error\-account\-closed
491 client\-error\-account\-info\-needed
492 client\-error\-account\-limit\-reached
493 client\-error\-attributes\-not\-settable
494 client\-error\-attributes\-or\-values\-not\-supported
495 client\-error\-bad\-request
496 client\-error\-charset\-not\-supported
497 client\-error\-compression\-error
498 client\-error\-compression\-not\-supported
499 client\-error\-conflicting\-attributes
500 client\-error\-document\-access\-error
501 client\-error\-document\-format\-error
502 client\-error\-document\-format\-not\-supported
503 client\-error\-document\-password\-error
504 client\-error\-document\-permission\-error
505 client\-error\-document\-security\-error
506 client\-error\-document\-unprintable\-error
507 client\-error\-forbidden
509 client\-error\-ignored\-all\-notifications
510 client\-error\-ignored\-all\-subscriptions
511 client\-error\-not\-authenticated
512 client\-error\-not\-authorized
513 client\-error\-not\-found
514 client\-error\-not\-possible
515 client\-error\-print\-support\-file\-not\-found
516 client\-error\-request\-entity\-too\-large
517 client\-error\-request\-value\-too\-long
518 client\-error\-timeout
519 client\-error\-too\-many\-subscriptions
520 client\-error\-uri\-scheme\-not\-supported
521 cups\-error\-account\-authorization\-failed
522 cups\-error\-account\-closed
523 cups\-error\-account\-info\-needed
524 cups\-error\-account\-limit\-reached
526 redirection\-other\-site
528 server\-error\-device\-error
529 server\-error\-internal\-error
530 server\-error\-job\-canceled
531 server\-error\-multiple\-document\-jobs\-not\-supported
532 server\-error\-not\-accepting\-jobs
533 server\-error\-operation\-not\-supported
534 server\-error\-printer\-is\-deactivated
535 server\-error\-service\-unavailable
536 server\-error\-temporary\-error
537 server\-error\-version\-not\-supported
539 successful\-ok\-but\-cancel\-subscription
540 successful\-ok\-conflicting\-attributes
541 successful\-ok\-events\-complete
542 successful\-ok\-ignored\-notifications
543 successful\-ok\-ignored\-or\-substituted\-attributes
544 successful\-ok\-ignored\-subscriptions
545 successful\-ok\-too\-many\-events
548 Value and group tags correspond to the names from RFC 8011 and other IPP extension specifications. Here are the group tags:
551 document\-attributes\-tag
552 event\-notification\-attributes\-tag
554 operation\-attributes\-tag
555 printer\-attributes\-tag
556 subscription\-attributes\-tag
557 unsupported\-attributes\-tag
560 Here are the value tags:
592 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:
595 Inserts a single "$" character.
597 \fB$ENV[\fIname\fB]\fR
598 Inserts the value of the named environment variable, or an empty string if the environment variable is not defined.
601 Inserts the filename provided to
603 with the \fI-f\fR option.
606 Inserts the MIME media type for the filename provided to
608 with the \fI-f\fR option.
611 Inserts the hostname from the URI provided to
615 Inserts the last "job\-id" attribute value returned in a test response or 0 if no "job\-id" attribute has been seen.
618 Inserts the last "job\-uri" attribute value returned in a test response or an empty string if no "job\-uri" attribute has been seen.
620 \fB$notify\-subscription\-id\fR
621 Inserts the last "notify\-subscription\-id" attribute value returned in a test response or 0 if no "notify\-subscription\-id" attribute has been seen.
624 Inserts the port number from the URI provided to
628 Inserts the resource path from the URI provided to
632 Inserts the scheme from the URI provided to
636 Inserts the URI provided to
640 Inserts the username from the URI provided to
645 Inserts the current user's login name.
648 IANA IPP Registry (http://www.iana.org/assignments/ipp-registrations),
649 PWG Internet Printing Protocol Workgroup (http://www.pwg.org/ipp),
650 RFC 8011 (http://tools.ietf.org/html/rfc8011)
652 Copyright \[co] 2007-2017 by Apple Inc.