IPPTOOL.txt - 2011-09-21
------------------------


INTRODUCTION

    Starting with CUPS 1.5, CUPS now installs a user program called ipptool that
    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.


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


CONFORMANCE TESTS

    We provide basic IPP conformance tests for IPP/1.1, IPP/2.0, IPP/2.1, and
    IPP/2.2.  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

    Print-by-reference (URL) printing can be tested by defining the document-uri
    variable to 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:

	http://www.cups.org/test/document-a4.pdf

    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.


READING THE DOCUMENTATION

    The command usage is described in the ipptest(1) man page, while the file
    format is described in the ipptestfile(5) man page.


GETTING SUPPORT AND OTHER RESOURCES

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

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

    See the CUPS web site at "http://www.cups.org/" for other resources.


REPORTING BUGS

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

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

    Be sure to identify the version of CUPS and 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 ipptool, please also re-run the
    test with debug logging enabled.  Run the following commands on Windows to
    enable debug logging:

	set CUPS_DEBUG_LOG=ipptool.log
	set CUPS_DEBUG_LEVEL=6

    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 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-2011 by Apple Inc.  CUPS and the CUPS logo are
    trademarks of Apple Inc.

    The MD5 Digest code is Copyright 1999 Aladdin Enterprises.

    This software is based in part on the work of the Independent JPEG Group.

    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.
