]>
Commit | Line | Data |
---|---|---|
f8b3a85b MS |
1 | .\" |
2 | .\" "$Id$" | |
3 | .\" | |
aaf19ab0 | 4 | .\" ipptoolfile man page for CUPS. |
f8b3a85b | 5 | .\" |
321d8d57 | 6 | .\" Copyright 2010-2011 by Apple Inc. |
f8b3a85b MS |
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 | .\" | |
83e08001 | 14 | .TH ipptoolfile 5 "CUPS" "13 September 2011" "Apple Inc." |
f8b3a85b | 15 | .SH NAME |
aaf19ab0 | 16 | ipptoolfile \- ipptool file format |
f8b3a85b MS |
17 | |
18 | .SH DESCRIPTION | |
aaf19ab0 | 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 curley braces, for example: |
f8b3a85b MS |
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 | |
aaf19ab0 | 29 | GROUP operation-attributes-tag |
f8b3a85b MS |
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 | |
aaf19ab0 | 49 | GROUP operation-attributes-tag |
f8b3a85b MS |
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 | |
aaf19ab0 | 75 | "-d variable-name=value" on the \fIipptool\fR command-line. |
f8b3a85b | 76 | .TP 5 |
321d8d57 MS |
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 | |
030ae6a1 MS |
81 | IGNORE-ERRORS yes |
82 | .TP 5 | |
83 | IGNORE-ERRORS no | |
84 | Specifies whether, by default, \fIipptool\fR will ignore errors and continue with | |
85 | subsequent tests. | |
86 | .TP 5 | |
f8b3a85b MS |
87 | INCLUDE "filename" |
88 | .TP 5 | |
89 | INCLUDE <filename> | |
90 | Includes another test file. The first form includes a file relative to the | |
aaf19ab0 | 91 | current test file, while the second form includes a file from the \fIipptool\fR |
f8b3a85b MS |
92 | include directory. |
93 | .TP 5 | |
321d8d57 MS |
94 | INCLUDE-IF-DEFINED name "filename" |
95 | .TP 5 | |
96 | INCLUDE-IF-DEFINED name <filename> | |
97 | Includes another test file if the named variable is defined. The first form | |
98 | includes a file relative to the current test file, while the second form | |
99 | includes a file from the \fIipptool\fR include directory. | |
100 | .TP 5 | |
101 | INCLUDE-IF-NOT-DEFINED name "filename" | |
102 | .TP 5 | |
103 | INCLUDE-IF-NOT-DEFINED name <filename> | |
104 | Includes another test file if the named variable is not defined. The first form | |
105 | includes a file relative to the current test file, while the second form | |
106 | includes a file from the \fIipptool\fR include directory. | |
107 | .TP 5 | |
030ae6a1 MS |
108 | SKIP-IF-DEFINED variable-name |
109 | .TP 5 | |
110 | SKIP-IF-NOT-DEFINED variable-name | |
111 | Specifies that the remainder of the test file should be skipped when the | |
112 | variable is or is not defined. | |
113 | .TP 5 | |
f8b3a85b MS |
114 | TRANSFER auto |
115 | Specifies that tests will, by default, use "Transfer-Encoding: chunked" for | |
116 | requests with attached files and "Content-Length:" for requests without attached | |
117 | files. | |
118 | .TP 5 | |
119 | TRANSFER chunked | |
120 | Specifies that tests will, by default, use the HTTP/1.1 "Transfer-Encoding: | |
121 | chunked" header. This is the default and is equivalent to specifying "-c" on the | |
aaf19ab0 | 122 | \fIipptool\fR command-line. Support for chunked requests is required for |
f8b3a85b MS |
123 | conformance with all versions of IPP. |
124 | .TP 5 | |
125 | TRANSFER length | |
126 | Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:" | |
aaf19ab0 | 127 | header. This is equivalent to specifying "-l" on the \fIipptool\fR command-line. |
f8b3a85b MS |
128 | Support for content length requests is required for conformance with all |
129 | versions of IPP. | |
130 | .TP 5 | |
131 | VERSION 1.0 | |
132 | .TP 5 | |
133 | VERSION 1.1 | |
134 | .TP 5 | |
135 | VERSION 2.0 | |
136 | .TP 5 | |
137 | VERSION 2.1 | |
138 | .TP 5 | |
139 | VERSION 2.2 | |
140 | Specifies the default IPP version number to use for the tests that follow. | |
141 | ||
142 | .SH TEST DIRECTIVES | |
143 | The following directives are understood in a test: | |
144 | .TP 5 | |
145 | ATTR tag attribute-name value(s) | |
146 | Adds an attribute to the test request. Values are separated by the comma (",") | |
147 | character - escape commas using the "\" character. | |
148 | .TP 5 | |
149 | ATTR collection attribute-name { MEMBER tag member-name value(s) ... } [ ... { ... } ] | |
150 | Adds a collection attribute to the test request. Member attributes follow the | |
151 | same syntax as regular attributes and can themselves be nested collections. | |
152 | Multiple collection values can be supplied as needed. | |
153 | .TP 5 | |
154 | DELAY seconds | |
155 | Specifies a delay before this test will be run. | |
156 | .TP 5 | |
157 | DISPLAY attribute-name | |
158 | Specifies that value of the named attribute should be output as part of the | |
159 | test report. | |
160 | .TP 5 | |
161 | EXPECT attribute-name [ predicate(s) ] | |
162 | .TP 5 | |
163 | EXPECT ?attribute-name predicate(s) | |
164 | .TP 5 | |
165 | EXPECT !attribute-name | |
166 | Specifies that the response must/may/must not include the named attribute. | |
167 | Additional requirements can be added as predicates - see the "EXPECT PREDICATES" | |
168 | section for more information on predicates. | |
169 | .TP 5 | |
170 | FILE filename | |
171 | Specifies a file to include at the end of the request. This is typically used | |
172 | when sending a test print file. | |
173 | .TP 5 | |
174 | GROUP tag | |
175 | Specifies the group tag for subsequent attributes in the request. | |
176 | .TP 5 | |
030ae6a1 MS |
177 | IGNORE-ERRORS yes |
178 | .TP 5 | |
179 | IGNORE-ERRORS no | |
180 | Specifies whether \fIipptool\fR will ignore errors and continue with subsequent | |
181 | tests. | |
182 | .TP 5 | |
f8b3a85b MS |
183 | NAME "literal string" |
184 | Specifies the human-readable name of the test. | |
185 | .TP 5 | |
186 | OPERATION operation-code | |
187 | Specifies the operation to be performed. | |
188 | .TP 5 | |
189 | REQUEST-ID number | |
190 | .TP 5 | |
191 | REQUEST-ID random | |
192 | Specifies the request-id value to use in the request, either an integer or the | |
193 | word "random" to use a randomly generated value (the default). | |
194 | .TP 5 | |
195 | RESOURCE path | |
196 | Specifies an alternate resource path that is used for the HTTP POST request. | |
aaf19ab0 | 197 | The default is the resource from the URI provided to the \fIipptool\fR program. |
f8b3a85b | 198 | .TP 5 |
030ae6a1 MS |
199 | SKIP-IF-DEFINED variable-name |
200 | .TP 5 | |
201 | SKIP-IF-NOT-DEFINED variable-name | |
202 | Specifies that the current test should be skipped when the variable is or is not | |
203 | defined. | |
204 | .TP 5 | |
205 | SKIP-PREVIOUS-ERROR yes | |
206 | .TP 5 | |
207 | SKIP-PREVIOUS-ERROR no | |
208 | Specifies whether \fIipptool\fR will skip the current test if the previous test | |
209 | resulted in an error/failure. | |
210 | .TP 5 | |
f8b3a85b MS |
211 | STATUS status-code [ predicate ] |
212 | Specifies an expected response status-code value. Additional requirements can be | |
213 | added as predicates - see the "STATUS PREDICATES" section for more information | |
214 | on predicates. | |
215 | .TP 5 | |
216 | TRANSFER auto | |
217 | Specifies that this test will use "Transfer-Encoding: chunked" if it has an | |
218 | attached file or "Content-Length:" otherwise. | |
219 | .TP 5 | |
220 | TRANSFER chunked | |
221 | Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked" | |
222 | header. | |
223 | .TP 5 | |
224 | TRANSFER length | |
225 | Specifies that this test will use the HTTP/1.0 "Content-Length:" header. | |
226 | .TP 5 | |
227 | VERSION 1.0 | |
228 | .TP 5 | |
229 | VERSION 1.1 | |
230 | .TP 5 | |
231 | VERSION 2.0 | |
232 | .TP 5 | |
233 | VERSION 2.1 | |
234 | .TP 5 | |
235 | VERSION 2.2 | |
236 | Specifies the IPP version number to use for this test. | |
237 | ||
238 | .SH EXPECT PREDICATES | |
239 | The following predicates are understood following the EXPECT test directive: | |
240 | .TP 5 | |
241 | COUNT number | |
242 | Requires the EXPECT attribute to have the specified number of values. | |
243 | .TP 5 | |
030ae6a1 MS |
244 | DEFINE-MATCH variable-name |
245 | Defines the variable to "1" when the EXPECT condition matches. A side-effect of | |
246 | this predicate is that this EXPECT will never fail a test. | |
247 | .TP 5 | |
248 | DEFINE-NO-MATCH variable-name | |
249 | Defines the variable to "1" when the EXPECT condition does not match. A side- | |
250 | effect of this predicate is that this EXPECT will never fail a test. | |
251 | .TP 5 | |
252 | DEFINE-VALUE variable-name | |
253 | Defines the variable to the value of the attribute when the EXPECT condition | |
254 | matches. | |
255 | .TP 5 | |
f8b3a85b MS |
256 | IF-DEFINED variable-name |
257 | Makes the EXPECT conditions apply only if the specified variable is defined. | |
258 | .TP 5 | |
7cf5915e | 259 | IF-NOT-DEFINED variable-name |
f8b3a85b MS |
260 | Makes the EXPECT conditions apply only if the specified variable is not |
261 | defined. | |
262 | .TP 5 | |
263 | IN-GROUP tag | |
264 | Requires the EXPECT attribute to be in the specified group tag. | |
265 | .TP 5 | |
266 | OF-TYPE tag[,tag,...] | |
267 | Requires the EXPECT attribute to use the specified value tag(s). | |
268 | .TP 5 | |
83e08001 MS |
269 | REPEAT-MATCH |
270 | .TP 5 | |
271 | REPEAT-NO-MATCH | |
272 | Specifies that the current test should be repeated when the EXPECT condition | |
273 | matches or does not match. | |
274 | .TP 5 | |
f8b3a85b MS |
275 | SAME-COUNT-AS attribute-name |
276 | Requires the EXPECT attribute to have the same number of values as the specified | |
277 | parallel attribute. | |
278 | .TP 5 | |
279 | WITH-VALUE "literal string" | |
280 | Requires at least one value of the EXPECT attribute to match the literal string. | |
281 | Comparisons are case-sensitive. | |
282 | .TP 5 | |
283 | WITH-VALUE "/regular expression/" | |
284 | Requires that all values of the EXPECT attribute match the regular expression, | |
285 | which must conform to the POSIX regular expression syntax. | |
286 | Comparisons are case-sensitive. | |
287 | ||
288 | .SH STATUS PREDICATES | |
289 | The following predicates are understood following the STATUS test directive: | |
290 | .TP 5 | |
291 | IF-DEFINED variable-name | |
292 | Makes the STATUS apply only if the specified variable is defined. | |
293 | .TP 5 | |
7cf5915e | 294 | IF-NOT-DEFINED variable-name |
f8b3a85b | 295 | Makes the STATUS apply only if the specified variable is not defined. |
83e08001 MS |
296 | .TP 5 |
297 | REPEAT-MATCH | |
298 | .TP 5 | |
299 | REPEAT-NO-MATCH | |
300 | Specifies that the current test should be repeated when the response status-code | |
301 | matches or does not match the value specified by the STATUS directive. | |
f8b3a85b MS |
302 | |
303 | .SH OPERATION CODES | |
aaf19ab0 MS |
304 | Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from |
305 | RFC 2911 and other IPP extension specifications. Here is a complete list: | |
f8b3a85b MS |
306 | .nf |
307 | Activate-Printer | |
308 | CUPS-Accept-Jobs | |
309 | CUPS-Add-Modify-Class | |
310 | CUPS-Add-Modify-Printer | |
311 | CUPS-Authenticate-Job | |
312 | CUPS-Delete-Class | |
313 | CUPS-Delete-Printer | |
314 | CUPS-Get-Classes | |
315 | CUPS-Get-Default | |
316 | CUPS-Get-Devices | |
317 | CUPS-Get-Document | |
318 | CUPS-Get-PPD | |
319 | CUPS-Get-PPDs | |
320 | CUPS-Get-Printers | |
321 | CUPS-Move-Job | |
322 | CUPS-Reject-Jobs | |
323 | CUPS-Set-Default | |
324 | Cancel-Current-Job | |
325 | Cancel-Job | |
aaf19ab0 MS |
326 | Cancel-Jobs |
327 | Cancel-My-Jobs | |
f8b3a85b | 328 | Cancel-Subscription |
aaf19ab0 | 329 | Close-Job |
f8b3a85b MS |
330 | Create-Job |
331 | Create-Job-Subscription | |
332 | Create-Printer-Subscription | |
333 | Deactivate-Printer | |
334 | Disable-Printer | |
335 | Enable-Printer | |
336 | Get-Job-Attributes | |
337 | Get-Jobs | |
338 | Get-Notifications | |
339 | Get-Printer-Attributes | |
340 | Get-Printer-Support-Files | |
341 | Get-Printer-Supported-Values | |
342 | Get-Subscription-Attributes | |
343 | Get-Subscriptions | |
344 | Hold-Job | |
345 | Hold-New-Jobs | |
346 | Pause-Printer | |
347 | Pause-Printer-After-Current-Job | |
348 | Print-Job | |
349 | Print-URI | |
350 | Promote-Job | |
351 | Purge-Jobs | |
352 | Release-Held-New-Jobs | |
353 | Release-Job | |
354 | Renew-Subscription | |
355 | Reprocess-Job | |
356 | Restart-Job | |
357 | Restart-Printer | |
aaf19ab0 | 358 | Resubmit-Job |
f8b3a85b MS |
359 | Resume-Job |
360 | Resume-Printer | |
361 | Schedule-Job-After | |
362 | Send-Document | |
363 | Send-Notifications | |
364 | Send-URI | |
365 | Set-Job-Attributes | |
366 | Set-Printer-Attributes | |
367 | Shutdown-Printer | |
368 | Startup-Printer | |
369 | Suspend-Current-Job | |
370 | Validate-Job | |
371 | .fi | |
372 | ||
373 | .SH STATUS CODES | |
030ae6a1 MS |
374 | Status codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC |
375 | 2911 and other IPP extension specifications. Here is a complete list: | |
f8b3a85b MS |
376 | .nf |
377 | client-error-attributes-not-settable | |
378 | client-error-attributes-or-values-not-supported | |
379 | client-error-bad-request | |
380 | client-error-charset-not-supported | |
381 | client-error-compression-error | |
382 | client-error-compression-not-supported | |
383 | client-error-conflicting-attributes | |
384 | client-error-document-access-error | |
385 | client-error-document-format-error | |
386 | client-error-document-format-not-supported | |
387 | client-error-forbidden | |
388 | client-error-gone | |
389 | client-error-ignored-all-notifications | |
390 | client-error-ignored-all-subscriptions | |
391 | client-error-not-authenticated | |
392 | client-error-not-authorized | |
393 | client-error-not-found | |
394 | client-error-not-possible | |
395 | client-error-print-support-file-not-found | |
396 | client-error-request-entity-too-large | |
397 | client-error-request-value-too-long | |
398 | client-error-timeout | |
399 | client-error-too-many-subscriptions | |
400 | client-error-uri-scheme-not-supported | |
401 | cups-see-other | |
402 | redirection-other-site | |
403 | server-error-busy | |
404 | server-error-device-error | |
405 | server-error-internal-error | |
406 | server-error-job-canceled | |
407 | server-error-multiple-document-jobs-not-supported | |
408 | server-error-not-accepting-jobs | |
409 | server-error-operation-not-supported | |
410 | server-error-printer-is-deactivated | |
411 | server-error-service-unavailable | |
412 | server-error-temporary-error | |
413 | server-error-version-not-supported | |
414 | successful-ok | |
415 | successful-ok-but-cancel-subscription | |
416 | successful-ok-conflicting-attributes | |
417 | successful-ok-events-complete | |
418 | successful-ok-ignored-notifications | |
419 | successful-ok-ignored-or-substituted-attributes | |
420 | successful-ok-ignored-subscriptions | |
421 | successful-ok-too-many-events | |
422 | .fi | |
423 | ||
424 | .SH TAGS | |
425 | Value and group tags correspond to the names from RFC 2911 and other IPP | |
426 | extension specifications. Here are the group tags: | |
427 | .nf | |
428 | event-notification-attributes-tag | |
429 | job-attributes-tag | |
430 | operation-attributes-tag | |
431 | printer-attributes-tag | |
432 | subscription-attributes-tag | |
433 | unsupported-attributes-tag | |
434 | .fi | |
435 | .LP | |
436 | Here are the value tags: | |
437 | .nf | |
438 | admin-define | |
439 | boolean | |
440 | charset | |
441 | collection | |
442 | dateTime | |
443 | default | |
444 | delete-attribute | |
445 | enum | |
446 | integer | |
447 | keyword | |
448 | mimeMediaType | |
449 | nameWithLanguage | |
450 | nameWithoutLanguage | |
451 | naturalLanguage | |
452 | no-value | |
453 | not-settable | |
454 | octetString | |
455 | rangeOfInteger | |
456 | resolution | |
457 | textWithLanguage | |
458 | textWithoutLanguage | |
459 | unknown | |
460 | unsupported | |
461 | uri | |
462 | uriScheme | |
463 | .fi | |
464 | ||
465 | .SH VARIABLES | |
aaf19ab0 | 466 | The \fIipptool\fR program maintains a list of variables that can be used in any |
f8b3a85b MS |
467 | literal string or attribute value by specifying "$variable-name". Aside from |
468 | variables defined using the "-d" option or "DEFINE" directive, the following | |
469 | pre-defined variables are available: | |
470 | .TP 5 | |
471 | $$ | |
472 | Inserts a single "$" character. | |
473 | .TP 5 | |
474 | $ENV[name] | |
475 | Inserts the value of the named environment variable, or an empty string if the | |
476 | environment variable is not defined. | |
477 | .TP 5 | |
478 | $filename | |
aaf19ab0 | 479 | Inserts the filename provided to \fIipptool\fR with the "-f" option. |
f8b3a85b MS |
480 | .TP 5 |
481 | $hostname | |
aaf19ab0 | 482 | Inserts the hostname from the URI provided to \fIipptool\fR. |
f8b3a85b MS |
483 | .TP 5 |
484 | $job-id | |
485 | Inserts the last job-id value returned in a test response or 0 if no job-id has | |
486 | been seen. | |
487 | .TP 5 | |
488 | $job-uri | |
489 | Inserts the last job-uri value returned in a test response or an empty string if | |
490 | no job-uri has been seen. | |
491 | .TP 5 | |
492 | $scheme | |
aaf19ab0 | 493 | Inserts the scheme from the URI provided to \fIipptool\fR. |
f8b3a85b MS |
494 | .TP 5 |
495 | $notify-subscription-id | |
496 | Inserts the last notify-subscription-id value returnd in a test response or 0 if | |
497 | no notify-subscription-id has been seen. | |
498 | .TP 5 | |
499 | $port | |
aaf19ab0 | 500 | Inserts the port number from the URI provided to \fIipptool\fR. |
f8b3a85b MS |
501 | .TP 5 |
502 | $resource | |
aaf19ab0 | 503 | Inserts the resource path from the URI provided to \fIipptool\fR. |
f8b3a85b MS |
504 | .TP 5 |
505 | $uri | |
aaf19ab0 | 506 | Inserts the URI provided to \fIipptool\fR. |
f8b3a85b MS |
507 | .TP 5 |
508 | $user | |
509 | Inserts the current user's login name. | |
510 | .TP 5 | |
511 | $username | |
aaf19ab0 | 512 | Inserts the username from the URI provided to \fIipptool\fR, if any. |
f8b3a85b MS |
513 | |
514 | .SH SEE ALSO | |
aaf19ab0 | 515 | \fIipptool(1)\fR, |
f8b3a85b MS |
516 | .br |
517 | http://localhost:631/help | |
518 | ||
519 | .SH COPYRIGHT | |
321d8d57 | 520 | Copyright 2007-2011 by Apple Inc. |
f8b3a85b MS |
521 | .\" |
522 | .\" End of "$Id$". | |
523 | .\" |