XcvDataPort 関数 (winsplp.h)

[アーティクル]
02/27/2024

ポートモニターサーバー DLL の XcvDataPort 関数は、ポートモニターの 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 は、ポートモニター UI DLL から情報を受信して情報を返すことができるように 、XcvDataPort 関数を定義するために必要です。関数のアドレスは、 MONITOR2 構造体に含まれている必要があります。

XcvDataPort 関数は、スプーラーの XcvData 関数によって呼び出されます。 XcvDataPort と XcvData の関数パラメーターはほぼ同じです。 (XcvData には、XcvDataPort に存在しない追加のパラメーター pdwStatus があります)。

pszDataName が指す文字列は、実行する操作を指定します。関数は、次のデータ名文字列を認識する必要があります。

データ名の文字列	操作
L"AddPort"	ポートを追加するために必要なすべての情報が送信されました。関数は、ポートキーの下のレジストリにポート名を書き込むなど、指定したポートを追加するために必要な操作を実行する必要があります。 pInputData パラメーターは、NULL で終わるポート名の文字列を指します。関数が ERROR_SUCCESSを返す場合、スプーラーはポートを追加済みとしてマークします。この文字列は、 AddPortUI 関数内から印刷モニター UI DLL によって指定されます。
L"DeletePort"	ポートを削除するために必要なすべての情報が送信されました。関数は、レジストリのポートキーからポート名を削除するなど、指定されたポートを削除するために必要な操作を実行する必要があります。 pInputData パラメーターは、NULL で終わるポート名の文字列を指します。関数が ERROR_SUCCESSを返す場合、スプーラーはポートを削除済みとしてマークします。この文字列は、 DeletePortUI 関数内から印刷モニター UI DLL によって指定されます。
L"MonitorUI"	関数は、pOutputData を使用して、関連付けられているポートモニター UI DLL の名前を返す必要があります。この文字列は、アプリケーションが Microsoft Windows SDK AddPort 関数を呼び出すときに、印刷スプーラーによって指定されます。

通常、関数は、AddPortUI、ConfigurePortUI、DeletePortUI 関数内から UI DLL によって送信される追加のカスタマイズされた文字列を認識するように記述されます。これらの文字列は、サーバー DLL から現在の構成値を要求するコマンド、または新しい値を提供するコマンドを表す場合があります。たとえば、 XcvDataPort 関数は文字列 "GetTransmissionRetryTimeout" を認識します。この文字列は、UI DLL がサーバー DLL に送信して、現在格納されている送信再試行タイムアウト値を要求できます。または、"AddPort" または "DeletePort" が送信される前に送信する必要がある文字列のセットを定義できます。ここで、追加または削除するポートを識別する情報を提供するために文字列が使用されます。

特定の pszDataName 文字列と入力バッファーの場合、最初に cbOutputData 値を 0 にして XcvDataPort を呼び出す場合があります。関数は、 pcbOutputNeeded で必要なバッファーサイズと、戻り値ERROR_INSUFFICIENT_BUFFERを返す必要があります。呼び出し元は、pcbOutputNeeded で受信した値を使用して適切なサイズの出力バッファーを割り当てることができ、今度は cbOutputData で割り当てられたバッファーサイズを指定して XcvDataPort を再度呼び出すことができます。

XcvDataPort 関数は、すべての入力引数を検証する必要があります。具体的には、関数は次の手順を実行する必要があります。

pszDataName パラメーターが指す文字列の内容を検証します。この文字列が管理操作 (通常はポートの追加、削除、または構成) を表す場合、 XcvDataPort 関数は、 XcvOpenPort 関数で以前に受信したアクセスマスクをSERVER_ACCESS_ADMINISTERと比較する必要があります。比較が失敗した場合、 XcvDataPort は ERROR_ACCESS_DENIEDを返す必要があります。
pInputData パラメーターが指すバッファーの内容を検証します。スプーラーは 、XcvOpenPort 関数を呼び出すときに、このバッファーの内容に対して検証を実行しません。モニターは、悪意のあるアプリケーションから取得される可能性がある、このデータの有効性に関する仮定を行う可能性はありません。

TCPMON と通信するポートモニターを作成する場合は、「 TCPMON Xcv インターフェイス」を参照してください。