.::libptal(3)

NAME

hpoj reference: PTAL API

DESCRIPTION

This document explains the C-language application programming interface to PTAL, the Peripheral Transport Abstraction Library, which is one of the major components of the hpoj software. See the Device protocols
page for background information. You need to include the line
""#include <ptal.h>"" in your program to include the necessary
"#define"s, "typedef"s, and function prototypes. Macros and other
"#define"s Unless otherwise specified, functions with an "int" return
type return the symbolic constant "PTAL_ERROR" (-1) on failure. On
success, they either return "PTAL_OK" (0), or any integer value other
than "PTAL_ERROR", depending on the function. Functions with a pointer return type return "NULL" (zero) on error, although "NULL" is not
defined in "ptal.h". For your convenience, the following macros are
provided for converting between native integers and "short"s/"long"s
stored in ""unsigned char"" arrays as big-endian or little-endian:

· BEND_GET_SHORT(s)

· BEND_GET_LONG(s)

· BEND_SET_SHORT(s,x)

· BEND_SET_LONG(s,x)

· LEND_GET_SHORT(s)

· LEND_GET_LONG(s)

· LEND_SET_SHORT(s,x)

· LEND_SET_LONG(s,x)

The ""s"" parameter is the character array. The "GET" macros return
the native integer value, and the "SET" macros take the native integer value as the ""x"" parameter. "typedef"s The following opaque pointer types are used:

· "ptalDevice_t" -- Contains the state of a device.

· "ptalChannel_t" -- Contains the state of a channel, which may or

may not currently be open.

· "ptalPmlObject_t" -- Instantiated for, and contains the state of,

each PML object you access on a given device.

Logging and debugging The following macros may be called for errorreporting or debugging purposes:

· "PTAL_LOG_ERROR(args...)" -- log level 0

· "PTAL_LOG_WARN(args...)" -- log level 1

· "PTAL_LOG_DEBUG(args...)" -- log level 2

The variable argument list is the same as is passed to the standard
"printf()" function. What actually gets logged (to standard error)
depends on the setting of the "PTAL_DEBUG" environment variable.
Setting it to -1 or lower disables all logging, setting it to 0 (or not setting it at all) logs only errors, setting it to 1 logs errors and
warnings, and setting it to 2 or higher logs everything.
Initialization and deinitialization

int ptalInit(void); int ptalDone(void);

Call "ptalInit()" when your application starts up before using PTAL;
this reads from "/etc/ptal" information on devices which have been
registed using ""ptal-init setup"". Call "ptalDone()" when finished
with PTAL before exiting. Opening, closing, and deleting devices

ptalDevice_t ptalDeviceOpen(char *name); int
ptalDeviceClose(ptalDevice_t dev); int ptalDeviceDelete(ptalDevice_t
dev); char *ptalDeviceGetName(ptalDevice_t dev);

Given a PTAL device name string, such as "mlc:usb:OfficeJet_G85",
"ptalDeviceOpen()" creates if necessary and returns a "ptalDevice_t"
pointer, which you pass to other functions that need to refer to that
device. If you pass a NULL device-name pointer, then the default
device is returned. If the return value was NULL, then the specified
or default device is not valid. "ptalDeviceClose()" closes/deallocates all channels and PML objects associated with the device, but leaves the "ptalDevice_t" pointer intact. On the other hand, "ptalDeviceDelete()" also deletes the "ptalDevice_t" pointer. "ptalDeviceGetName()" returns a pointer to the PTAL device name string associated with the given
device. Don't modify the string! Device ID string retrieval and
parsing

int ptalDeviceGetDeviceIDString(ptalDevice_t dev,char *buffer,int
maxlen); int ptalDeviceGetPreviousDeviceIDString(ptalDevice_t dev, char *buffer,int maxlen);

"ptalDeviceGetDeviceIDString()" attempts to retrieve the (nullterminated) device ID string for the given device into "buffer", up to "maxlen" characters. "ptalDeviceGetPreviousDeviceIDString()" is almost the same, except it attempts to retrieve the previous (as opposed to
current) device ID string. If successful, then you can pass "buffer"
as the first parameter to the following parse functions:

int ptalDeviceIDGetField(char *_devID,char *field, char **pValue,int
*pLenValue); int ptalDeviceIDGetEitherField(char *devID,char
*field1,char *field2, char **pValue,int *pLenValue); void
ptalDeviceIDPruneField(char **pValue,int *pLenValue);

