ReadPort

BOOL (WINAPI *pfnReadPort)(

HANDLE hPort,
LPBYTE pBuffer,
DWORD cbBuffer,
LPDWORD pcbRead
);

ReadPort reads data from the specified printer port.

Parameters

hPort

Handle to the port from which to read.

pBuffer

Points to a buffer in which data read from the printer can be written.

cbBuffer

Specifies the size, in bytes, of the buffer pointed to by pBuffer.

pcbRead

Points to the location in which to return the number of bytes successfully read from the printer.

Return Value

The return value is TRUE if the function is successful; otherwise it is FALSE.

Comments

ReadPort supports bidirectional printers. If the printer provides any data, this data is written to the buffer pointed to by pBuffer.

If there is no response from the printer, ReadPort waits long enough to ensure there is no data coming, and then returns FALSE. ReadPort should always initialize pcbRead to zero before attempting the port read. If the port read succeeds, pcbRead should be overwritten with the number of bytes read. Note that a port can return zero bytes on a successful read; ReadPort should return TRUE in this situation.

A timeout could be specified by calling a port monitor’s SetPortTimeOuts routine.

Both port and language monitors must implement ReadPort. Typically, a language monitor’s ReadPort function calls the ReadPort function of the port monitor that it is using. The port monitor must return the read data stream to the language monitor without altering the data in any way. The language monitor is then responsible for interpreting the data returned to it.

A language monitor can create a thread to asychronously call the port monitor’s ReadPort function in order to query unsolicited data from the printer at timed intervals. Language monitors might call a port monitor’s ReadPort routine outside of a StartDocPort/EndDocPort pair. Port monitors that do not allow this should fail the call, and language monitors should be written to handle such a failure.

See Also

GetPrinterDataFromPort