通过

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

指向 OVERLAPPED 结构的指针。 Stream读取不允许调用方指定读取的起始偏移量。 每个 hContentHandle 隐式维护下一个流读取偏移量。

返回值

如果函数成功，则 返回值ERROR_IO_PENDING。 否则，该函数返回以下值之一：

返回代码 说明
ERROR_INVALID_PARAMETER
 一个或多个参数无效。
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 参数将填充传输的字节数。 流偏移量将增加报告为读取的字节数。 若要查询大于 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。 如果 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
Library PeerDist.lib
DLL PeerDist.dll

另请参阅

PeerDistClientAddContentInformation

PeerDistClientCloseContent

PeerDistClientOpenContent

PeerDistServerOpenContentInformation

PeerDistStartup