man/ipptoolfile.man

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