ReadPort function (winsplp.h)
A port monitor's ReadPort function reads data from a printer port.
Syntax
BOOL ReadPort(
_In_ HANDLE hPort,
_Out_ LPBYTE pBuffer,
DWORD cbBuffer,
_Out_ LPDWORD pcbRead
);
Parameters
[in] hPort
Caller-supplied port handle.
[out] pBuffer
Caller-supplied pointer to a buffer to receive data read from the port.
cbBuffer
Caller-supplied size, in bytes, of pBuffer.
[out] pcbRead
Caller-supplied pointer to a location to receive the number of bytes successfully read from the port.
Return value
If the operation succeeds, the function should return TRUE. Otherwise it should return FALSE.
Remarks
Language monitors and port monitor server DLLs are required to define a ReadPort function and include the function's address in a MONITOR2 structure.
The handle received as the function's hPort argument is the port handle that the monitor's OpenPort or OpenPortEx function supplied.
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.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Desktop |
| Header | winsplp.h (include Winsplp.h) |
| Library | NtosKrnl.exe |