Fix cancel of jobs with multiple documents (<rdar://problem/24854834>)

[thirdparty/cups.git] / IPPTOOL.txt

IPPTOOL.txt - 2013-07-15
------------------------

See the file CHANGES-IPPTOOL.txt for a list of changes to this software.


INTRODUCTION

    CUPS includes two user programs for IPP printers.  The first is called
    ipptool and can be used to send arbitrary IPP requests to a CUPS server or
    IPP printer.  This tool started life as part of the CUPS automated test
    suite and has grown to support complex conformance tests and a simple way
    to query printer, job, and subscription attributes.

    The second program called ippfind that can be used to find IPP printers
    that have registered themselves using Bonjour (DNS-SD, mDNS, and Zeroconf)
    and run commands such as ipptool.


READING THE DOCUMENTATION

    Full documentation on the ipptool command can be found in the
    "man-ipptool.html" and "man-ipptoolfile.html" files; the latter describes
    the test file format supported by ipptool.

    Full documentation on the ippfind command can be found in the
    "man-ippfind.html" file.


IPPFIND BASIC USAGE

    The ippfind command can be used to discover IPP printers on your network.
    For example, the following command prints the printer URI of registered IPP
    printers:

        ippfind

    To find all color IPP printers, run:

        ippfind --txt-color T

    And to run the IPP Everywhere conformance test file on every registered IPP
    printer, run the following command:

        ippfind _ipp._tcp,_print --exec ipptool -t '{}' ipp-everywhere.test \;


IPPTOOL BASIC USAGE

    The ipptool command requires a printer URI and one or more "test" files that
    describe the operations, attributes to display, and expected status and
    attribute values. Several standard files are included with CUPS, for example
    to show a list of pending print jobs on a CUPS printer called "myprinter"
    you'd run:

        ipptool ipp://localhost/printers/myprinter get-jobs.test

    which would produce something like this:

	job-id job-state    job-name     job-originating-user-name
	------ ------------ ------------ -------------------------
	72     pending      testfile.pdf msweet
	73     pending      testfile.ps  msweet
	74     pending-held testfile.jpg msweet
	75     pending-held testfile.txt msweet

    To get output suitable for import into a spreadsheet, use the "-c" (CSV)
    option:

        ipptool -c ipp://localhost/printers/myprinter get-jobs.test

    which will produce something like this:

	job-id,job-state,job-name,job-originating-user-name
	72,pending,testfile.pdf,msweet
	73,pending,testfile.ps,msweet
	74,pending-held,testfile.jpg,msweet
	75,pending-held,testfile.txt,msweet


STANDARD TEST FILES

    The following standard test files are included with ipptool:

        create-printer-subscription.test    Creates a printer subscription for
                                            state change notifications
        get-completed-jobs.test             Shows a list of completed jobs
        get-jobs.test                       Shows a list of pending jobs
        get-notifications.test              Shows events for an ippget
	                                    subscription.
        get-printer-attributes.test         Shows printer attributes
        get-subscriptions.test              Shows a list of subscriptions
        ipp-1.1.test                        IPP/1.1 conformance test suite
        ipp-2.0.test                        IPP/2.0 conformance test suite
        ipp-2.1.test                        IPP/2.1 conformance test suite
        ipp-2.2.test                        IPP/2.2 conformance test suite
        ipp-everywhere.test                 IPP Everywhere conformance test
                                            suite
        print-job.test                      Prints a file
        print-job-deflate.test              Prints a file, compressing with
                                            deflate.
        print-job-gzip.test                 Prints a file, compressing with gzip
        validate-job.test                   Validates attributes for a job
                                            submission.


CONFORMANCE TESTS

    We provide basic IPP conformance tests for IPP/1.1, IPP/2.0, IPP/2.1,
    IPP/2.2, and IPP Everywhere.  For a given printer URI, the following
    commands perform tests at each level:

        ipptool -tf filename [options] -I printer-uri ipp-1.1.test
        ipptool -tf filename [options] -I -V 2.0 printer-uri ipp-2.0.test
        ipptool -tf filename [options] -I -V 2.1 printer-uri ipp-2.1.test
        ipptool -tf filename [options] -I -V 2.2 printer-uri ipp-2.2.test

    The filename must use a format supported by the printer; ipptool will guess
    the MIME media type using the extension, otherwise application/octet stream
    will be used.  The following standard test files are included:

	color.jpg
	document-a4.pdf
	document-a4.ps
	document-letter.pdf
	document-letter.ps
	gray.jpg
	onepage-a4.pdf
	onepage-a4.ps
	onepage-letter.pdf
	onepage-letter.ps
	testfile.jpg
	testfile.pcl
	testfile.pdf
	testfile.ps
	testfile.txt

    Useful options include the following:

        -4           Connect using IPv4
        -6           Connect using IPv6
        -C           Send chunked requests (default)
        -d name=val  Define a variable
        -E           Test IPP with HTTP Upgrade to TLS
        -L           Send requests using the Content-Length header (HTTP/1.0)
        -S           Test IPP over HTTPS (default for ipps: URIs)
        -T seconds   Set a timeout for responses in seconds
        -v           Be verbose, showing all attributes sent and received
        -X           Produce XML (Apple plist) output

    The printer-uri must be a URI supported by the printer using the "ipp" or
    "ipps" scheme, for example:

        ipp://192.168.0.1/ipp
        ipps://192.168.0.1/ipp/print

    Print-by-reference (URL) printing can be tested by defining the document-uri
    variable as a URL, for example:

        ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test

    The standard test files are available on cups.org under the "test"
    directory, for example:

        ipptool -tf document-a4.pdf \
            -d document-uri=http://www.cups.org/test/document-a4.pdf \
            ipp://192.168.0.1/ipp -I -V 2.0 ipp-2.0.test

    The "document" test files contain 4 pages each.  Doing the IPP conformance
    tests will will produce up to 90 pages on various media, depending on the
    printer.


IPP EVERYWHERE TESTING

    The IPP Everywhere tests use sample PWG raster files available from:

        ftp://ftp.pwg.org/pub/pwg/ipp/examples

    Extract the corresponding ZIP archives into the current directory before
    running the ipp-everywhere.test file.  The test file will attempt to print
    each PWG Raster file that is supported by the printer being tested - up to
    372 pages including the 90 pages produced by the regular IPP test suite.


GETTING SUPPORT AND OTHER RESOURCES

    If you have problems, READ THE DOCUMENTATION FIRST!  We also provide
    discussion forums which are available at:

	http://www.cups.org/


REPORTING BUGS

    If you believe you have discovered a bug in ippfind or ipptool, please fill
    out the bug form at:

	http://www.cups.org/str.php

    Be sure to identify the version of CUPS and ippfind/ipptool (if you
    downloaded the standalone version) you are using, the printer (if any) and
    firmware version, and include any files that apply.

    If you downloaded the standalone version of ippfind/ipptool, please also
    re-run the command with debug logging enabled.  Run the following commands
    on Windows to enable debug logging:

        setdebug.bat

    For Linux and Mac OS X use:

	CUPS_DEBUG_LOG=ipptool.log; export CUPS_DEBUG_LOG
	CUPS_DEBUG_LEVEL=6; export CUPS_DEBUG_LEVEL

    Then when you run the ippfind or ipptool command a new "ipptool.log" file
    will be created with detailed information - attach this file to the bug you
    file as well.


LEGAL STUFF

    CUPS is Copyright 2007-2013 by Apple Inc.  CUPS and the CUPS logo are
    trademarks of Apple Inc.

    The MD5 Digest code is Copyright 1999 Aladdin Enterprises.

    CUPS is provided under the terms of version 2 of the GNU General Public
    License and GNU Library General Public License. This program is distributed
    in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
    the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    See the "doc/help/license.html" or "LICENSE.txt" files for more information.