PeerDistClientStreamRead 関数 (peerdist.h)

[アーティクル]
03/15/2023

PeerDistClientStreamRead は、コンテンツストリームから一連のバイトを読み取ります。

構文

DWORD PeerDistClientStreamRead(
  [in]                PEERDIST_INSTANCE_HANDLE hPeerDist,
  [in]                PEERDIST_CONTENT_HANDLE  hContentHandle,
                      DWORD                    cbMaxNumberOfBytes,
  [in, out, optional] PBYTE                    pBuffer,
                      DWORD                    dwTimeoutInMilliseconds,
  [in]                LPOVERLAPPED             lpOverlapped
);

パラメーター

[in] hPeerDist

PeerDistStartup によって返されるPEERDIST_INSTANCE_HANDLE。

[in] hContentHandle

PeerDistClientOpenContent 関数呼び出しによって開かれたコンテンツハンドル。

cbMaxNumberOfBytes

読み取る最大バイト数。 cbMaxNumberOfBytesToRead が 0 に等しい場合は、PeerDistClientStreamRead 関数が、現在のストリーム読み取りオフセットにあるローカルキャッシュで使用可能な連続するコンテンツバイトの長さを照会していることを示します。クエリはピアからコンテンツをダウンロードすることも、ピアキャッシュに存在するバイト数も返しません。

[in, out, optional] pBuffer

ローカルキャッシュからデータを受信するバッファーへのポインター。このバッファーは、読み取り操作の間は有効なままである必要があります。読み取り操作が完了するまで、呼び出し元はこのバッファーを使用しないでください。 cbMaxNumberOfBytesToRead 引数が 0 の場合、pBuffer パラメーターには NULL を指定できます。

dwTimeoutInMilliseconds

読み取りのタイムアウト値 (ミリ秒単位)。指定できる特別な値は 2 つあります。

値	意味
PEERDIST_READ_TIMEOUT_LOCAL_CACHE_ONLY	ピアまたはホスト型キャッシュに接続して、読み取りによって追加のネットワークトラフィックが発生しないように指定します。
PEERDIST_READ_TIMEOUT_DEFAULT	5 秒の既定のタイムアウトを指定します。

[in] lpOverlapped

OVERLAPPED 構造体へのポインター。読み取りStream、呼び出し元は読み取りの開始オフセットを指定できません。次のストリーム読み取りオフセットは、 hContentHandle ごとに暗黙的に維持されます。

戻り値

関数が成功した場合、戻り値は ERROR_IO_PENDING。それ以外の場合は、関数から次の値のいずれかが返されます。

リターンコード	説明
ERROR_INVALID_PARAMETER	1 つ以上のパラメーターが無効です。
ERROR_INVALID_HANDLE	hPeerDist または hContent ハンドルが無効です。
ERROR_ACCESS_DISABLED_BY_POLICY	この機能は、グループポリシーによって無効になっています。
PEERDIST_ERROR_SERVICE_UNAVAILABLE	サービスを利用できません。

注釈

PeerDistClientStreamRead は読み取りをキューに入れ、すぐに呼び出し元に戻ります。その結果、先入れ先出しの方法で使用されるデータバッファーと同時に複数の読み取りを発行できます。 PeerDistClientStreamRead は、データが使用可能になるとすぐに読み取りを完了し、バッファーがいっぱいになるまで待機しません。

PeerDistClientStreamRead 関数の操作が正常に完了すると、OVERLAPPED 構造体の Offset フィールドと OffsetHigh フィールドに、読み取りが開始された ULONGLONG オフセットが設定されます。 OffsetHigh メンバーはオフセットの上位 32 ビットに設定され、Offset メンバーはオフセットの下位 32 ビットに設定されます。 GetOverlappedResult は、転送されたバイト数 を lpNumberOfBytesTransferred に設定します。呼び出し元が完了ポートを使用してピアディストリビューション API の入力候補を処理している場合、GetQueuedCompletionStatus の lpNumberOfBytes 引数に転送されたバイト数が設定されます。ストリームオフセットは、読み取りとして報告されたバイト数だけ進められます。 4 GB を超えるコンテンツに対して使用可能なコンテンツの長さを照会するために、 PeerDistClientBlockRead を cbMaxNumberOfBytesToRead が 0 と等しく、適切なオフセットと共に使用できます。

API がエラー値PEERDIST_ERROR_MISSING_DATAまたはERROR_TIMEOUTで完了した場合、OVERLAPPED 構造体の Offset フィールドと OffsetHigh フィールドは、不足しているデータ範囲が開始される ULONGLONG オフセットを指定します。 OffsetHigh メンバーはオフセットの上位 32 ビットに設定され、Offset メンバーはオフセットの下位 32 ビットに設定されます。この不足しているデータ範囲は、開始オフセット (コンテンツの開始に対する相対位置) と長さ (バイト単位) です。これは、元のコンテンツサーバーなどの代替ソースから取得する必要があります。今後、ピア配布サービスが同じ読み取りを満たすようにするには、 PeerDistClientAddData を呼び出して、このデータをローカルキャッシュに追加します。不足しているデータ範囲の長さは、転送されたバイト数 ( GetQueuedCompletionStatus または GetOverlappedResult を使用して取得) によって指定されます。ストリームオフセットは、不足しているデータ範囲の長さとして報告されたバイト数だけ進みます。

