From e5528d423b25eb1504c8ecb4d49b1e7c944ebd57 Mon Sep 17 00:00:00 2001 From: msweet Date: Fri, 7 Jun 2013 01:45:14 +0000 Subject: [PATCH] Update ippfind documentation with examples, change '-e' to '-x' for --exec. Add ippfind to the ipptool binary package. git-svn-id: svn+ssh://src.apple.com/svn/cups/cups.org/trunk@11027 a1ca3aef-8c08-0410-bb20-df032aa958be --- CHANGES-IPPTOOL.txt | 5 ++- CHANGES.txt | 4 +- IPPTOOL.txt | 26 ++++++++++- doc/help/man-ippfind.html | 90 ++++++++++++++++++++++++--------------- man/ippfind.man | 60 +++++++++++++++----------- test/ippfind.c | 66 ++++++++++++++-------------- tools/makeipptoolpkg | 3 +- 7 files changed, 155 insertions(+), 99 deletions(-) diff --git a/CHANGES-IPPTOOL.txt b/CHANGES-IPPTOOL.txt index 9c0a36fe0..c05f4c40f 100644 --- a/CHANGES-IPPTOOL.txt +++ b/CHANGES-IPPTOOL.txt @@ -1,11 +1,12 @@ -CHANGES-IPPTOOL.txt - 2013-05-29 +CHANGES-IPPTOOL.txt - 2013-06-06 -------------------------------- This file provides a list of changes to the ipptool binary distribution posted on cups.org. -2013-05-29 +2013-06-06 + - New ippfind tool now included with ipptool. - Added support for automatically extending the timeout when all of the request data has not yet been written (all platforms but Windows which does not support it...) diff --git a/CHANGES.txt b/CHANGES.txt index 002400e60..de0c0bab6 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,8 +1,10 @@ -CHANGES.txt - 1.7rc1 - 2013-06-05 +CHANGES.txt - 1.7rc1 - 2013-06-06 --------------------------------- CHANGES IN CUPS V1.7rc1 + - Added a new ippfind tool for finding IPP printers and other Bonjour + services () - Fixed some issues with conversion of PWG media size names to hundredths of millimeters () - The IPP backend could crash on OS X when printing to a Kerberized diff --git a/IPPTOOL.txt b/IPPTOOL.txt index 150605766..31d6fe4ee 100644 --- a/IPPTOOL.txt +++ b/IPPTOOL.txt @@ -1,4 +1,4 @@ -IPPTOOL.txt - 2013-05-02 +IPPTOOL.txt - 2013-06-06 ------------------------ See the file CHANGES-IPPTOOL.txt for a list of changes to this software. @@ -12,8 +12,30 @@ INTRODUCTION complex conformance tests and a simple way to query printer, job, and subscription attributes. + CUPS also includes a user 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. -BASIC USAGE + +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 + + To run the IPP Everywhere conformance test file on every registered IPP + printer, run the following command instead: + + ippfind --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 diff --git a/doc/help/man-ippfind.html b/doc/help/man-ippfind.html index 32c53985d..e614ad4da 100644 --- a/doc/help/man-ippfind.html +++ b/doc/help/man-ippfind.html @@ -26,31 +26,6 @@ ippfind - find internet printing protocol printers --help ippfind --version -

Supported Registration Types

-ippfind supports the following registration types: -
-
_http._tcp -
-
HyperText Transport Protocol (HTTP, RFC 2616) -
-
_https._tcp -
-
Secure HyperText Transport Protocol (HTTPS, RFC 2818) -
-
_ipp._tcp -
-
Internet Printing Protocol (IPP, RFC 2911) -
-
_ipps._tcp -
-
Secure Internet Printing Protocol (IPPS, draft) -
-
_printer._tcp -
-
Line Printer Daemon (LPD, RFC 1179) - -
-

Options

--help @@ -80,10 +55,43 @@ ippfind - find internet printing protocol printers

Description

-ippfind finds printer services registered with the local DNS infrastructure or available through the local links. +ippfind finds services registered with a DNS server or available through local devices. Its primary purpose is to find IPP printers and show their URIs, show their current status, or run commands. For example, to show the status of all registered IPP printers on your network, run: +
+    ippfind --ls
+
+Similarly, to send a PostScript test page to every PostScript printer, run: +
+    ippfind --txt-pdl application/postscript --exec ipptool \
+        -f onepage-letter.ps '{}' print-job.test \;
+
+ +

Registration Types

+ippfind supports the following registration types: +
+
_http._tcp +
+
HyperText Transport Protocol (HTTP, RFC 2616) +
+
_https._tcp +
+
Secure HyperText Transport Protocol (HTTPS, RFC 2818) +
+
_ipp._tcp +
+
Internet Printing Protocol (IPP, RFC 2911) +
+
_ipps._tcp +
+
Secure Internet Printing Protocol (IPPS, draft) +
+
_printer._tcp +
+
Line Printer Daemon (LPD, RFC 1179) +
+

