TCPMON Xcv 接口

本部分介绍标准 TCP/IP 端口监视器 (TCPMON) (Xcv) 接口。 此接口使用 XcvData 和 XcvDataPort 函数调用实现，使使用该接口的人能够配置 TCP/IP 打印机端口或获取有关 TCP/IP 打印机端口配置的信息。 本部分所述的 Xcv 接口特定于 TCP/IP 端口。 其他 Xcv 接口可能可用于其他端口类型。

若要获取本地计算机或远程计算机的 Xcv 接口的句柄，请调用 OpenPrinter 函数。 下面的代码示例演示如何获取端口的 Xcv 句柄：

HANDLE hXcv = INVALID_HANDLE_VALUE;
PRINTER_DEFAULTS Defaults = { NULL, NULL, <Required Access> };

// Handle to a local machine
if (OpenPrinter(",XcvPort <PortName>", &hXcv, &Defaults )
{
 // hXvc contains an Xcv data handle to a local TCPMON port
}

// Handle to a remote machine
if (OpenPrinter("<ServerName>\\,XcvPort <PortName>", &hXcv, &Defaults )
{
 // hXvc contains an Xcv data handle to a TCPMON port on <ServerName>
}

在代码示例中， ServerName 和 PortName 表示服务器和端口名称字符串。 获取句柄后，可以查询特定于 TCPMON 端口监视器的信息，也可以更改端口配置。 请注意，必须在 PRINTER_DEFAULTS 结构的 DesiredAccess 成员中指定端口监视器所需的访问权限，如果不需要特殊安全性，则传递 NULL 。 对于对 XcvData 函数的某些调用，例如指定 AddPort 和 DeletePort 命令 (请参阅 TCPMON Xcv 命令) ，SERVER_ACCESS_ADMINISTER权限是必需的。 有关 OpenPrinter 函数以及PRINTER_DEFAULTS结构中可能请求的访问权限的详细信息，请参阅 OpenPrinter 函数文档。

如果端口尚不存在，可以通过指定监视器名称从服务器获取 Xcv 句柄。 (对于标准 TCP/IP 端口监视器端口，这是“标准 TCP/IP 端口”。) 以下代码示例演示如何获取端口监视器的 Xcv 数据句柄：

HANDLE hXcv = INVALID_HANDLE_VALUE;
PRINTER_DEFAULTS Defaults = { NULL, NULL, <Required Access> };

// Handle to a local machine
if (OpenPrinter(",XcvMonitor <MonitorName>", &hXcv, &Defaults )
{
 // hXcv contains an Xcv data handle to the monitor <MonitorName>
}

// Handle to a remote machine
if (OpenPrinter("<ServerName>\\,XcvMonitor <MonitorName>", &hXcv, &Defaults )
{
 // hXcv contains an Xcv data handle to the monitor 
 // <MonitorName> on the server <ServerName>
}

在代码示例中， ServerName 和 PortName 表示服务器和端口名称字符串。 获取 Xcv 数据句柄后，可以通过调用 XcvData 函数向监视器发出指令和请求。

请注意， XcvData 函数的返回值仅指示数据是否已正确发送到端口监视器。 返回值 TRUE 不指示操作成功。 若要确定操作是否成功，请检查 *pdwStatus 中的值。 下表汇总了这些状态值：

状态值	含义
NO_ERROR	操作成功。
ERROR_ACCESS_DENIED	用户的权限不足。 命令需要SERVER_ACCESS_ADMINISTER权限。
ERROR_INSUFFICIENT_BUFFER	输出缓冲区是必需的，但小于所需缓冲区。
ERROR_INVALID_DATA	输入缓冲区是必需的，但指向它的指针为 NULL，或者输入缓冲区的大小小于所需大小。
ERROR_INVALID_HANDLE	Xcv 数据句柄无效。
ERROR_INVALID_LEVEL	输入或输出数据结构不是正确的版本。
ERROR_INVALID_PARAMETER	输出缓冲区是必需的，但它为 NULL，或者输出所需参数为 NULL 且输出缓冲区太小，或者标准 TCP/IP 端口监视器无法理解正在发出的命令。