共用方式為

PeerDistClientStreamRead 函式 (peerdist.h)

  • 發行項

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

讀取的逾時值，以毫秒為單位。 有兩個可指定的特殊值：

值 意義
PEERDIST_READ_TIMEOUT_LOCAL_CACHE_ONLY
 指定讀取不應該透過連絡對等或託管快取來造成任何其他網路流量。
PEERDIST_READ_TIMEOUT_DEFAULT
 指定預設逾時 5 秒。

[in] lpOverlapped

重疊結構的指標。 Stream 讀取不允許呼叫端指定讀取的開始 Offset。 每個 hContentHandle 會隱含維護下一個數據流讀取位移。

傳回值

如果函式成功，傳回值 會ERROR_IO_PENDING。 否則，此函式可能會傳回下列其中一個值：

傳回碼 Description
ERROR_INVALID_PARAMETER
 一或多個參數無效。
ERROR_INVALID_HANDLE
 hPeerDist 或 hContent 句柄無效。
ERROR_ACCESS_DISABLED_BY_POLICY
 群組原則 會停用此功能。
PEERDIST_ERROR_SERVICE_UNAVAILABLE
 服務無法使用。

備註

PeerDistClientStreamRead 會將讀取排入佇列，並立即返回呼叫端。 因此，可以同時發出多個讀取，以及以先出/先出方式使用的數據緩衝區。 PeerDistClientStreamRead 會在任何數據可用且不會等待緩衝區完全填滿時完成讀取。

如果 PeerDistClientStreamRead 函式作業順利完成，則重疊結構的Offset 和 OffsetHigh 字段將會填入讀取開始的 ULONGLONG 位移。 OffsetHigh 成員會設定為位移較高的 32 位，而 Offset 成員會設定為位移的較低 32 位。 GetOverlappedResult 會將傳輸的位元元組數目填入 lpNumberOfBytesTransferred 。 如果呼叫端使用完成埠來處理對等散發 API 完成，則 GetQueuedCompletionStatus 的 lpNumberOfBytes 自變數將會填入傳輸的位元元組數目。 數據流位移會依回報為讀取的位元元數目進階。 若要查詢大於 4GB 之內容的可用內容長度， 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。 PeerDistClientBlockRead 會以錯誤碼完成，PEERDIST_ERROR_NO_MORE如果 OVERLAPPED 參數中指定的位移小於 ullContentOffset 或大於 ullContentOffset + cbContentLength。 PeerDistClientStreamRead 和 PeerDistClientBlockRead 兩者都會限制與 PEERDIST_CONTENT_HANDLE相關聯之內容資訊中所指定內容範圍所報告的遺漏數據量。 例如，如果內容資訊只代表內容的前半部，遺漏的數據將會限製為內容的前半部。 在所有其他方面， PeerDistClientBlockRead 和 PeerDistClientStreamRead 會以完全相同的方式使用內容範圍，以與整體內容搭配使用的方式相同。

用戶端可以使用 PeerDistClientStreamRead 或 PeerDistClientBlockRead，從 ullContentOffset 所指定的位移擷取內容到 PeerDistServerRetrieveContentInformation 呼叫中指定的長度。 如果客戶端嘗試讀取超過 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 專業版 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 R2 [僅限傳統型應用程式]
目標平台 Windows
標頭 peerdist.h
程式庫 PeerDist.lib
Dll PeerDist.dll

另請參閱

PeerDistClientAddContentInformation

PeerDistClientCloseContent

PeerDistClientOpenContent

PeerDistServerOpenContentInformation

PeerDistStartup