man/ipptoolfile.man

   1 .\"
   2 .\" "$Id$"
   3 .\"
   4 .\"   ipptoolfile man page for CUPS.
   5 .\"
   6 .\"   Copyright 2010-2013 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" "10 January 2013" "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 curly 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 DEFINE-MATCH variable-name
 336 Defines the variable to "1" when the STATUS matches. A side-effect of this predicate is that this STATUS will never fail a test.
 337 .TP 5
 338 DEFINE-NO-MATCH variable-name
 339 Defines the variable to "1" when the STATUS does not match. A side-effect of this predicate is that this STATUS will never fail a test.
 340 .TP 5
 341 IF-DEFINED variable-name
 342 Makes the STATUS apply only if the specified variable is defined.
 343 .TP 5
 344 IF-NOT-DEFINED variable-name
 345 Makes the STATUS apply only if the specified variable is not defined.
 346 .TP 5
 347 REPEAT-LIMIT number
 348 .br
 349 Specifies the maximum number of times to repeat. The default value is 1000.
 350 .TP 5
 351 REPEAT-MATCH
 352 .TP 5
 353 REPEAT-NO-MATCH
 354 Specifies that the current test should be repeated when the response status-code
 355 matches or does not match the value specified by the STATUS directive.
 356
 357 .SH OPERATION CODES
 358 Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from
 359 RFC 2911 and other IPP extension specifications. Here is a complete list:
 360 .nf
 361     Activate-Printer
 362     CUPS-Accept-Jobs
 363     CUPS-Add-Modify-Class
 364     CUPS-Add-Modify-Printer
 365     CUPS-Authenticate-Job
 366     CUPS-Delete-Class
 367     CUPS-Delete-Printer
 368     CUPS-Get-Classes
 369     CUPS-Get-Default
 370     CUPS-Get-Devices
 371     CUPS-Get-Document
 372     CUPS-Get-PPD
 373     CUPS-Get-PPDs
 374     CUPS-Get-Printers
 375     CUPS-Move-Job
 376     CUPS-Reject-Jobs
 377     CUPS-Set-Default
 378     Cancel-Current-Job
 379     Cancel-Job
 380     Cancel-Jobs
 381     Cancel-My-Jobs
 382     Cancel-Subscription
 383     Close-Job
 384     Create-Job
 385     Create-Job-Subscription
 386     Create-Printer-Subscription
 387     Deactivate-Printer
 388     Disable-Printer
 389     Enable-Printer
 390     Get-Job-Attributes
 391     Get-Jobs
 392     Get-Notifications
 393     Get-Printer-Attributes
 394     Get-Printer-Support-Files
 395     Get-Printer-Supported-Values
 396     Get-Subscription-Attributes
 397     Get-Subscriptions
 398     Hold-Job
 399     Hold-New-Jobs
 400     Identify-Printer
 401     Pause-Printer
 402     Pause-Printer-After-Current-Job
 403     Print-Job
 404     Print-URI
 405     Promote-Job
 406     Purge-Jobs
 407     Release-Held-New-Jobs
 408     Release-Job
 409     Renew-Subscription
 410     Reprocess-Job
 411     Restart-Job
 412     Restart-Printer
 413     Resubmit-Job
 414     Resume-Job
 415     Resume-Printer
 416     Schedule-Job-After
 417     Send-Document
 418     Send-Notifications
 419     Send-URI
 420     Set-Job-Attributes
 421     Set-Printer-Attributes
 422     Shutdown-Printer
 423     Startup-Printer
 424     Suspend-Current-Job
 425     Validate-Document
 426     Validate-Job
 427 .fi
 428
 429 .SH STATUS CODES
 430 Status codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC
 431 2911 and other IPP extension specifications. Here is a complete list:
 432 .nf
 433     client-error-attributes-not-settable
 434     client-error-attributes-or-values-not-supported
 435     client-error-bad-request
 436     client-error-charset-not-supported
 437     client-error-compression-error
 438     client-error-compression-not-supported
 439     client-error-conflicting-attributes
 440     client-error-document-access-error
 441     client-error-document-format-error
 442     client-error-document-format-not-supported
 443     client-error-document-password-error
 444     client-error-document-permission-error
 445     client-error-document-security-error
 446     client-error-document-unprintable-error
 447     client-error-forbidden
 448     client-error-gone
 449     client-error-ignored-all-notifications
 450     client-error-ignored-all-subscriptions
 451     client-error-not-authenticated
 452     client-error-not-authorized
 453     client-error-not-found
 454     client-error-not-possible
 455     client-error-print-support-file-not-found
 456     client-error-request-entity-too-large
 457     client-error-request-value-too-long
 458     client-error-timeout
 459     client-error-too-many-subscriptions
 460     client-error-uri-scheme-not-supported
 461     cups-see-other
 462     redirection-other-site
 463     server-error-busy
 464     server-error-device-error
 465     server-error-internal-error
 466     server-error-job-canceled
 467     server-error-multiple-document-jobs-not-supported
 468     server-error-not-accepting-jobs
 469     server-error-operation-not-supported
 470     server-error-printer-is-deactivated
 471     server-error-service-unavailable
 472     server-error-temporary-error
 473     server-error-version-not-supported
 474     successful-ok
 475     successful-ok-but-cancel-subscription
 476     successful-ok-conflicting-attributes
 477     successful-ok-events-complete
 478     successful-ok-ignored-notifications
 479     successful-ok-ignored-or-substituted-attributes
 480     successful-ok-ignored-subscriptions
 481     successful-ok-too-many-events
 482 .fi
 483
 484 .SH TAGS
 485 Value and group tags correspond to the names from RFC 2911 and other IPP
 486 extension specifications. Here are the group tags:
 487 .nf
 488     event-notification-attributes-tag
 489     job-attributes-tag
 490     operation-attributes-tag
 491     printer-attributes-tag
 492     subscription-attributes-tag
 493     unsupported-attributes-tag
 494 .fi
 495 .LP
 496 Here are the value tags:
 497 .nf
 498     admin-define
 499     boolean
 500     charset
 501     collection
 502     dateTime
 503     default
 504     delete-attribute
 505     enum
 506     integer
 507     keyword
 508     mimeMediaType
 509     nameWithLanguage
 510     nameWithoutLanguage
 511     naturalLanguage
 512     no-value
 513     not-settable
 514     octetString
 515     rangeOfInteger
 516     resolution
 517     textWithLanguage
 518     textWithoutLanguage
 519     unknown
 520     unsupported
 521     uri
 522     uriScheme
 523 .fi
 524
 525 .SH VARIABLES
 526 The \fIipptool\fR program maintains a list of variables that can be used in any
 527 literal string or attribute value by specifying "$variable-name". Aside from
 528 variables defined using the "-d" option or "DEFINE" directive, the following
 529 pre-defined variables are available:
 530 .TP 5
 531 $$
 532 Inserts a single "$" character.
 533 .TP 5
 534 $ENV[name]
 535 Inserts the value of the named environment variable, or an empty string if the
 536 environment variable is not defined.
 537 .TP 5
 538 $filename
 539 Inserts the filename provided to \fIipptool\fR with the "-f" option.
 540 .TP 5
 541 $hostname
 542 Inserts the hostname from the URI provided to \fIipptool\fR.
 543 .TP 5
 544 $job-id
 545 Inserts the last job-id value returned in a test response or 0 if no job-id has
 546 been seen.
 547 .TP 5
 548 $job-uri
 549 Inserts the last job-uri value returned in a test response or an empty string if
 550 no job-uri has been seen.
 551 .TP 5
 552 $scheme
 553 Inserts the scheme from the URI provided to \fIipptool\fR.
 554 .TP 5
 555 $notify-subscription-id
 556 Inserts the last notify-subscription-id value returned in a test response or 0 if
 557 no notify-subscription-id has been seen.
 558 .TP 5
 559 $port
 560 Inserts the port number from the URI provided to \fIipptool\fR.
 561 .TP 5
 562 $resource
 563 Inserts the resource path from the URI provided to \fIipptool\fR.
 564 .TP 5
 565 $uri
 566 Inserts the URI provided to \fIipptool\fR.
 567 .TP 5
 568 $user
 569 Inserts the current user's login name.
 570 .TP 5
 571 $username
 572 Inserts the username from the URI provided to \fIipptool\fR, if any.
 573
 574 .SH SEE ALSO
 575 \fIipptool(1)\fR,
 576 .br
 577 http://localhost:631/help
 578
 579 .SH COPYRIGHT
 580 Copyright 2007-2013 by Apple Inc.
 581 .\"
 582 .\" End of "$Id$".
 583 .\"