Méthode 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 allant jusqu’à 2⁶⁴ octets de longueur nécessitant un pointeur de recherche 64 bits. Toutefois, l’implémentation COM prend uniquement en charge les flux allant jusqu’à 2³² octets de longueur (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 également en charge le verrouillage des transactions de flux ou de région.
Pour créer un flux simple basé sur la mémoire globale, obtenez un pointeur IStream en appelant la fonction 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é.
Remarque
L’implémentation de fichier composé de stockage structuré ne réussit pas sur une méthode QueryInterface pour ISequentialStream, mais inclut les méthodes lecture-écriture via le pointeur d’interface IStream.
Utilisation
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 de fichier composé COM d’objets de flux, les installations 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 stream 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.
Remarque
Si vous créez un objet de flux supérieur à la mémoire de votre ordinateur et que vous utilisez un handle HGLOBAL pour un objet mémoire globale, l’objet de flux appelle la méthode GlobalRealloc en interne lorsqu’il nécessite plus de mémoire. Étant donné que GlobalRealloc copie toujours les données de la source vers la destination, l’augmentation d’un objet de flux de 20 Mo à 25 Mo, par exemple, nécessite de grandes quantités de temps. Cela est dû à la taille des incréments copiés et s’il y a moins de 45 Mo de mémoire sur l’ordinateur en raison de l’échange de disque.
La solution préféré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 n’est validée que lorsqu’elle est requise.
Une alternative à GlobalRealloc consiste à appeler la méthode IStream ::SetSize sur l’objet de flux pour augmenter l’allocation de mémoire à l’avance. Cela n’est toutefois 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 comportement de « fin de fichier » trouvé dans le système de fichiers MS-DOS FAT.)
-
Écrit un nombre spécifié d’octets dans l’objet de flux à partir du 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 fichier composé 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, cela n’a pas d’importance si vous validez les modifications apportées aux flux, vous n’avez besoin que de valider les modifications pour les objets de stockage.
-
Cette implémentation ne prend pas en charge les flux transactionnés. Par conséquent, un appel à cette méthode n’a aucun effet.
-
Le verrouillage de plage n’est pas pris en charge par cette implémentation. Par conséquent, 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 un mode simple s’il a été créé ou ouvert à partir d’un stockage en mode simple. Un stockage est un mode simple s’il est créé ou ouvert avec l’indicateur de 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