Expressions

-ippfind supports expressions much like the find(1) utility. However, unlike find, ippfind uses POSIX regular expressions instead of shell filename matching patterns. If -e, --exec, -l, --ls, -p, --print, --print-name, -q, --quiet, or -s is not specified, ippfind adds --print to print the service URI of anything it finds. The following expressions are supported: +ippfind supports expressions much like the find(1) utility. However, unlike find, ippfind uses POSIX regular expressions instead of shell filename matching patterns. If --exec, -l, --ls, -p, --print, --print-name, -q, --quiet, -s, or -x is not specified, ippfind adds --print to print the service URI of anything it finds. The following expressions are supported:
-d regex
@@ -92,17 +100,17 @@ ippfind - find internet printing protocol printers
True if the domain matches the given regular expression.
-
-e utility [argument ...] ; -
-
-
--exec utility [argument ...] ; -
-
Executes the specified program if the current result is true. "{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below. -
--false
Always false.
+
-h regex +
+
+
--host regex +
+
True is the hostname matches the given regular expression. +
-l
@@ -125,6 +133,13 @@ ippfind - find internet printing protocol printers
True if the URI resource path matches the given regular expression.
+
-P number[-number] +
+
+
--port number[-number] +
+
True if the port matches the given number or range. +
-p
@@ -176,6 +191,13 @@ expression.
True if the URI matches the given regular expression.
+
-x utility [argument ...] ; +
+
+
--exec utility [argument ...] ; +
+
Executes the specified program if the current result is true. "{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below. +

Expressions may also contain modifiers:

