Constantes STGM

Les constantes STGM sont des indicateurs qui indiquent les conditions de création et de suppression de l’objet et des modes d’accès pour l’objet. Les constantes STGM sont incluses dans les interfaces IStorage, IStream et IPropertySetStorage et dans les fonctions StgCreateDocfile, StgCreateStorageEx, StgCreateDocfileOnILockBytes, StgOpenStorageEt StgOpenStorageEx .

Ces éléments sont souvent combinés à l’aide d’un opérateur OR. Ils sont interprétés dans des groupes, comme indiqué dans le tableau suivant. Il n’est pas valide d’utiliser plusieurs éléments d’un seul groupe.

Utilisez un indicateur du groupe de création lors de la création d’un objet, par exemple avec StgCreateStorageEx ou IStorage::CreateStream.

Pour plus d’informations sur la transaction, consultez la section Remarques.

STGM_READ

0x00000000L

Indique que l’objet est en lecture seule, ce qui signifie que des modifications ne peuvent pas être apportées. Par exemple, si un objet stream est ouvert avec STGM_READ, la méthode ISequentialStream::Read peut être appelée, mais pas la méthode ISequentialStream::Write . De même, si un objet de stockage ouvert avec STGM_READ, les méthodes IStorage::OpenStream et IStorage::OpenStorage peuvent être appelées, mais pas les méthodes IStorage::CreateStream et IStorage::CreateStorage .

STGM_WRITE

0x00000001L

Vous permet d’enregistrer les modifications apportées à l’objet, mais n’autorise pas l’accès à ses données. Les implémentations fournies des interfaces IPropertyStorage et IPropertySetStorage ne prennent pas en charge ce mode d’écriture seule.

STGM_READWRITE

0x00000002L

Permet l’accès et la modification des données d’objet. Par exemple, si un objet de flux est créé ou ouvert dans ce mode, il est possible d’appeler IStream::Read et IStream::Write. N’oubliez pas que cette constante n’est pas une simple opération binaire OR des éléments STGM_WRITE et STGM_READ .

STGM_SHARE_DENY_NONE

0x00000040L

Spécifie que l’accès en lecture ou en écriture n’est pas refusé aux ouvertures suivantes de l’objet. Si aucun indicateur du groupe de partage n’est spécifié, cet indicateur est supposé.

STGM_SHARE_DENY_READ

0x00000030L

Empêche d’autres utilisateurs d’ouvrir par la suite l’objet en mode STGM_READ . Il est généralement utilisé sur un objet de stockage racine.

STGM_SHARE_DENY_WRITE

0x00000020L

Empêche d’autres utilisateurs d’ouvrir par la suite l’objet pour un accès STGM_WRITE ou STGM_READWRITE . En mode transactionné, le partage de STGM_SHARE_DENY_WRITE ou de STGM_SHARE_EXCLUSIVE peut améliorer considérablement les performances, car ils ne nécessitent pas d’instantanés. Pour plus d’informations sur la transaction, consultez la section Remarques.

STGM_SHARE_EXCLUSIVE

0x00000010L

Empêche d’autres utilisateurs d’ouvrir par la suite l’objet dans n’importe quel mode. N’oubliez pas que cette valeur n’est pas une simple opération OR au niveau du bit des valeurs STGM_SHARE_DENY_READ et STGM_SHARE_DENY_WRITE . En mode transactionné, le partage de STGM_SHARE_DENY_WRITE ou de STGM_SHARE_EXCLUSIVE peut améliorer considérablement les performances, car ils ne nécessitent pas d’instantanés. Pour plus d’informations sur la transaction, consultez la section Remarques.

STGM_PRIORITY

0x00040000L

Ouvre l’objet de stockage avec un accès exclusif à la dernière version validée. Par conséquent, les autres utilisateurs ne peuvent pas valider les modifications apportées à l’objet tant que vous l’avez ouvert en mode priorité. Vous obtenez des avantages en matière de performances pour les opérations de copie, mais vous empêchez d’autres utilisateurs de valider des modifications. Limitez la durée pendant laquelle les objets sont ouverts en mode priorité. Vous devez spécifier STGM_DIRECT et STGM_READ avec le mode priorité, et vous ne pouvez pas spécifier STGM_DELETEONRELEASE. STGM_DELETEONRELEASE est valide uniquement lors de la création d’un objet racine, par exemple avec StgCreateStorageEx. Elle n’est pas valide lors de l’ouverture d’un objet racine existant, par exemple avec StgOpenStorageEx. Elle n’est pas non plus valide lors de la création ou de l’ouverture d’un sous-élément, par exemple avec IStorage::OpenStorage.

