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

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

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

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

必要条件

要件	価値
ターゲットプラットフォームの	デスクトップ
ヘッダー	winsplp.h (Winsplp.h を含む)
ライブラリ	NtosKrnl.exe

次の方法で共有

XcvDataPort 関数 (winsplp.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース