Codex

ipptoolfile

Section: Apple Inc. (5)

Updated: CUPS

Index?action=index Return to Main Contents


NAME

ipptoolfile - ipptool file format

DESCRIPTION

The ipptool?(1) 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:

TOP-LEVEL DIRECTIVES

The following directives can be used outside of a test:

{ test }
Defines a test.:
DEFINE variable-name value
Defines the named variable to the given value. This is equivalent to specifying "-d variable-name=value" on the ipptool command-line.:
DEFINE-DEFAULT variable-name value
Defines the named variable to the given value if it does not already have a value.:
FILE-ID "identifier"
Specifies an identifier string for the current file.:

:IGNORE-ERRORS yes

IGNORE-ERRORS no
Specifies whether, by default, ipptool will ignore errors and continue with subsequent tests.:

:INCLUDE "filename"

INCLUDE <filename>
Includes another test file. The first form includes a file relative to the current test file, while the second form includes a file from the ipptool include directory.:

:INCLUDE-IF-DEFINED name "filename"

INCLUDE-IF-DEFINED name <filename>
Includes another test file if the named variable is defined. The first form includes a file relative to the current test file, while the second form includes a file from the ipptool include directory.:

:INCLUDE-IF-NOT-DEFINED name "filename"

INCLUDE-IF-NOT-DEFINED name <filename>
Includes another test file if the named variable is not defined. The first form includes a file relative to the current test file, while the second form includes a file from the ipptool include directory.:

:SKIP-IF-DEFINED variable-name

SKIP-IF-NOT-DEFINED variable-name
Specifies that the remainder of the test file should be skipped when the variable is or is not defined.:

:STOP-AFTER-INCLUDE-ERROR no

STOP-AFTER-INCLUDE-ERROR yes
Specifies whether tests will be stopped after an error in an included file.:
TRANSFER auto
Specifies that tests will, by default, use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files.:
TRANSFER chunked
Specifies that tests will, by default, use the HTTP/1.1 "Transfer-Encoding: chunked" header. This is the default and is equivalent to specifying "-c" on the ipptool command-line. Support for chunked requests is required for conformance with all versions of IPP.:
TRANSFER length
Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:" header. This is equivalent to specifying "-l" on the ipptool command-line. Support for content length requests is required for conformance with all versions of IPP.:

:VERSION 1.0

:VERSION 1.1

:VERSION 2.0

:VERSION 2.1

VERSION 2.2
Specifies the default IPP version number to use for the tests that follow.:

TEST DIRECTIVES

The following directives are understood in a test:

ATTR tag attribute-name value(s)
Adds an attribute to the test request. Values are separated by the comma (",") character - escape commas using the "\" character. Common attributes and values are listed in the IANA IPP registry - see references below.:
ATTR collection attribute-name { MEMBER tag member-name value(s) ... } [ ... { ... } ]
Adds a collection attribute to the test request. Member attributes follow the same syntax as regular attributes and can themselves be nested collections. Multiple collection values can be supplied as needed.:

:COMPRESSION deflate

:COMPRESSION gzip

COMPRESSION none

Uses the specified compression on the document data following the attributes in a Print-Job or Send-Document request.:

DELAY seconds
Specifies a delay before this test will be run.:
DISPLAY attribute-name
Specifies that value of the named attribute should be output as part of the test report.:

:EXPECT attribute-name [ predicate(s) ]

:EXPECT ?attribute-name predicate(s)

EXPECT !attribute-name
Specifies that the response must/may/must not include the named attribute. Additional requirements can be added as predicates - see the "EXPECT PREDICATES" section for more information on predicates.:
FILE filename
Specifies a file to include at the end of the request. This is typically used when sending a test print file.:
GROUP tag
Specifies the group tag for subsequent attributes in the request.:

:IGNORE-ERRORS yes

IGNORE-ERRORS no
Specifies whether ipptool will ignore errors and continue with subsequent tests.:
NAME "literal string"
Specifies the human-readable name of the test.:
OPERATION operation-code
Specifies the operation to be performed.:

:REQUEST-ID number

REQUEST-ID random
Specifies the request-id value to use in the request, either an integer or the word "random" to use a randomly generated value (the default).:
RESOURCE path
Specifies an alternate resource path that is used for the HTTP POST request. The default is the resource from the URI provided to the ipptool program.:

:SKIP-IF-DEFINED variable-name

SKIP-IF-NOT-DEFINED variable-name
Specifies that the current test should be skipped when the variable is or is not defined.:

:SKIP-PREVIOUS-ERROR yes

SKIP-PREVIOUS-ERROR no
Specifies whether ipptool will skip the current test if the previous test resulted in an error/failure.:
STATUS status-code [ predicate ]
Specifies an expected response status-code value. Additional requirements can be added as predicates - see the "STATUS PREDICATES" section for more information on predicates.:
TEST-ID "identifier"
Specifies an identifier string for the current test.:
TRANSFER auto
Specifies that this test will use "Transfer-Encoding: chunked" if it has an attached file or "Content-Length:" otherwise.:
TRANSFER chunked
Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked" header.:
TRANSFER length
Specifies that this test will use the HTTP/1.0 "Content-Length:" header.:

:VERSION 1.0

:VERSION 1.1

:VERSION 2.0

:VERSION 2.1

VERSION 2.2
Specifies the IPP version number to use for this test.:

EXPECT PREDICATES

The following predicates are understood following the EXPECT test directive:

