implémentation de fichier IPropertyStorage-Compound
L’implémentation COM de l’architecture de stockage structuré est appelée fichiers composés. Les objets de stockage implémentés dans les fichiers composés incluent une implémentation d’IPropertyStorage, l’interface qui gère un jeu de propriétés persistant unique, et IPropertySetStorage, l’interface qui gère les groupes de jeux de propriétés persistants. Pour plus d’informations sur l’interface IPropertyStorage , consultez Considérations relatives à IPropertyStorage et au stockage des propriétés.
Pour obtenir un pointeur vers l’implémentation de fichier composé d’IPropertyStorage, appelez StgCreateStorageEx pour créer un objet de fichier composé ou StgOpenStorageEx pour ouvrir un objet de fichier composé précédemment créé. Dans le cas de StgCreateStorageEx, le paramètre stgfmt doit être défini sur STGFMT_STORAGE. Dans le cas de StgOpenStorageEx, le paramètre stgfmt doit être défini sur STGFMT_STORAGE ou STGFMT_ANY. Dans les deux cas, le paramètre riid doit être défini sur IID_IPropertySetStorage. Les deux fonctions fournissent un pointeur vers l’interface IPropertySetStorage de l’objet . En appelant la méthode Create ou Open de cette interface, vous obtenez 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 anciennes fonctions StgCreateDocfile et StgOpenStorage , ou à spécifier un paramètre riid de IID_IStorage à la fonction StgCreateStorageEx ou StgOpenStorageEx . Dans les deux cas, un pointeur vers l’interface IStorage de l’objet est retourné. Avec des 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’identificateur d’interface (IID) IID_IPropertySetStorage.
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 identificateurs de propriétés. 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 vous permet de définir des heures associées au stockage de propriétés, et une autre qui permet l’attribution d’un CLSID qui peut être utilisé pour associer un autre code, tel que le code d’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, ce qui vous permet d’énumérer les propriétés dans l’ensemble.
Notes
Si vous obtenez un pointeur vers IPropertyStorage en appelant StgCreateDocfile, StgCreateStorageEx, StgOpenStorage Ou StgOpenStorageEx sur un stockage d’ensembles de propriétés en mode simple, les méthodes IPropertyStorage respectent les règles des flux en mode simple. Le stockage du jeu de propriétés est en mode simple s’il a été obtenu pour un fichier qui a été créé ou ouvert avec l’indicateur STGM_SIMPLE. Dans ce cas, il n’est pas toujours possible d’agrandir le flux sous-jacent et il n’est pas possible de remplacer les propriétés existantes par des propriétés plus grandes. Pour plus d’informations, consultez Implémentation de fichier composé IPropertySetStorage.
IPropertyStorage et mise en cache
L’implémentation de fichiers composés d’IPropertyStorage cache des 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.
Ensembles 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 en mode simple. Par exemple, un objet de stockage de jeu de propriétés serait en mode simple s’il était obtenu à partir de la fonction StgOpenStorageEx , avec l’indicateur STGM_SIMPLE défini dans le paramètre grfMode . Notez que le « mode simple » n’est pas lié à « ensembles 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_NONSIMPLE défini dans le paramètre grfFlags . Pour plus d’informations sur les ensembles de propriétés simples et non simples, consultez Storage and Stream Objects for a Property Set.
Lorsqu’un objet de stockage de propriétés en mode simple est créé, il n’existe 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 développé. Par conséquent, il n’est pas toujours possible de modifier un tel objet de stockage de propriété si la modification nécessite un flux plus important.
Formats des ensembles de propriétés
L’implémentation de fichiers composés d’IPropertyStorage prend en charge les formats de sérialisation des ensembles de propriétés version 0 et version 1. Le format version 1 est pris en charge sur les ordinateurs exécutant 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 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 les implémentations qui reconnaissent uniquement la version 0.
Types IPropertyStorage et Variant
L’implémentation de fichiers composés d’IPropertyStorage ne prend pas en charge les types variants VT_UNKNOWN ou VT_DISPATCH dans le membre vt de la structure PROPVARIANT .
Le tableau suivant répertorie les types de variantes 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 de fichiers composés 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 de PROPVARIANTs. Dans l’implémentation de fichier composé COM, les identificateurs de propriété dupliqués 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 les opérations d’ouverture. Étant donné que dans un fichier composé STGM_SHARE_EXCLUSIVE est forcé, plusieurs tentatives ouvertes échouent. L’ouverture du 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 l’opération thread-safe si la même propriété de flux ou de stockage est demandée plusieurs fois par le biais du même pointeur IPropertyStorage dans l’implémentation de fichier composé COM, l’opération d’ouverture réussit ou échoue 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 stockage entraîne toujours un appel à IStorage::OpenStream, ou IStorage::OpenStorage, qui transmet 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 correctement, 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.
-
É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. 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 propriétés pour les propriétés spécifiées dans le tableau rgpropid[].
-
Définit le CLSID du flux de jeux de propriétés. Dans l’implémentation de fichier composé, la définition du CLSID sur un ensemble de propriétés non simples (qui peut contenir légalement 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 du jeu de propriétés dans le stockage sous-jacent. En outre, pour les jeux de propriétés en mode transactionné non simple, cette méthode effectue une validation (comme dans IStorage::Commit) sur le stockage qui contient 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, cette interface retourne toujours S_OK. Les jeux de propriétés non simples sont ceux qui ont été créés à l’aide de l’indicateur PROPSETFLAG_NONSIMPLE dans la méthode IPropertySetStorage::Create . Pour plus d’informations, consultez Objets de stockage et de flux pour un jeu de propriétés .
-
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 du jeu. Cette implémentation crée un tableau dans lequel l’ensemble du jeu de propriétés est lu et qui peut être partagé lorsque IEnumSTATPROPSTG::Clone est appelé. Les modifications apportées au jeu de propriétés ne sont pas répercutées dans un instance IEnumSTATPROPSTG ouvert. Pour voir ces modifications, une nouvelle instance de cet énumérateur doit être construite.
-
Remplit les membres d’une structure STATPROPSETSTG , qui contient des données sur le jeu de propriétés 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 heures du stockage ou du flux sous-jacent. Pour les jeux de stockage simples, aucune heure n’est conservée.
-
Pour les jeux de propriétés non simples uniquement, 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 : 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.
Rubriques connexes