STGM_CREATE

0x00001000L

Indique qu’un objet de stockage ou un flux existant doit être supprimé avant que le nouvel objet ne le remplace. Un nouvel objet est créé lorsque cet indicateur est spécifié uniquement si l’objet existant a été supprimé avec succès.

Cet indicateur est utilisé lors de la tentative de création :

• Objet de stockage sur un disque, mais un fichier de ce nom existe.
• Objet à l’intérieur d’un objet de stockage, mais un objet portant le nom spécifié existe.
• Un objet de tableau d’octets, mais un avec le nom spécifié existe.

Cet indicateur ne peut pas être utilisé avec des opérations d’ouverture, telles que StgOpenStorageEx ou IStorage::OpenStream.

STGM_CONVERT

0x00020000L

Crée l’objet tout en conservant les données existantes dans un flux nommé « Contenu ». Dans le cas d’un objet de stockage ou d’un tableau d’octets, les anciennes données sont mises en forme dans un flux, que le fichier ou le tableau d’octets existant contienne actuellement un objet de stockage en couches. Cet indicateur ne peut être utilisé que lors de la création d’un objet de stockage racine. Il ne peut pas être utilisé dans un objet de stockage ; par exemple, dans IStorage::CreateStream. Il n’est pas non plus valide d’utiliser cet indicateur et l’indicateur STGM_DELETEONRELEASE simultanément.

STGM_FAILIFTHERE

0x00000000L

Provoque l’échec de l’opération de création si un objet existant portant le nom spécifié existe. Dans ce cas, STG_E_FILEALREADYEXISTS est retourné. Il s’agit du mode de création par défaut ; autrement dit, si aucun autre indicateur de création n’est spécifié, STGM_FAILIFTHERE est implicite.

STGM_DIRECT

0x00000000L

Indique que, en mode direct, chaque modification apportée à un élément de stockage ou de flux est écrite au fur et à mesure. Il s’agit de la valeur par défaut si ni STGM_DIRECT ni STGM_TRANSACTED n’est spécifié.

STGM_TRANSACTED

0x00010000L

Indique que, en mode transactionné, les modifications sont mises en mémoire tampon et écrites uniquement si une opération de validation explicite est appelée. Pour ignorer les modifications, appelez la méthode Revert dans l’interface IStream, IStorage ou IPropertyStorage . L’implémentation de fichiers composés COM d’IStorage ne prend pas en charge les flux traités, ce qui signifie que les flux peuvent être ouverts uniquement en mode direct et que vous ne pouvez pas rétablir les modifications apportées à ces derniers, mais les stockages traités sont pris en charge. Les implémentations de fichiers composés, autonomes et de système de fichiers NTFS d’IPropertySetStorage ne prennent pas non plus en charge les jeux de propriétés simples traités, car ces jeux de propriétés sont stockés dans des flux. Toutefois, la transaction de jeux de propriétés non simples, qui peuvent être créées en spécifiant l’indicateur PROPSETFLAG_NONSIMPLE dans le paramètre grfFlags de IPropertySetStorage::Create, est prise en charge.

STGM_NOSCRATCH

0x00100000L

Indique que, en mode transactionné, un fichier de travail temporaire est généralement utilisé pour enregistrer les modifications jusqu’à ce que la méthode Commit soit appelée. La spécification de STGM_NOSCRATCH permet d’utiliser la partie inutilisée du fichier d’origine comme espace de travail au lieu de créer un fichier à cet effet. Cela n’affecte pas les données du fichier d’origine et, dans certains cas, peut améliorer les performances. Il n’est pas valide de spécifier cet indicateur sans spécifier également STGM_TRANSACTED, et cet indicateur ne peut être utilisé que dans une racine ouverte. Pour plus d’informations sur le mode NoScratch, consultez la section Remarques.

STGM_NOSNAPSHOT

0x00200000L

