implémentation de fichier IStorage-Compound

  • Article

L’implémentation de fichiers composés d’IStorage vous permet de créer et de gérer des sous-stockages et des flux au sein d’un objet de stockage résidant dans un objet de fichier composé. Pour créer un objet de fichier composé et obtenir un pointeur IStorage , appelez la fonction d’API StgCreateStorageEx. Pour ouvrir un objet de fichier composé existant et obtenir son pointeur IStorage racine, appelez StgOpenStorageEx.

Les applications qui utilisent le stockage composé doivent être inscrites dans HKEY_CLASSES_ROOT\SystemFileAssociations et doivent fournir leurs propres gestionnaires de propriétés. Pour plus d’informations, consultez la section « Inscription de verbes et d’autres informations d’association de fichiers » de l’inscription de l’application.

Quand l’utiliser

La plupart des applications utilisent cette implémentation pour créer et gérer des stockages et des flux.

Méthodes

IStorage::CreateStream

Crée et ouvre un objet stream avec le nom spécifié contenu dans cet objet de stockage. Le nom ne doit pas dépasser 31 caractères (sans l’élément de terminaison de chaîne). Les caractères 000 à 01f qui servent de premier caractère au nom de flux/de stockage, sont réservés pour être utilisés par OLE. Il s'agit d'une restriction de fichier composé, pas d'une restriction de stockage de mémoire. L’implémentation de fichier composé fournie par COM de la méthode IStorage::CreateStream ne prend pas en charge les comportements suivants :

  • L’indicateur STGM_DELETEONRELEASE n’est pas pris en charge.
  • Le mode transactionné (STGM_TRANSACTED) n’est pas pris en charge pour les objets stream.
  • L’ouverture du même flux plusieurs fois à partir du même stockage n’est pas prise en charge. L’indicateur STGM_SHARE_EXCLUSIVE mode de partage doit être spécifié dans le paramètre grfMode .

IStorage::OpenStream

Ouvre un objet stream existant dans cet objet de stockage à l’aide des modes d’accès spécifiés dans le paramètre grfMode . Les caractères 000 à 01f qui servent de premier caractère au nom de flux/de stockage, sont réservés pour être utilisés par OLE. Il s'agit d'une restriction de fichier composé, pas d'une restriction de stockage de mémoire. L’implémentation de fichier composé fournie par COM de la méthode IStorage::OpenStream ne prend pas en charge le comportement suivant :

  • Indicateur STGM_DELETEONRELEASE.
  • Mode traité (STGM_TRANSACTED) pour les objets de flux.
  • Ouverture du même flux plusieurs fois à partir du même stockage. L’indicateur STGM_SHARE_EXCLUSIVE doit être spécifié.

IStorage::CreateStorage

Crée et ouvre un objet de stockage avec le nom spécifié dans le mode d’accès spécifié. Le nom ne doit pas dépasser 31 caractères (sans l’élément de terminaison de chaîne). Les caractères 000 à 01f qui servent de premier caractère au nom de flux/de stockage, sont réservés pour être utilisés par OLE. Il s'agit d'une restriction de fichier composé, pas d'une restriction de stockage de mémoire. L’implémentation de fichier composé fournie par COM de la méthode IStorage::CreateStorage ne prend pas en charge le comportement suivant :

  • Indicateur STGM_PRIORITY pour les stockages non root.
  • Ouverture du même objet de stockage plusieurs fois à partir du même stockage parent. L’indicateur STGM_SHARE_EXCLUSIVE doit être spécifié.
  • Indicateur STGM_DELETEONRELEASE. Si cet indicateur est spécifié, la fonction retourne STG_E_INVALIDFLAG.

IStorage::OpenStorage

Ouvre un objet de stockage existant avec le nom spécifié dans le mode d’accès spécifié. Les caractères 000 à 01f qui servent de premier caractère au nom de flux/de stockage, sont réservés pour être utilisés par OLE. Il s'agit d'une restriction de fichier composé, pas d'une restriction de stockage de mémoire. L’implémentation de fichier composé fournie par COM de la méthode IStorage::OpenStorage ne prend pas en charge le comportement suivant :

  • Indicateur STGM_PRIORITY pour les stockages non root.
  • Ouverture du même objet de stockage plusieurs fois à partir du même stockage parent. L’indicateur STGM_SHARE_EXCLUSIVE doit être spécifié.
  • Indicateur STGM_DELETEONRELEASE. Si cet indicateur est spécifié, la fonction retourne STG_E_INVALIDFUNCTION.

IStorage::CopyTo

Copie uniquement les sous-stockages et les flux de cet objet de stockage ouvert dans un autre objet de stockage. Le paramètre rgiidExclude peut être défini sur IID_IStream pour copier uniquement les sous-stockages ou pour IID_IStorage pour copier uniquement des flux.

IStorage::MoveElementTo

