Implémentation de fichiers IPropertyStorage-Compound

l’implémentation COM de l’architecture Stockage structurée est appelée fichiers composés. les objets Stockage tels qu’ils sont implémentés dans les fichiers composés incluent une implémentation de IPropertyStorage, l’interface qui gère un jeu de propriétés persistantes unique et IPropertySetStorage, l’interface qui gère les groupes de jeux de propriétés persistantes. pour plus d’informations sur l’interface IPropertyStorage , consultez considérations relativesà la Stockage de propriétés et de IPropertyStorage .

Pour obtenir un pointeur vers l’implémentation de fichier composé de IPropertyStorage, appelez StgCreateStorageEx pour créer un objet de fichier composé ou StgOpenStorageEx pour ouvrir un objet de fichier composé créé précédemment. Dans le cas de StgCreateStorageEx, le paramètre stgfmt doit être défini sur _ stockage stgfmt. Dans le cas de StgOpenStorageEx, le paramètre stgfmt doit être défini sur _ stockage stgfmt ou stgfmt _ Any. Dans les deux cas, le paramètre riid doit avoir la valeur IID _ IPropertySetStorage. Les deux fonctions fournissent un pointeur vers l’interface de l’objet IPropertySetStorage . En appelant la méthode Create ou Open de cette interface, vous obtiendrez un pointeur vers l’interface IPropertyStorage , que vous pouvez utiliser pour appeler l’une de ses méthodes.

Une autre façon d’obtenir un pointeur vers l’implémentation de fichier composé de IPropertySetStorage consiste à appeler les fonctions StgCreateDocFile et StgOpenStorage plus anciennes, ou à spécifier un paramètre riid d’IID _ IStorage pour la fonction StgCreateStorageEx ou StgOpenStorageEx . Dans les deux cas, un pointeur vers l’interface IStorage de l’objet est retourné. Avec les jeux de propriétés persistants, appelez QueryInterface pour l’interface IPropertySetStorage , en spécifiant le nom défini par l’en-tête pour l’IID (identificateur d’interface) IID _ IPropertySetStorage.

Quand l’utiliser

Utilisez IPropertyStorage pour gérer les propriétés dans un même jeu de propriétés. Ses méthodes prennent en charge la lecture, l’écriture et la suppression des propriétés et des noms de chaînes facultatifs qui peuvent être associés à des identificateurs de propriété. Les autres méthodes prennent en charge la validation standard et les opérations de restauration de stockage. Il existe également une méthode qui vous permet de définir les heures associées au stockage des propriétés, et une autre qui autorise l’attribution d’un CLSID qui peut être utilisé pour associer un autre code, tel que le code de l’interface utilisateur, au jeu de propriétés. L’appel de la méthode enum fournit un pointeur vers l’implémentation de fichier composé de IEnumSTATPROPSTG, qui vous permet d’énumérer les propriétés dans le jeu.

Notes

Si vous obtenez un pointeur vers IPropertyStorage en appelant StgCreateDocFile, StgCreateStorageEx, StgOpenStorage ou StgOpenStorageEx sur un stockage de jeu de propriétés en mode simple, les méthodes IPropertyStorage adhèrent aux règles des flux en mode simple. Le stockage de jeu de propriétés est un mode simple s’il a été obtenu pour un fichier qui a été créé ou ouvert avec l' _ indicateur simple STGM. Dans ce cas, il n’est pas toujours possible de rendre le flux sous-jacent plus grand et il n’est pas possible de remplacer des propriétés existantes par des propriétés plus grandes. Pour plus d’informations, consultez IPropertySetStorage-composed file Implementation.

IPropertyStorage et mise en cache

L’implémentation de fichier composé de IPropertyStorage met en cache les jeux de propriétés ouverts en mémoire afin d’améliorer les performances. Par conséquent, les modifications apportées à un jeu de propriétés ne sont pas écrites dans le fichier composé tant que les méthodes Commit ou Release (dernière référence) ne sont pas appelées.

Jeux de propriétés en mode simple

Un objet de stockage de propriétés est en mode simple s’il est créé à partir d’un objet de stockage de jeu de propriétés de mode simple. Par exemple, un objet de stockage de jeu de propriétés serait en mode simple s’il a été obtenu à partir de la fonction StgOpenStorageEx , avec l' _ indicateur simple STGM défini dans le paramètre grfMode . Notez que « mode simple » n’est pas lié aux « jeux de propriétés simples ». Un jeu de propriétés est simple s’il est créé en appelant IPropertySetStorage :: Create avec l’indicateur PROPSETFLAG non _ simple défini dans le paramètre grfFlags . pour plus d’informations sur les jeux de propriétés simples et simples, consultez Stockage et objets de flux pour un jeu de propriétés.

