Perl IPP API
============
This API can be used to send Internet Printing Protocol requests and receive
the corresponding responses.
Currently not implemented is the collection syntax as specified in [RFC 3382].
A Warning will appear if an IPP response contains a collection attribute.
All other IPP related Operations and Types should work as described in the RFCs.
You can use this API in two different ways:
1. build your own IPP requests: This is the low level access to the API.
Principally you look at the RFC which attributes a specific IPP request requires,
encode all required and optional attributes as shown in sample/ipptest.pl and let
Net::IPP::IPPRequest::ippRequest($request) do the rest.
2. Use the functions in Net::IPP::IPPMethods: This is the high level access to the API.
Some IPP Operations have already been implemented in IPPMethods. You can for example
use getPrinterAttributes($url) to get all attributes of a printer object, and you only
need to know the URL of the printer. For more examples read/run the programs
sample/printerAttributes.pl and sample/showJobs.pl.
You can of course mix both methods as the functions in IPPMethods are just wrappers around
ippRequest.
Every important line in the sample programs is commented, so you really should read them...
INSTALLATION
To install this module type the following:
perl Makefile.PL
make
make test
make install
RUNNING TESTS
To run all tests in the t/ directory type the following:
make test
For more details while running the tests type:
make TEST_VERBOSE=1 test
RUNNING SAMPLES
After installation all programs in the sample directory should run
without problems. To run the sample programs without installing this
package use the blib module:
perl Makefile.PL
make
cd samples
perl -Mblib sampleprogram.pl [arguments]
STRUCTURE
+------------+
| IPPMethods |
+------------+
^
|
+------------+
| IPPRequest |
+------------+
^
|
+-------------+---+-----------+
| | |
+--------------+ +---------+ +-----+
| IPPAttribute | | IPPUtil | | IPP |
+--------------+ +---------+ +-----+
WHAT TO DO, IF
1. you get the error "Error: Unknown attribute xyz used in request.":
The API did not find a default IPP type for attribute xyz in the hash
Net::IPP::IPPAttribute::attributeTypes.
Method 1 (workaround): Look in [RFC 2911] which type attribute xyz has. It may
f.e. have the type XYZ. If you used something like
"xyz" => "value",
in the IPP request before, substitute that with
"xyz" => { &TYPE => &XYZ,
&VALUE => "value" },
Method 2 (permanent solution): Find the attribute type like in Method 1.
Insert the line
"xyz" => &XYZ,
into the hash Net::IPP::IPPAttribute::attributeTypes.
2. you get the warning "Unknown Value type 0x88 for key "xyz". Performing no
transformation.":
While de- or encoding a unknown IPP type was encountered. To permanently add
this type to the API search for the name of this type in the RFCs and add this
type to the IPP type in IPP.pm. You also have to write transform methods for
this IPP type. All value transformations between IPP byte encoding and Perl
encoding are done in transformValue in IPPAttribute.pm. A additional testcase
in t/transform.t would be nice, too.
Alternatively you can ignore this warning if you don't need the value of
attribute xyz or if the value does not need to be transformed.
3. you get the error "ERROR: IPP response is not RFC conform.":
The length check in testLengths() went wrong, the decoding became probably
totally confused some bytes earlier.
Bad Luck, the printer encoded the IPP response wrong (or you just found a bug
in this API). This error simply says that a length field contained a greater
length than the remaining bytes in the response. The API became probably
totally confused much earlier than the offset states.
If the printer is from HP you can try to run the same IPP request with the
HP_BUGFIX option turned on.
4. you get the warning "WARNING: Collection Syntax not supported. Attribute
xyz will have invalid value.":
Implement the collection syntax ;-)
DEPENDENCIES
LWP: IPPRequest.pm uses LWP::UserAgent to send the HTTP Request.
COPYRIGHT AND LICENCE
Copyright (c) 2004 Matthias Hilbig <bighil@cpan.org>
All rights reserved.
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.