1ipptoolfile(5) Apple Inc. ipptoolfile(5)
2
6 ipptoolfile - ipptool file format
7
10 The ipptool(1) program accepts free-form plain text files that describe
11 one or more IPP requests. Comments start with the "#" character and
12 continue to the end of the line. Each request is enclosed by curly
13 braces, for example:
14 # This is a comment
16 {
17 # The name of the test
18 NAME "Print PostScript Job"
19 # The request to send
21 OPERATION Print-Job
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 FILE testfile.ps
28 # The response to expect
30 STATUS successful-ok
31 EXPECT attributes-charset OF-TYPE charset
32 EXPECT attributes-natural-language OF-TYPE naturalLanguage
33 EXPECT job-id OF-TYPE integer
34 EXPECT job-uri OF-TYPE uri
35 }
36 {
37 # The name of the test
38 NAME "Get Attributes of PostScript Job"
39 # The request to send
41 OPERATION Get-Job-Attributes
42 GROUP operation-attributes-tag
43 ATTR charset attributes-charset utf-8
44 ATTR language attributes-natural-language en
45 ATTR uri printer-uri $uri
46 ATTR integer job-id $job-id
47 ATTR name requesting-user-name $user
48 # The response to expect
50 STATUS successful-ok
51 EXPECT attributes-charset OF-TYPE charset
52 EXPECT attributes-natural-language OF-TYPE naturalLanguage
53 EXPECT job-id OF-TYPE integer
54 EXPECT job-uri OF-TYPE uri
55 EXPECT job-state OF-TYPE enum
56 EXPECT job-originating-user-name OF-TYPE name WITH-VALUE "$user"
57 }
58
61 The following directives can be used outside of a test:
62 { test }
64 Defines a test.
65 DEFINE variable-name value
67 Defines the named variable to the given value. This is equivalent
68 to specifying "-d variable-name=value" on the ipptool command-
69 line.
70 DEFINE-DEFAULT variable-name value
72 Defines the named variable to the given value if it does not
73 already have a value.
74 IGNORE-ERRORS yes
76 IGNORE-ERRORS no
78 Specifies whether, by default, ipptool will ignore errors and con‐
79 tinue with subsequent tests.
80 INCLUDE "filename"
82 INCLUDE <filename>
84 Includes another test file. The first form includes a file rela‐
85 tive to the current test file, while the second form includes a
86 file from the ipptool include directory.
87 INCLUDE-IF-DEFINED name "filename"
89 INCLUDE-IF-DEFINED name <filename>
91 Includes another test file if the named variable is defined. The
92 first form includes a file relative to the current test file,
93 while the second form includes a file from the ipptool include
94 directory.
95 INCLUDE-IF-NOT-DEFINED name "filename"
97 INCLUDE-IF-NOT-DEFINED name <filename>
99 Includes another test file if the named variable is not defined.
100 The first form includes a file relative to the current test file,
101 while the second form includes a file from the ipptool include
102 directory.
103 SKIP-IF-DEFINED variable-name
105 SKIP-IF-NOT-DEFINED variable-name
107 Specifies that the remainder of the test file should be skipped
108 when the variable is or is not defined.
109 TRANSFER auto
111 Specifies that tests will, by default, use "Transfer-Encoding:
112 chunked" for requests with attached files and "Content-Length:"
113 for requests without attached files.
114 TRANSFER chunked
116 Specifies that tests will, by default, use the HTTP/1.1 "Transfer-
117 Encoding: chunked" header. This is the default and is equivalent
118 to specifying "-c" on the ipptool command-line. Support for chun‐
119 ked requests is required for conformance with all versions of IPP.
120 TRANSFER length
122 Specifies that tests will, by default, use the HTTP/1.0 "Content-
123 Length:" header. This is equivalent to specifying "-l" on the ipp‐
124 tool command-line. Support for content length requests is
125 required for conformance with all versions of IPP.
126 VERSION 1.0
128 VERSION 1.1
130 VERSION 2.0
132 VERSION 2.1
134 VERSION 2.2
136 Specifies the default IPP version number to use for the tests that
137 follow.
138
141 The following directives are understood in a test:
142 ATTR tag attribute-name value(s)
144 Adds an attribute to the test request. Values are separated by the
145 comma (",") character - escape commas using the "
146 ATTR collection attribute-name { MEMBER tag member-name value(s) ... }
148 [ ... { ... } ]
149 Adds a collection attribute to the test request. Member attributes
150 follow the same syntax as regular attributes and can themselves be
151 nested collections. Multiple collection values can be supplied as
152 needed.
153 DELAY seconds
155 Specifies a delay before this test will be run.
156 DISPLAY attribute-name
158 Specifies that value of the named attribute should be output as
159 part of the test report.
160 EXPECT attribute-name [ predicate(s) ]
162 EXPECT ?attribute-name predicate(s)
164 EXPECT !attribute-name
166 Specifies that the response must/may/must not include the named
167 attribute. Additional requirements can be added as predicates -
168 see the "EXPECT PREDICATES" section for more information on predi‐
169 cates.
170 FILE filename
172 Specifies a file to include at the end of the request. This is
173 typically used when sending a test print file.
174 GROUP tag
176 Specifies the group tag for subsequent attributes in the request.
177 IGNORE-ERRORS yes
179 IGNORE-ERRORS no
181 Specifies whether ipptool will ignore errors and continue with
182 subsequent tests.
183 NAME "literal string"
185 Specifies the human-readable name of the test.
186 OPERATION operation-code
188 Specifies the operation to be performed.
189 REQUEST-ID number
191 REQUEST-ID random
193 Specifies the request-id value to use in the request, either an
194 integer or the word "random" to use a randomly generated value
195 (the default).
196 RESOURCE path
198 Specifies an alternate resource path that is used for the HTTP
199 POST request. The default is the resource from the URI provided
200 to the ipptool program.
201 SKIP-IF-DEFINED variable-name
203 SKIP-IF-NOT-DEFINED variable-name
205 Specifies that the current test should be skipped when the vari‐
206 able is or is not defined.
207 SKIP-PREVIOUS-ERROR yes
209 SKIP-PREVIOUS-ERROR no
211 Specifies whether ipptool will skip the current test if the previ‐
212 ous test resulted in an error/failure.
213 STATUS status-code [ predicate ]
215 Specifies an expected response status-code value. Additional
216 requirements can be added as predicates - see the "STATUS PREDI‐
217 CATES" section for more information on predicates.
218 TRANSFER auto
220 Specifies that this test will use "Transfer-Encoding: chunked" if
221 it has an attached file or "Content-Length:" otherwise.
222 TRANSFER chunked
224 Specifies that this test will use the HTTP/1.1 "Transfer-Encoding:
225 chunked" header.
226 TRANSFER length
228 Specifies that this test will use the HTTP/1.0 "Content-Length:"
229 header.
230 VERSION 1.0
232 VERSION 1.1
234 VERSION 2.0
236 VERSION 2.1
238 VERSION 2.2
240 Specifies the IPP version number to use for this test.
241
244 The following predicates are understood following the EXPECT test
245 directive:
246 COUNT number
248 Requires the EXPECT attribute to have the specified number of val‐
249 ues.
250 DEFINE-MATCH variable-name
252 Defines the variable to "1" when the EXPECT condition matches. A
253 side-effect of this predicate is that this EXPECT will never fail
254 a test.
255 DEFINE-NO-MATCH variable-name
257 Defines the variable to "1" when the EXPECT condition does not
258 match. A side- effect of this predicate is that this EXPECT will
259 never fail a test.
260 DEFINE-VALUE variable-name
262 Defines the variable to the value of the attribute when the EXPECT
263 condition matches. A side-effect of this predicate is that this
264 EXPECT will never fail a test.
265 IF-DEFINED variable-name
267 Makes the EXPECT conditions apply only if the specified variable
268 is defined.
269 IF-NOT-DEFINED variable-name
271 Makes the EXPECT conditions apply only if the specified variable
272 is not defined.
273 IN-GROUP tag
275 Requires the EXPECT attribute to be in the specified group tag.
276 OF-TYPE tag[,tag,...]
278 Requires the EXPECT attribute to use the specified value tag(s).
279 REPEAT-LIMIT number
281 Specifies the maximum number of times to repeat. The default value
282 is 1000.
283 REPEAT-MATCH
285 REPEAT-NO-MATCH
287 Specifies that the current test should be repeated when the EXPECT
288 condition matches or does not match.
289 SAME-COUNT-AS attribute-name
291 Requires the EXPECT attribute to have the same number of values as
292 the specified parallel attribute.
293 WITH-ALL-VALUES "literal string"
295 Requires that all values of the EXPECT attribute match the literal
296 string. Comparisons are case-sensitive.
297 WITH-ALL-VALUES <number
299 WITH-ALL-VALUES =number
301 WITH-ALL-VALUES >number
303 WITH-ALL-VALUES number[,number,...]
305 Requires that all values of the EXPECT attribute match the num‐
306 ber(s) or numeric comparison. When comparing rangeOfInteger val‐
307 ues, the "<" and ">" operators only check the upper bound of the
308 range.
309 WITH-ALL-VALUES "false"
311 WITH-ALL-VALUES "true"
313 Requires that all values of the EXPECT attribute match the boolean
314 value given.
315 WITH-ALL-VALUES "/regular expression/"
317 Requires that all values of the EXPECT attribute match the regular
318 expression, which must conform to the POSIX regular expression
319 syntax. Comparisons are case-sensitive.
320 WITH-VALUE "literal string"
322 Requires that at least one value of the EXPECT attribute matches
323 the literal string. Comparisons are case-sensitive.
324 WITH-VALUE <number
326 WITH-VALUE =number
328 WITH-VALUE >number
330 WITH-VALUE number[,number,...]
332 Requires that at least one value of the EXPECT attribute matches
333 the number(s) or numeric comparison. When comparing rangeOfInteger
334 values, the "<" and ">" operators only check the upper bound of
335 the range.
336 WITH-VALUE "false"
338 WITH-VALUE "true"
340 Requires that at least one value of the EXPECT attribute matches
341 the boolean value given.
342 WITH-VALUE "/regular expression/"
344 Requires that at least one value of the EXPECT attribute matches
345 the regular expression, which must conform to the POSIX regular
346 expression syntax. Comparisons are case-sensitive.
347
350 The following predicates are understood following the STATUS test
351 directive:
352 DEFINE-MATCH variable-name
354 Defines the variable to "1" when the STATUS matches. A side-effect
355 of this predicate is that this STATUS will never fail a test.
356 DEFINE-NO-MATCH variable-name
358 Defines the variable to "1" when the STATUS does not match. A
359 side-effect of this predicate is that this STATUS will never fail
360 a test.
361 IF-DEFINED variable-name
363 Makes the STATUS apply only if the specified variable is defined.
364 IF-NOT-DEFINED variable-name
366 Makes the STATUS apply only if the specified variable is not
367 defined.
368 REPEAT-LIMIT number
370 Specifies the maximum number of times to repeat. The default value
371 is 1000.
372 REPEAT-MATCH
374 REPEAT-NO-MATCH
376 Specifies that the current test should be repeated when the
377 response status-code matches or does not match the value specified
378 by the STATUS directive.
379
382 Operation codes correspond to the hexadecimal numbers (0xHHHH) and
383 names from RFC 2911 and other IPP extension specifications. Here is a
384 complete list:
385 Activate-Printer
386 CUPS-Accept-Jobs
387 CUPS-Add-Modify-Class
388 CUPS-Add-Modify-Printer
389 CUPS-Authenticate-Job
390 CUPS-Delete-Class
391 CUPS-Delete-Printer
392 CUPS-Get-Classes
393 CUPS-Get-Default
394 CUPS-Get-Devices
395 CUPS-Get-Document
396 CUPS-Get-PPD
397 CUPS-Get-PPDs
398 CUPS-Get-Printers
399 CUPS-Move-Job
400 CUPS-Reject-Jobs
401 CUPS-Set-Default
402 Cancel-Current-Job
403 Cancel-Job
404 Cancel-Jobs
405 Cancel-My-Jobs
406 Cancel-Subscription
407 Close-Job
408 Create-Job
409 Create-Job-Subscription
410 Create-Printer-Subscription
411 Deactivate-Printer
412 Disable-Printer
413 Enable-Printer
414 Get-Job-Attributes
415 Get-Jobs
416 Get-Notifications
417 Get-Printer-Attributes
418 Get-Printer-Support-Files
419 Get-Printer-Supported-Values
420 Get-Subscription-Attributes
421 Get-Subscriptions
422 Hold-Job
423 Hold-New-Jobs
424 Identify-Printer
425 Pause-Printer
426 Pause-Printer-After-Current-Job
427 Print-Job
428 Print-URI
429 Promote-Job
430 Purge-Jobs
431 Release-Held-New-Jobs
432 Release-Job
433 Renew-Subscription
434 Reprocess-Job
435 Restart-Job
436 Restart-Printer
437 Resubmit-Job
438 Resume-Job
439 Resume-Printer
440 Schedule-Job-After
441 Send-Document
442 Send-Notifications
443 Send-URI
444 Set-Job-Attributes
445 Set-Printer-Attributes
446 Shutdown-Printer
447 Startup-Printer
448 Suspend-Current-Job
449 Validate-Document
450 Validate-Job
451
454 Status codes correspond to the hexadecimal numbers (0xHHHH) and names
455 from RFC 2911 and other IPP extension specifications. Here is a com‐
456 plete list:
457 client-error-attributes-not-settable
458 client-error-attributes-or-values-not-supported
459 client-error-bad-request
460 client-error-charset-not-supported
461 client-error-compression-error
462 client-error-compression-not-supported
463 client-error-conflicting-attributes
464 client-error-document-access-error
465 client-error-document-format-error
466 client-error-document-format-not-supported
467 client-error-document-password-error
468 client-error-document-permission-error
469 client-error-document-security-error
470 client-error-document-unprintable-error
471 client-error-forbidden
472 client-error-gone
473 client-error-ignored-all-notifications
474 client-error-ignored-all-subscriptions
475 client-error-not-authenticated
476 client-error-not-authorized
477 client-error-not-found
478 client-error-not-possible
479 client-error-print-support-file-not-found
480 client-error-request-entity-too-large
481 client-error-request-value-too-long
482 client-error-timeout
483 client-error-too-many-subscriptions
484 client-error-uri-scheme-not-supported
485 cups-see-other
486 redirection-other-site
487 server-error-busy
488 server-error-device-error
489 server-error-internal-error
490 server-error-job-canceled
491 server-error-multiple-document-jobs-not-supported
492 server-error-not-accepting-jobs
493 server-error-operation-not-supported
494 server-error-printer-is-deactivated
495 server-error-service-unavailable
496 server-error-temporary-error
497 server-error-version-not-supported
498 successful-ok
499 successful-ok-but-cancel-subscription
500 successful-ok-conflicting-attributes
501 successful-ok-events-complete
502 successful-ok-ignored-notifications
503 successful-ok-ignored-or-substituted-attributes
504 successful-ok-ignored-subscriptions
505 successful-ok-too-many-events
506
509 Value and group tags correspond to the names from RFC 2911 and other
510 IPP extension specifications. Here are the group tags:
511 event-notification-attributes-tag
512 job-attributes-tag
513 operation-attributes-tag
514 printer-attributes-tag
515 subscription-attributes-tag
516 unsupported-attributes-tag
517 Here are the value tags:
519 admin-define
520 boolean
521 charset
522 collection
523 dateTime
524 default
525 delete-attribute
526 enum
527 integer
528 keyword
529 mimeMediaType
530 nameWithLanguage
531 nameWithoutLanguage
532 naturalLanguage
533 no-value
534 not-settable
535 octetString
536 rangeOfInteger
537 resolution
538 textWithLanguage
539 textWithoutLanguage
540 unknown
541 unsupported
542 uri
543 uriScheme
544
547 The ipptool program maintains a list of variables that can be used in
548 any literal string or attribute value by specifying "$variable-name".
549 Aside from variables defined using the "-d" option or "DEFINE" direc‐
550 tive, the following pre-defined variables are available:
551 $$ Inserts a single "$" character.
553 $ENV[name]
555 Inserts the value of the named environment variable, or an empty
556 string if the environment variable is not defined.
557 $filename
559 Inserts the filename provided to ipptool with the "-f" option.
560 $hostname
562 Inserts the hostname from the URI provided to ipptool.
563 $job-id
565 Inserts the last job-id value returned in a test response or 0 if
566 no job-id has been seen.
567 $job-uri
569 Inserts the last job-uri value returned in a test response or an
570 empty string if no job-uri has been seen.
571 $scheme
573 Inserts the scheme from the URI provided to ipptool.
574 $notify-subscription-id
576 Inserts the last notify-subscription-id value returned in a test
577 response or 0 if no notify-subscription-id has been seen.
578 $port
580 Inserts the port number from the URI provided to ipptool.
581 $resource
583 Inserts the resource path from the URI provided to ipptool.
584 $uri Inserts the URI provided to ipptool.
586 $user
588 Inserts the current user's login name.
589 $username
591 Inserts the username from the URI provided to ipptool, if any.
592
595 ipptool(1),
596 http://localhost:631/help
597
600 Copyright 2007-2013 by Apple Inc.
60110 January 2013 CUPS ipptoolfile(5)