diff --git a/man/ippfind.man b/man/ippfind.man index ae67c3206..24c5a2660 100644 --- a/man/ippfind.man +++ b/man/ippfind.man @@ -11,7 +11,7 @@ .\" which should have been included with this file. If this file is .\" file is missing or damaged, see the license at "http://www.cups.org/". .\" -.TH ippfind 1 "CUPS" "5 June 2013" "Apple Inc." +.TH ippfind 1 "CUPS" "6 June 2013" "Apple Inc." .SH NAME ippfind - find internet printing protocol printers .SH SYNOPSIS @@ -31,24 +31,6 @@ ippfind - find internet printing protocol printers --help .B ippfind --version -.SH SUPPORTED REGISTRATION TYPES -\fIippfind\fR supports the following registration types: -.TP 5 -_http._tcp -HyperText Transport Protocol (HTTP, RFC 2616) -.TP 5 -_https._tcp -Secure HyperText Transport Protocol (HTTPS, RFC 2818) -.TP 5 -_ipp._tcp -Internet Printing Protocol (IPP, RFC 2911) -.TP 5 -_ipps._tcp -Secure Internet Printing Protocol (IPPS, draft) -.TP 5 -_printer._tcp -Line Printer Daemon (LPD, RFC 1179) - .SH OPTIONS .TP 5 --help @@ -70,21 +52,42 @@ Specify find timeout in seconds. If 1 or less, \fIippfind\fR stops as soon as it Specifies the IPP version when listing. Supported values are 1.1, 2.0, 2.1, and 2.2. .SH DESCRIPTION -\fIippfind\fR finds printer services registered with the local DNS infrastructure or available through the local links. +\fIippfind\fR finds services registered with a DNS server or available through local devices. Its primary purpose is to find IPP printers and show their URIs, show their current status, or run commands. For example, to show the status of all registered IPP printers on your network, run: +.nf + ippfind --ls +.fi +Similarly, to send a PostScript test page to every PostScript printer, run: +.nf + ippfind --txt-pdl application/postscript --exec ipptool \\ + -f onepage-letter.ps '{}' print-job.test \\; +.fi + +.SH REGISTRATION TYPES +\fIippfind\fR supports the following registration types: +.TP 5 +_http._tcp +HyperText Transport Protocol (HTTP, RFC 2616) +.TP 5 +_https._tcp +Secure HyperText Transport Protocol (HTTPS, RFC 2818) +.TP 5 +_ipp._tcp +Internet Printing Protocol (IPP, RFC 2911) +.TP 5 +_ipps._tcp +Secure Internet Printing Protocol (IPPS, draft) +.TP 5 +_printer._tcp +Line Printer Daemon (LPD, RFC 1179) .SH EXPRESSIONS -\fIippfind\fR supports expressions much like the \fIfind(1)\fR utility. However, unlike \fIfind\fR, \fIippfind\fR uses POSIX regular expressions instead of shell filename matching patterns. If -e, --exec, -l, --ls, -p, --print, --print-name, -q, --quiet, or -s is not specified, \fIippfind\fR adds --print to print the service URI of anything it finds. The following expressions are supported: +\fIippfind\fR supports expressions much like the \fIfind(1)\fR utility. However, unlike \fIfind\fR, \fIippfind\fR uses POSIX regular expressions instead of shell filename matching patterns. If --exec, -l, --ls, -p, --print, --print-name, -q, --quiet, -s, or -x is not specified, \fIippfind\fR adds --print to print the service URI of anything it finds. The following expressions are supported: .TP 5 -d regex .TP 5 --domain regex True if the domain matches the given regular expression. .TP 5 --e utility [argument ...] ; -.TP 5 ---exec utility [argument ...] ; -Executes the specified program if the current result is true. "{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below. -.TP 5 --false Always false. .TP 5 @@ -150,6 +153,11 @@ expression. .TP 5 --uri regex True if the URI matches the given regular expression. +.TP 5 +-x utility [argument ...] ; +.TP 5 +--exec utility [argument ...] ; +Executes the specified program if the current result is true. "{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below. .PP Expressions may also contain modifiers: .TP 5 diff --git a/test/ippfind.c b/test/ippfind.c index d8dfe5f42..588306059 100644 --- a/test/ippfind.c +++ b/test/ippfind.c @@ -806,37 +806,6 @@ main(int argc, /* I - Number of command-line args */ return (IPPFIND_EXIT_MEMORY); break; - case 'e' : - i ++; - if (i >= argc) - { - _cupsLangPrintf(stderr, - _("ippfind: Missing program after %s."), - "-e"); - show_usage(); - } - - if ((temp = new_expr(IPPFIND_OP_EXEC, invert, NULL, NULL, - argv + i)) == NULL) - return (IPPFIND_EXIT_MEMORY); - - while (i < argc) - if (!strcmp(argv[i], ";")) - break; - else - i ++; - - if (i >= argc) - { - _cupsLangPrintf(stderr, - _("ippfind: Missing semi-colon after %s."), - "-e"); - show_usage(); - } - - have_output = 1; - break; - case 'h' : i ++; if (i >= argc) @@ -935,6 +904,37 @@ main(int argc, /* I - Number of command-line args */ return (IPPFIND_EXIT_MEMORY); break; + case 'x' : + i ++; + if (i >= argc) + { + _cupsLangPrintf(stderr, + _("ippfind: Missing program after %s."), + "-x"); + show_usage(); + } + + if ((temp = new_expr(IPPFIND_OP_EXEC, invert, NULL, NULL, + argv + i)) == NULL) + return (IPPFIND_EXIT_MEMORY); + + while (i < argc) + if (!strcmp(argv[i], ";")) + break; + else + i ++; + + if (i >= argc) + { + _cupsLangPrintf(stderr, + _("ippfind: Missing semi-colon after %s."), + "-x"); + show_usage(); + } + + have_output = 1; + break; + default : _cupsLangPrintf(stderr, _("%s: Unknown option \"-%c\"."), "ippfind", *opt); @@ -2729,8 +2729,6 @@ show_usage(void) _cupsLangPuts(stderr, _("Expressions:")); _cupsLangPuts(stderr, _(" -P number[-number] Match port to number or range.")); _cupsLangPuts(stderr, _(" -d regex Match domain to regular expression.")); - _cupsLangPuts(stderr, _(" -e utility [argument ...] ;\n" - " Execute program if true.")); _cupsLangPuts(stderr, _(" -h regex Match hostname to regular expression.")); _cupsLangPuts(stderr, _(" -l List attributes.")); _cupsLangPuts(stderr, _(" -n regex Match service name to regular expression.")); @@ -2740,6 +2738,8 @@ show_usage(void) _cupsLangPuts(stderr, _(" -s Print service name if true.")); _cupsLangPuts(stderr, _(" -t key True if the TXT record contains the key.")); _cupsLangPuts(stderr, _(" -u regex Match URI to regular expression.")); + _cupsLangPuts(stderr, _(" -x utility [argument ...] ;\n" + " Execute program if true.")); _cupsLangPuts(stderr, _(" --domain regex Match domain to regular expression.")); _cupsLangPuts(stderr, _(" --exec utility [argument ...] ;\n" " Execute program if true.")); diff --git a/tools/makeipptoolpkg b/tools/makeipptoolpkg index df0b1d8c2..1428257e4 100644 --- a/tools/makeipptoolpkg +++ b/tools/makeipptoolpkg @@ -52,7 +52,7 @@ mkdir $pkgdir || exit 1 echo Copying package files cp CHANGES-IPPTOOL.txt IPPTOOL.txt LICENSE.txt $pkgdir -cp doc/help/man-ipptool*.html $pkgdir +cp doc/help/man-ipp*.html $pkgdir cp test/color.jpg $pkgdir cp test/create-printer-subscription.test $pkgdir cp test/document-*.pdf $pkgdir @@ -64,6 +64,7 @@ cp test/get-subscriptions.test $pkgdir cp test/gray.jpg $pkgdir cp test/ipp-[12].*.test $pkgdir cp test/ipp-everywhere.test $pkgdir +cp test/ippfind-static $pkgdir/ippfind cp test/ipptool-static $pkgdir/ipptool cp test/onepage-*.pdf $pkgdir cp test/onepage-*.ps $pkgdir -- 2.39.2