A port monitor's
ReadPort function reads data from a printer port.
BOOL ReadPort( _In_ HANDLE hPort, _Out_ LPBYTE pBuffer, DWORD cbBuffer, _Out_ LPDWORD pcbRead );
Caller-supplied port handle.
Caller-supplied pointer to a buffer to receive data read from the port.
Caller-supplied size, in bytes, of pBuffer.
Caller-supplied pointer to a location to receive the number of bytes successfully read from the port.
If the operation succeeds, the function should return TRUE. Otherwise it should return FALSE.
Typically, a language monitor's
ReadPort function calls the associated port monitor's
ReadPort function, and returns the obtained buffer contents to the caller.
Additionally, a language monitor might create a separate thread that calls the port monitor's
ReadPort function to check for unsolicited status information. If such a read operation succeeds, the status information should be returned to the spooler by calling SetPort (described in the Microsoft Windows SDK documentation).
Typically, a port monitor server DLL's
ReadPort function calls ReadFile (described in the Windows SDK documentation) to obtain data from the kernel-mode port driver. The function just returns the data to the caller.
Even though both language monitors and port monitors must define
ReadPort functions and place their addresses in MONITOR2 structures, a language monitor's
ReadPort function is never actually called by the spooler or an application. The function is solely for the internal use of the language monitor itself.
For example pjlmon.dll, the sample language monitor, creates a separate thread that calls its own
ReadPort to watch for unsolicited printer status information, and the
ReadPort function calls the port monitor's
ReadPort function. When the port monitor returns data to the language monitor, the language monitor parses the received data and calls SetPort (described in the Windows SDK documentation) to send status information to the spooler.
The function should return the number of bytes successfully read by placing the number in the location pointed to by pcbRead. The caller determines the success or failure of the write operation by checking
ReadPort's return value, not the returned byte count. So a returned byte count of zero does not represent a failed read unless the function returns FALSE.
Some sort of system-implemented or monitor-implemented time-out mechanism must ensure that the
ReadPort function will return within a reasonable amount of time, to avoid stalling the spooler.
It is acceptable for a language monitor to call a port monitor's
ReadPort routine outside of a StartDocPort/EndDocPort pair. (Such a call might be generated by a thread checking for unsolicited status.) However, some port monitors might fail such a call, so the language monitor must be written to handle this failure.
|Header||winsplp.h (include Winsplp.h)|