AddPortUI 函数 (winsplp.h)

项目
08/08/2023

端口监视器 UI DLL 的 AddPortUI 函数添加打印机端口，然后从用户获取端口配置信息并将其发送到端口监视器服务器 DLL。

语法

BOOL AddPortUI(
  [in, optional]  PCWSTR pszServer,
  [in]            HWND   hWnd,
                  PCWSTR pszMonitorNameIn,
  [out, optional] PWSTR  *ppszPortNameOut
);

参数

[in, optional] pszServer

调用方提供的指向表示服务器名称的字符串的指针;如果打印机是本地的，则为 NULL 。

[in] hWnd

应用作对话框的父窗口的调用方提供的句柄。如果 为 NULL，则不应显示任何对话框。

pszMonitorNameIn

调用方提供的指针，指向表示监视器名称的字符串。可以为 NULL。

[out, optional] ppszPortNameOut

调用方提供的指向要接收端口名称字符串的位置的指针。可以为 NULL，在这种情况下，不返回名称。

返回值

如果操作成功，函数应返回 TRUE。否则，应调用 SetLastError 以指定错误代码，并且函数应返回 FALSE。如果操作被用户取消或不受支持，则函数应调用 SetLastError (ERROR_CANCELLED) ，然后返回 FALSE。

注解

需要端口监视器 UI DLL 来定义 AddPortUI 函数，并将函数的地址包含在 MONITORUI 结构中。

后台处理程序从其 AddPort 函数中调用 AddPortUI。 AddPortUI 接收的前三个参数是 AddPort 接收的参数。 (Microsoft Windows SDK 文档中介绍了 AddPort 函数。)

函数应执行以下操作：

调用 OpenPrinter，指定具有以下格式的打印机名称：

\\ServerName\，XcvMonitorMonitorName

其中 ，ServerName 和 MonitorName 是作为 AddPortUI 函数参数接收的服务器和监视器名称。

调用 OpenPrinter 需要PRINTER_DEFAULTS结构，如 Windows SDK 文档中所述。结构的 DesiredAccess 成员必须设置为 SERVER_ACCESS_ADMINISTER。其 pDatatype 和 pDevMode 成员可以为 NULL。

此调用会导致调用打印监视器服务器 DLL 的 XcvOpenPort 函数。
通过显示对话框从用户获取端口名称。
调用 XcvData，指定以下输入参数：
- 从 OpenPrinter 接收的句柄
- 从用户接收的端口名称
- 自定义数据名称字符串，例如“PortExists”
此调用会导致调用服务器 DLL 的 XcvDataPort 函数。 XcvDataPort 函数应返回一个值，该值指示是否已使用指定的端口名称。如果具有，则 UI DLL 应从用户请求另一个名称，然后再次调用 XcvData 。
收到有效的新端口名称后，再次调用 XcvData ，这次指定以下输入参数
- 从 OpenPrinter 接收的句柄
- 从用户收到的验证端口名称
- “AddPort”的数据名称字符串
此调用会导致再次调用服务器 DLL 的 XcvDataPort 函数。
通过显示对话框从用户获取端口配置参数。
调用 XcvData 一次或多次，指定自定义数据名称字符串，将每个配置参数发送到服务器 DLL。每次 XcvData 调用都会调用服务器的 XcvDataPort 函数。
调用 ClosePrinter，指定从 OpenPrinter 接收的句柄。这会导致调用服务器 DLL 的 XcvClosePort 函数。