Cet indicateur est utilisé lors de l’ouverture d’un objet de stockage avec STGM_TRANSACTED et sans STGM_SHARE_EXCLUSIVE ni STGM_SHARE_DENY_WRITE. Dans ce cas, la spécification de STGM_NOSNAPSHOT empêche l’implémentation fournie par le système de créer une copie instantané du fichier. Au lieu de cela, les modifications apportées au fichier sont écrites à la fin du fichier. L’espace inutilisé n’est pas récupéré, sauf si la consolidation est effectuée pendant la validation et qu’il n’y a qu’un seul enregistreur actuel sur le fichier. Lorsque le fichier est ouvert en mode sans instantané, une autre opération d’ouverture ne peut pas être effectuée sans spécifier STGM_NOSNAPSHOT. Cet indicateur ne peut être utilisé que dans une opération d’ouverture racine. Pour plus d’informations sur le mode NoSnapshot, consultez la section Remarques.

STGM_SIMPLE

0x08000000L

Fournit une implémentation plus rapide d’un fichier composé dans un cas limité, mais fréquemment utilisé. Pour plus d'informations, consultez la section Notes.

STGM_DIRECT_SWMR

0x00400000L

Prend en charge le mode direct pour les opérations de fichier multilecteur à écriture unique. Pour plus d'informations, consultez la section Notes.

STGM_DELETEONRELEASE

0x04000000L

Indique que le fichier sous-jacent doit être automatiquement détruit lorsque l’objet de stockage racine est libéré. Cette fonctionnalité est particulièrement utile pour créer des fichiers temporaires. Cet indicateur ne peut être utilisé que lors de la création d’un objet racine, par exemple avec StgCreateStorageEx. Elle n’est pas valide lors de l’ouverture d’un objet racine, par exemple avec StgOpenStorageEx, ou lors de la création ou de l’ouverture d’un sous-élément, par exemple avec IStorage::CreateStream. Il n’est pas non plus valide d’utiliser cet indicateur et l’indicateur STGM_CONVERT simultanément.

Notes

Vous pouvez combiner ces indicateurs, mais vous ne pouvez choisir qu’un seul indicateur dans chaque groupe d’indicateurs associés. En règle générale, un indicateur de chacun des groupes d’accès et de partage doit être spécifié pour toutes les fonctions et méthodes qui utilisent ces constantes. Les indicateurs d’autres groupes sont facultatifs.

Mode transactionné

Lorsque l’indicateur STGM_DIRECTest spécifié, une seule des combinaisons d’indicateurs suivantes peut être spécifiée à partir des groupes d’accès et de partage.

    STGM_READ      | STGM_SHARE_DENY_WRITE

    STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_READ      | STGM_PRIORITY

N’oubliez pas que le mode direct est impliqué par l’absence de STGM_TRANSACTED. Autrement dit, si ni STGM_DIRECT ni STGM_TRANSACTED ne sont spécifiés, STGM_DIRECT est supposé.

Lorsque l’indicateur STGM_TRANSACTED est spécifié, les objets sont créés ou ouverts en mode transactionné. Dans ce mode, les modifications apportées à un objet ne sont pas conservées tant qu’elles n’ont pas été validées. Par exemple, les modifications apportées à un objet de stockage traité ne sont pas conservées tant que la méthode IStorage::Commit n’est pas appelée. Les modifications apportées à un tel objet de stockage seront perdues si l’objet de stockage est libéré (version finale) avant l’appel de la méthode Commit , ou si la méthode IStorage::Revert est appelée.

Lorsqu’un objet est créé ou ouvert en mode transactionné, l’implémentation doit conserver les données d’origine et les mises à jour de ces données, afin que les mises à jour puissent être annulées si nécessaire. Cela est généralement effectué en écrivant des modifications dans une zone de travail jusqu’à ce qu’elles soient validées, ou en créant une copie, appelée instantané, des données validées les plus récentes.

Lorsqu’un objet de stockage racine est ouvert en mode transactionné, l’emplacement et le comportement des données de travail et des copies instantané peuvent être contrôlés pour optimiser les performances avec les indicateurs STGM_NOSCRATCH et STGM_NOSNAPSHOT. (Un objet de stockage racine est obtenu à partir, par exemple, de la fonction StgOpenStorageEx ; un objet de stockage obtenu à partir de la méthode IStorage::OpenStorage est un objet de sous-stockage.) En règle générale, les données de travail et les instantanés sont stockés dans des fichiers temporaires, distincts du stockage.