Lorsqu’un objet de stockage de propriété en mode simple est créé, il n’y a aucune restriction sur son utilisation. Lorsqu’un objet de stockage de propriétés en mode simple existant est ouvert, l’objet de flux sous-jacent qui stocke le jeu de propriétés ne peut pas être augmenté. Par conséquent, il n’est pas toujours possible de modifier un tel objet de stockage de propriétés si la modification requiert un flux de plus grande taille.

Formats de jeu de propriétés

L’implémentation de fichier composé de IPropertyStorage prend en charge les formats de sérialisation des jeux de propriétés version 0 et version 1. le format version 1 est pris en charge sur les ordinateurs qui s’exécutent sur Windows 2000. Pour plus d’informations, consultez sérialisation du jeu de propriétés. Les jeux de propriétés sont créés au format version 0 et restent dans ce format, sauf si de nouvelles fonctionnalités sont demandées. Lorsque cela se produit, le format est mis à jour vers la version 1.

Par exemple, si un jeu de propriétés est créé avec l' _ indicateur par défaut PROPSETFLAG, son format est version 0. Tant que les types de propriété conformes au format de version 0 sont écrits et lus à partir de ce jeu de propriétés, le jeu de propriétés reste au format de la version 0. Si un type de propriété de la version 1 est écrit dans le jeu de propriétés, le jeu de propriétés est automatiquement mis à jour vers la version 1. Par la suite, ce jeu de propriétés ne peut plus être lu par les implémentations qui reconnaissent uniquement la version 0.

Types IPropertyStorage et variant

L’implémentation de fichier composé de IPropertyStorage ne prend pas en charge les types variant VT _ Unknown ou VT _ Dispatch dans le membre VT de la structure PROPVARIANT .

Le tableau suivant répertorie les types variant pris en charge dans un SafeArray. autrement dit, ces valeurs peuvent être combinées avec _ un tableau VT dans le membre VT de la structure PROPVARIANT .

Types variant pris en charge dans SafeArray par implémentation de fichier composé de IPropertyStorage

VT _ I1

_UI1 VT

VT _ I2

_UI2 VT

VT _

VT _ UI4

VT _ int

VT _ uint

VT _ R4

VT _ R8

VT _ ca

_Date VT

VT _ BSTR

VT _ bool

_valeur décimale VT

_erreur VT

_variante VT

Lorsque VT _ Variant est combiné avec _ un tableau VT, le SAFEARRAY lui-même contient des structures PROPVARIANT . Toutefois, les types de ces éléments doivent être extraits de la liste précédente, ne peuvent pas être des _ variantes VT et ne peuvent pas inclure les _ indicateurs de vecteur VT, de _ matrice VT ou VT _ .

Méthodes IPropertyStorage

L’implémentation de fichier composé de IPropertyStorage prend en charge les méthodes suivantes :

IPropertyStorage::ReadMultiple

Lit les propriétés spécifiées dans le tableau rgpspec et fournit les valeurs de toutes les propriétés valides dans le tableau rgvar de PROPVARIANTs. Dans l’implémentation de fichier composé COM, les identificateurs de propriété dupliqués qui font référence à des types de flux ou de stockage entraînent plusieurs appels à IStorage :: OpenStream ou IStorage :: OpenStorage et la réussite ou l’échec de ReadMultiple dépend de la capacité de l’implémentation de stockage sous-jacente à partager les opérations d’ouverture. Étant donné que dans un fichier composé _ , le partage STGM _ exclusif est forcé, le fait que plusieurs tentatives d’ouverture échouent. L’ouverture d’un même objet de stockage plusieurs fois à partir du même stockage parent n’est pas prise en charge. L' _ indicateur STGM share _ exclusive doit être spécifié.

En outre, pour garantir une opération thread-safe si la même propriété de flux ou de valeur de stockage est demandée plusieurs fois via le même pointeur IPropertyStorage dans l’implémentation de fichier composé com, l’opération d’ouverture réussira ou échouera selon que la propriété est déjà ouverte et si le système de fichiers sous-jacent gère plusieurs ouvertures d’un flux ou d’un stockage. Ainsi, l’opération ReadMultiple sur une propriété de flux ou de valeur de stockage entraîne toujours un appel à IStorage :: OpenStreamou IStorage :: OpenStorage, qui passe l’accès (STGM ReadWrite, etc. _ ) et les indicateurs de partage (STGM _ share _ exclusive, etc.) spécifiés lors de l’ouverture ou de la création du jeu de propriétés d’origine.

