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 ポート モニター ポートの場合、これは「Standard TCP/IP Port」です)。次のコード例は、ポート モニターへの 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 ポート モニターが発行されるコマンドを認識しません。