L’effet de ces indicateurs dépend du nombre de lecteurs et/ou d’enregistreurs qui accèdent au stockage racine.

Dans le cas d’un « enregistreur unique », un objet de stockage en mode transactionné est ouvert pour l’accès en écriture et il ne peut y avoir aucun autre accès au fichier. Autrement dit, le fichier est ouvert avec STGM_TRANSACTED, l’accès de STGM_WRITE ou de STGM_READWRITE et le partage de STGM_SHARE_EXCLUSIVE. Dans ce cas, les modifications apportées à l’objet de stockage sont écrites dans la zone de travail. Lorsque ces modifications sont validées, elles sont copiées dans le stockage d’origine. Par conséquent, si aucune modification n’est réellement apportée à l’objet de stockage, il n’y aura pas de transfert de données inutile.

Dans le cas de « plusieurs enregistreurs », un objet de stockage traité est ouvert pour l’accès en écriture, mais est partagé dans tel que pour autoriser d’autres enregistreurs. Autrement dit, l’objet de stockage est ouvert avec STGM_TRANSACTED, l’accès de STGM_WRITE ou de STGM_READWRITE et le partage de STGM_SHARE_DENY_READ. Si le partage de STGM_SHARE_DENY_NONE est spécifié à la place, le cas est « multi-writer, multi-reader ». Dans ce cas, une instantané des données d’origine est effectuée pendant l’opération d’ouverture. Par conséquent, même si aucune modification n’est réellement apportée au stockage et/ou s’il n’est pas ouvert simultanément par un autre enregistreur, le transfert de données est toujours nécessaire pendant l’ouverture. Par conséquent, les meilleures performances d’ouverture peuvent être obtenues en ouvrant l’objet de stockage en mode STGM_SHARE_DENY_WRITE ou STGM_SHARE_EXCLUSIVE . Pour plus d’informations sur la façon dont les modifications sont validées lorsqu’il existe plusieurs enregistreurs, consultez IStorage::Commit.

Dans le cas « mono-writer, multi-lecteur », un objet de stockage traité est ouvert pour l’accès en écriture, mais est partagé avec les lecteurs. Autrement dit, l’objet de stockage est ouvert par l’enregistreur avec STGM_TRANSACTED, l’accès de STGM_READWRITE ou de STGM_WRITE et le partage de STGM_SHARE_DENY_WRITE. Le stockage est ouvert par les lecteurs avec STGM_TRANSACTED, l’accès de STGM_READ et le partage de STGM_SHARE_DENY_NONE. Dans ce cas, l’enregistreur utilise la zone de travail pour stocker les modifications non validées. Comme dans les cas ci-dessus, le lecteur entraîne une pénalité de performances en temps ouvert pendant qu’une copie instantané des données est créée.

En règle générale, la zone de travail est un fichier temporaire, distinct des données d’origine. Lorsque des modifications sont validées dans le fichier d’origine, les données doivent être transférées à partir du fichier temporaire. Pour éviter ce transfert de données, l’indicateur STGM_NOSCRATCHpeut être spécifié. Lorsque cet indicateur est spécifié, des parties du fichier objet de stockage sont utilisées pour la zone de travail, plutôt qu’un fichier temporaire distinct. Par conséquent, la validation des modifications peut être effectuée rapidement, car peu de transfert de données est nécessaire. L’inconvénient est que le fichier de stockage peut devenir plus volumineux qu’il ne le serait autrement, car il doit être développé pour être suffisamment grand pour les données d’origine et la zone de travail. Pour consolider les données et supprimer cette zone inutile, rouvrez le stockage racine en mode traité, mais sans définir l’indicateur STGM_NOSCRATCH . Ensuite, appelez IStorage::Commit avec l’indicateur STGC_CONSOLIDATE défini.

La zone instantané, comme la zone de travail, est également, généralement, un fichier temporaire, et cela peut également être affecté avec un indicateur STGM. En spécifiant l’indicateur STGM_NOSNAPSHOT, un fichier instantané temporaire distinct n’est pas créé. Au lieu de cela, les données d’origine ne sont jamais modifiées, même s’il existe un ou plusieurs enregistreurs par objet. Lorsque les modifications sont validées, elles sont ajoutées au fichier, mais les données d’origine restent intactes. Ce mode augmente l’efficacité, car il réduit le temps d’exécution en éliminant la nécessité de créer un instantané pendant l’opération d’ouverture. Toutefois, l’utilisation de ce mode peut entraîner un fichier de stockage très volumineux, car les données du fichier ne peuvent jamais être remplacées. Il ne s’agit pas d’une limite à la taille des fichiers ouverts en mode NoSnapshot.

