PeerDistClientStreamRead, fonction (peerdist.h)
PeerDistClientStreamRead lit une séquence d’octets à partir du flux de contenu.
Syntaxe
DWORD PeerDistClientStreamRead(
[in] PEERDIST_INSTANCE_HANDLE hPeerDist,
[in] PEERDIST_CONTENT_HANDLE hContentHandle,
DWORD cbMaxNumberOfBytes,
[in, out, optional] PBYTE pBuffer,
DWORD dwTimeoutInMilliseconds,
[in] LPOVERLAPPED lpOverlapped
);
Paramètres
[in] hPeerDist
Une PEERDIST_INSTANCE_HANDLE retournée par PeerDistStartup.
[in] hContentHandle
Handle de contenu ouvert par l’appel de fonction PeerDistClientOpenContent .
cbMaxNumberOfBytes
Nombre maximal d'octets à lire. Si cbMaxNumberOfBytesToRead est égal à 0, cela indique que la fonction PeerDistClientStreamRead interroge la longueur des octets de contenu consécutifs disponibles dans le cache local au décalage de lecture du flux actuel. La requête ne télécharge pas le contenu à partir des homologues, ni ne retourne le nombre d’octets présents dans le cache d’homologue.
[in, out, optional] pBuffer
Pointeur vers la mémoire tampon qui reçoit les données du cache local. Cette mémoire tampon doit rester valide pendant toute la durée de l’opération de lecture. L’appelant ne doit pas utiliser cette mémoire tampon tant que l’opération de lecture n’est pas terminée. Si l’argument cbMaxNumberOfBytesToRead est égal à 0, le paramètre pBuffer peut être NULL.
dwTimeoutInMilliseconds
Valeur de délai d’expiration pour la lecture, en millisecondes. Deux valeurs spéciales peuvent être spécifiées :
[in] lpOverlapped
Pointeur vers une structure CHEVAUCHÉE . Stream lecture ne permet pas à l’appelant de spécifier le décalage de début pour la lecture. Le décalage de lecture du flux suivant est implicitement géré par hContentHandle.
Valeur retournée
Si la fonction réussit, la valeur de retour est ERROR_IO_PENDING. Sinon, la fonction peut retourner l’une des valeurs suivantes :
| Code de retour | Description |
|---|---|
|
Un ou plusieurs paramètres ne sont pas valides. |
|
Le handle hPeerDist ou hContent n’est pas valide. |
|
La fonctionnalité est désactivée par stratégie de groupe. |
|
Le service n’est pas disponible. |
Remarques
PeerDistClientStreamRead met en file d’attente la lecture et retourne immédiatement à l’appelant. Par conséquent, plusieurs lectures peuvent être émises simultanément avec les mémoires tampons de données utilisées de manière premier entrant/premier sorti. PeerDistClientStreamRead termine une lecture dès qu’une donnée est disponible et n’attend pas que la mémoire tampon se remplisse complètement.
Si l’opération de fonction PeerDistClientStreamRead se termine correctement, les champs Offset et OffsetHigh de la structure OVERLAPPED sont renseignés avec le décalage ULONGLONG à partir duquel la lecture a commencé. Le membre OffsetHigh est défini sur les 32 bits les plus élevés du décalage et le membre Offset est défini sur les 32 bits inférieurs du décalage. GetOverlappedResult remplit lpNumberOfBytesTransferred avec le nombre d’octets transférés. Dans le cas où l’appelant utilise un port d’achèvement pour traiter les achèvements de l’API de distribution d’homologues, l’argument lpNumberOfBytes de GetQueuedCompletionStatus est rempli avec le nombre d’octets transférés. Le décalage du flux est avancé par le nombre d’octets signalés comme lus. Pour interroger la longueur du contenu disponible pour le contenu supérieur à 4 Go, PeerDistClientBlockRead peut être utilisé avec cbMaxNumberOfBytesToRead égal à 0 et des décalages appropriés.
Si l’API se termine avec la valeur d’erreur PEERDIST_ERROR_MISSING_DATA ou ERROR_TIMEOUT, les champs Offset et OffsetHigh de la structure OVERLAPPED spécifient le décalage ULONGLONG à partir duquel commence la plage de données manquante. Le membre OffsetHigh est défini sur les 32 bits les plus élevés du décalage et le membre Offset est défini sur les 32 bits inférieurs du décalage. Cette plage de données manquante est le décalage de début (par rapport au début du contenu) et la longueur, en octets, qui doit être récupérée à partir d’une autre source, comme le serveur de contenu d’origine. Pour permettre au service de distribution homologue de satisfaire la même lecture à l’avenir, ajoutez ces données au cache local en appelant PeerDistClientAddData. La longueur de la plage de données manquantes est spécifiée par le nombre d’octets transférés (obtenu via GetQueuedCompletionStatus ou GetOverlappedResult). Le décalage de flux est avancé par le nombre d’octets signalés comme longueur de la plage de données manquante.
Si PeerDistClientStreamRead est appelé après que le décalage du flux a avancé au-delà de la fin du contenu, l’API se termine avec ERROR_NO_MORE.
Il est important de noter que la plage de données manquantes peut commencer à n’importe quel décalage dans le contenu et être n’importe quelle longueur jusqu’à la fin du contenu. Dans le cas où les informations de contenu transmises à PeerDistClientAddContentInformation ont été générées en réponse à une demande de plage, la plage de données manquante est limitée aux limites de la demande de plage. Cela se produit lorsque l’appel à PeerDistServerOpenContentInformation sur le serveur de contenu a spécifié un décalage et une longueur qui était une sous-plage du contenu dans son ensemble. Une complétion avec ERROR_NO_MORE dans ce cas indique que le décalage de lecture est en dehors de la sous-plage du contenu.
Requêtes de plage
Si un client ne s’intéresse qu’à une partie du contenu d’origine, une demande de plage peut être utilisée pour récupérer cette partie. Une demande de plage contient un décalage et une longueur du contenu d’origine. La taille des informations de contenu est directement proportionnelle à la taille du contenu demandé.PeerDistServerOpenContentInformation prend en charge la génération d’informations de contenu pour une demande de plage via les paramètres ullContentOffset et cbContentLength . Le paramètre ullContentOffset représente le décalage dans le contenu d’origine où commence la plage et cbContentLength représente la longueur de la plage.
Une fois qu’un client obtient des informations de contenu représentant une plage de contenu particulière, ces informations fonctionnent en toute transparence avec les API PeerDistClientOpenContent,PeerDistClientAddContentInformation et PeerDistClientCompleteContentInformation . Les informations de contenu peuvent être transmises à PeerDistServerOpenContentInformation et associent le PEERDIST_CONTENT_HANDLE à la plage de contenu. PeerDistClientStreamRead est limité par le décalage ullContentOffset et la longueur cbContentLength spécifiés dans l’appel côté serveur à PeerDistServerRetrieveContentInformation. PeerDistClientStreamRead commence à ullContentOffset et se termine avec le code d’erreur PEERDIST_ERROR_NO_MORE lorsque la fin de la plage de contenu est atteinte à ullContentOffset + cbContentLength. PeerDistClientBlockRead se termine avec le code d’erreur PEERDIST_ERROR_NO_MORE si le décalage spécifié dans le paramètre OVERLAPPED est inférieur à ullContentOffset ou supérieur à ullContentOffset + cbContentLength. PeerDistClientStreamRead et PeerDistClientBlockRead limitent la quantité de données manquantes signalées à la plage de contenu spécifiée dans les informations de contenu associées au PEERDIST_CONTENT_HANDLE. Par exemple, si les informations de contenu représentent uniquement la première moitié du contenu, les données manquantes sont limitées à la première moitié du contenu. À tous les autres égards, PeerDistClientBlockRead et PeerDistClientStreamRead fonctionnent avec des plages de contenu exactement de la même façon qu’ils fonctionnent avec le contenu dans son ensemble.
Un client peut utiliser PeerDistClientStreamRead ou PeerDistClientBlockRead pour récupérer le contenu du décalage spécifié par ullContentOffset jusqu’à la longueur spécifiée par cbContentLength dans l’appel PeerDistServerRetrieveContentInformation . PeerDistClientStreamRead et PeerDistClientBlockRead se terminent avec PEERDIST_ERROR_NO_MORE si le client tente de lire au-delà de la plage spécifiée par ullContentOffset et cbContentLength. En outre, PeerDistClientBlockRead se termine également avec le code d’erreur PEERDIST_ERROR_NO_MORE si le décalage spécifié dans le paramètre OVERLAPPED est inférieur à ullContentOffset
Si la lecture ne peut pas être effectuée à partir du cache local ou du cache d’homologue, PeerDistClientStreamRead et PeerDistClientBlockRead signaleront PEERDIST_ERROR_MISSING_DATA. Lors de l’utilisation des informations de contenu plage, PeerDistClientStreamRead signale une donnée manquante du décalage de début de la plage jusqu’à la fin de la plage. PeerDistClientBlockRead signale les données manquantes à partir du décalage de début de la plage jusqu’à la fin de la plage.
PeerDistClientAddData permet d’ajouter des données de contenu même si elles se trouvent en dehors de la plage de contenu. Ces données étendues seront validées une fois les informations de contenu correspondantes ajoutées au cache local. Une fois validé, il devient disponible pour les pairs. En d’autres termes, si un client ajoute uniquement des informations de contenu pour la première moitié du contenu, PeerDistClientAddData permet toujours au client d’ajouter des données pour l’ensemble du contenu. Toutefois, la deuxième moitié du contenu ne sera pas validée tant que les informations de contenu correspondantes pour la deuxième moitié n’auront pas été ajoutées. Aucune autre API de distribution d’homologues n’est affectée par les demandes de plage.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 7 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 R2 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | peerdist.h |
| Bibliothèque | PeerDist.lib |
| DLL | PeerDist.dll |
Voir aussi
PeerDistClientAddContentInformation