4 .\" ipptoolfile man page for CUPS.
6 .\" Copyright 2010-2013 by Apple Inc.
8 .\" These coded instructions, statements, and computer programs are the
9 .\" property of Apple Inc. and are protected by Federal copyright
10 .\" law. Distribution and use rights are outlined in the file "LICENSE.txt"
11 .\" which should have been included with this file. If this file is
12 .\" file is missing or damaged, see the license at "http://www.cups.org/".
14 .TH ipptoolfile 5 "CUPS" "13 May 2013" "Apple Inc."
16 ipptoolfile \- ipptool file format
19 The \fIipptool(1)\fR program accepts free-form plain text files that describe one or more IPP requests. Comments start with the "#" character and continue to the end of the line. Each request is enclosed by curly braces, for example:
24 # The name of the test
25 NAME "Print PostScript Job"
29 GROUP operation-attributes-tag
30 ATTR charset attributes-charset utf-8
31 ATTR language attributes-natural-language en
32 ATTR uri printer-uri $uri
33 ATTR name requesting-user-name $user
36 # The response to expect
38 EXPECT attributes-charset OF-TYPE charset
39 EXPECT attributes-natural-language OF-TYPE naturalLanguage
40 EXPECT job-id OF-TYPE integer
41 EXPECT job-uri OF-TYPE uri
44 # The name of the test
45 NAME "Get Attributes of PostScript Job"
48 OPERATION Get-Job-Attributes
49 GROUP operation-attributes-tag
50 ATTR charset attributes-charset utf-8
51 ATTR language attributes-natural-language en
52 ATTR uri printer-uri $uri
53 ATTR integer job-id $job-id
54 ATTR name requesting-user-name $user
56 # The response to expect
58 EXPECT attributes-charset OF-TYPE charset
59 EXPECT attributes-natural-language OF-TYPE naturalLanguage
60 EXPECT job-id OF-TYPE integer
61 EXPECT job-uri OF-TYPE uri
62 EXPECT job-state OF-TYPE enum
63 EXPECT job-originating-user-name OF-TYPE name WITH-VALUE "$user"
67 .SH TOP-LEVEL DIRECTIVES
68 The following directives can be used outside of a test:
73 DEFINE variable-name value
74 Defines the named variable to the given value. This is equivalent to specifying
75 "-d variable-name=value" on the \fIipptool\fR command-line.
77 DEFINE-DEFAULT variable-name value
78 Defines the named variable to the given value if it does not already have a
82 Specifies an identifier string for the current file.
87 Specifies whether, by default, \fIipptool\fR will ignore errors and continue with
93 Includes another test file. The first form includes a file relative to the
94 current test file, while the second form includes a file from the \fIipptool\fR
97 INCLUDE-IF-DEFINED name "filename"
99 INCLUDE-IF-DEFINED name <filename>
100 Includes another test file if the named variable is defined. The first form
101 includes a file relative to the current test file, while the second form
102 includes a file from the \fIipptool\fR include directory.
104 INCLUDE-IF-NOT-DEFINED name "filename"
106 INCLUDE-IF-NOT-DEFINED name <filename>
107 Includes another test file if the named variable is not defined. The first form
108 includes a file relative to the current test file, while the second form
109 includes a file from the \fIipptool\fR include directory.
111 SKIP-IF-DEFINED variable-name
113 SKIP-IF-NOT-DEFINED variable-name
114 Specifies that the remainder of the test file should be skipped when the
115 variable is or is not defined.
117 STOP-AFTER-INCLUDE-ERROR no
119 STOP-AFTER-INCLUDE-ERROR yes
120 Specifies whether tests will be stopped after an error in an included file.
123 Specifies that tests will, by default, use "Transfer-Encoding: chunked" for
124 requests with attached files and "Content-Length:" for requests without attached
128 Specifies that tests will, by default, use the HTTP/1.1 "Transfer-Encoding:
129 chunked" header. This is the default and is equivalent to specifying "-c" on the
130 \fIipptool\fR command-line. Support for chunked requests is required for
131 conformance with all versions of IPP.
134 Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:"
135 header. This is equivalent to specifying "-l" on the \fIipptool\fR command-line.
136 Support for content length requests is required for conformance with all
148 Specifies the default IPP version number to use for the tests that follow.
151 The following directives are understood in a test:
153 ATTR tag attribute-name value(s)
154 Adds an attribute to the test request. Values are separated by the comma (",")
155 character - escape commas using the "\" character.
157 ATTR collection attribute-name { MEMBER tag member-name value(s) ... } [ ... { ... } ]
158 Adds a collection attribute to the test request. Member attributes follow the
159 same syntax as regular attributes and can themselves be nested collections.
160 Multiple collection values can be supplied as needed.
168 Uses the specified compression on the document data following the attributes in
169 a Print-Job or Send-Document request.
172 Specifies a delay before this test will be run.
174 DISPLAY attribute-name
175 Specifies that value of the named attribute should be output as part of the
178 EXPECT attribute-name [ predicate(s) ]
180 EXPECT ?attribute-name predicate(s)
182 EXPECT !attribute-name
183 Specifies that the response must/may/must not include the named attribute.
184 Additional requirements can be added as predicates - see the "EXPECT PREDICATES"
185 section for more information on predicates.
188 Specifies a file to include at the end of the request. This is typically used
189 when sending a test print file.
192 Specifies the group tag for subsequent attributes in the request.
197 Specifies whether \fIipptool\fR will ignore errors and continue with subsequent
200 NAME "literal string"
201 Specifies the human-readable name of the test.
203 OPERATION operation-code
204 Specifies the operation to be performed.
209 Specifies the request-id value to use in the request, either an integer or the
210 word "random" to use a randomly generated value (the default).
213 Specifies an alternate resource path that is used for the HTTP POST request.
214 The default is the resource from the URI provided to the \fIipptool\fR program.
216 SKIP-IF-DEFINED variable-name
218 SKIP-IF-NOT-DEFINED variable-name
219 Specifies that the current test should be skipped when the variable is or is not
222 SKIP-PREVIOUS-ERROR yes
224 SKIP-PREVIOUS-ERROR no
225 Specifies whether \fIipptool\fR will skip the current test if the previous test
226 resulted in an error/failure.
228 STATUS status-code [ predicate ]
229 Specifies an expected response status-code value. Additional requirements can be
230 added as predicates - see the "STATUS PREDICATES" section for more information
234 Specifies an identifier string for the current test.
237 Specifies that this test will use "Transfer-Encoding: chunked" if it has an
238 attached file or "Content-Length:" otherwise.
241 Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked"
245 Specifies that this test will use the HTTP/1.0 "Content-Length:" header.
256 Specifies the IPP version number to use for this test.
258 .SH EXPECT PREDICATES
259 The following predicates are understood following the EXPECT test directive:
262 Requires the EXPECT attribute to have the specified number of values.
264 DEFINE-MATCH variable-name
265 Defines the variable to "1" when the EXPECT condition matches. A side-effect of
266 this predicate is that this EXPECT will never fail a test.
268 DEFINE-NO-MATCH variable-name
269 Defines the variable to "1" when the EXPECT condition does not match. A side-
270 effect of this predicate is that this EXPECT will never fail a test.
272 DEFINE-VALUE variable-name
273 Defines the variable to the value of the attribute when the EXPECT condition
274 matches. A side-effect of this predicate is that this EXPECT will never fail a test.
276 IF-DEFINED variable-name
277 Makes the EXPECT conditions apply only if the specified variable is defined.
279 IF-NOT-DEFINED variable-name
280 Makes the EXPECT conditions apply only if the specified variable is not
284 Requires the EXPECT attribute to be in the specified group tag.
286 OF-TYPE tag[,tag,...]
287 Requires the EXPECT attribute to use the specified value tag(s).
291 Specifies the maximum number of times to repeat. The default value is 1000.
296 Specifies that the current test should be repeated when the EXPECT condition
297 matches or does not match.
299 SAME-COUNT-AS attribute-name
300 Requires the EXPECT attribute to have the same number of values as the specified
303 WITH-ALL-VALUES "literal string"
304 Requires that all values of the EXPECT attribute match the literal string. Comparisons are case-sensitive.
306 WITH-ALL-VALUES <number
308 WITH-ALL-VALUES =number
310 WITH-ALL-VALUES >number
312 WITH-ALL-VALUES number[,number,...]
313 Requires that all values of the EXPECT attribute match the number(s) or numeric comparison. When comparing rangeOfInteger values, the "<" and ">" operators only check the upper bound of the range.
315 WITH-ALL-VALUES "false"
317 WITH-ALL-VALUES "true"
318 Requires that all values of the EXPECT attribute match the boolean value given.
320 WITH-ALL-VALUES "/regular expression/"
321 Requires that all values of the EXPECT attribute match the regular expression, which must conform to the POSIX regular expression syntax. Comparisons are case-sensitive.
323 WITH-VALUE "literal string"
324 Requires that at least one value of the EXPECT attribute matches the literal string. Comparisons are case-sensitive.
332 WITH-VALUE number[,number,...]
333 Requires that at least one value of the EXPECT attribute matches the number(s) or numeric comparison. When comparing rangeOfInteger values, the "<" and ">" operators only check the upper bound of the range.
338 Requires that at least one value of the EXPECT attribute matches the boolean value given.
340 WITH-VALUE "/regular expression/"
341 Requires that at least one value of the EXPECT attribute matches the regular expression, which must conform to the POSIX regular expression syntax. Comparisons are case-sensitive.
343 .SH STATUS PREDICATES
344 The following predicates are understood following the STATUS test directive:
346 DEFINE-MATCH variable-name
347 Defines the variable to "1" when the STATUS matches. A side-effect of this predicate is that this STATUS will never fail a test.
349 DEFINE-NO-MATCH variable-name
350 Defines the variable to "1" when the STATUS does not match. A side-effect of this predicate is that this STATUS will never fail a test.
352 IF-DEFINED variable-name
353 Makes the STATUS apply only if the specified variable is defined.
355 IF-NOT-DEFINED variable-name
356 Makes the STATUS apply only if the specified variable is not defined.
360 Specifies the maximum number of times to repeat. The default value is 1000.
365 Specifies that the current test should be repeated when the response status-code
366 matches or does not match the value specified by the STATUS directive.
369 Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from
370 RFC 2911 and other IPP extension specifications. Here is a complete list:
374 CUPS-Add-Modify-Class
375 CUPS-Add-Modify-Printer
376 CUPS-Authenticate-Job
396 Create-Job-Subscription
397 Create-Printer-Subscription
404 Get-Printer-Attributes
405 Get-Printer-Support-Files
406 Get-Printer-Supported-Values
407 Get-Subscription-Attributes
413 Pause-Printer-After-Current-Job
418 Release-Held-New-Jobs
429 Send-Hardcopy-Document
433 Set-Printer-Attributes
442 Status codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC
443 2911 and other IPP extension specifications. Here is a complete list:
445 client-error-attributes-not-settable
446 client-error-attributes-or-values-not-supported
447 client-error-bad-request
448 client-error-charset-not-supported
449 client-error-compression-error
450 client-error-compression-not-supported
451 client-error-conflicting-attributes
452 client-error-document-access-error
453 client-error-document-format-error
454 client-error-document-format-not-supported
455 client-error-document-password-error
456 client-error-document-permission-error
457 client-error-document-security-error
458 client-error-document-unprintable-error
459 client-error-forbidden
461 client-error-ignored-all-notifications
462 client-error-ignored-all-subscriptions
463 client-error-not-authenticated
464 client-error-not-authorized
465 client-error-not-found
466 client-error-not-possible
467 client-error-print-support-file-not-found
468 client-error-request-entity-too-large
469 client-error-request-value-too-long
471 client-error-too-many-subscriptions
472 client-error-uri-scheme-not-supported
474 redirection-other-site
476 server-error-device-error
477 server-error-internal-error
478 server-error-job-canceled
479 server-error-multiple-document-jobs-not-supported
480 server-error-not-accepting-jobs
481 server-error-operation-not-supported
482 server-error-printer-is-deactivated
483 server-error-service-unavailable
484 server-error-temporary-error
485 server-error-version-not-supported
487 successful-ok-but-cancel-subscription
488 successful-ok-conflicting-attributes
489 successful-ok-events-complete
490 successful-ok-ignored-notifications
491 successful-ok-ignored-or-substituted-attributes
492 successful-ok-ignored-subscriptions
493 successful-ok-too-many-events
497 Value and group tags correspond to the names from RFC 2911 and other IPP
498 extension specifications. Here are the group tags:
500 event-notification-attributes-tag
502 operation-attributes-tag
503 printer-attributes-tag
504 subscription-attributes-tag
505 unsupported-attributes-tag
508 Here are the value tags:
538 The \fIipptool\fR program maintains a list of variables that can be used in any
539 literal string or attribute value by specifying "$variable-name". Aside from
540 variables defined using the "-d" option or "DEFINE" directive, the following
541 pre-defined variables are available:
544 Inserts a single "$" character.
547 Inserts the value of the named environment variable, or an empty string if the
548 environment variable is not defined.
551 Inserts the filename provided to \fIipptool\fR with the "-f" option.
554 Inserts the hostname from the URI provided to \fIipptool\fR.
557 Inserts the last job-id value returned in a test response or 0 if no job-id has
561 Inserts the last job-uri value returned in a test response or an empty string if
562 no job-uri has been seen.
565 Inserts the scheme from the URI provided to \fIipptool\fR.
567 $notify-subscription-id
568 Inserts the last notify-subscription-id value returned in a test response or 0 if
569 no notify-subscription-id has been seen.
572 Inserts the port number from the URI provided to \fIipptool\fR.
575 Inserts the resource path from the URI provided to \fIipptool\fR.
578 Inserts the URI provided to \fIipptool\fR.
581 Inserts the current user's login name.
584 Inserts the username from the URI provided to \fIipptool\fR, if any.
589 http://localhost:631/help
592 Copyright 2007-2013 by Apple Inc.