Direct Single-Writer, Multiple-Reader Mode

Comme décrit, il est possible d’avoir un seul enregistreur et plusieurs lecteurs d’un objet de stockage, si cet objet est ouvert en mode transactionné. Il est également possible d’obtenir le cas multilecteur unique en mode direct en spécifiant l’indicateur STGM_DIRECT_SWMR .

En mode STGM_DIRECT_SWMR , il est possible pour un appelant d’ouvrir un objet pour l’accès en lecture/écriture, tandis que d’autres appelants ont simultanément le fichier ouvert pour un accès en lecture seule. Il n’est pas valide d’utiliser cet indicateur en combinaison avec l’indicateur STGM_TRANSACTED . Dans ce mode, l’enregistreur ouvre l’objet avec les indicateurs suivants :

| STGM_DIRECT_SWMR | STGM_READWRITE STGM_SHARE_DENYWRITE

et chacun des lecteurs ouvre l’objet avec les indicateurs suivants :

| STGM_DIRECT_SWMR | STGM_READ STGM_SHARE_DENY_NONE

Dans ce mode, pour modifier l’objet de stockage, l’enregistreur doit obtenir un accès exclusif à l’objet. Cela est possible lorsque tous les lecteurs l’ont fermé. L’enregistreur utilise l’interface IDirectWriterLock pour obtenir cet accès exclusif.

Mode simple

Le mode simple (STGM_SIMPLE) est utile pour les applications qui effectuent des opérations d’enregistrement complètes. Il est efficace, mais présente les contraintes suivantes :

• Il n’existe aucune prise en charge pour les sous-stockages.
• L’objet de stockage et les objets de flux obtenus à partir de celui-ci ne peuvent pas être marshalés.
• Chaque flux a une taille minimale. Si moins d’octets minimum sont écrits dans un flux lorsque le flux est libéré, celui-ci est étendu à la taille minimale. Par exemple, la taille minimale d’une implémentation IStream particulière est de 4 Ko. Un flux est créé et 1 Ko y est écrit. À la version finale de cet IStream, la taille du flux est automatiquement étendue à 4 Ko. Par la suite, l’ouverture du flux et l’appel de la méthode IStream::Stat affichent une taille de 4 Ko.
• Toutes les méthodes d’IStorage ou D’IStream ne seront pas prises en charge par l’implémentation. Pour plus d’informations, consultez IStorage - Implémentation de fichier composé et IStream - Implémentation de fichiers composés.

Le marshaling est le processus d’empaquetage, de décompression et d’envoi de paramètres de méthode d’interface au sein d’un appel de procédure distante (RPC). Pour plus d’informations, consultez Marshaling Details et Interface Marshaling.

Lorsqu’un objet de stockage est obtenu par une opération Create en mode simple :

• Les éléments stream peuvent être créés, mais pas ouverts.
• Lorsqu’un élément stream est créé en appelant IStorage::CreateStream, il n’est pas possible de créer un autre flux tant que cet objet de flux n’est pas libéré.
• Une fois tous les flux écrits, appelez IStorage::Commit pour vider les modifications.

Lorsqu’un objet de stockage est obtenu par une opération Open en mode simple :

• Il est possible d’ouvrir un seul élément de flux à la fois.
• Il n’est pas possible de modifier la taille d’un flux en appelant la méthode IStream::SetSize ou en recherchant ou en écrivant au-delà de la fin du flux. Toutefois, étant donné que tous les flux ont une taille minimale, il est possible d’utiliser le flux jusqu’à cette taille, même si moins de données y ont été écrites à l’origine. Pour déterminer la taille d’un flux, utilisez la méthode IStream::Stat .

N’oubliez pas que, si un élément de stockage est modifié par un objet de stockage qui n’est pas en mode simple, il ne sera pas possible, là encore, d’ouvrir cet élément de stockage en mode simple.

Spécifications

Voir aussi

ISequentialStream::Read

IStorage

StgCreateDocfile

StgCreateDocfileOnILockBytes

StgCreateStorageEx

StgOpenStorage

StgOpenStorageEx

StgOpenStorageOnILockBytes