ReadPort 函数 (winsplp.h)

项目
02/27/2024

端口监视器的 ReadPort 函数从打印机端口读取数据。

语法

BOOL ReadPort(
  _In_  HANDLE  hPort,
  _Out_ LPBYTE  pBuffer,
        DWORD   cbBuffer,
  _Out_ LPDWORD pcbRead
);

参数

[in] hPort

调用方提供的端口句柄。

[out] pBuffer

调用方提供的指向缓冲区的指针，用于接收从端口读取的数据。

cbBuffer

pBuffer 的调用方提供的大小（以字节为单位）。

[out] pcbRead

调用方提供的指针指向要接收从端口成功读取的字节数的位置。

返回值

如果操作成功，函数应返回 TRUE。否则应返回 FALSE。

注解

需要语言监视器和端口监视器服务器 DLL 来定义 ReadPort 函数，并将函数的地址包含在 MONITOR2 结构中。

作为函数的 hPort 参数接收的句柄是监视器的 OpenPort 或 OpenPortEx 函数提供的端口句柄。

通常，语言监视器的 ReadPort 函数调用关联的端口监视器的 ReadPort 函数，并将获取的缓冲区内容返回给调用方。

此外，语言监视器可能会创建一个单独的线程，用于调用端口监视器的ReadPort函数来检查未经请求的状态信息。如果此类读取操作成功，应通过调用 Microsoft Windows SDK 文档) 中所述的 SetPort (将状态信息返回到后台处理程序。

通常，端口监视器服务器 DLL 的ReadPort函数调用 Windows SDK 文档) 中所述的 ReadFile (，以从内核模式端口驱动程序获取数据。函数只是将数据返回给调用方。

尽管语言监视器和端口监视器都必须定义 ReadPort 函数并将其地址置于MONITOR2结构中，但后台处理程序或应用程序从未实际调用语言监视器的 ReadPort 函数。函数仅用于语言监视器本身的内部使用。

例如，pjlmon.dll，示例语言监视器创建一个单独的线程，该线程调用自己的ReadPort线程来watch未经请求的打印机状态信息，函数ReadPort调用端口监视器的 ReadPort 函数。当端口监视器将数据返回到语言监视器时，语言监视器将分析收到的数据，并调用 Windows SDK 文档) 中所述的 SetPort (，以将状态信息发送到后台处理程序。

函数应通过将数字放置在由读指向的位置来返回成功读取的字节数。调用方通过检查 ReadPort's 返回值（而不是返回的字节计数）来确定写入操作的成功或失败。因此，返回的字节计数为零并不表示读取失败，除非函数返回 FALSE。

某种系统实现或监视实现的超时机制必须确保 ReadPort 函数将在合理的时间内返回，以避免后台处理程序停止。

语言监视器可以在 StartDocPort EndDocPort/ 对之外调用端口监视器的ReadPort例程。 (此类调用可能是由线程检查未经请求的状态生成的。) 但是，某些端口监视器可能会使此类调用失败，因此必须编写语言监视器来处理此失败。