TCPMON Xcv 介面

本節說明標準 TCP/IP 埠監視器的 transceive (Xcv) 介面， (TCPMON) 。 這個介面是使用 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 埠監視器無法瞭解所發出的命令。