XcvDataPort 函数 (winsplp.h)

项目
03/05/2024

端口监视器服务器 DLL 的 XcvDataPort 函数从端口监视器的 UI DLL 接收信息，并将信息返回给端口监视器的 UI DLL。

语法

DWORD XcvDataPort(
  _In_  HANDLE  hXcv,
  _In_  LPCWSTR pszDataName,
  _In_  PBYTE   pInputData,
        DWORD   cbInputData,
  _Out_ PBYTE   pOutputData,
        DWORD   cbOutputData,
  _Out_ PDWORD  pcbOutputNeeded
);

参数

[in] hXcv

调用方提供的打印机句柄，通过调用 openPrinter (获取，如Microsoft Windows SDK文档) 中所述。此句柄由 XcvOpenPort 函数创建并返回。

[in] pszDataName

调用方提供的指向表示所请求数据名称的字符串的指针。有关更多信息，请参见下面的“备注”部分。

[in] pInputData

调用方提供的指向包含输入数据的缓冲区的指针。

cbInputData

pInputData 指向的缓冲区的调用方提供的大小（以字节为单位）。

[out] pOutputData

调用方提供的指向用于接收输出数据的缓冲区的指针。

cbOutputData

pOutputData 指向的缓冲区的调用方提供的大小（以字节为单位）。

[out] pcbOutputNeeded

调用方提供的指针，指向接收 pOutputData 指向的缓冲区所需的最小大小（以字节为单位）的位置。

返回值

如果操作成功，此函数应返回ERROR_SUCCESS。否则，它应返回前缀为 ERROR_ 的 Win32 错误代码。打印监视器 UI DLL 在为 XcvData 指定的 pdwStatus 位置接收此值。

注解

需要端口监视器服务器 DLL 来定义 XcvDataPort 函数，以便它们可以从端口监视器 UI DLL 接收信息并将信息返回给端口监视器 UI DLL。函数的地址必须包含在 MONITOR2 结构中。

XcvDataPort 函数由后台处理程序的 XcvData 函数调用。 XcvDataPort 和 XcvData 的函数参数几乎相同。 (XcvData 具有 XcvDataPort.)

pszDataName 指向的字符串指定要执行的操作。函数必须识别以下数据名称字符串：

数据名称字符串	操作
L“AddPort”	已发送添加端口所需的所有信息。函数应执行添加指定端口所需的操作，包括在注册表中的端口键下写入端口名称。 pInputData 参数指向以 NULL 结尾的端口名称字符串。如果函数返回ERROR_SUCCESS，则后台处理程序会将端口标记为已添加。此字符串由打印监视器 UI DLL 在其 AddPortUI 函数中指定。
L“DeletePort”	删除端口所需的所有信息都已发送。函数应执行删除指定端口所需的操作，包括从注册表的 Ports 键中删除端口名称。 pInputData 参数指向以 NULL 结尾的端口名称字符串。如果函数返回ERROR_SUCCESS，则后台处理程序会将端口标记为已删除。此字符串由打印监视器 UI DLL 在其 DeletePortUI 函数中指定。
L“MonitorUI”	函数应使用 pOutputData 返回关联的端口监视器 UI DLL 的名称。当应用程序调用 Microsoft Windows SDK AddPort 函数时，此字符串由打印后台处理程序指定。

通常，编写函数可识别 UI DLL 在其 AddPortUI、ConfigurePortUI 和 DeletePortUI 函数中发送的其他自定义字符串。这些字符串可能表示从服务器 DLL 请求当前配置值的命令，或提供新值的命令。例如， XcvDataPort 函数可以识别字符串“GetTransmissionRetryTimeout”，UI DLL 可以将其发送到服务器 DLL 以请求当前存储的传输重试超时值。或者，可以定义一组在发送“AddPort”或“DeletePort”之前必须发送的字符串，其中字符串用于提供标识要添加或删除的端口的信息。

对于给定 的 pszDataName 字符串和输入缓冲区，可能首先调用 xcvDataPort ，其 cbOutputData 值为零。该函数应返回 所需的缓冲区大小（以ERROR_INSUFFICIENT_BUFFER为单位），同时返回ERROR_INSUFFICIENT_BUFFER。调用方可以使用 在pcbOutputNeeded 中接收的值来分配足够大小的输出缓冲区，然后可以再次调用 XcvDataPort ，这次在 cbOutputData 中指定分配的缓冲区大小。

XcvDataPort 函数必须验证所有输入参数。具体而言，函数必须：

验证 pszDataName 参数指向的字符串的内容。如果此字符串表示通常 (添加、删除或配置端口) 的管理操作， 则 XcvDataPort 函数应将 XcvOpenPort 函数以前接收的已授权访问掩码与SERVER_ACCESS_ADMINISTER进行比较。如果比较失败， XcvDataPort 必须返回ERROR_ACCESS_DENIED。
验证 pInputData 参数指向的缓冲区的内容。当后台处理程序调用 XcvOpenPort 函数时，它不会对此缓冲区的内容执行验证。监视器不能对此数据的有效性做出任何假设，这些数据可能来自恶意应用程序。

如果要编写与 TCPMON 通信的端口监视器，请参阅 TCPMON Xcv 接口。