Copie ou déplace un sous-stockage ou un flux de cet objet de stockage vers un autre objet de stockage.

IStorage::Commit

Garantit que toutes les modifications apportées à un objet de stockage ouvert en mode transactionné sont reflétées dans le stockage parent ; pour un stockage racine, reflète les modifications apportées à l’appareil réel ; par exemple, un fichier sur disque. Pour un objet de stockage racine ouvert en mode direct, cette méthode n’a aucun effet, sauf pour vider toutes les mémoires tampons sur le disque. Pour les objets de stockage non root en mode direct, cette méthode n’a aucun effet.

L’implémentation de fichiers composés fournis par COM utilise un processus de validation en deux phases, sauf si STGC_OVERWRITE est spécifié dans le paramètre grfCommitFlags . Ce processus en deux phases garantit la robustesse des données, en cas d’échec de l’opération de validation. Tout d’abord, toutes les nouvelles données sont écrites dans l’espace inutilisé dans le fichier sous-jacent. Si nécessaire, un nouvel espace est alloué au fichier. Une fois cette étape terminée, une table du fichier est mise à jour à l’aide d’une opération d’écriture à secteur unique pour indiquer que les nouvelles données doivent être utilisées à la place de l’ancienne. Les anciennes données deviennent de l’espace libre à utiliser lors de l’opération de validation suivante. Ainsi, les anciennes données sont disponibles et peuvent être restaurées si une erreur se produit lors de la validation des modifications. Si STGC_OVERWRITE est spécifié, une opération de validation en phase unique est utilisée. Pour plus d’informations sur les indicateurs de mode traité, consultez Énumération STGC .

IStorage::Revert

Ignore toutes les modifications apportées à l’objet de stockage depuis la dernière opération de validation.

IStorage::EnumElements

Crée et récupère un pointeur vers un objet énumérateur qui peut être utilisé pour énumérer les objets de stockage et de diffusion en continu contenus dans cet objet de stockage. L’implémentation de fichiers composés fournis par COM prend une instantané de ces informations. Par conséquent, les modifications apportées aux flux et aux stockages ne sont pas reflétées dans l’énumérateur tant qu’un nouvel énumérateur n’est pas obtenu.

IStorage::D estroyElement

Supprime l’élément spécifié (sous-stockage ou flux) de cet objet de stockage.

IStorage::RenameElement

Renomme le sous-stockage ou le flux spécifié dans cet objet de stockage. Les caractères 000 à 01f qui servent de premier caractère au nom de flux/de stockage, sont réservés pour être utilisés par OLE. Il s'agit d'une restriction de fichier composé, pas d'une restriction de stockage de mémoire.

IStorage::SetElementTimes

Définit les heures de modification, d’accès et de création de l’élément de stockage spécifié. L’implémentation de fichier composé fournie par COM gère les heures de modification et de modification des objets de stockage interne. Les objets de stockage racine prennent en charge tout ce qui est pris en charge par le système de fichiers sous-jacent (ou par ILockBytes). L’implémentation de fichier composé ne conserve aucun horodatage pour les flux internes. Les horodatages non pris en charge sont signalés comme zéro, ce qui permet à l’appelant de tester la prise en charge.

IStorage::SetClass

Affecte le CLSID spécifié à cet objet de stockage.

IStorage::SetStateBits

Stocke jusqu’à 32 bits d’informations d’état dans cet objet de stockage. L’état défini par cette méthode est uniquement à usage externe. L’implémentation de fichier composé fournie par COM n’effectue aucune action basée sur l’état.

IStorage::Stat

Récupère la structure STATSTG pour cet objet de stockage ouvert.

Notes

Si l’objet de stockage est ouvert en mode simple, l’utilisation des méthodes ci-dessus est restreinte. Un stockage est en mode simple s’il est ouvert avec l’élément STGM_SIMPLE spécifié dans le paramètre grfMode de la fonction StgCreateStorageEx ou StgOpenStorageEx . Pour plus d’informations sur les stockages en mode simple, consultez Constantes STGM. Si l’objet de stockage en mode simple a été obtenu à partir de la fonction StgCreateStorageEx , la méthode CreateStream peut être appelée, mais la méthode OpenStream ne le peut pas. Si l’objet de stockage en mode simple a été obtenu à partir de la fonction StgOpenStorageEx , la méthode OpenStream peut être appelée, mais pas la méthode CreateStream .

Lorsqu’un objet de stockage en mode simple est utilisé pour créer un flux, la taille minimale de ce flux est généralement de 4 096 octets. Si moins de données sont écrites dans le flux, la taille est arrondie à 4 096 octets.

Limites d’implémentation de fichiers composés

IFillLockBytes

ILockBytes

IRootStorage

IStorage

IStream

StgCreateDocfile

StgCreateStorageEx

StgOpenStorage

StgOpenStorageEx