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 April 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 INCLUDE "filename"
  78 .TP 5
  79 INCLUDE <filename>
  80 Includes another test file. The first form includes a file relative to the
  81 current test file, while the second form includes a file from the \fIipptool\fR
  82 include directory.
  83 .TP 5
  84 TRANSFER auto
  85 Specifies that tests will, by default, use "Transfer-Encoding: chunked" for
  86 requests with attached files and "Content-Length:" for requests without attached
  87 files.
  88 .TP 5
  89 TRANSFER chunked
  90 Specifies that tests will, by default, use the HTTP/1.1 "Transfer-Encoding:
  91 chunked" header. This is the default and is equivalent to specifying "-c" on the
  92 \fIipptool\fR command-line. Support for chunked requests is required for
  93 conformance with all versions of IPP.
  94 .TP 5
  95 TRANSFER length
  96 Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:"
  97 header. This is equivalent to specifying "-l" on the \fIipptool\fR command-line.
  98 Support for content length requests is required for conformance with all
  99 versions of IPP.
 100 .TP 5
 101 VERSION 1.0
 102 .TP 5
 103 VERSION 1.1
 104 .TP 5
 105 VERSION 2.0
 106 .TP 5
 107 VERSION 2.1
 108 .TP 5
 109 VERSION 2.2
 110 Specifies the default IPP version number to use for the tests that follow.
 111
 112 .SH TEST DIRECTIVES
 113 The following directives are understood in a test:
 114 .TP 5
 115 ATTR tag attribute-name value(s)
 116 Adds an attribute to the test request. Values are separated by the comma (",")
 117 character - escape commas using the "\" character.
 118 .TP 5
 119 ATTR collection attribute-name { MEMBER tag member-name value(s) ... } [ ... { ... } ]
 120 Adds a collection attribute to the test request. Member attributes follow the
 121 same syntax as regular attributes and can themselves be nested collections.
 122 Multiple collection values can be supplied as needed.
 123 .TP 5
 124 DELAY seconds
 125 Specifies a delay before this test will be run.
 126 .TP 5
 127 DISPLAY attribute-name
 128 Specifies that value of the named attribute should be output as part of the
 129 test report.
 130 .TP 5
 131 EXPECT attribute-name [ predicate(s) ]
 132 .TP 5
 133 EXPECT ?attribute-name predicate(s)
 134 .TP 5
 135 EXPECT !attribute-name
 136 Specifies that the response must/may/must not include the named attribute.
 137 Additional requirements can be added as predicates - see the "EXPECT PREDICATES"
 138 section for more information on predicates.
 139 .TP 5
 140 FILE filename
 141 Specifies a file to include at the end of the request. This is typically used
 142 when sending a test print file.
 143 .TP 5
 144 GROUP tag
 145 Specifies the group tag for subsequent attributes in the request.
 146 .TP 5
 147 NAME "literal string"
 148 Specifies the human-readable name of the test.
 149 .TP 5
 150 OPERATION operation-code
 151 Specifies the operation to be performed.
 152 .TP 5
 153 REQUEST-ID number
 154 .TP 5
 155 REQUEST-ID random
 156 Specifies the request-id value to use in the request, either an integer or the
 157 word "random" to use a randomly generated value (the default).
 158 .TP 5
 159 RESOURCE path
 160 Specifies an alternate resource path that is used for the HTTP POST request.
 161 The default is the resource from the URI provided to the \fIipptool\fR program.
 162 .TP 5
 163 STATUS status-code [ predicate ]
 164 Specifies an expected response status-code value. Additional requirements can be
 165 added as predicates - see the "STATUS PREDICATES" section for more information
 166 on predicates.
 167 .TP 5
 168 TRANSFER auto
 169 Specifies that this test will use "Transfer-Encoding: chunked" if it has an
 170 attached file or "Content-Length:" otherwise.
 171 .TP 5
 172 TRANSFER chunked
 173 Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked"
 174 header.
 175 .TP 5
 176 TRANSFER length
 177 Specifies that this test will use the HTTP/1.0 "Content-Length:" header.
 178 .TP 5
 179 VERSION 1.0
 180 .TP 5
 181 VERSION 1.1
 182 .TP 5
 183 VERSION 2.0
 184 .TP 5
 185 VERSION 2.1
 186 .TP 5
 187 VERSION 2.2
 188 Specifies the IPP version number to use for this test.
 189
 190 .SH EXPECT PREDICATES
 191 The following predicates are understood following the EXPECT test directive:
 192 .TP 5
 193 COUNT number
 194 Requires the EXPECT attribute to have the specified number of values.
 195 .TP 5
 196 IF-DEFINED variable-name
 197 Makes the EXPECT conditions apply only if the specified variable is defined.
 198 .TP 5
 199 IF-UNDEFINED variable-name
 200 Makes the EXPECT conditions apply only if the specified variable is not
 201 defined.
 202 .TP 5
 203 IN-GROUP tag
 204 Requires the EXPECT attribute to be in the specified group tag.
 205 .TP 5
 206 OF-TYPE tag[,tag,...]
 207 Requires the EXPECT attribute to use the specified value tag(s).
 208 .TP 5
 209 SAME-COUNT-AS attribute-name
 210 Requires the EXPECT attribute to have the same number of values as the specified
 211 parallel attribute.
 212 .TP 5
 213 WITH-VALUE "literal string"
 214 Requires at least one value of the EXPECT attribute to match the literal string.
 215 Comparisons are case-sensitive.
 216 .TP 5
 217 WITH-VALUE "/regular expression/"
 218 Requires that all values of the EXPECT attribute match the regular expression,
 219 which must conform to the POSIX regular expression syntax.
 220 Comparisons are case-sensitive.
 221
 222 .SH STATUS PREDICATES
 223 The following predicates are understood following the STATUS test directive:
 224 .TP 5
 225 IF-DEFINED variable-name
 226 Makes the STATUS apply only if the specified variable is defined.
 227 .TP 5
 228 IF-UNDEFINED variable-name
 229 Makes the STATUS apply only if the specified variable is not defined.
 230
 231 .SH OPERATION CODES
 232 Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from
 233 RFC 2911 and other IPP extension specifications. Here is a complete list:
 234 .nf
 235     Activate-Printer
 236     CUPS-Accept-Jobs
 237     CUPS-Add-Modify-Class
 238     CUPS-Add-Modify-Printer
 239     CUPS-Authenticate-Job
 240     CUPS-Delete-Class
 241     CUPS-Delete-Printer
 242     CUPS-Get-Classes
 243     CUPS-Get-Default
 244     CUPS-Get-Devices
 245     CUPS-Get-Document
 246     CUPS-Get-PPD
 247     CUPS-Get-PPDs
 248     CUPS-Get-Printers
 249     CUPS-Move-Job
 250     CUPS-Reject-Jobs
 251     CUPS-Set-Default
 252     Cancel-Current-Job
 253     Cancel-Job
 254     Cancel-Jobs
 255     Cancel-My-Jobs
 256     Cancel-Subscription
 257     Close-Job
 258     Create-Job
 259     Create-Job-Subscription
 260     Create-Printer-Subscription
 261     Deactivate-Printer
 262     Disable-Printer
 263     Enable-Printer
 264     Get-Job-Attributes
 265     Get-Jobs
 266     Get-Notifications
 267     Get-Printer-Attributes
 268     Get-Printer-Support-Files
 269     Get-Printer-Supported-Values
 270     Get-Subscription-Attributes
 271     Get-Subscriptions
 272     Hold-Job
 273     Hold-New-Jobs
 274     Pause-Printer
 275     Pause-Printer-After-Current-Job
 276     Print-Job
 277     Print-URI
 278     Promote-Job
 279     Purge-Jobs
 280     Release-Held-New-Jobs
 281     Release-Job
 282     Renew-Subscription
 283     Reprocess-Job
 284     Restart-Job
 285     Restart-Printer
 286     Resubmit-Job
 287     Resume-Job
 288     Resume-Printer
 289     Schedule-Job-After
 290     Send-Document
 291     Send-Notifications
 292     Send-URI
 293     Set-Job-Attributes
 294     Set-Printer-Attributes
 295     Shutdown-Printer
 296     Startup-Printer
 297     Suspend-Current-Job
 298     Validate-Job
 299 .fi
 300
 301 .SH STATUS CODES
 302 Status codes correspond to the names from RFC 2911 and other IPP extension
 303 specifications. Here is a complete list:
 304 .nf
 305     client-error-attributes-not-settable
 306     client-error-attributes-or-values-not-supported
 307     client-error-bad-request
 308     client-error-charset-not-supported
 309     client-error-compression-error
 310     client-error-compression-not-supported
 311     client-error-conflicting-attributes
 312     client-error-document-access-error
 313     client-error-document-format-error
 314     client-error-document-format-not-supported
 315     client-error-forbidden
 316     client-error-gone
 317     client-error-ignored-all-notifications
 318     client-error-ignored-all-subscriptions
 319     client-error-not-authenticated
 320     client-error-not-authorized
 321     client-error-not-found
 322     client-error-not-possible
 323     client-error-print-support-file-not-found
 324     client-error-request-entity-too-large
 325     client-error-request-value-too-long
 326     client-error-timeout
 327     client-error-too-many-subscriptions
 328     client-error-uri-scheme-not-supported
 329     cups-see-other
 330     redirection-other-site
 331     server-error-busy
 332     server-error-device-error
 333     server-error-internal-error
 334     server-error-job-canceled
 335     server-error-multiple-document-jobs-not-supported
 336     server-error-not-accepting-jobs
 337     server-error-operation-not-supported
 338     server-error-printer-is-deactivated
 339     server-error-service-unavailable
 340     server-error-temporary-error
 341     server-error-version-not-supported
 342     successful-ok
 343     successful-ok-but-cancel-subscription
 344     successful-ok-conflicting-attributes
 345     successful-ok-events-complete
 346     successful-ok-ignored-notifications
 347     successful-ok-ignored-or-substituted-attributes
 348     successful-ok-ignored-subscriptions
 349     successful-ok-too-many-events
 350 .fi
 351
 352 .SH TAGS
 353 Value and group tags correspond to the names from RFC 2911 and other IPP
 354 extension specifications. Here are the group tags:
 355 .nf
 356     event-notification-attributes-tag
 357     job-attributes-tag
 358     operation-attributes-tag
 359     printer-attributes-tag
 360     subscription-attributes-tag
 361     unsupported-attributes-tag
 362 .fi
 363 .LP
 364 Here are the value tags:
 365 .nf
 366     admin-define
 367     boolean
 368     charset
 369     collection
 370     dateTime
 371     default
 372     delete-attribute
 373     enum
 374     integer
 375     keyword
 376     mimeMediaType
 377     nameWithLanguage
 378     nameWithoutLanguage
 379     naturalLanguage
 380     no-value
 381     not-settable
 382     octetString
 383     rangeOfInteger
 384     resolution
 385     textWithLanguage
 386     textWithoutLanguage
 387     unknown
 388     unsupported
 389     uri
 390     uriScheme
 391 .fi
 392
 393 .SH VARIABLES
 394 The \fIipptool\fR program maintains a list of variables that can be used in any
 395 literal string or attribute value by specifying "$variable-name". Aside from
 396 variables defined using the "-d" option or "DEFINE" directive, the following
 397 pre-defined variables are available:
 398 .TP 5
 399 $$
 400 Inserts a single "$" character.
 401 .TP 5
 402 $ENV[name]
 403 Inserts the value of the named environment variable, or an empty string if the
 404 environment variable is not defined.
 405 .TP 5
 406 $filename
 407 Inserts the filename provided to \fIipptool\fR with the "-f" option.
 408 .TP 5
 409 $hostname
 410 Inserts the hostname from the URI provided to \fIipptool\fR.
 411 .TP 5
 412 $job-id
 413 Inserts the last job-id value returned in a test response or 0 if no job-id has
 414 been seen.
 415 .TP 5
 416 $job-uri
 417 Inserts the last job-uri value returned in a test response or an empty string if
 418 no job-uri has been seen.
 419 .TP 5
 420 $scheme
 421 Inserts the scheme from the URI provided to \fIipptool\fR.
 422 .TP 5
 423 $notify-subscription-id
 424 Inserts the last notify-subscription-id value returnd in a test response or 0 if
 425 no notify-subscription-id has been seen.
 426 .TP 5
 427 $port
 428 Inserts the port number from the URI provided to \fIipptool\fR.
 429 .TP 5
 430 $resource
 431 Inserts the resource path from the URI provided to \fIipptool\fR.
 432 .TP 5
 433 $uri
 434 Inserts the URI provided to \fIipptool\fR.
 435 .TP 5
 436 $user
 437 Inserts the current user's login name.
 438 .TP 5
 439 $username
 440 Inserts the username from the URI provided to \fIipptool\fR, if any.
 441
 442 .SH SEE ALSO
 443 \fIipptool(1)\fR,
 444 .br
 445 http://localhost:631/help
 446
 447 .SH COPYRIGHT
 448 Copyright 2007-2010 by Apple Inc.
 449 .\"
 450 .\" End of "$Id$".
 451 .\"