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