COUNT number
Requires the EXPECT attribute to have the specified number of values.:
DEFINE-MATCH variable-name
Defines the variable to "1" when the EXPECT condition matches. A side-effect of this predicate is that this EXPECT will never fail a test.:
DEFINE-NO-MATCH variable-name
Defines the variable to "1" when the EXPECT condition does not match. A side- effect of this predicate is that this EXPECT will never fail a test.:
DEFINE-VALUE variable-name
Defines the variable to the value of the attribute when the EXPECT condition matches. A side-effect of this predicate is that this EXPECT will never fail a test.:
IF-DEFINED variable-name
Makes the EXPECT conditions apply only if the specified variable is defined.:
IF-NOT-DEFINED variable-name
Makes the EXPECT conditions apply only if the specified variable is not defined.:
IN-GROUP tag
Requires the EXPECT attribute to be in the specified group tag.:
OF-TYPE tag[,tag,...]
Requires the EXPECT attribute to use the specified value tag(s).:
REPEAT-LIMIT number

Specifies the maximum number of times to repeat. The default value is 1000.:

:REPEAT-MATCH

REPEAT-NO-MATCH
Specifies that the current test should be repeated when the EXPECT condition matches or does not match.:
SAME-COUNT-AS attribute-name
Requires the EXPECT attribute to have the same number of values as the specified parallel attribute.:

:WITH-ALL-HOSTNAMES "literal string"

WITH-ALL-HOSTNAMES "/regular expression/"
Requires that all URI values contain a matching hostname.:

:WITH-ALL-RESOURCES "literal string"

WITH-ALL-RESOURCES "/regular expression/"
Requires that all URI values contain a matching resource (including leading /).:

:WITH-ALL-SCHEMES "literal string"

WITH-ALL-SCHEMES "/regular expression/"
Requires that all URI values contain a matching scheme.:
WITH-ALL-VALUES "literal string"
Requires that all values of the EXPECT attribute match the literal string. Comparisons are case-sensitive.:

:WITH-ALL-VALUES <number

:WITH-ALL-VALUES =number

:WITH-ALL-VALUES >number

WITH-ALL-VALUES number[,number,...]
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.:

:WITH-ALL-VALUES "false"

WITH-ALL-VALUES "true"
Requires that all values of the EXPECT attribute match the boolean value given.:
WITH-ALL-VALUES "/regular expression/"
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.:

:WITH-HOSTNAME "literal string"

WITH-HOSTNAME "/regular expression/"
Requires that at least one URI value contains a matching hostname.:

:WITH-RESOURCE "literal string"

WITH-RESOURCE "/regular expression/"
Requires that at least one URI value contains a matching resource (including leading /).:

:WITH-SCHEME "literal string"

WITH-SCHEME "/regular expression/"
Requires that at least one URI value contains a matching scheme.:
WITH-VALUE "literal string"
Requires that at least one value of the EXPECT attribute matches the literal string. Comparisons are case-sensitive.:

:WITH-VALUE <number

:WITH-VALUE =number

:WITH-VALUE >number

WITH-VALUE number[,number,...]
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.:

:WITH-VALUE "false"

WITH-VALUE "true"
Requires that at least one value of the EXPECT attribute matches the boolean value given.:
WITH-VALUE "/regular expression/"
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.:

STATUS PREDICATES

The following predicates are understood following the STATUS test directive:

DEFINE-MATCH variable-name
Defines the variable to "1" when the STATUS matches. A side-effect of this predicate is that this STATUS will never fail a test.:
DEFINE-NO-MATCH variable-name
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.:
IF-DEFINED variable-name
Makes the STATUS apply only if the specified variable is defined.:
IF-NOT-DEFINED variable-name
Makes the STATUS apply only if the specified variable is not defined.:
REPEAT-LIMIT number

Specifies the maximum number of times to repeat. The default value is 1000.:

:REPEAT-MATCH

REPEAT-NO-MATCH
Specifies that the current test should be repeated when the response status-code matches or does not match the value specified by the STATUS directive.:

OPERATION CODES

Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC 2911 and other IPP extension specifications. Here is a complete list:

STATUS CODES

Status codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC 2911 and other IPP extension specifications. Here is a complete list:

TAGS

Value and group tags correspond to the names from RFC 2911 and other IPP extension specifications. Here are the group tags:

Here are the value tags:

VARIABLES

The ipptool program maintains a list of variables that can be used in any literal string or attribute value by specifying "$variable-name". Aside from variables defined using the "-d" option or "DEFINE" directive, the following pre-defined variables are available:

$$
Inserts a single "$" character.:
$ENV[name]
Inserts the value of the named environment variable, or an empty string if the environment variable is not defined.:
$filename
Inserts the filename provided to ipptool with the "-f" option.:
$hostname
Inserts the hostname from the URI provided to ipptool.:
$job-id
Inserts the last job-id value returned in a test response or 0 if no job-id has been seen.:
$job-uri
Inserts the last job-uri value returned in a test response or an empty string if no job-uri has been seen.:
$scheme
Inserts the scheme from the URI provided to ipptool.:
$notify-subscription-id
Inserts the last notify-subscription-id value returned in a test response or 0 if no notify-subscription-id has been seen.:
$port
Inserts the port number from the URI provided to ipptool.:
$resource
Inserts the resource path from the URI provided to ipptool.:
$uri
Inserts the URI provided to ipptool.:
$user
Inserts the current user's login name.:
$username
Inserts the username from the URI provided to ipptool, if any.:

SEE ALSO

ipptool?(1), RFC 2911,

http://localhost:631/help

http://www.iana.org/assignments/ipp-registrations

http://www.pwg.org/ipp

COPYRIGHT

Copyright 2007-2014 by Apple Inc.


Index

NAME

DESCRIPTION

TOP-LEVEL DIRECTIVES

TEST DIRECTIVES

EXPECT PREDICATES

STATUS PREDICATES

OPERATION CODES

STATUS CODES

TAGS

VARIABLES

SEE ALSO

COPYRIGHT