Функция PeerDistClientStreamRead (peerdist.h)

Статья
03/05/2024

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

PEERDIST_INSTANCE_HANDLE, возвращенный PeerDistStartup.

[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 успешно завершена, поля Offset и OffsetHigh структуры OVERLAPPED будут заполнены смещением ULONGLONG , с которого началось чтение. Для элемента OffsetHigh будут заданы более высокие 32 бита смещения, а для элемента Offset — нижние 32 бита смещения. GetOverlappedResult заполняет lpNumberOfBytesTransferred количеством переданных байтов. Если вызывающий объект использует порт завершения для обработки завершений API однорангового распределения, то аргумент lpNumberOfBytesgetQueuedCompletionStatus будет заполнен количеством переданных байтов. Смещение потока будет расширено на количество байтов, сообщаемых при чтении. Чтобы запросить длину доступного содержимого для содержимого размером более 4 ГБ, можно использовать PeerDistClientBlockRead с cbMaxNumberOfBytesToRead равным 0 и соответствующими смещениями.

Если API завершается со значением ошибки PEERDIST_ERROR_MISSING_DATA или ERROR_TIMEOUT, поля Offset и OffsetHigh структуры OVERLAPPED указывают смещение ULONGLONG, с которого начинается недостающий диапазон данных. Для элемента OffsetHigh будут заданы более высокие 32 бита смещения, а для элемента Offset — нижние 32 бита смещения. Этот отсутствующий диапазон данных является начальным смещением (относительно начала содержимого) и длиной в байтах, которые необходимо извлечь из альтернативного источника, например исходного сервера содержимого. Чтобы служба однорангового распределения удобочиталась в будущем, добавьте эти данные в локальный кэш, вызвав PeerDistClientAddData. Длина недостающего диапазона данных определяется количеством переданных байтов (полученных с помощью GetQueuedCompletionStatus или GetOverlappedResult). Смещение потока определяется числом байтов, сообщаемым в качестве длины диапазона отсутствующих данных.

Если метод PeerDistClientStreamRead вызывается после того, как смещение потока выходит за пределы конца содержимого, API завершит работу с ERROR_NO_MORE.

Важно отметить, что отсутствующий диапазон данных может начинаться с любого смещения в содержимом и иметь длину до конца содержимого. Если в ответ на запрос диапазона была создана информация о содержимом, переданная в PeerDistClientAddContentInformation , то отсутствующий диапазон данных будет ограничен границами запроса диапазона. Это произойдет, когда при вызове PeerDistServerOpenContentInformation на сервере содержимого задано смещение и длина, которая была поддиапазоном содержимого в целом. Завершение с ERROR_NO_MORE в этом случае указывает, что смещение чтения находится за пределами под-диапазона содержимого.

Запросы диапазона

Если клиент заинтересован только в части исходного содержимого, для получения этой части можно использовать запрос диапазона. Запрос диапазона содержит смещение и длину исходного содержимого. Размер сведений о содержимом прямо пропорционален размеру запрошенного содержимого.

PeerDistServerOpenContentInformation поддерживает создание сведений о содержимом для запроса диапазона с помощью параметров ullContentOffset и cbContentLength . Параметр ullContentOffset представляет смещение в исходном содержимом, где начинается диапазон, а cbContentLength — длину диапазона.

После получения клиентом сведений о содержимом, представляющих определенный диапазон контента, эти сведения о содержимом легко работают с API PeerDistClientOpenContent, PeerDistClientAddContentInformation и PeerDistClientCompleteContentInformation . Сведения о содержимом можно передать в PeerDistServerOpenContentInformation и связать PEERDIST_CONTENT_HANDLE с диапазоном содержимого. PeerDistClientStreamRead ограничивается смещением ullContentOffset и длиной cbContentLength , указанной в вызове PeerDistServerRetrieveContentInformation на стороне сервера. PeerDistClientStreamRead начинается с ullContentOffset и завершается с кодом ошибки PEERDIST_ERROR_NO_MORE при достижении конца диапазона содержимого в ullContentOffset + cbContentLength. PeerDistClientBlockRead завершит работу с кодом ошибки PEERDIST_ERROR_NO_MORE , если смещение, указанное в параметре OVERLAPPED , меньше ullContentOffset или больше ullContentOffset + cbContentLength. PeerDistClientStreamRead и PeerDistClientBlockRead ограничивают объем отсутствующих данных, передаваемых в диапазон содержимого, указанный в сведениях о содержимом , связанных с PEERDIST_CONTENT_HANDLE. Например, если сведения о содержимом представляют только первую половину содержимого, отсутствующие данные будут ограничены первой половиной содержимого. Во всех остальных отношениях PeerDistClientBlockRead и PeerDistClientStreamRead работают с диапазонами контента точно так же, как они работают с содержимым в целом.

Клиент может использовать PeerDistClientStreamRead или PeerDistClientBlockRead для получения содержимого от смещения, указанного параметром ullContentOffset , до длины, указанной cbContentLength в вызове PeerDistServerRetrieveContentInformation . И PeerDistClientStreamRead , и PeerDistClientBlockRead будут завершать работу с PEERDIST_ERROR_NO_MORE , если клиент пытается считывать за пределы диапазона, указанного ullContentOffset и cbContentLength. Кроме того, PeerDistClientBlockRead также завершит код ошибки PEERDIST_ERROR_NO_MORE, если смещение, указанное в параметре OVERLAPPED, меньше, чем ullContentOffset.

Если не удается выполнить чтение из локального кэша или однорангового кэша, peerDistClientStreamRead и PeerDistClientBlockRead будут сообщать о PEERDIST_ERROR_MISSING_DATA. При использовании сведений о содержимом в диапазоне PeerDistClientStreamRead сообщит об отсутствующих данных от начального смещения диапазона до конца диапазона. PeerDistClientBlockRead будет сообщать об отсутствующих данных от начального смещения диапазона до конца диапазона.

PeerDistClientAddData позволяет добавлять данные содержимого, даже если они находятся за пределами диапазона содержимого. Эти расширенные данные будут проверены после добавления соответствующих сведений о содержимом в локальный кэш. После проверки он становится доступным для одноранговых узлов. Другими словами, если клиент добавляет только сведения о содержимом для первой половины содержимого, PeerDistClientAddData по-прежнему позволяет клиенту добавлять данные для всего содержимого. Однако вторая половина содержимого не будет проверена до тех пор, пока не будут добавлены соответствующие сведения о содержимом для второй половины. Никакие другие API однорангового распределения не затрагиваются запросами диапазона.

Требования

Требование	Значение
Минимальная версия клиента	Windows 7 Профессиональная [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 [только классические приложения]
Целевая платформа	Windows
Header	peerdist.h
Библиотека	PeerDist.lib
DLL	PeerDist.dll