Implémentation autonome IPropertyStorage
L’implémentation autonome d’IPropertySetStorage fournie par le système inclut une implémentation d’IPropertyStorage, l’interface qui lit et écrit des propriétés dans un stockage de jeux de propriétés. L’interface IPropertySetStorage crée et ouvre des jeux de propriétés dans un stockage. Les interfaces IEnumSTATPROPSTG et IEnumSTATPROPSETSTG sont également fournies dans l’implémentation autonome.
Pour obtenir un pointeur vers l’implémentation autonome d’IPropertyStorage, appelez la fonction StgCreatePropStg pour créer un jeu de propriétés ou StgOpenPropStg pour obtenir le pointeur d’interface sur un jeu de propriétés existant (ou appelez les méthodes Create ou Open de l’implémentation autonome IPropertySetStorage ).
L’implémentation autonome d’IPropertyStorage crée des jeux de propriétés sur n’importe quel objet de stockage ou de flux, pas seulement sur les stockages et flux de fichiers composés. L’implémentation autonome ne dépend pas de fichiers composés et peut être utilisée avec n’importe quelle implémentation de stockages structurés. Pour plus d’informations sur l’implémentation de fichiers composés de cette interface, consultez IPropertyStorage-Compound File Implementation.
Quand l’utiliser
Utilisez IPropertyStorage pour gérer les propriétés au sein d’un jeu de propriétés unique. Ses méthodes prennent en charge la lecture, l’écriture et la suppression des propriétés et des noms de chaîne facultatifs qui peuvent être associés aux ID de propriété. D’autres méthodes prennent en charge les opérations de stockage standard de validation et de restauration. Il existe également une méthode qui définit les heures associées au stockage de propriétés, et une autre qui permet d’utiliser l’attribution d’un CLSID pour associer d’autres codes, tels que le code d’interface utilisateur, au jeu de propriétés. La méthode Enum fournit un pointeur vers l’implémentation autonome d’IEnumSTATPROPSTG, qui énumère les propriétés dans l’ensemble.
Formats d’ensemble de propriétés version 0 et version 1
L’implémentation autonome d’IPropertyStorage prend en charge les formats de sérialisation des ensembles de propriétés version 0 et version 1. 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. À ce moment-là, le format est mis à jour vers la version 1.
Par exemple, si un jeu de propriétés est créé avec l’indicateur PROPSETFLAG_DEFAULT, son format est la version 0. Tant que les types de propriétés conformes au format version 0 sont écrits et lus à partir de ce jeu de propriétés, le jeu de propriétés reste au format version 0. Si un type de propriété 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 des implémentations qui ne comprennent que la version 0.
Types IPropertyStorage et Variant
L’implémentation autonome d’IPropertyStorage ne prend pas en charge les types de variantes VT_UNKNOWN ou VT_DISPATCH dans le membre vt de la structure PROPVARIANT .
Les types de variantes suivants sont pris en charge dans un SafeArray ; autrement dit, ces valeurs peuvent être combinées avec VT_ARRAY dans le membre vt de la structure PROPVARIANT .
Types de variantes pris en charge dans SafeArray par l’implémentation de fichiers composés d’IPropertyStorage
VT_I1
VT_UI1
VT_I2
VT_UI2
VT_I4
VT_UI4
VT_INT
VT_UINT
VT_R4
VT_R8
VT_CY
VT_DATE
VT_BSTR
VT_BOOL
VT_DECIMAL
VT_ERROR
VT_VARIANT
Lorsque VT_VARIANT est combiné à VT_ARRAY, le SafeArray lui-même contient les structures PROPVARIANT . Toutefois, les types de ces éléments doivent être extraits de la liste précédente, ne peuvent pas être VT_VARIANT et ne peuvent pas inclure les indicateurs VT_VECTOR, VT_ARRAY ou VT_BYREF.
Méthodes IPropertyStorage
L’implémentation autonome d’IPropertyStorage prend en charge les méthodes suivantes :
-
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 des éléments PROPVARIANT .
Dans l’implémentation autonome fournie par le système, les identificateurs de propriétés en double qui font référence aux 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 des stockages ouverts.
En outre, pour garantir l’opération thread-safe si la même propriété de flux ou de stockage est demandée plusieurs fois via le même pointeur IPropertyStorage , l’ouverture réussit ou échoue selon que la propriété est déjà ouverte ou non 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 stockage entraîne toujours un appel à IStorage::OpenStream, ou IStorage::OpenStorage, en passant l’accès (STGM_READWRITE, par exemple) et les valeurs de partage (STGM_SHARE_EXCLUSIVE, par exemple) spécifiées lors de l’ouverture ou de la création initiale du jeu de propriétés.
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, ces propriétés doivent être libérées avant le retour de la méthode.
-
Écrit les propriétés spécifiées dans le tableau rgpspec[] en leur attribuant les balises PROPVARIANT et les valeurs spécifiées dans rgvar[]. Les propriétés qui existent déjà se voient attribuer les valeurs PROPVARIANT spécifiées et les propriétés qui n’existent pas actuellement sont créées.
-
Supprime les propriétés spécifiées dans rgpspec[].
-
Lit les noms de chaînes existants associés aux ID de propriété spécifiés dans le tableau rgpropid[].
-
Affecte les noms de chaîne spécifiés dans le tableau rglpwstrName aux ID de propriété spécifiés dans le tableau rgpropid .
-
Supprime les noms de chaîne des ID de propriété spécifiés dans le tableau rgpropid en écrivant NULL dans le nom de la propriété.
-
Définit le CLSID du flux de jeux de propriétés. Dans l’implémentation autonome, la définition du CLSID sur un ensemble de propriétés non simples (qui peut contenir des propriétés à valeur de stockage ou 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.
-
Pour les jeux de propriétés simples et non simples, vide l’image mémoire sur le sous-système de disque. En outre, pour les ensembles de propriétés en mode transactionné non simple, cette méthode appelle IStorage::Commit sur le jeu de propriétés.
-
Pour les jeux de propriétés non simples uniquement, appelle la méthode Revert du stockage sous-jacent et rouvre le flux « contents ». Pour les jeux de propriétés simples, retourne uniquement E_OK.
-
Crée un objet énumérateur qui implémente 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é.
-
Remplit les membres d’une structure STATPROPSETSTG , qui contient des informations sur la propriété définie dans son ensemble. Au retour, fournit un pointeur vers la structure.
Pour les jeux de stockage non simples, cette implémentation appelle IStorage::Stat (ou IStream::Stat) pour obtenir les informations du stockage ou du flux sous-jacent.
-
Pour les jeux de propriétés non simples uniquement, définit les heures prises en charge par le stockage sous-jacent. Cette implémentation de SetTimes appelle la méthode IStorage::SetElementTimes du stockage sous-jacent pour modifier les heures. Il prend en charge les heures prises en charge par la méthode sous-jacente, qui peut être l’heure de modification, le temps d’accès ou le temps de création.
Rubriques connexes