Si la méthode échoue, les valeurs écrites dans rgvar [ ] ne sont pas définies. Si certaines propriétés de flux ou de stockage sont ouvertes avec succès mais qu’une erreur se produit avant la fin de l’exécution, celles-ci doivent être libérées avant le retour de la méthode.

IPropertyStorage::WriteMultiple

Écrit les propriétés spécifiées dans le tableau rgpspec , en leur [ ] assignant les balises et les valeurs PROPVARIANT spécifiées dans rgvar [ ] . Les valeurs PROPVARIANT spécifiées sont affectées aux propriétés qui existent déjà. Les propriétés qui n’existent pas sont créées.

IPropertyStorage ::D eleteMultiple

Supprime les propriétés spécifiées dans rgpspec [ ] .

IPropertyStorage::ReadPropertyNames

Lit les noms de chaîne existants associés aux ID de propriété spécifiés dans le tableau rgpropid [ ] .

IPropertyStorage::WritePropertyNames

Attribue des noms de chaîne spécifiés dans le tableau rglpwstrName aux ID de propriété spécifiés dans le tableau rgpropid .

IPropertyStorage ::D eletePropertyNames

Supprime les noms de propriété pour les propriétés spécifiées dans le tableau rgpropid [ ] .

IPropertyStorage::SetClass

Définit le CLSID du flux de jeu de propriétés. Dans l’implémentation de fichier composé, la définition du CLSID sur un jeu de propriétés non simple (un qui peut légalement contenir des propriétés de stockage ou de valeur de flux, comme décrit dans IPropertySetStorage :: Create) définit également le CLSID sur le sous-stockage sous-jacent afin qu’il puisse être obtenu via un appel à IStorage :: stat.

IPropertyStorage :: Commit

Pour les jeux de propriétés simples et simples, vide l’image mémoire du jeu de propriétés sur le stockage sous-jacent. En outre, pour les jeux de propriétés de mode transactionnel non simple, cette méthode effectue une validation (comme dans IStorage :: Commit) sur le stockage qui contient le jeu de propriétés.

IPropertyStorage :: Revert

Pour les jeux de propriétés qui ne sont pas simples, appelle la méthode Revert du stockage sous-jacent et ouvre à nouveau le flux de contenu. Pour les jeux de propriétés simples, cette interface retourne toujours S _ OK. Les jeux de propriétés insimples sont ceux qui ont été créés à l’aide de l' _ indicateur PROPSETFLAG unsimple dans la méthode IPropertySetStorage :: Create . pour plus d’informations, consultez Stockage et objets de flux pour un jeu de propriétés .

IPropertyStorage :: enum

Construit une instance de IEnumSTATPROPSTG, dont les méthodes peuvent être appelées pour énumérer les structures STATPROPSTG qui fournissent des informations sur chacune des propriétés de l’ensemble. Cette implémentation crée un tableau dans lequel le jeu de propriétés entier est lu et qui peut être partagé quand IEnumSTATPROPSTG :: Clone est appelé. Les modifications apportées au jeu de propriétés ne sont pas reflétées dans une instance IEnumSTATPROPSTG ouverte. Pour voir ces modifications, une nouvelle instance de cet énumérateur doit être construite.

IPropertyStorage :: stat

Remplit les membres d’une structure STATPROPSETSTG , qui contient les données relatives à la propriété définie dans son ensemble. Au retour, fournit un pointeur vers la structure. Pour les jeux de stockage qui ne sont pas simples, cette implémentation appelle IStorage :: stat (ou IStream :: stat) pour obtenir les heures du flux ou du stockage sous-jacent. Pour les jeux de stockage simples, aucune heure n’est conservée.

IPropertyStorage::SetTimes

Pour les jeux de propriétés qui ne sont pas simples, définit les heures prises en charge par le stockage sous-jacent. L’implémentation du stockage de fichiers composés prend en charge les trois éléments suivants : modification, accès et création. Cette implémentation de SetTimes appelle la méthode IStorage :: SetElementTimes du stockage sous-jacent pour récupérer ces heures.

IPropertyStorage

IStorage :: SetElementTimes