ストリームオフセットがコンテンツの末尾を超えて拡張された後に PeerDistClientStreamRead が呼び出された場合、API は ERROR_NO_MOREで完了します。

不足しているデータ範囲は、コンテンツ内の任意のオフセットから始まり、コンテンツの末尾までの任意の長さになることに注意することが重要です。 PeerDistClientAddContentInformation に渡されたコンテンツ情報が範囲要求に応答して生成された場合、不足しているデータ範囲は範囲要求の境界に制限されます。これは、コンテンツサーバー上の PeerDistServerOpenContentInformation の呼び出しで、コンテンツ全体のサブ範囲であるオフセットと長さを指定した場合に発生します。この場合 、ERROR_NO_MORE の入力候補は、読み取りオフセットがコンテンツのサブ範囲の外にあることを示します。

範囲要求

クライアントが元のコンテンツの一部のみに関心がある場合は、範囲要求を使用してその部分を取得できます。範囲要求には、元のコンテンツのオフセットと長さが含まれます。コンテンツ情報のサイズは、要求されたコンテンツのサイズに直接比例します。

PeerDistServerOpenContentInformation では、ullContentOffset パラメーターと cbContentLength パラメーターを使用した範囲要求のコンテンツ情報の生成がサポートされています。 ullContentOffset パラメーターは、範囲が始まる元のコンテンツのオフセットを表し、cbContentLength は範囲の長さを表します。

クライアントが特定のコンテンツ範囲を表すコンテンツ情報を取得すると、そのコンテンツ情報は PeerDistClientOpenContent、 PeerDistClientAddContentInformation 、 PeerDistClientCompleteContentInformation API とシームレスに連携します。コンテンツ情報は PeerDistServerOpenContentInformation に渡し、 PEERDIST_CONTENT_HANDLE をコンテンツ範囲に関連付けます。 PeerDistClientStreamRead は、PeerDistServerRetrieveContentInformation へのサーバー側の呼び出しで指定された ullContentOffset オフセットと cbContentLength の長さによって制限されます。 PeerDistClientStreamRead は ullContentOffset から始まり、コンテンツ範囲の末尾が ullContentOffset + cbContentLength に達したときにPEERDIST_ERROR_NO_MOREエラーコードで完了します。 OVERLAPPED パラメーターで指定されたオフセットが ullContentOffset より小さいか、ullContentOffsetcbContentLength より大きい + 場合、PeerDistClientBlockRead はエラーコード PEERDIST_ERROR_NO_MOREで完了します。 PeerDistClientStreamRead と PeerDistClientBlockRead はどちらも、PEERDIST_CONTENT_HANDLEに関連付けられているコンテンツ情報で指定されたコンテンツ範囲に報告される不足データの量を制限 します。たとえば、コンテンツ情報がコンテンツの前半のみを表す場合、不足しているデータはコンテンツの前半に制限されます。他のすべての点で、 PeerDistClientBlockRead と PeerDistClientStreamRead は、コンテンツ全体を操作するのとまったく同じ方法でコンテンツ範囲を操作します。

クライアントは PeerDistClientStreamRead または PeerDistClientBlockRead を使用して、ullContentOffset で指定されたオフセットから、PeerDistServerRetrieveContentInformation 呼び出しで cbContentLength で指定された長さまでコンテンツを取得できます。クライアントが ullContentOffset と cbContentLength で指定された範囲を超えて読み取ろうとした場合、PeerDistClientStreamRead と PeerDistClientBlockRead はどちらも PEERDIST_ERROR_NO_MORE で完了します。また、OVERLAPPED パラメーターで指定されたオフセットが ullContentOffset より小さい場合は、PeerDistClientBlockRead もエラーコード PEERDIST_ERROR_NO_MOREで完了します

ローカルキャッシュまたはピアキャッシュから読み取りを完了できない場合は、 PeerDistClientStreamRead と PeerDistClientBlockRead の両方が PEERDIST_ERROR_MISSING_DATAを報告します。範囲指定されたコンテンツ情報を使用する場合、 PeerDistClientStreamRead は、範囲の開始オフセットから範囲の末尾までの欠落データを報告します。 PeerDistClientBlockRead は、範囲の開始オフセットから範囲の末尾までの欠落データを報告します。

PeerDistClientAddData を使用すると、コンテンツデータがコンテンツ範囲外にある場合でも、コンテンツデータを追加できます。この拡張データは、対応するコンテンツ情報がローカルキャッシュに追加された後に検証されます。検証されると、ピアが使用できるようになります。つまり、クライアントがコンテンツの前半のコンテンツ情報のみを追加する場合でも、 PeerDistClientAddData を使用すると、クライアントはコンテンツ全体のデータを追加できます。ただし、コンテンツの後半は、後半の対応するコンテンツ情報が追加されるまで検証されません。範囲要求の影響を受けるピア配布 API は他にありません。

要件

要件	値
サポートされている最小のクライアント	Windows 7 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 R2 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	peerdist.h
Library	PeerDist.lib
[DLL]	PeerDist.dll