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
읽기에 대한 시간 제한 값(밀리초)입니다. 지정할 수 있는 두 가지 특수 값이 있습니다.
| 값 | 의미 |
|---|---|
|
읽기가 피어 또는 호스트 캐시에 연결하여 추가 네트워크 트래픽을 발생시키지 않도록 지정합니다. |
|
기본 제한 시간인 5초를 지정합니다. |
[in] lpOverlapped
OVERLAPPED 구조체에 대한 포인터입니다. 읽기 시작 오프셋은 OVERLAPPED 구조체의 Offset 및 OffsetHigh 멤버를 설정하여 지정합니다. OffsetHigh 멤버는 시작 오프셋의 상위 32비트로 설정되어야 하며 Offset 멤버는 시작 오프셋의 하위 32비트로 설정해야 합니다.
반환 값
함수가 성공하면 반환 값이 ERROR_IO_PENDING. 그렇지 않은 경우에는 함수가 다음 값 중 하나를 반환할 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
하나 이상의 매개 변수가 잘못되었습니다. |
|
hPeerDist 또는 hContent 핸들이 잘못되었습니다. |
|
이 기능은 그룹 정책 사용하지 않도록 설정됩니다. |
|
서비스를 사용할 수 없습니다. |
설명
PeerDistClientBlockRead 는 읽기를 큐에 대기하고 호출자에게 즉시 반환합니다. 따라서 여러 읽기를 동시에 실행할 수 있습니다. PeerDistClientBlockRead 는 데이터를 사용할 수 있는 즉시 읽기를 완료하고 버퍼가 완전히 채워질 때까지 기다리지 않습니다.
PeerDistClientBlockRead 함수 작업이 성공적으로 완료되면 OVERLAPPED 구조체의 Offset 및 OffsetHigh 필드가 읽기가 시작된 ULONGLONG 오프셋으로 채워집니다. OffsetHigh 멤버는 오프셋의 상위 32비트로 설정되고 Offset 멤버는 오프셋의 하위 32비트로 설정됩니다. GetOverlappedResult 는 lpNumberOfBytesTransferred를 전송된 바이트 수로 채웁니다. 호출자가 완료 포트를 사용하여 피어 배포 API 완성을 처리하는 경우 GetQueuedCompletionStatus의 lpNumberOfBytes 인수가 전송된 바이트 수로 채워집니다.
cbMaxNumberOfBytesToRead 인수가 0과 같고 PeerDistClientBlockRead 함수가 성공적으로 완료되면 전송된 바이트 수(GetQueuedCompletionStatus 또는 GetOverlappedResult를 통해 얻은)에는 로컬 캐시에서 사용할 수 있는 실제 콘텐츠 길이가 포함됩니다.
이 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에서 시작되며 콘텐츠 범위의 끝에 도달 + 하면 오류 코드 PEERDIST_ERROR_NO_MORE 완료됩니다. PEERDistClientBlockRead는 OVERLAPPED 매개 변수에 지정된 오프셋이 ullContentOffset보다 작거나 ullContentOffset + cbContentLength보다 큰 경우 오류 코드 PEERDIST_ERROR_NO_MORE 완료됩니다. PeerDistClientStreamRead 및 PeerDistClientBlockRead 는 모두 PEERDIST_CONTENT_HANDLE 연결된 콘텐츠 정보에 지정된 콘텐츠 범위에 보고된 누락된 데이터의 양을 제한합니다. 예를 들어 콘텐츠 정보가 콘텐츠의 전반부만 나타내는 경우 누락된 데이터는 콘텐츠의 전반부로 제한됩니다. 다른 모든 면에서 PeerDistClientBlockRead 및 PeerDistClientStreamRead 는 콘텐츠 전체에서 작동하는 것과 정확히 동일한 방식으로 콘텐츠 범위를 사용합니다.
클라이언트는 PeerDistClientStreamRead 또는 PeerDistClientBlockRead를 사용하여 PeerDistServerRetrieveContentInformation 호출에서 cbContentLength에 지정된 길이까지 ullContentOffset에 지정된 오프셋에서 콘텐츠를 검색할 수 있습니다. 클라이언트가 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 |
| 라이브러리 | PeerDist.lib |
| DLL | PeerDist.dll |
추가 정보
PeerDistClientAddContentInformation