"ptalDeviceIDGetField()" and "ptalDeviceIDGetEitherField()" search for a specific field (or either of two fields). If successful, *pValue is set to the start of the field, and *pLenValue is set to the field
length, including the leading field name and colon and the trailing
semicolon (if any). "ptalDeviceIDPruneField()" alters the field start and length to "prune" the leading and trailing stuff, leaving you with just the value part of the field between the colon and semicolon. The following functions may be called to search for specific common fields:

int ptalDeviceIDGetManufacturer(char *devID,char **pValue,int
*pLenValue); int ptalDeviceIDGetModel(char *devID,char **pValue,int
*pLenValue); int ptalDeviceIDGetCommandSet(char *devID,char
**pValue,int *pLenValue); int ptalDeviceIDGetSerialNumber(char
*devID,char **pValue,int *pLenValue);

Channel allocate and deallocate functions

ptalChannel_t ptalChannelAllocate(ptalDevice_t dev); ptalChannel_t
ptalChannelFindOrAllocate(ptalDevice_t dev, int serviceType,int
socketID,char *serviceName); int ptalChannelDeallocate(ptalChannel_t
chan);

"ptalChannelAllocate()" creates and returns a new "ptalChannel_t"
pointer, which you pass to other functions that need to refer to that
channel. "ptalChannelFindOrAllocate()" searches for a channel that has already been allocated on the given device and set to the given remote service parameters (see "ptalChannelSetRemoteService()" below). If
found, it returns the previously-allocated channel, but if not found,
then it allocates it and sets the given remote service parameters.
"ptalChannelDeallocate()" closes (if necessary) and deallocates the
channel pointer. Channel setup functions

int ptalChannelGetRemoteService(ptalChannel_t chan, int
*pServiceType,int *pSocketID,char **pServiceName); int
ptalChannelSetRemoteService(ptalChannel_t chan, int serviceType,int
socketID,char *serviceName);

"ptalChannelSetRemoteService()" specifies what socket/service to
connect to on the peripheral. The "serviceType" parameter may be one
of the following:

· "PTAL_STYPE_PRINT" -- The print service.

· "PTAL_STYPE_SCAN" -- The scan service.

· "PTAL_STYPE_GENERIC" -- Any other service. In this case,

"serviceName" is the 1284.4 service name string such as "ECHO", or "NULL" for none, and "socketID" is the socket ID such as 6, or 0
for none.

int ptalChannelSetPacketSizes(ptalChannel_t chan, int desiredHPSize,int desiredPHSize); int ptalChannelAdjustPacketSizes(ptalChannel_t chan,
int *pDesiredHPSize,int *pDesiredPHSize);

"ptalChannelSetPacketSizes()" requests the given host-to-peripheral and peripheral-to-host packet sizes, not including any added protocol
overhead, such as the MLC/1284.4 6-byte header.
"ptalChannelAdjustPacketSizes()" may be called after opening the
channel, passing pointers to the same requested packet sizes which were passed to "ptalChannelSetPacketSizes()". If either actual packet size ended up being lower than the requested packet size, then the value is reduced accordingly. Note that it's not guaranteed that your requested packet sizes will be honored or that it's possible to even determine
the actual packet sizes.

int ptalChannelSetErrorHandling(ptalChannel_t chan, int retryCount,int retryDelay);

"ptalChannelSetErrorHandling()" sets "retryCount" and "retryDelay" (in seconds) that may be used to retry certain types of open failures,
depending on the particular provider. A negative "retryCount" means
retry forever. Channel open and close functions

int ptalChannelIsOpen(ptalChannel_t chan); int
ptalChannelOpen(ptalChannel_t chan); int
ptalChannelOpenOrReopen(ptalChannel_t chan); int
ptalChannelClose(ptalChannel_t chan);

"ptalChannelIsOpen()" returns nonzero if the channel is already open or zero if not. "ptalChannelOpen()" attempts to open the channel if it's not already open. "ptalChannelOpenOrReopen()" also first closes the
channel if it happens to be "stale" (closed remotely, see
"ptalChannelIsStale()" below). "ptalChannelClose()" closes the channel if it is currently open. Channel data transfer functions

