man/ipptoolfile.man

   1 .\"
   2 .\" "$Id$"
   3 .\"
   4 .\"   ipptoolfile man page for CUPS.
   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 .\"
  14 .TH ipptoolfile 5 "CUPS" "6 August 2010" "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 curley 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 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
  83 INCLUDE "filename"
  84 .TP 5
  85 INCLUDE <filename>
  86 Includes another test file. The first form includes a file relative to the
  87 current test file, while the second form includes a file from the \fIipptool\fR
  88 include directory.
  89 .TP 5
  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
  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
 104 \fIipptool\fR command-line. Support for chunked requests is required for
 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:"
 109 header. This is equivalent to specifying "-l" on the \fIipptool\fR command-line.
 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
 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
 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.
 179 The default is the resource from the URI provided to the \fIipptool\fR program.
 180 .TP 5
 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
 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
 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
 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
 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:
 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
 296     Cancel-Jobs
 297     Cancel-My-Jobs
 298     Cancel-Subscription
 299     Close-Job
 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
 328     Resubmit-Job
 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
 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:
 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
 436 The \fIipptool\fR program maintains a list of variables that can be used in any
 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
 449 Inserts the filename provided to \fIipptool\fR with the "-f" option.
 450 .TP 5
 451 $hostname
 452 Inserts the hostname from the URI provided to \fIipptool\fR.
 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
 463 Inserts the scheme from the URI provided to \fIipptool\fR.
 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
 470 Inserts the port number from the URI provided to \fIipptool\fR.
 471 .TP 5
 472 $resource
 473 Inserts the resource path from the URI provided to \fIipptool\fR.
 474 .TP 5
 475 $uri
 476 Inserts the URI provided to \fIipptool\fR.
 477 .TP 5
 478 $user
 479 Inserts the current user's login name.
 480 .TP 5
 481 $username
 482 Inserts the username from the URI provided to \fIipptool\fR, if any.
 483
 484 .SH SEE ALSO
 485 \fIipptool(1)\fR,
 486 .br
 487 http://localhost:631/help
 488
 489 .SH COPYRIGHT
 490 Copyright 2007-2010 by Apple Inc.
 491 .\"
 492 .\" End of "$Id$".
 493 .\"