PeerDistClientBlockRead function (peerdist.h)
The PeerDistClientBlockRead function reads content data blocks.
Syntax
DWORD PeerDistClientBlockRead(
[in] PEERDIST_INSTANCE_HANDLE hPeerDist,
[in] PEERDIST_CONTENT_HANDLE hContentHandle,
DWORD cbMaxNumberOfBytes,
[in, out, optional] PBYTE pBuffer,
DWORD dwTimeoutInMilliseconds,
[in] LPOVERLAPPED lpOverlapped
);
Parameters
[in] hPeerDist
A PEERDIST_INSTANCE_HANDLE returned by PeerDistStartup.
[in] hContentHandle
A content handle opened by PeerDistClientOpenContent function call.
cbMaxNumberOfBytes
The maximum number of bytes to read. If the cbMaxNumberOfBytesToRead is equal to 0, it indicates that the PeerDistClientBlockRead function is querying the length of available consecutive content bytes in the local cache at the current block read offset. The query will neither download content from the peers, nor return the count of bytes present in the peer cache.
[in, out, optional] pBuffer
Pointer to the buffer that receives the data from the local cache. This buffer must remain valid for the duration of the read operation. The caller must not use this buffer until the read operation is completed. If the cbMaxNumberOfBytesToRead argument is equal to 0, the pBuffer parameter can be NULL
dwTimeoutInMilliseconds
Timeout value for the read, in milliseconds. There are two special values that may be specified:
[in] lpOverlapped
Pointer to an OVERLAPPED structure. The start offset for read is specified by setting the Offset and OffsetHigh members of the OVERLAPPED structure. The OffsetHigh member should be set to the higher 32 bits of the start offset and the Offset member should be set to the lower 32 bits of the start offset.
Return value
If the function succeeds, the return value is ERROR_IO_PENDING. Otherwise, the function may return one of the following values:
| Return code | Description |
|---|---|
|
One or more parameters are invalid. |
|
The hPeerDist or hContent handle is invalid. |
|
The feature is disabled by Group Policy. |
|
The service is unavailable. |
Remarks
PeerDistClientBlockRead queues the read and immediately returns to the caller. As a result, multiple reads can be issued simultaneously. PeerDistClientBlockRead will complete a read as soon as any data is available and will not wait for the buffer to fill completely.
If the PeerDistClientBlockRead function operation completes successfully, the Offset and OffsetHigh fields of the OVERLAPPED structure will be populated with the ULONGLONG offset at which the read started. The OffsetHigh member will be set to the higher 32 bits of the offset and the Offset member will be set to the lower 32 bits of the offset. GetOverlappedResult will populate lpNumberOfBytesTransferred with the number of bytes transferred. In the event the caller is using a completion port to process Peer Distribution API completions then the lpNumberOfBytes argument of GetQueuedCompletionStatus will be populated with the number of bytes transferred.
If the cbMaxNumberOfBytesToRead argument is equal to 0, and the PeerDistClientBlockRead function completes successfully, the number of bytes transferred (obtained via either GetQueuedCompletionStatus or GetOverlappedResult) will contain the actual length of content available in the local cache.
When this API completes with error values PEERDIST_ERROR_MISSING_DATA or ERROR_TIMEOUT, the Offset and OffsetHigh fields of the OVERLAPPED structure specify the ULONGLONG offset at which the missing data range begins. The OffsetHigh member will be set to the higher 32 bits of the offset and the Offset member will be set to the lower 32 bits of the offset. This missing data range is the start offset (relative to start of the content) and length, in bytes, which needs to be retrieved from an alternate source, like the original content server. In order to allow the Peer Distribution service to satisfy the same read in the future, add this data to the local cache by calling PeerDistClientAddData. The length of the missing data range is specified by the number of bytes transferred (obtained via GetQueuedCompletionStatus or GetOverlappedResult).
It is important to note that the missing data range can start at any offset in the content and be any length up to the end of the content. In the event the content information passed to PeerDistClientAddContentInformation was generated in response to a range request, then the missing data range will be constrained to the range request bounds. This occurs when the call to PeerDistServerOpenContentInformation on the content server specified an offset and a length which was a sub-range of the content as a whole. A completion with ERROR_NO_MORE in this case indicates that the read offset is outside of the sub-range of the content.
Range Requests
If a client is interested in only a portion of the original content, a range request can be used to retrieve that portion. A range request contains an offset and length of the original content. The size of the content information is directly proportional to the size of the content requested.PeerDistServerOpenContentInformation supports generating content information for a range request via the ullContentOffset and cbContentLength parameters. The ullContentOffset parameter represents the offset in the original content where the range begins and cbContentLength represents the length of the range.
Once a client obtains content information representing a particular content range, that content information works seamlessly with the PeerDistClientOpenContent, PeerDistClientAddContentInformation and PeerDistClientCompleteContentInformation APIs. The content information can be passed to PeerDistServerOpenContentInformation and will associate the PEERDIST_CONTENT_HANDLE with the content range. PeerDistClientStreamRead is constrained by the ullContentOffset offset and cbContentLength length specified in the server side call to PeerDistServerRetrieveContentInformation. PeerDistClientStreamRead will begin at ullContentOffset and will complete with the error code PEERDIST_ERROR_NO_MORE when the end of the content range is reached at ullContentOffset + cbContentLength. PeerDistClientBlockRead will complete with the error code PEERDIST_ERROR_NO_MORE if the offset specified in the OVERLAPPED parameter is less than ullContentOffset or greater than ullContentOffset + cbContentLength. PeerDistClientStreamRead and PeerDistClientBlockRead both limit the amount of missing data reported to the content range specified in the content information associated with the PEERDIST_CONTENT_HANDLE. For example, if the content information represents only the first half of the content, missing data will be limited to the first half of the content. In all other respects, PeerDistClientBlockRead and PeerDistClientStreamRead work with content ranges in exactly the same manner in which they work with the content as a whole.
A client can use PeerDistClientStreamRead or PeerDistClientBlockRead to retrieve the content from the offset specified by the ullContentOffset up to the length specified by cbContentLength in the PeerDistServerRetrieveContentInformation call. Both PeerDistClientStreamRead and PeerDistClientBlockRead will complete with PEERDIST_ERROR_NO_MORE if the client tries to read beyond the range specified by the ullContentOffset and cbContentLength. Additionally, PeerDistClientBlockRead will also complete with the error code PEERDIST_ERROR_NO_MORE if the offset specified in the OVERLAPPED parameter is less than ullContentOffset
If the read cannot not be completed from either the local cache or the peer cache, both PeerDistClientStreamRead and PeerDistClientBlockRead will report PEERDIST_ERROR_MISSING_DATA. When using the ranged content information, PeerDistClientStreamRead will report a missing data from the start offset of the range up to the end of the range. PeerDistClientBlockRead will report missing data from start offset of the range up to the end of the range.
PeerDistClientAddData allows content data to be added even if it lies outside the content range. This extended data will be validated after the corresponding content information has been added to the local cache. Once validated, it becomes available to peers. In other words, if a client adds only content information for the first half of content, PeerDistClientAddData still allows the client to add data for the entire content. However, the second half of the content will not be validated until the corresponding content information for the second half has been added. No other Peer Distribution APIs are affected by range requests.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 7 Professional [desktop apps only] |
| Minimum supported server | Windows Server 2008 R2 [desktop apps only] |
| Target Platform | Windows |
| Header | peerdist.h |
| Library | PeerDist.lib |
| DLL | PeerDist.dll |
See also
PeerDistClientAddContentInformation