int ptalFdPrepareForSelect(int fd,int *pn, fd_set *prset,fd_set
*pwset,fd_set *pxset); int ptalChannelPrepareForSelect(ptalChannel_t
chan, int *pfd,int *pn,fd_set *prset,fd_set *pwset,fd_set *pxset); int ptalChannelSelect(ptalChannel_t chan,int *pr,int *pw,int *px, struct
timeval *timeout);

"ptalFdPrepareForSelect()" and "ptalChannelPrepareForSelect()" take an arbitrary file descriptor or a channel, respectively, and add the
(corresponding) file descriptor to each of the file descriptor sets
with a non-"NULL" pointer. In addition, the *pn parameter is set to
the maximum of the current value or the file descriptor if "pn" is
non-"NULL". For "ptalChannelPrepareForSelect()", *pfd is set to the
corresponding file descriptor if "pfd" is non-"NULL".
"ptalChannelSelect()" is a somewhat simpler "select()" wrapper for a
single channel. Instead of file descriptor sets, the ""int *pX""
parameters may be set to nonzero if "select()" should check for
read/write/exception activity, or zero (or "NULL" pointer) if not; the resulting values of these variables are nonzero if the channel is ready for the corresponding activity and zero if not. As with "select()",
the ""struct timeval *timeout"" parameter is "NULL" for an infinite
timeout.

int ptalChannelRead(ptalChannel_t chan,char *buffer,int count); int
ptalChannelWrite(ptalChannel_t chan,char *buffer,int count);

"ptalChannelRead()" and "ptalChannelWrite()" read/write data on the
channel, generally using standard "read()" and "write()" semantics.
They return the number of bytes read or written, or "PTAL_ERROR" on an error.

int ptalChannelIsStale(ptalChannel_t chan); int
ptalChannelReadTimeout(ptalChannel_t chan,char *buffer,int countdown,
struct timeval *startTimeout,struct timeval *continueTimeout); int
ptalChannelFlush(ptalChannel_t chan, struct timeval
*startTimeout,struct timeval *continueTimeout);

"ptalChannelIsStale()" returns nonzero if the channel is "stale", or in other words, has been closed remotely. It may consume a byte of data, so don't call it if you intend to read afterwards data that may be
waiting. "ptalChannelReadTimeout()" and "ptalChannelFlush()" read data in a loop until the given timeout runs out, and so are less sensitive
to the "partial read" phenomenon that you may experience with
"ptalChannelRead()" due to packet boundaries on the underlying link.
"ptalChannelReadTimeout()" reads into the "buffer" a maximum of
"countdown" bytes, and "ptalChannelFlush()" discards all data received within the given timeout constraints. "startTimeout" is the timeout
for reading the first packet of data, and "continueTimeout" is the
timeout for reading successive packets of data. PML open and close
functions

int ptalPmlOpen(ptalDevice_t dev); int ptalPmlClose(ptalDevice_t dev);

"ptalPmlOpen()" is called to open the PML channel before you use it,
and "ptalPmlClose()" is called to close the PML channel when you're
done. PML object allocate and deallocate functions

ptalPmlObject_t ptalPmlAllocate(ptalDevice_t dev); ptalPmlObject_t
ptalPmlAllocateID(ptalDevice_t dev,char *oid); int
ptalPmlDeallocate(ptalPmlObject_t obj); int
ptalPmlDeallocateAll(ptalDevice_t dev);

"ptalPmlAllocate()" allocates and returns a pointer to a new PML object tied to the specified device. "ptalPmlAllocateID()" also initializes
the object ID to the given binary object ID (see "ptalPmlSetID()"
below). "ptalPmlDeallocate()" deallocates the previously-allocated PML object, and "ptalPmlDeallocateAll()" deallocates all PML objects
allocated on the given device. PML object ID functions

int ptalPmlSetID(ptalPmlObject_t obj,char *oid); int
ptalPmlSetAsciiID(ptalPmlObject_t obj,char *s); int
ptalPmlGetID(ptalPmlObject_t obj,char *buffer,int maxlen);

"ptalPmlSetID()" sets the given binary object ID, and
"ptalPmlSetAsciiID()" sets the given ASCII (dotted-decimal) object ID. "ptalPmlGetID()" retrieves the object ID in binary form into the given "buffer" up to "maxlen" bytes. For example, to set the object ID
"1.2.2.1.12", you could call one of the following functions:

ptalPmlSetID(obj,"\x1\x2\x2\x1\xC"); /* binary */
ptalPmlSetAsciiID(obj,"1.2.2.1.12"); /* ASCII */

