]> git.ipfire.org Git - thirdparty/cups.git/blob - man/ipptoolfile.man
<rdar://problem/13876038> cups.org: ipptool does not include any version information...
[thirdparty/cups.git] / man / ipptoolfile.man
1 .\"
2 .\" "$Id$"
3 .\"
4 .\" ipptoolfile man page for CUPS.
5 .\"
6 .\" Copyright 2010-2013 by Apple Inc.
7 .\"
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/".
13 .\"
14 .TH ipptoolfile 5 "CUPS" "13 May 2013" "Apple Inc."
15 .SH NAME
16 ipptoolfile \- ipptool file format
17
18 .SH DESCRIPTION
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:
20 .nf
21
22 # This is a comment
23 {
24 # The name of the test
25 NAME "Print PostScript Job"
26
27 # The request to send
28 OPERATION Print-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
34 FILE testfile.ps
35
36 # The response to expect
37 STATUS successful-ok
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
42 }
43 {
44 # The name of the test
45 NAME "Get Attributes of PostScript Job"
46
47 # The request to send
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
55
56 # The response to expect
57 STATUS successful-ok
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"
64 }
65 .fi
66
67 .SH TOP-LEVEL DIRECTIVES
68 The following directives can be used outside of a test:
69 .TP 5
70 { test }
71 Defines a test.
72 .TP 5
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.
76 .TP 5
77 DEFINE-DEFAULT variable-name value
78 Defines the named variable to the given value if it does not already have a
79 value.
80 .TP 5
81 FILE-ID "identifier"
82 Specifies an identifier string for the current file.
83 .TP 5
84 IGNORE-ERRORS yes
85 .TP 5
86 IGNORE-ERRORS no
87 Specifies whether, by default, \fIipptool\fR will ignore errors and continue with
88 subsequent tests.
89 .TP 5
90 INCLUDE "filename"
91 .TP 5
92 INCLUDE <filename>
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
95 include directory.
96 .TP 5
97 INCLUDE-IF-DEFINED name "filename"
98 .TP 5
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.
103 .TP 5
104 INCLUDE-IF-NOT-DEFINED name "filename"
105 .TP 5
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.
110 .TP 5
111 SKIP-IF-DEFINED variable-name
112 .TP 5
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.
116 .TP 5
117 STOP-AFTER-INCLUDE-ERROR no
118 .TP 5
119 STOP-AFTER-INCLUDE-ERROR yes
120 Specifies whether tests will be stopped after an error in an included file.
121 .TP 5
122 TRANSFER auto
123 Specifies that tests will, by default, use "Transfer-Encoding: chunked" for
124 requests with attached files and "Content-Length:" for requests without attached
125 files.
126 .TP 5
127 TRANSFER chunked
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.
132 .TP 5
133 TRANSFER length
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
137 versions of IPP.
138 .TP 5
139 VERSION 1.0
140 .TP 5
141 VERSION 1.1
142 .TP 5
143 VERSION 2.0
144 .TP 5
145 VERSION 2.1
146 .TP 5
147 VERSION 2.2
148 Specifies the default IPP version number to use for the tests that follow.
149
150 .SH TEST DIRECTIVES
151 The following directives are understood in a test:
152 .TP 5
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.
156 .TP 5
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.
161 .TP 5
162 COMPRESSION deflate
163 .TP 5
164 COMPRESSION gzip
165 .TP 5
166 COMPRESSION none
167 .br
168 Uses the specified compression on the document data following the attributes in
169 a Print-Job or Send-Document request.
170 .TP 5
171 DELAY seconds
172 Specifies a delay before this test will be run.
173 .TP 5
174 DISPLAY attribute-name
175 Specifies that value of the named attribute should be output as part of the
176 test report.
177 .TP 5
178 EXPECT attribute-name [ predicate(s) ]
179 .TP 5
180 EXPECT ?attribute-name predicate(s)
181 .TP 5
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.
186 .TP 5
187 FILE filename
188 Specifies a file to include at the end of the request. This is typically used
189 when sending a test print file.
190 .TP 5
191 GROUP tag
192 Specifies the group tag for subsequent attributes in the request.
193 .TP 5
194 IGNORE-ERRORS yes
195 .TP 5
196 IGNORE-ERRORS no
197 Specifies whether \fIipptool\fR will ignore errors and continue with subsequent
198 tests.
199 .TP 5
200 NAME "literal string"
201 Specifies the human-readable name of the test.
202 .TP 5
203 OPERATION operation-code
204 Specifies the operation to be performed.
205 .TP 5
206 REQUEST-ID number
207 .TP 5
208 REQUEST-ID random
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).
211 .TP 5
212 RESOURCE path
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.
215 .TP 5
216 SKIP-IF-DEFINED variable-name
217 .TP 5
218 SKIP-IF-NOT-DEFINED variable-name
219 Specifies that the current test should be skipped when the variable is or is not
220 defined.
221 .TP 5
222 SKIP-PREVIOUS-ERROR yes
223 .TP 5
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.
227 .TP 5
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
231 on predicates.
232 .TP 5
233 TEST-ID "identifier"
234 Specifies an identifier string for the current test.
235 .TP 5
236 TRANSFER auto
237 Specifies that this test will use "Transfer-Encoding: chunked" if it has an
238 attached file or "Content-Length:" otherwise.
239 .TP 5
240 TRANSFER chunked
241 Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked"
242 header.
243 .TP 5
244 TRANSFER length
245 Specifies that this test will use the HTTP/1.0 "Content-Length:" header.
246 .TP 5
247 VERSION 1.0
248 .TP 5
249 VERSION 1.1
250 .TP 5
251 VERSION 2.0
252 .TP 5
253 VERSION 2.1
254 .TP 5
255 VERSION 2.2
256 Specifies the IPP version number to use for this test.
257
258 .SH EXPECT PREDICATES
259 The following predicates are understood following the EXPECT test directive:
260 .TP 5
261 COUNT number
262 Requires the EXPECT attribute to have the specified number of values.
263 .TP 5
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.
267 .TP 5
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.
271 .TP 5
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.
275 .TP 5
276 IF-DEFINED variable-name
277 Makes the EXPECT conditions apply only if the specified variable is defined.
278 .TP 5
279 IF-NOT-DEFINED variable-name
280 Makes the EXPECT conditions apply only if the specified variable is not
281 defined.
282 .TP 5
283 IN-GROUP tag
284 Requires the EXPECT attribute to be in the specified group tag.
285 .TP 5
286 OF-TYPE tag[,tag,...]
287 Requires the EXPECT attribute to use the specified value tag(s).
288 .TP 5
289 REPEAT-LIMIT number
290 .br
291 Specifies the maximum number of times to repeat. The default value is 1000.
292 .TP 5
293 REPEAT-MATCH
294 .TP 5
295 REPEAT-NO-MATCH
296 Specifies that the current test should be repeated when the EXPECT condition
297 matches or does not match.
298 .TP 5
299 SAME-COUNT-AS attribute-name
300 Requires the EXPECT attribute to have the same number of values as the specified
301 parallel attribute.
302 .TP 5
303 WITH-ALL-VALUES "literal string"
304 Requires that all values of the EXPECT attribute match the literal string. Comparisons are case-sensitive.
305 .TP 5
306 WITH-ALL-VALUES <number
307 .TP 5
308 WITH-ALL-VALUES =number
309 .TP 5
310 WITH-ALL-VALUES >number
311 .TP 5
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.
314 .TP 5
315 WITH-ALL-VALUES "false"
316 .TP 5
317 WITH-ALL-VALUES "true"
318 Requires that all values of the EXPECT attribute match the boolean value given.
319 .TP 5
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.
322 .TP 5
323 WITH-VALUE "literal string"
324 Requires that at least one value of the EXPECT attribute matches the literal string. Comparisons are case-sensitive.
325 .TP 5
326 WITH-VALUE <number
327 .TP 5
328 WITH-VALUE =number
329 .TP 5
330 WITH-VALUE >number
331 .TP 5
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.
334 .TP 5
335 WITH-VALUE "false"
336 .TP 5
337 WITH-VALUE "true"
338 Requires that at least one value of the EXPECT attribute matches the boolean value given.
339 .TP 5
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.
342
343 .SH STATUS PREDICATES
344 The following predicates are understood following the STATUS test directive:
345 .TP 5
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.
348 .TP 5
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.
351 .TP 5
352 IF-DEFINED variable-name
353 Makes the STATUS apply only if the specified variable is defined.
354 .TP 5
355 IF-NOT-DEFINED variable-name
356 Makes the STATUS apply only if the specified variable is not defined.
357 .TP 5
358 REPEAT-LIMIT number
359 .br
360 Specifies the maximum number of times to repeat. The default value is 1000.
361 .TP 5
362 REPEAT-MATCH
363 .TP 5
364 REPEAT-NO-MATCH
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.
367
368 .SH OPERATION CODES
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:
371 .nf
372 Activate-Printer
373 CUPS-Accept-Jobs
374 CUPS-Add-Modify-Class
375 CUPS-Add-Modify-Printer
376 CUPS-Authenticate-Job
377 CUPS-Delete-Class
378 CUPS-Delete-Printer
379 CUPS-Get-Classes
380 CUPS-Get-Default
381 CUPS-Get-Devices
382 CUPS-Get-Document
383 CUPS-Get-PPD
384 CUPS-Get-PPDs
385 CUPS-Get-Printers
386 CUPS-Move-Job
387 CUPS-Reject-Jobs
388 CUPS-Set-Default
389 Cancel-Current-Job
390 Cancel-Job
391 Cancel-Jobs
392 Cancel-My-Jobs
393 Cancel-Subscription
394 Close-Job
395 Create-Job
396 Create-Job-Subscription
397 Create-Printer-Subscription
398 Deactivate-Printer
399 Disable-Printer
400 Enable-Printer
401 Get-Job-Attributes
402 Get-Jobs
403 Get-Notifications
404 Get-Printer-Attributes
405 Get-Printer-Support-Files
406 Get-Printer-Supported-Values
407 Get-Subscription-Attributes
408 Get-Subscriptions
409 Hold-Job
410 Hold-New-Jobs
411 Identify-Printer
412 Pause-Printer
413 Pause-Printer-After-Current-Job
414 Print-Job
415 Print-URI
416 Promote-Job
417 Purge-Jobs
418 Release-Held-New-Jobs
419 Release-Job
420 Renew-Subscription
421 Reprocess-Job
422 Restart-Job
423 Restart-Printer
424 Resubmit-Job
425 Resume-Job
426 Resume-Printer
427 Schedule-Job-After
428 Send-Document
429 Send-Hardcopy-Document
430 Send-Notifications
431 Send-URI
432 Set-Job-Attributes
433 Set-Printer-Attributes
434 Shutdown-Printer
435 Startup-Printer
436 Suspend-Current-Job
437 Validate-Document
438 Validate-Job
439 .fi
440
441 .SH STATUS CODES
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:
444 .nf
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
460 client-error-gone
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
470 client-error-timeout
471 client-error-too-many-subscriptions
472 client-error-uri-scheme-not-supported
473 cups-see-other
474 redirection-other-site
475 server-error-busy
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
486 successful-ok
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
494 .fi
495
496 .SH TAGS
497 Value and group tags correspond to the names from RFC 2911 and other IPP
498 extension specifications. Here are the group tags:
499 .nf
500 event-notification-attributes-tag
501 job-attributes-tag
502 operation-attributes-tag
503 printer-attributes-tag
504 subscription-attributes-tag
505 unsupported-attributes-tag
506 .fi
507 .LP
508 Here are the value tags:
509 .nf
510 admin-define
511 boolean
512 charset
513 collection
514 dateTime
515 default
516 delete-attribute
517 enum
518 integer
519 keyword
520 mimeMediaType
521 nameWithLanguage
522 nameWithoutLanguage
523 naturalLanguage
524 no-value
525 not-settable
526 octetString
527 rangeOfInteger
528 resolution
529 textWithLanguage
530 textWithoutLanguage
531 unknown
532 unsupported
533 uri
534 uriScheme
535 .fi
536
537 .SH VARIABLES
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:
542 .TP 5
543 $$
544 Inserts a single "$" character.
545 .TP 5
546 $ENV[name]
547 Inserts the value of the named environment variable, or an empty string if the
548 environment variable is not defined.
549 .TP 5
550 $filename
551 Inserts the filename provided to \fIipptool\fR with the "-f" option.
552 .TP 5
553 $hostname
554 Inserts the hostname from the URI provided to \fIipptool\fR.
555 .TP 5
556 $job-id
557 Inserts the last job-id value returned in a test response or 0 if no job-id has
558 been seen.
559 .TP 5
560 $job-uri
561 Inserts the last job-uri value returned in a test response or an empty string if
562 no job-uri has been seen.
563 .TP 5
564 $scheme
565 Inserts the scheme from the URI provided to \fIipptool\fR.
566 .TP 5
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.
570 .TP 5
571 $port
572 Inserts the port number from the URI provided to \fIipptool\fR.
573 .TP 5
574 $resource
575 Inserts the resource path from the URI provided to \fIipptool\fR.
576 .TP 5
577 $uri
578 Inserts the URI provided to \fIipptool\fR.
579 .TP 5
580 $user
581 Inserts the current user's login name.
582 .TP 5
583 $username
584 Inserts the username from the URI provided to \fIipptool\fR, if any.
585
586 .SH SEE ALSO
587 \fIipptool(1)\fR,
588 .br
589 http://localhost:631/help
590
591 .SH COPYRIGHT
592 Copyright 2007-2013 by Apple Inc.
593 .\"
594 .\" End of "$Id$".
595 .\"