hpoj reference: PTAL API

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 "CW#include <ptal.h>" in your program to include the necessary CW#defines, CWtypedefs, and function prototypes. Macros and other CW#defines Unless otherwise specified, functions with an CWint return type return the symbolic constant CWPTAL_ERROR (-1) on failure. On success, they either return CWPTAL_OK (0), or any integer value other than CWPTAL_ERROR, depending on the function. Functions with a pointer return type return CWNULL (zero) on error, although CWNULL is not defined in CWptal.h. For your convenience, the following macros are provided for converting between native integers and CWshorts/CWlongs stored in "CWunsigned 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 "CWs parameter is the character array. The GET macros return the native integer value, and the SET macros take the native integer value as the CWx" parameter. CWtypedefs The following opaque pointer types are used:

•

CWptalDevice_t Contains the state of a device.

•

CWptalChannel_t Contains the state of a channel, which may or may not currently be open.

•

CWptalPmlObject_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 error-reporting or debugging purposes:

•

CWPTAL_LOG_ERROR(args...) log level 0

•

CWPTAL_LOG_WARN(args...) log level 1

•

CWPTAL_LOG_DEBUG(args...) log level 2

The variable argument list is the same as is passed to the standard CWprintf() function. What actually gets logged (to standard error) depends on the setting of the CWPTAL_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 CWptalInit() when your application starts up before using PTAL; this reads from CW/etc/ptal information on devices which have been registed using "CWptal-init setup". Call CWptalDone() 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 CW"mlc:usb:OfficeJet_G85", CWptalDeviceOpen() creates if necessary and returns a CWptalDevice_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. CWptalDeviceClose() closes/deallocates all channels and PML objects associated with the device, but leaves the CWptalDevice_t pointer intact. On the other hand, CWptalDeviceDelete() also deletes the CWptalDevice_t pointer. CWptalDeviceGetName() 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);

CWptalDeviceGetDeviceIDString() attempts to retrieve the (null-terminated) device ID string for the given device into CWbuffer, up to CWmaxlen characters. CWptalDeviceGetPreviousDeviceIDString() is almost the same, except it attempts to retrieve the previous (as opposed to current) device ID string. If successful, then you can pass CWbuffer 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);

CWptalDeviceIDGetField() and CWptalDeviceIDGetEitherField() search for a specific field (or either of two fields). If successful, CW*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). CWptalDeviceIDPruneField() 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);

CWptalChannelAllocate() creates and returns a new CWptalChannel_t pointer, which you pass to other functions that need to refer to that channel. CWptalChannelFindOrAllocate() searches for a channel that has already been allocated on the given device and set to the given remote service parameters (see CWptalChannelSetRemoteService() below). If found, it returns the previously-allocated channel, but if not found, then it allocates it and sets the given remote service parameters. CWptalChannelDeallocate() 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);

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

•

CWPTAL_STYPE_PRINT The print service.

•

CWPTAL_STYPE_SCAN The scan service.

•

CWPTAL_STYPE_GENERIC Any other service. In this case, CWserviceName is the 1284.4 service name string such as CW"ECHO", or CWNULL for none, and CWsocketID 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);

CWptalChannelSetPacketSizes() 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. CWptalChannelAdjustPacketSizes() may be called after opening the channel, passing pointers to the same requested packet sizes which were passed to CWptalChannelSetPacketSizes(). 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);

CWptalChannelSetErrorHandling() sets CWretryCount and CWretryDelay (in seconds) that may be used to retry certain types of open failures, depending on the particular provider. A negative CWretryCount 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);

CWptalChannelIsOpen() returns nonzero if the channel is already open or zero if not. CWptalChannelOpen() attempts to open the channel if it's not already open. CWptalChannelOpenOrReopen() also first closes the channel if it happens to be stale (closed remotely, see CWptalChannelIsStale() below). CWptalChannelClose() 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);

CWptalFdPrepareForSelect() and CWptalChannelPrepareForSelect() 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-CWNULL pointer. In addition, the CW*pn parameter is set to the maximum of the current value or the file descriptor if CWpn is non-CWNULL. For CWptalChannelPrepareForSelect(), CW*pfd is set to the corresponding file descriptor if CWpfd is non-CWNULL. CWptalChannelSelect() is a somewhat simpler CWselect() wrapper for a single channel. Instead of file descriptor sets, the "CWint *pCIXCW" parameters may be set to nonzero if CWselect() should check for read/write/exception activity, or zero (or CWNULL 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 CWselect(), the "CWstruct timeval *timeout" parameter is CWNULL for an infinite timeout.

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

CWptalChannelRead() and CWptalChannelWrite() read/write data on the channel, generally using standard CWread() and CWwrite() semantics. They return the number of bytes read or written, or CWPTAL_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);

CWptalChannelIsStale() 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. CWptalChannelReadTimeout() and CWptalChannelFlush() 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 CWptalChannelRead() due to packet boundaries on the underlying link. CWptalChannelReadTimeout() reads into the CWbuffer a maximum of CWcountdown bytes, and CWptalChannelFlush() discards all data received within the given timeout constraints. CWstartTimeout is the timeout for reading the first packet of data, and CWcontinueTimeout is the timeout for reading successive packets of data. PML open and close functions

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

CWptalPmlOpen() is called to open the PML channel before you use it, and CWptalPmlClose() 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);

CWptalPmlAllocate() allocates and returns a pointer to a new PML object tied to the specified device. CWptalPmlAllocateID() also initializes the object ID to the given binary object ID (see CWptalPmlSetID() below). CWptalPmlDeallocate() deallocates the previously-allocated PML object, and CWptalPmlDeallocateAll() 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);

CWptalPmlSetID() sets the given binary object ID, and CWptalPmlSetAsciiID() sets the given ASCII (dotted-decimal) object ID. CWptalPmlGetID() retrieves the object ID in binary form into the given CWbuffer up to CWmaxlen 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 CWptalPmlObject_t and set the object ID, if you haven't already.

•

Set the value into the CWptalPmlObject_t.

•

Call CWptalPmlRequestSet() 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);

CWptalPmlSetValue() sets a CWPTAL_PML_TYPE_BINARY value. CWptalPmlSetStringValue() sets a PTAL_PML_TYPE_STRING value. It's probably safe to specify zero for the symbol set, or you can pass one of CWPTAL_PML_SYMSET_0E, CWPTAL_PML_SYMSET_ROMAN8, or another constant defined in CWptal.h. Pass zero for the CWlen parameter if the string is null-terminated. CWptalPmlSetIntegerValue() sets a CWPTAL_PML_TYPE_ENUMERATION, CWPTAL_PML_TYPE_SIGNED_INTEGER, or CWPTAL_PML_TYPE_COLLECTION value. PML GET functions To get a PML object on the peripheral, you must:

•

Allocate a CWptalPmlObject_t and set the object ID, if you haven't already.

•

Call CWptalPmlRequestGet() to request the GET operation.

•

Check the status (see below).

•

Get the value out of the CWptalPmlObject_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);

CWptalPmlGetValue() 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. CWptalPmlGetStringValue() and CWptalPmlGetIntegerValue() 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. CWptalPmlDoLastValuesDiffer() 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);

CWptalPmlGetStatus() returns that PML status code from the last CWptalPmlRequestSet() or CWptalPmlRequestGet() 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