PML data types The following symbolic constants are defined for PML
data types. "Basically" integer types:

· PTAL_PML_TYPE_ENUMERATION

· PTAL_PML_TYPE_SIGNED_INTEGER

· PTAL_PML_TYPE_COLLECTION

"Basically" character-array types:

· PTAL_PML_TYPE_STRING

· PTAL_PML_TYPE_BINARY

PML SET functions To set a PML object on the peripheral, you must:

· Allocate a "ptalPmlObject_t" and set the object ID, if you haven't

already.

· Set the value into the "ptalPmlObject_t".

· Call "ptalPmlRequestSet()" to request the SET operation.

· Check the status (see below).

int ptalPmlSetValue(ptalPmlObject_t obj,int type,char *value,int
len); int ptalPmlSetStringValue(ptalPmlObject_t obj,int symbolSet, char *value,int len); int ptalPmlSetIntegerValue(ptalPmlObject_t
obj,int type,int value); int ptalPmlRequestSet(ptalPmlObject_t
obj);

"ptalPmlSetValue()" sets a "PTAL_PML_TYPE_BINARY" value.
"ptalPmlSetStringValue()" sets a PTAL_PML_TYPE_STRING value. It's probably safe to specify zero for the symbol set, or you can pass
one of "PTAL_PML_SYMSET_0E", "PTAL_PML_SYMSET_ROMAN8", or another
constant defined in "ptal.h". Pass zero for the "len" parameter if the string is null-terminated. "ptalPmlSetIntegerValue()" sets a
"PTAL_PML_TYPE_ENUMERATION", "PTAL_PML_TYPE_SIGNED_INTEGER", or
"PTAL_PML_TYPE_COLLECTION" value. PML GET functions To get a PML
object on the peripheral, you must:

· Allocate a "ptalPmlObject_t" and set the object ID, if you haven't

already.

· Call "ptalPmlRequestGet()" to request the GET operation.

· Check the status (see below).

· Get the value out of the "ptalPmlObject_t" if the operation was

successful.

int ptalPmlRequestGet(ptalPmlObject_t obj,ptalPmlObject_t next);
int ptalPmlGetValue(ptalPmlObject_t obj,int *pType,char *buffer,int maxlen); int ptalPmlGetStringValue(ptalPmlObject_t obj,int
*pSymbolSet, char *buffer,int maxlen); int
ptalPmlGetIntegerValue(ptalPmlObject_t obj,int *pType,int *pValue);
int ptalPmlDoLastValuesDiffer(ptalPmlObject_t obj);

"ptalPmlGetValue()" gets the binary value for any type, which
probably is not what you want for any type other than binary.
However, it can be a useful starting point for determine what data type the value is. "ptalPmlGetStringValue()" and
"ptalPmlGetIntegerValue()" get string and integer data types,
respectively. They succeed even if the actual value has an
incompatible data type, but the result may not be meaningful.
"ptalPmlDoLastValuesDiffer()" returns nonzero if the last two
cached values of the PML object differ, for example, between two
GETs. Checking status from a PML GET or SET

int ptalPmlGetStatus(ptalPmlObject_t obj);

"ptalPmlGetStatus()" returns that PML status code from the last
"ptalPmlRequestSet()" or "ptalPmlRequestGet()" call. The following successful status values are defined:

· PTAL_PML_OK

· PTAL_PML_OK_END_OF_SUPPORTED_OBJECTS

· PTAL_PML_OK_NEAREST_LEGAL_VALUE_SUBSTITUTED

The following unsuccessful status values are defined:

· PTAL_PML_ERROR_UNKNOWN_REQUEST

· PTAL_PML_ERROR_BUFFER_OVERFLOW

· PTAL_PML_ERROR_COMMAND_EXECUTION_ERROR

· PTAL_PML_ERROR_UNKNOWN_OBJECT_IDENTIFIER

· PTAL_PML_ERROR_OBJECT_DOES_NOT_SUPPORT_REQUESTED_ACTION

· PTAL_PML_ERROR_INVALID_OR_UNSUPPORTED_VALUE

· PTAL_PML_ERROR_PAST_END_OF_SUPPORTED_OBJECTS

· PTAL_PML_ERROR_ACTION_CAN_NOT_BE_PERFORMED_NOW

· PTAL_PML_ERROR_SYNTAX_ERROR

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 452:

'=item' outside of any '=over'

current October 8, 2008 .::libptal(3)