]>
Commit | Line | Data |
---|---|---|
f8b3a85b | 1 | .\" |
f1dd3a39 | 2 | .\" ipptoolfile man page. |
f8b3a85b | 3 | .\" |
064e50fb | 4 | .\" Copyright © 2010-2021 by Apple Inc. |
f8b3a85b | 5 | .\" |
87030afb MS |
6 | .\" Licensed under Apache License v2.0. See the file "LICENSE" for more |
7 | .\" information. | |
f8b3a85b | 8 | .\" |
90a7970b | 9 | .TH ipptoolfile 5 "CUPS" "12 May 2021" "Apple Inc." |
f8b3a85b | 10 | .SH NAME |
aaf19ab0 | 11 | ipptoolfile \- ipptool file format |
f8b3a85b | 12 | .SH DESCRIPTION |
6b13fa61 MS |
13 | The |
14 | .BR ipptool (1) | |
f1dd3a39 MS |
15 | program accepts free-form plain text files that describe one or more IPP requests. |
16 | Comments start with the "#" character and continue to the end of the line. | |
17 | Each request is enclosed by curly braces, for example: | |
f8b3a85b MS |
18 | .nf |
19 | ||
20 | # This is a comment | |
21 | { | |
22 | # The name of the test | |
f1dd3a39 | 23 | NAME "Print PDF File" |
f8b3a85b MS |
24 | |
25 | # The request to send | |
6b13fa61 | 26 | OPERATION Print\-Job |
f1dd3a39 | 27 | |
6b13fa61 MS |
28 | GROUP operation\-attributes\-tag |
29 | ATTR charset attributes\-charset utf\-8 | |
30 | ATTR language attributes\-natural\-language en | |
31 | ATTR uri printer\-uri $uri | |
32 | ATTR name requesting\-user\-name $user | |
f1dd3a39 MS |
33 | ATTR mimeMediaType document\-format application/pdf |
34 | ||
35 | GROUP job\-attributes\-tag | |
36 | ATTR collection media\-col { | |
37 | # US Letter plain paper from the "main" tray | |
38 | MEMBER collection media\-size { | |
39 | MEMBER integer x\-dimension 21590 | |
40 | MEMBER integer y\-dimension 27940 | |
41 | } | |
42 | MEMBER integer media\-top\-margin 423 | |
43 | MEMBER integer media\-bottom\-margin 423 | |
44 | MEMBER integer media\-left\-margin 423 | |
45 | MEMBER integer media\-right\-margin 423 | |
46 | MEMBER keyword media\-source "main" | |
47 | MEMBER keyword media\-type "stationery" | |
48 | } | |
49 | ||
50 | FILE testfile.pdf | |
f8b3a85b MS |
51 | |
52 | # The response to expect | |
6b13fa61 MS |
53 | STATUS successful\-ok |
54 | EXPECT job\-id OF\-TYPE integer WITH\-VALUE >0 | |
55 | EXPECT job\-uri OF\-TYPE uri | |
f8b3a85b MS |
56 | } |
57 | { | |
58 | # The name of the test | |
f1dd3a39 | 59 | NAME "Wait for Job to Complete" |
f8b3a85b MS |
60 | |
61 | # The request to send | |
6b13fa61 | 62 | OPERATION Get\-Job\-Attributes |
f1dd3a39 | 63 | |
6b13fa61 MS |
64 | GROUP operation\-attributes\-tag |
65 | ATTR charset attributes\-charset utf\-8 | |
66 | ATTR language attributes\-natural\-language en | |
67 | ATTR uri printer\-uri $uri | |
68 | ATTR integer job\-id $job\-id | |
69 | ATTR name requesting\-user\-name $user | |
f8b3a85b MS |
70 | |
71 | # The response to expect | |
6b13fa61 MS |
72 | STATUS successful\-ok |
73 | EXPECT job\-id OF\-TYPE integer WITH\-VALUE $job\-id | |
74 | EXPECT job\-uri OF\-TYPE uri | |
f1dd3a39 | 75 | EXPECT job\-state OF\-TYPE enum WITH\-VALUE >5 REPEAT\-NO\-MATCH |
6b13fa61 | 76 | EXPECT job\-originating\-user\-name OF\-TYPE name WITH\-VALUE "$user" |
f1dd3a39 MS |
77 | |
78 | # Show the job state until completed... | |
79 | DISPLAY job-state | |
80 | DISPLAY job-state-reasons | |
f8b3a85b MS |
81 | } |
82 | .fi | |
6b13fa61 MS |
83 | .SS TOP-LEVEL DIRECTIVES |
84 | The following directives can be used outside of a \fItest\fR: | |
f8b3a85b | 85 | .TP 5 |
6b13fa61 | 86 | \fB{ \fItest \fB}\fR |
f8b3a85b MS |
87 | Defines a test. |
88 | .TP 5 | |
6b13fa61 MS |
89 | \fBDEFINE \fIvariable-name value\fR |
90 | Defines the named variable to the given value. This is equivalent to specifying \fI\-d variable-name=value\fR on the | |
91 | .BR ipptool (8) | |
92 | command-line. | |
f8b3a85b | 93 | .TP 5 |
6b13fa61 MS |
94 | \fBDEFINE\-DEFAULT \fIvariable-name value\fR |
95 | Defines the named variable to the given value if it does not already have a value. | |
321d8d57 | 96 | .TP 5 |
6b13fa61 | 97 | \fBFILE\-ID "\fIidentifier\fB"\fR |
1d47b929 MS |
98 | Specifies an identifier string for the current file. |
99 | .TP 5 | |
6b13fa61 | 100 | \fBIGNORE\-ERRORS yes\fR |
030ae6a1 | 101 | .TP 5 |
6b13fa61 MS |
102 | \fBIGNORE\-ERRORS no\fR |
103 | Specifies whether, by default, | |
104 | .BR ipptool (8) | |
105 | will ignore errors and continue with subsequent tests. | |
030ae6a1 | 106 | .TP 5 |
6b13fa61 | 107 | \fBINCLUDE "\fIfilename\fB"\fR |
f8b3a85b | 108 | .TP 5 |
6b13fa61 MS |
109 | \fBINCLUDE <\fIfilename\fB>\fR |
110 | Includes another test file. The first form includes a file relative to the current test file, while the second form includes a file from the | |
111 | .BR ipptool (8) | |
f8b3a85b MS |
112 | include directory. |
113 | .TP 5 | |
6b13fa61 | 114 | \fBINCLUDE\-IF\-DEFINED \fIname \fB"\fIfilename\fB"\fR |
321d8d57 | 115 | .TP 5 |
6b13fa61 MS |
116 | \fBINCLUDE\-IF\-DEFINED \fIname \fB<\fIfilename\fB>\fR |
117 | Includes another test file if the named variable is defined. The first form includes a file relative to the current test file, while the second form includes a file from the | |
118 | .BR ipptool (8) | |
119 | include directory. | |
321d8d57 | 120 | .TP 5 |
6b13fa61 | 121 | \fBINCLUDE\-IF\-NOT\-DEFINED \fIname \fB"\fIfilename\fB"\fR |
321d8d57 | 122 | .TP 5 |
6b13fa61 MS |
123 | \fBINCLUDE\-IF\-NOT\-DEFINED \fIname \fB<\fIfilename\fB>\fR |
124 | Includes another test file if the named variable is not defined. The first form includes a file relative to the current test file, while the second form includes a file from the | |
125 | .BR ipptool (8) | |
126 | include directory. | |
321d8d57 | 127 | .TP 5 |
6b13fa61 | 128 | \fBSKIP\-IF\-DEFINED \fIvariable-name\fR |
030ae6a1 | 129 | .TP 5 |
6b13fa61 MS |
130 | \fBSKIP\-IF\-NOT\-DEFINED \fIvariable-name\fR |
131 | Specifies that the remainder of the test file should be skipped when the variable is or is not defined. | |
030ae6a1 | 132 | .TP 5 |
6b13fa61 | 133 | \fBSTOP\-AFTER\-INCLUDE\-ERROR no\fR |
9475ec92 | 134 | .TP 5 |
6b13fa61 | 135 | \fBSTOP\-AFTER\-INCLUDE\-ERROR yes\fR |
9475ec92 MS |
136 | Specifies whether tests will be stopped after an error in an included file. |
137 | .TP 5 | |
6b13fa61 MS |
138 | \fBTRANSFER auto\fR |
139 | Specifies that tests will, by default, use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files. | |
f8b3a85b | 140 | .TP 5 |
6b13fa61 MS |
141 | \fBTRANSFER chunked\fR |
142 | Specifies that tests will, by default, use the HTTP/1.1 "Transfer-Encoding: chunked" header. This is the default and is equivalent to specifying \fI\-c\fR on the | |
143 | .BR ipptool (8) | |
144 | command-line. Support for chunked requests is required for conformance with all versions of IPP. | |
f8b3a85b | 145 | .TP 5 |
6b13fa61 MS |
146 | \fBTRANSFER length\fR |
147 | Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:" header. This is equivalent to specifying \fI\-l\fR on the | |
148 | .BR ipptool (8) | |
149 | command-line. Support for content length requests is required for conformance with all versions of IPP. | |
f8b3a85b | 150 | .TP 5 |
6b13fa61 | 151 | \fBVERSION 1.0\fR |
f8b3a85b | 152 | .TP 5 |
6b13fa61 | 153 | \fBVERSION 1.1\fR |
f8b3a85b | 154 | .TP 5 |
6b13fa61 | 155 | \fBVERSION 2.0\fR |
f8b3a85b | 156 | .TP 5 |
6b13fa61 | 157 | \fBVERSION 2.1\fR |
f8b3a85b | 158 | .TP 5 |
6b13fa61 | 159 | \fBVERSION 2.2\fR |
f8b3a85b | 160 | Specifies the default IPP version number to use for the tests that follow. |
6b13fa61 MS |
161 | .SS TEST DIRECTIVES |
162 | The following directives are understood within a \fItest\fR: | |
f8b3a85b | 163 | .TP 5 |
2a75f21b MS |
164 | \fBATTR \fIout-of-band-tag attribute-name\fR |
165 | .TP 5 | |
6b13fa61 | 166 | \fBATTR \fItag attribute-name value(s)\fR |
f1dd3a39 | 167 | Adds an attribute to the test request. |
2a75f21b | 168 | Out-of-band tags (admin-define, delete-attribute, no-value, not-settable, unknown, unsupported) have no value. |
d784ca2f | 169 | Values for other tags are delimited by the comma (",") character - escape commas using the "\\" character. |
f1dd3a39 | 170 | Common attributes and values are listed in the IANA IPP registry - see references below. |
f8b3a85b | 171 | .TP 5 |
6b13fa61 | 172 | \fBATTR collection \fIattribute-name \fB{ MEMBER \fItag member-name value(s) ... \fB}\fR [ \fI... \fB,{ \fI... \fB} \fR] |
f1dd3a39 MS |
173 | Adds a collection attribute to the test request. |
174 | Member attributes follow the same syntax as regular attributes and can themselves be nested collections. | |
175 | Multiple collection values can be supplied as needed, separated by commas. | |
f8b3a85b | 176 | .TP 5 |
6b13fa61 | 177 | \fBCOMPRESSION deflate\fR |
c41769ff | 178 | .TP 5 |
6b13fa61 | 179 | \fBCOMPRESSION gzip\fR |
c41769ff | 180 | .TP 5 |
6b13fa61 MS |
181 | \fBCOMPRESSION none\fR |
182 | Uses the specified compression on the document data following the attributes in a Print-Job or Send-Document request. | |
c41769ff | 183 | .TP 5 |
f1dd3a39 MS |
184 | \fBDELAY \fIseconds\fR[\fI,repeat-seconds\fR] |
185 | Specifies a delay in seconds before this test will be run. | |
186 | If two values are specified, the second value is used as the delay between repeated tests. | |
f8b3a85b | 187 | .TP 5 |
6b13fa61 | 188 | \fBDISPLAY \fIattribute-name\fR |
f8b3a85b MS |
189 | Specifies that value of the named attribute should be output as part of the |
190 | test report. | |
191 | .TP 5 | |
6b13fa61 | 192 | \fBEXPECT \fIattribute-name \fR[ \fIpredicate(s) \fR] |
f8b3a85b | 193 | .TP 5 |
6b13fa61 | 194 | \fBEXPECT ?\fIattribute-name predicate(s)\fR |
f8b3a85b | 195 | .TP 5 |
6b13fa61 MS |
196 | \fBEXPECT !\fIattribute-name\fR |
197 | Specifies that the response must/may/must not include the named attribute. Additional requirements can be added as predicates - see the "EXPECT PREDICATES" section for more information on predicates. Attribute names can specify member attributes by separating the attribute and member names with the forward slash, for example "media\-col/media\-size/x\-dimension". | |
f8b3a85b | 198 | .TP 5 |
e83646d5 MS |
199 | \fBEXPECT-ALL \fIattribute-name \fR[ \fIpredicate(s) \fR] |
200 | .TP 5 | |
201 | \fBEXPECT-ALL ?\fIattribute-name predicate(s)\fR | |
202 | Specifies that the response must/may include the named attribute and that all occurrences of that attribute must match the given predicates. | |
203 | .TP 5 | |
6b13fa61 MS |
204 | \fBFILE filename\fR |
205 | Specifies a file to include at the end of the request. This is typically used when sending a test print file. | |
f8b3a85b | 206 | .TP 5 |
6b13fa61 | 207 | \fBGROUP tag\fR |
f8b3a85b MS |
208 | Specifies the group tag for subsequent attributes in the request. |
209 | .TP 5 | |
6b13fa61 | 210 | \fBIGNORE\-ERRORS yes\fR |
030ae6a1 | 211 | .TP 5 |
6b13fa61 MS |
212 | \fBIGNORE\-ERRORS no\fR |
213 | Specifies whether | |
214 | .BR ipptool (8) | |
215 | will ignore errors and continue with subsequent tests. | |
030ae6a1 | 216 | .TP 5 |
064e50fb MS |
217 | \fBMONITOR-PRINTER-STATE \fR[ \fIprinter-uri \fR] \fB{ EXPECT \fIattribute-name \fR[ \fIpredicate(s) \fR] \fB}\fR |
218 | Specifies printer state monitoring tests to run in parallel with the test operation. | |
219 | The monitoring tests will run until all of the \fBEXPECT\fR conditions are satisfied or the primary test operation has completed, whichever occurs first. | |
220 | .TP 5 | |
6b13fa61 | 221 | \fBNAME "\fIliteral string\fB"\fR |
f8b3a85b MS |
222 | Specifies the human-readable name of the test. |
223 | .TP 5 | |
6b13fa61 | 224 | \fBOPERATION \fIoperation-code\fR |
f8b3a85b MS |
225 | Specifies the operation to be performed. |
226 | .TP 5 | |
9fcdd250 MS |
227 | \fBPAUSE "\fImessage\fB"\fR |
228 | Displays the provided message and waits for the user to press a key to continue. | |
229 | .TP 5 | |
6b13fa61 | 230 | \fBREQUEST\-ID \fInumber\fR\fR |
f8b3a85b | 231 | .TP 5 |
6b13fa61 MS |
232 | \fBREQUEST\-ID random\fR |
233 | Specifies the request-id value to use in the request, either an integer or the word "random" to use a randomly generated value (the default). | |
f8b3a85b | 234 | .TP 5 |
6b13fa61 MS |
235 | \fBRESOURCE \fIpath\fR |
236 | Specifies an alternate resource path that is used for the HTTP POST request. The default is the resource from the URI provided to the | |
237 | .BR ipptool (8) | |
238 | program. | |
f8b3a85b | 239 | .TP 5 |
6b13fa61 | 240 | \fBSKIP\-IF\-DEFINED \fIvariable-name\fR |
030ae6a1 | 241 | .TP 5 |
6b13fa61 MS |
242 | \fBSKIP\-IF\-NOT\-DEFINED \fIvariable-name\fR |
243 | Specifies that the current test should be skipped when the variable is or is not defined. | |
030ae6a1 | 244 | .TP 5 |
6b13fa61 | 245 | \fBSKIP\-PREVIOUS\-ERROR yes\fR |
030ae6a1 | 246 | .TP 5 |
6b13fa61 MS |
247 | \fBSKIP\-PREVIOUS\-ERROR no\fR |
248 | Specifies whether | |
249 | .BR ipptool (8) | |
250 | will skip the current test if the previous test resulted in an error/failure. | |
030ae6a1 | 251 | .TP 5 |
6b13fa61 MS |
252 | \fBSTATUS \fIstatus-code \fR[ \fIpredicate\fR ] |
253 | Specifies an expected response status-code value. Additional requirements can be added as predicates - see the "STATUS PREDICATES" section for more information on predicates. | |
f8b3a85b | 254 | .TP 5 |
6b13fa61 | 255 | \fBTEST\-ID "\fIidentifier\fR" |
1d47b929 MS |
256 | Specifies an identifier string for the current test. |
257 | .TP 5 | |
6b13fa61 MS |
258 | \fBTRANSFER auto\fR |
259 | Specifies that this test will use "Transfer-Encoding: chunked" if it has an attached file or "Content-Length:" otherwise. | |
f8b3a85b | 260 | .TP 5 |
6b13fa61 MS |
261 | \fBTRANSFER chunked\fR |
262 | Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked" header. | |
f8b3a85b | 263 | .TP 5 |
6b13fa61 | 264 | \fBTRANSFER length\fR |
f8b3a85b MS |
265 | Specifies that this test will use the HTTP/1.0 "Content-Length:" header. |
266 | .TP 5 | |
6b13fa61 | 267 | \fBVERSION 1.0\fR |
f8b3a85b | 268 | .TP 5 |
6b13fa61 | 269 | \fBVERSION 1.1\fR |
f8b3a85b | 270 | .TP 5 |
6b13fa61 | 271 | \fBVERSION 2.0\fR |
f8b3a85b | 272 | .TP 5 |
6b13fa61 | 273 | \fBVERSION 2.1\fR |
f8b3a85b | 274 | .TP 5 |
6b13fa61 | 275 | \fBVERSION 2.2\fR |
f8b3a85b | 276 | Specifies the IPP version number to use for this test. |
6b13fa61 MS |
277 | .SS EXPECT PREDICATES |
278 | The following predicates are understood following the \fBEXPECT\fR test directive: | |
f8b3a85b | 279 | .TP 5 |
6b13fa61 MS |
280 | \fBCOUNT \fInumber\fR |
281 | Requires the \fBEXPECT\fR attribute to have the specified number of values. | |
f8b3a85b | 282 | .TP 5 |
6b13fa61 | 283 | \fBDEFINE\-MATCH \fIvariable-name\fR |
90a7970b MS |
284 | Defines the variable to "1" when the \fBEXPECT\fR condition matches. |
285 | A side-effect of this predicate is that this \fBEXPECT\fR will never fail a test. | |
030ae6a1 | 286 | .TP 5 |
6b13fa61 | 287 | \fBDEFINE\-NO\-MATCH \fIvariable-name\fR |
90a7970b MS |
288 | Defines the variable to "1" when the \fBEXPECT\fR condition does not match. |
289 | A side-effect of this predicate is that this \fBEXPECT\fR will never fail a test. | |
030ae6a1 | 290 | .TP 5 |
6b13fa61 | 291 | \fBDEFINE\-VALUE \fIvariable-name\fR |
90a7970b MS |
292 | Defines the variable to the value of the attribute when the \fBEXPECT\fR condition matches. |
293 | A side-effect of this predicate is that this \fBEXPECT\fR will never fail a test. | |
294 | .TP 5 | |
295 | \fBDISPLAY\-MATCH \fI"message"\fR | |
296 | Displays the specified message when the \fBEXPECT\fR condition matches. | |
030ae6a1 | 297 | .TP 5 |
6b13fa61 MS |
298 | \fBIF\-DEFINED \fIvariable-name\fR |
299 | Makes the \fBEXPECT\fR conditions apply only if the specified variable is defined. | |
f8b3a85b | 300 | .TP 5 |
6b13fa61 MS |
301 | \fBIF\-NOT\-DEFINED \fIvariable-name\fR |
302 | Makes the \fBEXPECT\fR conditions apply only if the specified variable is not defined. | |
f8b3a85b | 303 | .TP 5 |
6b13fa61 MS |
304 | \fBIN\-GROUP \fItag\fR |
305 | Requires the \fBEXPECT\fR attribute to be in the specified group tag. | |
f8b3a85b | 306 | .TP 5 |
064e50fb | 307 | \fBOF\-TYPE \fItag[(limits)|tag|...]\fR |
6b13fa61 | 308 | Requires the \fBEXPECT\fR attribute to use one of the specified value tag(s). |
064e50fb | 309 | Most value tags also support the specification of limits in parenthesis, for example "name(42)" would allow nameWith/WithoutLanguage strings up to 42 octets in length, "name(4:MAX)" would allow nameWith/WithoutLanguage strings between 4 and 255 octets in length, and "integer(-273:MAX)" would allow integers between -273 and 2147483647. |
f8b3a85b | 310 | .TP 5 |
6b13fa61 | 311 | \fBREPEAT\-LIMIT \fInumber\fR |
a29fd7dd | 312 | .br |
6b13fa61 | 313 | Specifies the maximum number of times to repeat if the \fBREPEAT-MATCH\fR or \fBREPEAT-NO-MATCH\fR predicate is specified. The default value is 1000. |
a29fd7dd | 314 | .TP 5 |
6b13fa61 | 315 | \fBREPEAT\-MATCH\fR |
83e08001 | 316 | .TP 5 |
6b13fa61 MS |
317 | \fBREPEAT\-NO\-MATCH\fR |
318 | Specifies that the current test should be repeated when the \fBEXPECT\fR condition matches or does not match. | |
83e08001 | 319 | .TP 5 |
6b13fa61 MS |
320 | \fBSAME\-COUNT\-AS \fIattribute-name\fR |
321 | Requires the \fBEXPECT\fR attribute to have the same number of values as the specified parallel attribute. | |
f8b3a85b | 322 | .TP 5 |
6b13fa61 | 323 | \fBWITH\-ALL\-HOSTNAMES "\fIliteral string\fB"\fR |
890a10b7 | 324 | .TP 5 |
6b13fa61 | 325 | \fBWITH\-ALL\-HOSTNAMES "/\fIregular expression\fB/"\fR |
890a10b7 MS |
326 | Requires that all URI values contain a matching hostname. |
327 | .TP 5 | |
6b13fa61 | 328 | \fBWITH\-ALL\-RESOURCES "\fIliteral string\fB"\fR |
890a10b7 | 329 | .TP 5 |
6b13fa61 | 330 | \fBWITH\-ALL\-RESOURCES "/\fIregular expression\fB/"\fR |
890a10b7 MS |
331 | Requires that all URI values contain a matching resource (including leading /). |
332 | .TP 5 | |
6b13fa61 | 333 | \fBWITH\-ALL\-SCHEMES "\fIliteral string\fB"\fR |
890a10b7 | 334 | .TP 5 |
6b13fa61 | 335 | \fBWITH\-ALL-SCHEMES "/\fIregular expression\fB/"\fR |
890a10b7 MS |
336 | Requires that all URI values contain a matching scheme. |
337 | .TP 5 | |
6b13fa61 MS |
338 | \fBWITH\-ALL\-VALUES "\fIliteral string\fB"\fR |
339 | Requires that all values of the \fBEXPECT\fR attribute match the literal string. Comparisons are case-sensitive. | |
82cc1f9a | 340 | .TP 5 |
6b13fa61 | 341 | \fBWITH\-ALL\-VALUES <\fInumber\fR |
82cc1f9a | 342 | .TP 5 |
6b13fa61 | 343 | \fBWITH\-ALL\-VALUES =\fInumber\fR |
82cc1f9a | 344 | .TP 5 |
6b13fa61 | 345 | \fBWITH\-ALL\-VALUES >\fInumber\fR |
82cc1f9a | 346 | .TP 5 |
6b13fa61 MS |
347 | \fBWITH\-ALL\-VALUES \fInumber\fR[\fI,...,number\fR] |
348 | Requires that all values of the \fBEXPECT\fR attribute match the number(s) or numeric comparison. When comparing rangeOfInteger values, the "<" and ">" operators only check the upper bound of the range. | |
82cc1f9a | 349 | .TP 5 |
6b13fa61 | 350 | \fBWITH\-ALL\-VALUES "false"\fR |
82cc1f9a | 351 | .TP 5 |
6b13fa61 MS |
352 | \fBWITH\-ALL\-VALUES "true"\fR |
353 | Requires that all values of the \fBEXPECT\fR attribute match the boolean value given. | |
82cc1f9a | 354 | .TP 5 |
6b13fa61 | 355 | \fBWITH\-ALL\-VALUES "/\fIregular expression\fB/"\fR |
064e50fb MS |
356 | Requires that all values of the \fBEXPECT\fR attribute match the regular expression, which must conform to the POSIX regular expression syntax. |
357 | Comparisons are case-sensitive. | |
358 | .TP 5 | |
359 | \fBWITH\-DISTINCT\-VALUES\fR | |
360 | Requires that all values of the \fBEXPECT\fR attribute are unique. | |
361 | Comparisons are case-sensitive. | |
9a13f253 | 362 | Only charset, collection, enum, integer, keyword, mimeMediaType, naturalLanguage, rangeOfInteger, resolution, uriScheme attributes support this predicate. |
82cc1f9a | 363 | .TP 5 |
6b13fa61 | 364 | \fBWITH\-HOSTNAME "\fIliteral string\fB"\fR |
890a10b7 | 365 | .TP 5 |
6b13fa61 | 366 | \fBWITH\-HOSTNAME "/\fIregular expression\fB/"\fR |
890a10b7 MS |
367 | Requires that at least one URI value contains a matching hostname. |
368 | .TP 5 | |
6b13fa61 | 369 | \fBWITH\-RESOURCE "\fIliteral string\fB"\fR |
890a10b7 | 370 | .TP 5 |
6b13fa61 | 371 | \fBWITH\-RESOURCE "/\fIregular expression\fB/"\fR |
890a10b7 MS |
372 | Requires that at least one URI value contains a matching resource (including leading /). |
373 | .TP 5 | |
6b13fa61 | 374 | \fBWITH\-SCHEME "\fIliteral string\fB"\fR |
890a10b7 | 375 | .TP 5 |
6b13fa61 | 376 | \fBWITH\-SCHEME "/\fIregular expression\fB/"\fR |
890a10b7 MS |
377 | Requires that at least one URI value contains a matching scheme. |
378 | .TP 5 | |
6b13fa61 MS |
379 | \fBWITH\-VALUE "\fIliteral string\fB"\fR |
380 | Requires that at least one value of the \fBEXPECT\fR attribute matches the literal string. Comparisons are case-sensitive. | |
82cc1f9a | 381 | .TP 5 |
6b13fa61 | 382 | \fBWITH\-VALUE <\fInumber\fR |
82cc1f9a | 383 | .TP 5 |
6b13fa61 | 384 | \fBWITH\-VALUE =\fInumber\fR |
82cc1f9a | 385 | .TP 5 |
6b13fa61 | 386 | \fBWITH\-VALUE >\fInumber\fR |
82cc1f9a | 387 | .TP 5 |
6b13fa61 MS |
388 | \fBWITH\-VALUE \fInumber\fR[\fI,...,number\fR] |
389 | Requires that at least one value of the \fBEXPECT\fR attribute matches the number(s) or numeric comparison. When comparing rangeOfInteger values, the "<" and ">" operators only check the upper bound of the range. | |
82cc1f9a | 390 | .TP 5 |
6b13fa61 | 391 | \fBWITH\-VALUE "false"\fR |
82cc1f9a | 392 | .TP 5 |
6b13fa61 MS |
393 | \fBWITH\-VALUE "true"\fR |
394 | Requires that at least one value of the \fBEXPECT\fR attribute matches the boolean value given. | |
f8b3a85b | 395 | .TP 5 |
6b13fa61 MS |
396 | \fBWITH\-VALUE "/\fIregular expression\fB/"\fR |
397 | Requires that at least one value of the \fBEXPECT\fR attribute matches the regular expression, which must conform to the POSIX regular expression syntax. Comparisons are case-sensitive. | |
a21c36fa MS |
398 | .TP 5 |
399 | \fBWITH\-VALUE\-FROM \fIattribute-name\fR | |
400 | Requires that the value(s) of the \fBEXPECT\fR attribute matches the value(s) in the specified attribute. | |
401 | For example, "EXPECT job\-sheets WITH\-VALUE\-FROM job\-sheets\-supported" requires that the "job\-sheets" value is listed as a value of the "job\-sheets\-supported" attribute. | |
6b13fa61 MS |
402 | .SS STATUS PREDICATES |
403 | The following predicates are understood following the \fBSTATUS\fR test directive: | |
f8b3a85b | 404 | .TP 5 |
6b13fa61 MS |
405 | \fBDEFINE\-MATCH \fIvariable-name\fR |
406 | Defines the variable to "1" when the \fBSTATUS\fR matches. A side-effect of this predicate is that this \fBSTATUS\fR will never fail a test. | |
0fa6c7fa | 407 | .TP 5 |
6b13fa61 MS |
408 | \fBDEFINE\-NO\-MATCH \fIvariable-name\fR |
409 | Defines the variable to "1" when the \fBSTATUS\fR does not match. A side-effect of this predicate is that this \fBSTATUS\fR will never fail a test. | |
0fa6c7fa | 410 | .TP 5 |
6b13fa61 MS |
411 | \fBIF\-DEFINED \fIvariable-name\fR |
412 | Makes the \fBSTATUS\fR apply only if the specified variable is defined. | |
f8b3a85b | 413 | .TP 5 |
6b13fa61 MS |
414 | \fBIF\-NOT\-DEFINED \fIvariable-name\fR |
415 | Makes the \fBSTATUS\fR apply only if the specified variable is not defined. | |
83e08001 | 416 | .TP 5 |
6b13fa61 | 417 | \fBREPEAT\-LIMIT \fInumber\fR |
a29fd7dd MS |
418 | .br |
419 | Specifies the maximum number of times to repeat. The default value is 1000. | |
420 | .TP 5 | |
6b13fa61 | 421 | \fBREPEAT\-MATCH\fR |
83e08001 | 422 | .TP 5 |
6b13fa61 MS |
423 | \fBREPEAT\-NO\-MATCH\fR |
424 | Specifies that the current test should be repeated when the response status-code matches or does not match the value specified by the STATUS directive. | |
425 | .SS OPERATION CODES | |
2a75f21b | 426 | Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC 8011 and other IPP extension specifications. Here is a complete list of names supported by |
6b13fa61 | 427 | .BR ipptool (8): |
f8b3a85b | 428 | .nf |
f8b3a85b | 429 | |
6b13fa61 MS |
430 | Activate\-Printer |
431 | CUPS\-Accept\-Jobs | |
432 | CUPS\-Add\-Modify\-Class | |
433 | CUPS\-Add\-Modify\-Printer | |
434 | CUPS\-Authenticate\-Job | |
435 | CUPS\-Delete\-Class | |
436 | CUPS\-Delete\-Printer | |
437 | CUPS\-Get\-Classes | |
438 | CUPS\-Get\-Default | |
439 | CUPS\-Get\-Devices | |
440 | CUPS\-Get\-Document | |
441 | CUPS\-Get\-PPD | |
442 | CUPS\-Get\-PPDs | |
443 | CUPS\-Get\-Printers | |
444 | CUPS\-Move\-Job | |
445 | CUPS\-Reject\-Jobs | |
446 | CUPS\-Set\-Default | |
447 | Cancel\-Current\-Job | |
448 | Cancel\-Job | |
449 | Cancel\-Jobs | |
450 | Cancel\-My\-Jobs | |
451 | Cancel\-Subscription | |
452 | Close\-Job | |
453 | Create\-Job | |
454 | Create\-Job\-Subscriptions | |
455 | Create\-Printer\-Subscriptions | |
456 | Deactivate\-Printer | |
457 | Disable\-Printer | |
458 | Enable\-Printer | |
459 | Get\-Job\-Attributes | |
460 | Get\-Jobs | |
461 | Get\-Notifications | |
462 | Get\-Printer\-Attributes | |
463 | Get\-Printer\-Support\-Files | |
464 | Get\-Printer\-Supported\-Values | |
465 | Get\-Subscription\-Attributes | |
466 | Get\-Subscriptions | |
467 | Hold\-Job | |
468 | Hold\-New\-Jobs | |
469 | Identify\-Printer | |
470 | Pause\-Printer | |
471 | Pause\-Printer\-After\-Current\-Job | |
472 | Print\-Job | |
473 | Print\-URI | |
474 | Promote\-Job | |
475 | Purge\-Jobs | |
476 | Release\-Held\-New\-Jobs | |
477 | Release\-Job | |
478 | Renew\-Subscription | |
479 | Reprocess\-Job | |
480 | Restart\-Job | |
481 | Restart\-Printer | |
482 | Resubmit\-Job | |
483 | Resume\-Job | |
484 | Resume\-Printer | |
485 | Schedule\-Job\-After | |
486 | Send\-Document | |
487 | Send\-Hardcopy\-Document | |
488 | Send\-Notifications | |
489 | Send\-URI | |
490 | Set\-Job\-Attributes | |
491 | Set\-Printer\-Attributes | |
492 | Shutdown\-Printer | |
493 | Startup\-Printer | |
494 | Suspend\-Current\-Job | |
495 | Validate\-Document | |
496 | Validate\-Job | |
f8b3a85b | 497 | .fi |
6b13fa61 | 498 | .SS STATUS CODES |
2a75f21b | 499 | Status codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC 8011 and other IPP extension specifications. Here is a complete list of the names supported by |
6b13fa61 MS |
500 | .BR ipptool (8): |
501 | .nf | |
f8b3a85b | 502 | |
6b13fa61 MS |
503 | client\-error\-account\-authorization\-failed |
504 | client\-error\-account\-closed | |
505 | client\-error\-account\-info\-needed | |
506 | client\-error\-account\-limit\-reached | |
507 | client\-error\-attributes\-not\-settable | |
508 | client\-error\-attributes\-or\-values\-not\-supported | |
509 | client\-error\-bad\-request | |
510 | client\-error\-charset\-not\-supported | |
511 | client\-error\-compression\-error | |
512 | client\-error\-compression\-not\-supported | |
513 | client\-error\-conflicting\-attributes | |
514 | client\-error\-document\-access\-error | |
515 | client\-error\-document\-format\-error | |
516 | client\-error\-document\-format\-not\-supported | |
517 | client\-error\-document\-password\-error | |
518 | client\-error\-document\-permission\-error | |
519 | client\-error\-document\-security\-error | |
520 | client\-error\-document\-unprintable\-error | |
521 | client\-error\-forbidden | |
522 | client\-error\-gone | |
523 | client\-error\-ignored\-all\-notifications | |
524 | client\-error\-ignored\-all\-subscriptions | |
525 | client\-error\-not\-authenticated | |
526 | client\-error\-not\-authorized | |
527 | client\-error\-not\-found | |
528 | client\-error\-not\-possible | |
529 | client\-error\-print\-support\-file\-not\-found | |
530 | client\-error\-request\-entity\-too\-large | |
531 | client\-error\-request\-value\-too\-long | |
532 | client\-error\-timeout | |
533 | client\-error\-too\-many\-subscriptions | |
534 | client\-error\-uri\-scheme\-not\-supported | |
535 | cups\-error\-account\-authorization\-failed | |
536 | cups\-error\-account\-closed | |
537 | cups\-error\-account\-info\-needed | |
538 | cups\-error\-account\-limit\-reached | |
539 | cups\-see\-other | |
540 | redirection\-other\-site | |
541 | server\-error\-busy | |
542 | server\-error\-device\-error | |
543 | server\-error\-internal\-error | |
544 | server\-error\-job\-canceled | |
545 | server\-error\-multiple\-document\-jobs\-not\-supported | |
546 | server\-error\-not\-accepting\-jobs | |
547 | server\-error\-operation\-not\-supported | |
548 | server\-error\-printer\-is\-deactivated | |
549 | server\-error\-service\-unavailable | |
550 | server\-error\-temporary\-error | |
551 | server\-error\-version\-not\-supported | |
552 | successful\-ok | |
553 | successful\-ok\-but\-cancel\-subscription | |
554 | successful\-ok\-conflicting\-attributes | |
555 | successful\-ok\-events\-complete | |
556 | successful\-ok\-ignored\-notifications | |
557 | successful\-ok\-ignored\-or\-substituted\-attributes | |
558 | successful\-ok\-ignored\-subscriptions | |
559 | successful\-ok\-too\-many\-events | |
560 | .fi | |
561 | .SS TAGS | |
2a75f21b | 562 | Value and group tags correspond to the names from RFC 8011 and other IPP extension specifications. Here are the group tags: |
f8b3a85b | 563 | .nf |
6b13fa61 MS |
564 | |
565 | document\-attributes\-tag | |
566 | event\-notification\-attributes\-tag | |
567 | job\-attributes\-tag | |
568 | operation\-attributes\-tag | |
569 | printer\-attributes\-tag | |
570 | subscription\-attributes\-tag | |
571 | unsupported\-attributes\-tag | |
f8b3a85b MS |
572 | .fi |
573 | .LP | |
574 | Here are the value tags: | |
575 | .nf | |
6b13fa61 MS |
576 | |
577 | admin\-define | |
f8b3a85b MS |
578 | boolean |
579 | charset | |
580 | collection | |
581 | dateTime | |
582 | default | |
6b13fa61 | 583 | delete\-attribute |
f8b3a85b MS |
584 | enum |
585 | integer | |
586 | keyword | |
587 | mimeMediaType | |
588 | nameWithLanguage | |
589 | nameWithoutLanguage | |
590 | naturalLanguage | |
6b13fa61 MS |
591 | no\-value |
592 | not\-settable | |
f8b3a85b MS |
593 | octetString |
594 | rangeOfInteger | |
595 | resolution | |
596 | textWithLanguage | |
597 | textWithoutLanguage | |
598 | unknown | |
599 | unsupported | |
600 | uri | |
601 | uriScheme | |
602 | .fi | |
6b13fa61 MS |
603 | .SS VARIABLES |
604 | The | |
605 | .BR ipptool (8) | |
606 | program maintains a list of variables that can be used in any literal string or attribute value by specifying "\fI$variable-name\fR". Aside from variables defined using the \fI-d\fR option or \fBDEFINE\fR directive, the following pre-defined variables are available: | |
f8b3a85b | 607 | .TP 5 |
6b13fa61 | 608 | \fB$$\fR |
f8b3a85b MS |
609 | Inserts a single "$" character. |
610 | .TP 5 | |
6b13fa61 MS |
611 | \fB$ENV[\fIname\fB]\fR |
612 | Inserts the value of the named environment variable, or an empty string if the environment variable is not defined. | |
f8b3a85b | 613 | .TP 5 |
c8d7d4bf MS |
614 | \fB$date-current\fR |
615 | Inserts the current date and time using the ISO-8601 format ("yyyy-mm-ddThh:mm:ssZ"). | |
616 | .TP 5 | |
617 | \fB$date-start\fR | |
618 | Inserts the starting date and time using the ISO-8601 format ("yyyy-mm-ddThh:mm:ssZ"). | |
619 | .TP 5 | |
6b13fa61 MS |
620 | \fB$filename\fR |
621 | Inserts the filename provided to | |
622 | .BR ipptool (8) | |
623 | with the \fI-f\fR option. | |
f8b3a85b | 624 | .TP 5 |
6b13fa61 MS |
625 | \fB$filetype\fR |
626 | Inserts the MIME media type for the filename provided to | |
627 | .BR ipptool (8) | |
628 | with the \fI-f\fR option. | |
f8b3a85b | 629 | .TP 5 |
6b13fa61 MS |
630 | \fB$hostname\fR |
631 | Inserts the hostname from the URI provided to | |
632 | .BR ipptool (8). | |
f8b3a85b | 633 | .TP 5 |
6b13fa61 MS |
634 | \fB$job\-id\fR |
635 | Inserts the last "job\-id" attribute value returned in a test response or 0 if no "job\-id" attribute has been seen. | |
f8b3a85b | 636 | .TP 5 |
6b13fa61 MS |
637 | \fB$job\-uri\fR |
638 | Inserts the last "job\-uri" attribute value returned in a test response or an empty string if no "job\-uri" attribute has been seen. | |
f8b3a85b | 639 | .TP 5 |
6b13fa61 MS |
640 | \fB$notify\-subscription\-id\fR |
641 | Inserts the last "notify\-subscription\-id" attribute value returned in a test response or 0 if no "notify\-subscription\-id" attribute has been seen. | |
f8b3a85b | 642 | .TP 5 |
6b13fa61 MS |
643 | \fB$port\fR |
644 | Inserts the port number from the URI provided to | |
645 | .BR ipptool (8). | |
f8b3a85b | 646 | .TP 5 |
6b13fa61 MS |
647 | \fB$resource\fR |
648 | Inserts the resource path from the URI provided to | |
649 | .BR ipptool (8). | |
f8b3a85b | 650 | .TP 5 |
6b13fa61 MS |
651 | \fB$scheme\fR |
652 | Inserts the scheme from the URI provided to | |
653 | .BR ipptool (8). | |
f8b3a85b | 654 | .TP 5 |
6b13fa61 MS |
655 | \fB$uri\fR |
656 | Inserts the URI provided to | |
657 | .BR ipptool (8). | |
f8b3a85b | 658 | .TP 5 |
6b13fa61 MS |
659 | \fB$uriuser\fR |
660 | Inserts the username from the URI provided to | |
661 | .BR ipptool (8), | |
662 | if any. | |
663 | .TP 5 | |
664 | \fB$user\fR | |
665 | Inserts the current user's login name. | |
f8b3a85b | 666 | .SH SEE ALSO |
6b13fa61 | 667 | .BR ipptool (1), |
6b13fa61 MS |
668 | IANA IPP Registry (http://www.iana.org/assignments/ipp-registrations), |
669 | PWG Internet Printing Protocol Workgroup (http://www.pwg.org/ipp), | |
f1dd3a39 | 670 | RFC 8011 (http://tools.ietf.org/html/rfc8011) |
f8b3a85b | 671 | .SH COPYRIGHT |
064e50fb | 672 | Copyright \[co] 2007-2021 by Apple Inc. |