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