共用方式為

PeerDistClientBlockRead 函式 (peerdist.h)

  • 發行項

PeerDistClientBlockRead 函式會讀取內容數據區塊。

語法

DWORD PeerDistClientBlockRead(
  [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，表示 PeerDistClientBlockRead 函式正在查詢本機快取中目前區塊讀取位移中可用連續內容位元組的長度。 查詢不會從對等下載內容，也不會傳回對等快取中存在的位元組計數。

[in, out, optional] pBuffer

從本機快取接收數據的緩衝區指標。 此緩衝區在讀取作業的持續期間必須保持有效。 在讀取作業完成之前，呼叫端不得使用此緩衝區。 如果 cbMaxNumberOfBytesToRead 自變數等於 0，pBuffer 參數可以是 NULL

dwTimeoutInMilliseconds

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

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

[in] lpOverlapped

重疊結構的指標。 讀取的開始位移是藉由設定 OVERLAPPED 結構的 Offset 和 OffsetHigh 成員來指定。 OffsetHigh 成員應該設定為起始位移的 32 位較高，而 Offset 成員應該設定為起始位移的下層 32 位。

傳回值

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

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

備註

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

如果 PeerDistClientBlockRead 函式作業順利完成，則 OVERLAPPED 結構的 Offset 和 OffsetHigh 字段將會填入讀取開始的 ULONGLONG 位移。 OffsetHigh 成員會設定為位移較高的 32 位，而 Offset 成員將會設定為位移的下層 32 位。 GetOverlappedResult 會將傳輸的位元元組數目填入 lpNumberOfBytesTransferred 。 如果呼叫端使用完成埠來處理對等分配 API 完成，則 GetQueuedCompletionStatus 的 lpNumberOfBytes 自變數將會填入傳輸的位元元數目。

如果 cbMaxNumberOfBytesToRead 自變數等於 0，且 PeerDistClientBlockRead 函式順利完成，則透過 GetQueuedCompletionStatus 或 GetOverlappedRes) ult 取得 (的位元組數目會包含本機快取中可用的內容實際長度。

當此 API 完成錯誤值PEERDIST_ERROR_MISSING_DATA或ERROR_TIMEOUT時，OVERLAPPED 結構的 Offset 和 OffsetHigh 字段會指定遺漏數據範圍開始的 ULONGLONG 位移。 OffsetHigh 成員會設定為位移較高的 32 位，而 Offset 成員將會設定為位移的下層 32 位。 這個遺漏的數據範圍是相對於內容開頭) 和長度的開始位移 (，以位元組為單位，需要從替代來源擷取，例如原始內容伺服器。 為了讓對等散發服務在未來滿足相同的讀取，請呼叫PeerDistClientAddData將此數據新增至本機快取。 遺漏數據範圍的長度是由透過 GetQueuedCompletionStatus 或 GetOverlappedResult) 取得 (傳輸的位元元組數目來指定。

請務必注意，遺漏的數據範圍可以從內容中的任何位移開始，而且長度上限為內容結尾。 如果傳遞至 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 或大於 ullContentOffset + cbContentLength，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 專業版 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 R2 [僅限桌面應用程式]
目標平台 Windows
標頭 peerdist.h
程式庫 PeerDist.lib
Dll PeerDist.dll

另請參閱

PeerDistClientAddContentInformation

PeerDistClientOpenContent

PeerDistServerOpenContentInformation

PeerDistStartup