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