2 .\" "$Id: ipptoolfile.man 11022 2013-06-06 22:14:09Z msweet $"
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-HOSTNAMES "literal string"
305 WITH-ALL-HOSTNAMES "/regular expression/"
306 Requires that all URI values contain a matching hostname.
308 WITH-ALL-RESOURCES "literal string"
310 WITH-ALL-RESOURCES "/regular expression/"
311 Requires that all URI values contain a matching resource (including leading /).
313 WITH-ALL-SCHEMES "literal string"
315 WITH-ALL-SCHEMES "/regular expression/"
316 Requires that all URI values contain a matching scheme.
318 WITH-ALL-VALUES "literal string"
319 Requires that all values of the EXPECT attribute match the literal string. Comparisons are case-sensitive.
321 WITH-ALL-VALUES <number
323 WITH-ALL-VALUES =number
325 WITH-ALL-VALUES >number
327 WITH-ALL-VALUES number[,number,...]
328 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.
330 WITH-ALL-VALUES "false"
332 WITH-ALL-VALUES "true"
333 Requires that all values of the EXPECT attribute match the boolean value given.
335 WITH-ALL-VALUES "/regular expression/"
336 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.
338 WITH-HOSTNAME "literal string"
340 WITH-HOSTNAME "/regular expression/"
341 Requires that at least one URI value contains a matching hostname.
343 WITH-RESOURCE "literal string"
345 WITH-RESOURCE "/regular expression/"
346 Requires that at least one URI value contains a matching resource (including leading /).
348 WITH-SCHEME "literal string"
350 WITH-SCHEME "/regular expression/"
351 Requires that at least one URI value contains a matching scheme.
353 WITH-VALUE "literal string"
354 Requires that at least one value of the EXPECT attribute matches the literal string. Comparisons are case-sensitive.
362 WITH-VALUE number[,number,...]
363 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.
368 Requires that at least one value of the EXPECT attribute matches the boolean value given.
370 WITH-VALUE "/regular expression/"
371 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.
373 .SH STATUS PREDICATES
374 The following predicates are understood following the STATUS test directive:
376 DEFINE-MATCH variable-name
377 Defines the variable to "1" when the STATUS matches. A side-effect of this predicate is that this STATUS will never fail a test.
379 DEFINE-NO-MATCH variable-name
380 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.
382 IF-DEFINED variable-name
383 Makes the STATUS apply only if the specified variable is defined.
385 IF-NOT-DEFINED variable-name
386 Makes the STATUS apply only if the specified variable is not defined.
390 Specifies the maximum number of times to repeat. The default value is 1000.
395 Specifies that the current test should be repeated when the response status-code
396 matches or does not match the value specified by the STATUS directive.
399 Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from
400 RFC 2911 and other IPP extension specifications. Here is a complete list:
404 CUPS-Add-Modify-Class
405 CUPS-Add-Modify-Printer
406 CUPS-Authenticate-Job
426 Create-Job-Subscription
427 Create-Printer-Subscription
434 Get-Printer-Attributes
435 Get-Printer-Support-Files
436 Get-Printer-Supported-Values
437 Get-Subscription-Attributes
443 Pause-Printer-After-Current-Job
448 Release-Held-New-Jobs
459 Send-Hardcopy-Document
463 Set-Printer-Attributes
472 Status codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC
473 2911 and other IPP extension specifications. Here is a complete list:
475 client-error-attributes-not-settable
476 client-error-attributes-or-values-not-supported
477 client-error-bad-request
478 client-error-charset-not-supported
479 client-error-compression-error
480 client-error-compression-not-supported
481 client-error-conflicting-attributes
482 client-error-document-access-error
483 client-error-document-format-error
484 client-error-document-format-not-supported
485 client-error-document-password-error
486 client-error-document-permission-error
487 client-error-document-security-error
488 client-error-document-unprintable-error
489 client-error-forbidden
491 client-error-ignored-all-notifications
492 client-error-ignored-all-subscriptions
493 client-error-not-authenticated
494 client-error-not-authorized
495 client-error-not-found
496 client-error-not-possible
497 client-error-print-support-file-not-found
498 client-error-request-entity-too-large
499 client-error-request-value-too-long
501 client-error-too-many-subscriptions
502 client-error-uri-scheme-not-supported
504 redirection-other-site
506 server-error-device-error
507 server-error-internal-error
508 server-error-job-canceled
509 server-error-multiple-document-jobs-not-supported
510 server-error-not-accepting-jobs
511 server-error-operation-not-supported
512 server-error-printer-is-deactivated
513 server-error-service-unavailable
514 server-error-temporary-error
515 server-error-version-not-supported
517 successful-ok-but-cancel-subscription
518 successful-ok-conflicting-attributes
519 successful-ok-events-complete
520 successful-ok-ignored-notifications
521 successful-ok-ignored-or-substituted-attributes
522 successful-ok-ignored-subscriptions
523 successful-ok-too-many-events
527 Value and group tags correspond to the names from RFC 2911 and other IPP
528 extension specifications. Here are the group tags:
530 event-notification-attributes-tag
532 operation-attributes-tag
533 printer-attributes-tag
534 subscription-attributes-tag
535 unsupported-attributes-tag
538 Here are the value tags:
568 The \fIipptool\fR program maintains a list of variables that can be used in any
569 literal string or attribute value by specifying "$variable-name". Aside from
570 variables defined using the "-d" option or "DEFINE" directive, the following
571 pre-defined variables are available:
574 Inserts a single "$" character.
577 Inserts the value of the named environment variable, or an empty string if the
578 environment variable is not defined.
581 Inserts the filename provided to \fIipptool\fR with the "-f" option.
584 Inserts the hostname from the URI provided to \fIipptool\fR.
587 Inserts the last job-id value returned in a test response or 0 if no job-id has
591 Inserts the last job-uri value returned in a test response or an empty string if
592 no job-uri has been seen.
595 Inserts the scheme from the URI provided to \fIipptool\fR.
597 $notify-subscription-id
598 Inserts the last notify-subscription-id value returned in a test response or 0 if
599 no notify-subscription-id has been seen.
602 Inserts the port number from the URI provided to \fIipptool\fR.
605 Inserts the resource path from the URI provided to \fIipptool\fR.
608 Inserts the URI provided to \fIipptool\fR.
611 Inserts the current user's login name.
614 Inserts the username from the URI provided to \fIipptool\fR, if any.
619 http://localhost:631/help
622 Copyright 2007-2013 by Apple Inc.
624 .\" End of "$Id: ipptoolfile.man 11022 2013-06-06 22:14:09Z msweet $".