IStream - Implémentation de fichier composé
L’interface IStream prend en charge la lecture et l’écriture de données pour diffuser des objets. Dans un objet de stockage structuré, les objets de flux contiennent les données et les stockages fournissent la structure. Les données simples peuvent être écrites directement dans un flux, mais plus fréquemment, les flux sont des éléments imbriqués dans un objet de stockage. Ils sont similaires aux fichiers standard.
La spécification d’IStream définit plus de fonctionnalités que l’implémentation COM prend en charge. Par exemple, l’interface IStream définit des flux d’une longueur maximale de 2⁶⁴ octets nécessitant un pointeur de recherche 64 bits. Toutefois, l’implémentation COM prend uniquement en charge les flux d’une longueur maximale de 2³² octets (4 Go), et les opérations de lecture et d’écriture sont toujours limitées à 2 octets² à la fois. L’implémentation COM ne prend pas non plus en charge la transaction de flux ni le verrouillage de région.
Pour créer un flux simple basé sur la mémoire globale, obtenez un pointeur IStream en appelant la fonction d’API CreateStreamOnHGlobal. Pour obtenir un pointeur IStream dans un objet de fichier composé, appelez StgCreateDocfile ou StgOpenStorage. Ces fonctions récupèrent un pointeur IStorage , avec lequel vous pouvez ensuite appeler CreateStream ou OpenStream pour un pointeur IStream . Dans les deux cas, le même code d’implémentation IStream est utilisé.
Notes
L’implémentation de fichiers composés du stockage structuré ne réussit pas sur une méthode QueryInterface pour ISequentialStream, mais elle inclut les méthodes Read et Write via le pointeur d’interface IStream .
Quand l’utiliser
Appelez les méthodes d’IStream pour lire et écrire des données dans un flux.
Étant donné que les objets de flux peuvent être marshalés vers d’autres processus, les applications peuvent partager les données dans des objets de stockage sans avoir à utiliser la mémoire globale. Dans l’implémentation du fichier composé COM des objets de flux, les fonctionnalités de marshaling personnalisées dans COM créent une version distante de l’objet d’origine dans le nouveau processus lorsque les deux processus ont un accès en mémoire partagée. Ainsi, la version distante n’a pas besoin de communiquer avec le processus d’origine pour exécuter ses fonctions.
La version distante de l’objet de flux partage le même pointeur de recherche que le flux d’origine. Si vous ne souhaitez pas partager le pointeur de recherche, utilisez la méthode IStream::Clone pour fournir une copie de l’objet de flux pour le processus distant.
Notes
Si vous créez un objet de flux plus grand que le tas dans la mémoire de votre ordinateur et que vous utilisez un handle HGLOBAL pour un objet de mémoire globale, l’objet stream appelle la méthode GlobalRealloc en interne, ce qui nécessite plus de mémoire. Étant donné que GlobalRealloc copie toujours des données de la source vers la destination, l’augmentation d’un objet de flux de 20 Mo à 25 Mo, par exemple, nécessite beaucoup de temps. Cela est dû à la taille des incréments copiés et est aggravé s’il y a moins de 45 Mo de mémoire sur l’ordinateur en raison de l’échange de disque.
La solution recommandée consiste à implémenter une méthode IStream qui utilise la mémoire allouée par VirtualAlloc au lieu de GlobalAlloc. Cela peut réserver une grande partie de l’espace d’adressage virtuel, puis valider la mémoire dans cet espace d’adressage en fonction des besoins. Aucune copie de données ne se produit et la mémoire est validée uniquement en fonction des besoins.
Une alternative à GlobalRealloc consiste à appeler la méthode IStream::SetSize sur l’objet de flux pour augmenter l’allocation de mémoire à l’avance. Toutefois, cela n’est pas aussi efficace que l’utilisation de VirtualAlloc, comme décrit ci-dessus.
Méthodes
-
Lit un nombre spécifié d'octets à partir de l'objet de flux dans la mémoire en commençant au niveau du pointeur de recherche actuel. Cette implémentation retourne S_OK si la fin du flux a été atteinte pendant la lecture. (Il s’agit du même comportement que le comportement de « fin de fichier » trouvé dans le système de fichiers MS-DOS FAT.)
-
Écrit un nombre spécifié à partir d’octets dans l’objet de flux en commençant par le pointeur de recherche actuel. Dans cette implémentation, les objets de flux ne sont pas partiellement alloués. Tous les octets de remplissage sont finalement alloués sur le disque et affectés au flux.
-
Modifie le pointeur de recherche vers un nouvel emplacement relatif au début du flux, à la fin du flux, ou au pointeur de recherche actuel.
-
Modifie la taille de l'objet de flux. Dans cette implémentation, il n’existe aucune garantie que l’espace alloué sera contigu.
-
Copie un nombre spécifié d'octets à partir du pointeur de recherche actuel d'un flux vers le pointeur de recherche actuel d'un autre flux.
-
L’implémentation de fichiers composés d’IStream prend en charge l’ouverture de flux uniquement en mode direct, et non en mode transactionné. Par conséquent, la méthode n’a aucun effet lorsqu’elle est appelée autre que pour vider toutes les mémoires tampons au niveau de stockage suivant.
Dans cette implémentation, peu importe si vous validez les modifications apportées aux flux, vous devez uniquement valider les modifications pour les objets de stockage.
-
Cette implémentation ne prend pas en charge les flux traités. Par conséquent, un appel à cette méthode n’a aucun effet.
-
Le verrouillage de plage n’étant pas pris en charge par cette implémentation, un appel à cette méthode n’a aucun effet.
-
Supprime la restriction d’accès sur une plage d’octets précédemment restreinte avec IStream::LockRegion.
-
Récupère la structure STATSTG pour ce flux
-
Crée un objet de flux avec son propre pointeur de recherche qui référence les mêmes octets que le flux d'origine.
Un IStream en mode simple est soumis aux contraintes suivantes.
- Un flux est en mode simple s’il a été créé ou ouvert à partir d’un stockage en mode simple. Un stockage est en mode simple s’il est créé ou ouvert avec l’indicateur STGM_SIMPLE défini dans le paramètre grfMode .
- Les méthodes Clone et CopyTo ne sont pas prises en charge.
- La méthode Stat est prise en charge, mais la valeur STATFLAG_NONAME doit être spécifiée.
Rubriques connexes
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour