[thirdparty/cups.git] / IPPTOOL.txt

IPPTOOL.txt - 2011-09-28
------------------------

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


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.

    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.
Commit	Line	Data
4822113c	1	IPPTOOL.txt - 2011-09-28
c7c21fe6	2	------------------------
c7c21fe6	3
4822113c	4	See the file CHANGES-IPPTOOL.txt for a list of changes to this software.
4822113c	5
c7c21fe6	6
	7	INTRODUCTION
	8
78edd696	9	Starting with CUPS 1.5, CUPS now installs a user program called ipptool that
	10	can be used to send arbitrary IPP requests to a CUPS server or IPP printer.
	11	This tool started life as part of the CUPS automated test suite and has
	12	grown to support complex conformance tests and a simple way to query
	13	printer, job, and subscription attributes.
c7c21fe6	14
	15
	16	BASIC USAGE
	17
78edd696	18	The ipptool command requires a printer URI and one or more "test" files that
	19	describe the operations, attributes to display, and expected status and
	20	attribute values. Several standard files are included with CUPS, for example
	21	to show a list of pending print jobs on a CUPS printer called "myprinter"
	22	you'd run:
c7c21fe6	23
	24	ipptool ipp://localhost/printers/myprinter get-jobs.test
	25
	26	which would produce something like this:
	27
	28	job-id job-state job-name job-originating-user-name
	29	------ ------------ ------------ -------------------------
	30	72 pending testfile.pdf msweet
	31	73 pending testfile.ps msweet
	32	74 pending-held testfile.jpg msweet
	33	75 pending-held testfile.txt msweet
	34
78edd696	35	To get output suitable for import into a spreadsheet, use the "-c" (CSV)
78edd696	36	option:
c7c21fe6	37
	38	ipptool -c ipp://localhost/printers/myprinter get-jobs.test
	39
2393589b	40	which will produce something like this:
c7c21fe6	41
	42	job-id,job-state,job-name,job-originating-user-name
	43	72,pending,testfile.pdf,msweet
	44	73,pending,testfile.ps,msweet
	45	74,pending-held,testfile.jpg,msweet
	46	75,pending-held,testfile.txt,msweet
	47
	48
	49	CONFORMANCE TESTS
	50
2393589b	51	We provide basic IPP conformance tests for IPP/1.1, IPP/2.0, IPP/2.1, and
	52	IPP/2.2. For a given printer URI, the following commands perform tests at
	53	each level:
	54
788eaf1d	55	ipptool -tf filename [options] -I printer-uri ipp-1.1.test
	56	ipptool -tf filename [options] -I -V 2.0 printer-uri ipp-2.0.test
	57	ipptool -tf filename [options] -I -V 2.1 printer-uri ipp-2.1.test
	58	ipptool -tf filename [options] -I -V 2.2 printer-uri ipp-2.2.test
2393589b	59
	60	The filename must use a format supported by the printer; ipptool will guess
	61	the MIME media type using the extension, otherwise application/octet stream
	62	will be used. The following standard test files are included:
	63
	64	color.jpg
	65	document-a4.pdf
	66	document-a4.ps
	67	document-letter.pdf
	68	document-letter.ps
	69	gray.jpg
	70	onepage-a4.pdf
	71	onepage-a4.ps
	72	onepage-letter.pdf
	73	onepage-letter.ps
	74
	75	Print-by-reference (URL) printing can be tested by defining the document-uri
	76	variable to a URL, for example:
	77
788eaf1d	78	ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test
2393589b	79
	80	The standard test files are available on cups.org under the "test"
	81	directory, for example:
c7c21fe6	82
2393589b	83	http://www.cups.org/test/document-a4.pdf
c7c21fe6	84
dc022813	85	The "document" test files contain 4 pages each. Doing the IPP conformance
	86	tests will will produce up to 90 pages on various media, depending on the
	87	printer.
	88
c7c21fe6	89
	90	READING THE DOCUMENTATION
	91
78edd696	92	The command usage is described in the ipptest(1) man page, while the file
78edd696	93	format is described in the ipptestfile(5) man page.
c7c21fe6	94
	95
	96	GETTING SUPPORT AND OTHER RESOURCES
	97
	98	If you have problems, READ THE DOCUMENTATION FIRST! We also provide many
	99	discussion forums which are available at:
	100
	101	http://www.cups.org/newsgroups.php
	102
	103	See the CUPS web site at "http://www.cups.org/" for other resources.
	104
	105
58ec0453	106	REPORTING BUGS
	107
	108	If you believe you have discovered a bug in ipptool, please fill out the
	109	bug form at:
	110
	111	http://www.cups.org/str.php
	112
	113	Be sure to identify the version of CUPS and ipptool (if you downloaded the
	114	standalone version) you are using, the printer (if any) and firmware
	115	version, and include any files that apply.
	116
	117	If you downloaded the standalone version of ipptool, please also re-run the
	118	test with debug logging enabled. Run the following commands on Windows to
	119	enable debug logging:
	120
	121	set CUPS_DEBUG_LOG=ipptool.log
	122	set CUPS_DEBUG_LEVEL=6
	123
	124	For Linux and Mac OS X use:
	125
	126	CUPS_DEBUG_LOG=ipptool.log; export CUPS_DEBUG_LOG
	127	CUPS_DEBUG_LEVEL=6; export CUPS_DEBUG_LEVEL
	128
	129	Then when you run the ipptool command a new "ipptool.log" file will be
	130	created with detailed information - attach this file to the bug you file
	131	as well.
	132
	133
c7c21fe6	134	LEGAL STUFF
c7c21fe6	135
a1a2e89a	136	CUPS is Copyright 2007-2011 by Apple Inc. CUPS and the CUPS logo are
c7c21fe6	137	trademarks of Apple Inc.
	138
	139	The MD5 Digest code is Copyright 1999 Aladdin Enterprises.
	140
c7c21fe6	141	CUPS is provided under the terms of version 2 of the GNU General Public
	142	License and GNU Library General Public License. This program is distributed
	143	in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
	144	the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
	145	See the "doc/help/license.html" or "LICENSE.txt" files for more information.