ReadPort 関数 (winsplp.h)

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

ポートモニターの ReadPort 関数は、プリンターポートからデータを読み取ります。

構文

BOOL ReadPort(
  _In_  HANDLE  hPort,
  _Out_ LPBYTE  pBuffer,
        DWORD   cbBuffer,
  _Out_ LPDWORD pcbRead
);

パラメーター

[in] hPort

呼び出し元が指定したポートハンドル。

[out] pBuffer

ポートから読み取られたデータを受信するバッファーへの呼び出し元提供のポインター。

cbBuffer

pBuffer の呼び出し元が指定したサイズ (バイト単位)。

[out] pcbRead

ポートから正常に読み取られたバイト数を受け取る場所への呼び出し元指定ポインター。

戻り値

操作が成功した場合、関数は TRUE を返す必要があります。それ以外の場合は 、FALSE を返す必要があります。

注釈

関数を定義 ReadPort し、 MONITOR2 構造に関数のアドレスを含めるには、言語モニターとポートモニターサーバー DLL が必要です。

関数の hPort 引数として受け取るハンドルは、モニターの OpenPort 関数または OpenPortEx 関数が指定したポートハンドルです。

通常、言語モニターの ReadPort 関数は、関連付けられているポートモニターの ReadPort 関数を呼び出し、取得したバッファーの内容を呼び出し元に返します。

さらに、言語モニターは、ポートモニターの関数を呼び出して、未承諾のReadPort状態情報をチェックする別のスレッドを作成する場合があります。このような読み取り操作が成功した場合は、SetPort を呼び出して状態情報をスプーラーに返す必要があります (Microsoft Windows SDKドキュメントで説明)。

通常、ポートモニターサーバー DLL のReadPort関数は ReadFile (Windows SDK ドキュメントで説明) を呼び出して、カーネルモードポートドライバーからデータを取得します。関数は、呼び出し元にデータを返すだけです。

言語モニターとポートモニターの両方で関数を定義 ReadPort し、そのアドレスをMONITOR2構造に配置する必要がありますが、言語モニターの ReadPort 関数は実際にはスプーラーやアプリケーションによって呼び出されることはありません。関数は、言語モニター自体の内部使用のみを目的としています。

たとえば、サンプル言語モニター pjlmon.dll、要求されていないプリンターの状態情報をwatchする独自ReadPortのを呼び出す別のスレッドを作成しReadPort、関数はポートモニターのReadPort関数を呼び出します。ポートモニターが言語モニターにデータを返すと、言語モニターは受信したデータを解析し、SetPort (Windows SDKドキュメントで説明) を呼び出してスプーラーに状態情報を送信します。

関数は 、pcbRead が指す位置に数値を配置することで、正常に読み取られたバイト数を返す必要があります。呼び出し元は、返されたバイト数ではなく、戻り値をチェック ReadPort's して、書き込み操作の成功または失敗を判断します。したがって、返されるバイト数が 0 の場合、関数が FALSE を返さない限り、失敗した読み取りは表されません。

何らかのシステム実装またはモニター実装のタイムアウトメカニズムでは、スプーラーが停止しないように、関数が妥当な時間内に返されるように ReadPort する必要があります。

言語モニターは、StartDocPort/EndDocPort ペアの外部でポートモニターのReadPortルーチンを呼び出すことができます。 (このような呼び出しは、未承諾の状態をチェックするスレッドによって生成される可能性があります)。ただし、一部のポートモニターではこのような呼び出しが失敗する可能性があるため、このエラーを処理するには言語モニターを記述する必要があります。