Costanti STGM

Le costanti STGM sono flag che indicano le condizioni per la creazione e l'eliminazione dell'oggetto e delle modalità di accesso per l'oggetto. Le costanti STGM sono incluse nelle interfacce IStorage, IStream e IPropertySetStoragee nelle funzioni StgCreateDocfile, StgCreateStorageEx, StgCreateDocfileOnILockBytes, StgOpenStorage e StgOpenStorageEx.

Questi elementi vengono spesso combinati usando un operatore OR. Vengono interpretati in gruppi come elencati nella tabella seguente. Non è valido usare più di un elemento da un singolo gruppo.

Usare un flag dal gruppo di creazione durante la creazione di un oggetto, ad esempio con StgCreateStorageEx o IStorage::CreateStream.

Per altre informazioni sulla transazione, vedere la sezione Osservazioni.

STGM_READ

0x00000000L

Indica che l'oggetto è di sola lettura, ovvero che non è possibile apportare modifiche. Ad esempio, se un oggetto di flusso viene aperto con STGM_READ, il metodo ISequentialStream: :Read può essere chiamato, ma il metodo ISequentialStream::Write potrebbe non essere chiamato. Analogamente, se un oggetto di archiviazione aperto con STGM_READ, i metodi IStorage::OpenStream e IStorage::OpenStorage possono essere chiamati, ma i metodi IStorage::CreateStream e IStorage::CreateStorage::CreateStorage potrebbero non essere chiamati.

STGM_WRITE

0x00000001L

Consente di salvare le modifiche all'oggetto, ma non consente l'accesso ai dati. Le implementazioni fornite delle interfacce IPropertyStorage e IPropertySetStorage non supportano questa modalità di sola scrittura.

STGM_READWRITE

0x00000002L

Abilita l'accesso e la modifica dei dati dell'oggetto. Ad esempio, se un oggetto di flusso viene creato o aperto in questa modalità, è possibile chiamare sia IStream::Read che IStream::Write. Tenere presente che questa costante non è una semplice operazione OR binaria degli elementi STGM_WRITE e STGM_READ .

STGM_SHARE_DENY_NONE

0x00000040L

Specifica che le aperture successive dell'oggetto non vengono negate l'accesso in lettura o scrittura. Se non viene specificato alcun flag dal gruppo di condivisione, questo flag viene assunto.

STGM_SHARE_DENY_READ

0x0000030L

Impedisce ad altri di aprire successivamente l'oggetto in modalità STGM_READ. Viene in genere usato in un oggetto di archiviazione radice.

STGM_SHARE_DENY_WRITE

0x00000020L

Impedisce ad altri utenti di aprire successivamente l'oggetto per STGM_WRITE o STGM_READWRITE accesso. In modalità transazionata la condivisione di STGM_SHARE_DENY_WRITE o STGM_SHARE_EXCLUSIVE può migliorare significativamente le prestazioni perché non richiedono snapshot. Per altre informazioni sulla transazione, vedere la sezione Osservazioni.

STGM_SHARE_EXCLUSIVE

0x00000010L

Impedisce ad altri di aprire successivamente l'oggetto in qualsiasi modalità. Tenere presente che questo valore non è un'operazione OR bit per bit semplice dei valori STGM_SHARE_DENY_READ e STGM_SHARE_DENY_WRITE . In modalità transazionata la condivisione di STGM_SHARE_DENY_WRITE o STGM_SHARE_EXCLUSIVE può migliorare significativamente le prestazioni perché non richiedono snapshot. Per altre informazioni sulla transazione, vedere la sezione Osservazioni.

STGM_PRIORITY

0x00040000L

Apre l'oggetto di archiviazione con accesso esclusivo alla versione di commit più recente. Pertanto, altri utenti non possono eseguire il commit delle modifiche all'oggetto mentre sono aperte in modalità priorità. Si ottengono vantaggi delle prestazioni per le operazioni di copia, ma si impedisce ad altri utenti di eseguire il commit delle modifiche. Limitare il tempo di apertura degli oggetti in modalità priorità. È necessario specificare STGM_DIRECT e STGM_READ con la modalità di priorità e non è possibile specificare STGM_DELETEONRELEASE. STGM_DELETEONRELEASE è valido solo quando si crea un oggetto radice, ad esempio con StgCreateStorageEx. Non è valido quando si apre un oggetto radice esistente, ad esempio con StgOpenStorageEx. Non è valido anche quando si crea o si apre un sottoelemento, ad esempio con IStorage::OpenStorage.

STGM_CREATE

0x00001000L

Indica che un oggetto di archiviazione o un flusso esistente deve essere rimosso prima che il nuovo oggetto lo sostituisca. Un nuovo oggetto viene creato quando questo flag viene specificato solo se l'oggetto esistente è stato rimosso correttamente.

Questo flag viene usato durante il tentativo di creazione:

• Oggetto di archiviazione su un disco, ma esiste un file di tale nome.
• Un oggetto all'interno di un oggetto di archiviazione, ma esiste un oggetto con il nome specificato.
• Un oggetto matrice di byte, ma uno con il nome specificato esiste.

Questo flag non può essere usato con operazioni aperte, ad esempio StgOpenStorageEx o IStorage::OpenStream.

STGM_CONVERT

0x0002000L

Crea il nuovo oggetto mantenendo i dati esistenti in un flusso denominato "Contenuto". Nel caso di un oggetto di archiviazione o di una matrice di byte, i dati precedenti vengono formattati in un flusso indipendentemente dal fatto che il file o la matrice di byte esistente contenga attualmente un oggetto di archiviazione a livelli. Questo flag può essere usato solo quando si crea un oggetto di archiviazione radice. Non può essere usato all'interno di un oggetto di archiviazione; ad esempio, in IStorage::CreateStream. Non è anche valido usare questo flag e il flag di STGM_DELETEONRELEASE contemporaneamente.

STGM_FAILIFTHERE

0x00000000L

Causa l'esito negativo dell'operazione di creazione se esiste un oggetto esistente con il nome specificato. In questo caso, STG_E_FILEALREADYEXISTS viene restituito. Si tratta della modalità di creazione predefinita; ovvero, se non viene specificato alcun altro flag di creazione, STGM_FAILIFTHERE è implicito.

STGM_DIRECT

0x00000000L

Indica che, in modalità diretta, ogni modifica a un elemento di archiviazione o flusso viene scritta come si verifica. Si tratta dell'impostazione predefinita se non viene specificato né STGM_DIRECT né STGM_TRANSACTED .

STGM_TRANSACTED

0x00010000L

Indica che, in modalità transazionata, le modifiche vengono memorizzate nel buffer e scritte solo se viene chiamata un'operazione di commit esplicita. Per ignorare le modifiche, chiamare il metodo Revert nell'interfaccia IStream, IStorage o IPropertyStorage . L'implementazione del file composto COM di IStorage non supporta i flussi transazionati, il che significa che i flussi possono essere aperti solo in modalità diretta e non è possibile ripristinare le modifiche apportate, tuttavia sono supportate le risorse di archiviazione transazionate. I file composti, autonomi e le implementazioni del file system NTFS di IPropertySetStorage non supportano in modo analogo i set di proprietà transazionati, semplici perché questi set di proprietà vengono archiviati in flussi. Tuttavia, la transazione di set di proprietà nonsimple, che possono essere creati specificando il flag PROPSETFLAG_NONSIMPLE nel parametro grfFlags di IPropertySetStorage::Create, sono supportati.

STGM_NOSCRATCH

0x0010000L

Indica che, in modalità transazionata, viene in genere usato un file di gratta e temporaneo per salvare le modifiche finché non viene chiamato il metodo Commit . Se si specifica STGM_NOSCRATCH , la parte inutilizzata del file originale deve essere usata come spazio di lavoro anziché creare un nuovo file per tale scopo. Ciò non influisce sui dati nel file originale e in alcuni casi può comportare prestazioni migliorate. Non è valido specificare questo flag senza specificare anche STGM_TRANSACTED e questo flag può essere usato solo in un'apertura radice. Per altre informazioni sulla modalità NoScratch, vedere la sezione Osservazioni.

STGM_NOSNAPSHOT

0x0020000L

Questo flag viene usato quando si apre un oggetto di archiviazione con STGM_TRANSACTED e senza STGM_SHARE_EXCLUSIVE o STGM_SHARE_DENY_WRITE. In questo caso, specificando STGM_NOSNAPSHOT impedisce all'implementazione fornita dal sistema di creare una copia snapshot del file. Le modifiche apportate al file vengono invece scritte alla fine del file. Lo spazio inutilizzato non viene recuperato a meno che il consolidamento non venga eseguito durante il commit e che nel file sia presente un solo writer corrente. Quando il file viene aperto in modalità snapshot, non è possibile eseguire un'altra operazione aperta senza specificare STGM_NOSNAPSHOT. Questo flag può essere usato solo in un'operazione di apertura radice. Per altre informazioni sulla modalità NoSnapshot, vedere la sezione Osservazioni.

STGM_SIMPLE

0x08000000L

Fornisce un'implementazione più veloce di un file composto in un numero limitato, ma spesso usato, caso. Per altre informazioni, vedere la sezione Osservazioni.

STGM_DIRECT_SWMR

0x0040000L

Supporta la modalità diretta per operazioni di file a scrittura singola e multireader. Per altre informazioni, vedere la sezione Osservazioni.

STGM_DELETEONRELEASE

0x0400000L

Indica che il file sottostante deve essere eliminato automaticamente quando l'oggetto di archiviazione radice viene rilasciato. Questa funzionalità è più utile per la creazione di file temporanei. Questo flag può essere usato solo quando si crea un oggetto radice, ad esempio con StgCreateStorageEx. Non è valido quando si apre un oggetto radice, ad esempio con StgOpenStorageEx o quando si crea o si apre un sottoelemento, ad esempio con IStorage::CreateStream. Non è anche valido usare questo flag e il flag di STGM_CONVERT contemporaneamente.

Commenti

È possibile combinare questi flag, ma è possibile scegliere un solo flag da ogni gruppo di flag correlati. In genere un flag di ognuno dei gruppi di accesso e condivisione deve essere specificato per tutte le funzioni e i metodi che usano queste costanti. I flag di altri gruppi sono facoltativi.

Modalità transazionata

Quando viene specificato il flag di STGM_DIRECT, è possibile specificare solo una delle combinazioni seguenti di flag dai gruppi di accesso e condivisione.

    STGM_READ      | STGM_SHARE_DENY_WRITE

    STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_READ      | STGM_PRIORITY

Tenere presente che la modalità diretta è implicita dall'assenza di STGM_TRANSACTED. Vale a dire, se non viene specificato né STGM_DIRECT né STGM_TRANSACTED , STGM_DIRECT viene assunto.

Quando viene specificato il flag STGM_TRANSACTED , gli oggetti vengono creati o aperti in modalità transazionata. In questa modalità le modifiche a un oggetto non vengono mantenute finché non vengono eseguite il commit. Ad esempio, le modifiche apportate a un oggetto di archiviazione transazionato non vengono mantenute finché non viene chiamato il metodo IStorage::Commit . Le modifiche apportate a tale oggetto di archiviazione verranno perse se l'oggetto di archiviazione viene rilasciato (versione finale) prima che venga chiamato il metodo Commit oppure se viene chiamato il metodo IStorage::Revert .

Quando un oggetto viene creato o aperto in modalità transazionata, l'implementazione deve mantenere sia i dati originali che gli aggiornamenti a questi dati, in modo che gli aggiornamenti possano essere ripristinati se necessario. Questa operazione viene in genere eseguita scrivendo modifiche in un'area di graffi fino a quando non vengono eseguite il commit o creando una copia, denominata snapshot, dei dati di cui è stato eseguito il commit più recente.

Quando un oggetto di archiviazione radice viene aperto in modalità transazionata, la posizione e il comportamento dei dati zero e le copie snapshot possono essere controllate per ottimizzare le prestazioni con i flag di STGM_NOSCRATCH e STGM_NOSNAPSHOT . Un oggetto di archiviazione radice viene ottenuto, ad esempio, dalla funzione StgOpenStorageEx . Un oggetto di archiviazione ottenuto dal metodo IStorage::OpenStorage è un oggetto sottostorage. In genere, i dati e gli snapshot di zero vengono archiviati in file temporanei, separati dall'archiviazione.

L'effetto di questi flag dipende dal numero di lettori e/o writer che accedono all'archiviazione radice.

Nel caso "single-writer" viene aperto un oggetto di archiviazione in modalità transacted per l'accesso in scrittura e non è possibile accedere al file. Ovvero, il file viene aperto con STGM_TRANSACTED, accesso di STGM_WRITE oSTGM_READWRITE e condivisione di STGM_SHARE_EXCLUSIVE. In questo caso, le modifiche apportate all'oggetto di archiviazione vengono scritte nell'area zero. Quando tali modifiche vengono eseguite il commit, vengono copiate nell'archiviazione originale. Pertanto, se non vengono apportate modifiche all'oggetto di archiviazione, non sarà necessario trasferire dati non necessari.

Nel caso "multiple-writer" viene aperto un oggetto di archiviazione transazionato per l'accesso in scrittura, ma è condiviso in modo da consentire ad altri writer. Ovvero, l'oggetto di archiviazione viene aperto con STGM_TRANSACTED, accesso di STGM_WRITE o STGM_READWRITE e condivisione di STGM_SHARE_DENY_READ. Se invece viene specificata la condivisione di STGM_SHARE_DENY_NONE , il caso è "multiple-writer, multiple-reader". In questi casi viene eseguito uno snapshot dei dati originali durante l'operazione aperta. Pertanto, anche se non vengono apportate modifiche all'archiviazione e/o non è effettivamente aperto da un altro writer contemporaneamente, il trasferimento dei dati è ancora necessario durante l'apertura. Di conseguenza, è possibile ottenere le migliori prestazioni open-time aprendo l'oggetto di archiviazione in STGM_SHARE_DENY_WRITE o STGM_SHARE_EXCLUSIVE modalità. Per altre informazioni sul commit delle modifiche quando sono presenti più writer, vedere IStorage::Commit.

Nel caso "single-writer, multiple-reader" viene aperto un oggetto di archiviazione transazionato per l'accesso in scrittura, ma è condiviso con i lettori. Ovvero, l'oggetto di archiviazione viene aperto dal writer con STGM_TRANSACTED, accesso di STGM_READWRITE o STGM_WRITE e condivisione di STGM_SHARE_DENY_WRITE. L'archiviazione viene aperta dai lettori con STGM_TRANSACTED, accesso di STGM_READ e condivisione di STGM_SHARE_DENY_NONE. In questo caso il writer usa l'area zero per archiviare le modifiche non inviate. Come nei casi precedenti, il lettore comporta una penalità delle prestazioni open-time mentre viene creata una copia snapshot dei dati.

In genere, l'area zero è un file temporaneo, separato dai dati originali. Quando le modifiche vengono eseguite nel file originale, i dati devono essere trasferiti dal file temporaneo. Per evitare il trasferimento dei dati, è possibile specificare il flag di STGM_NOSCRATCH. Quando viene specificato questo flag, le parti del file dell'oggetto di archiviazione vengono usate per l'area di graffio anziché per un file temporaneo separato. Di conseguenza, il commit delle modifiche può essere eseguito rapidamente, perché è necessario un trasferimento di dati di piccole dimensioni. Lo svantaggio è che il file di archiviazione può diventare più grande di quello che altrimenti sarebbe, perché deve essere cresciuto abbastanza grande sia per i dati originali che per l'area di graffio. Per consolidare i dati e rimuovere questa area non necessaria, riaprire l'archiviazione radice in modalità transazionata, ma senza impostare il flag di STGM_NOSCRATCH . Chiamare quindi IStorage::Commit con il set di flag STGC_CONSOLIDATE .

L'area dello snapshot, come l'area di graffi, è anche, in genere, un file temporaneo e questo può essere interessato anche con un flag STGM. Specificando il flag STGM_NOSNAPSHOT , non viene creato un file snapshot temporaneo separato. I dati originali non vengono invece mai modificati, anche se sono presenti uno o più writer per oggetto. Quando si esegue il commit delle modifiche, vengono aggiunti al file, ma i dati originali rimangono intatti. Questa modalità aumenta l'efficienza perché riduce il tempo di esecuzione eliminando il requisito di creazione di uno snapshot durante l'operazione aperta. Tuttavia, l'uso di questa modalità può comportare un file di archiviazione molto grande perché i dati nel file non possono mai essere sovrascritti. Non si tratta di alcun limite alle dimensioni dei file aperti in modalità NoSnapshot.

Scrittura singola diretta, modalità Multiple-Reader

Come descritto, è possibile avere un singolo writer e più lettori di un oggetto di archiviazione, se tale oggetto viene aperto in modalità transacted. È anche possibile ottenere il caso single-writer, multireader in modalità diretta, specificando il flag di STGM_DIRECT_SWMR .

In STGM_DIRECT_SWMR modalità è possibile aprire un chiamante per l'accesso in lettura/scrittura, mentre altri chiamanti hanno simultaneamente l'apertura del file per l'accesso in sola lettura. Non è valido usare questo flag in combinazione con il flag STGM_TRANSACTED . In questa modalità, il writer apre l'oggetto con i flag seguenti:

| STGM_DIRECT_SWMR | STGM_READWRITE STGM_SHARE_DENYWRITE

e ognuno dei lettori apre l'oggetto con questi flag:

| STGM_DIRECT_SWMR | STGM_READ STGM_SHARE_DENY_NONE

In questa modalità, per modificare l'oggetto di archiviazione, il writer deve ottenere l'accesso esclusivo all'oggetto. Ciò è possibile quando tutti i lettori lo hanno chiuso. Il writer usa l'interfaccia IDirectWriterLock per ottenere questo accesso esclusivo.

Modalità semplice

La modalità semplice (STGM_SIMPLE) è utile per le applicazioni che eseguono operazioni di salvataggio complete. È efficiente, ma presenta i vincoli seguenti:

• Nessun supporto per le sottostorage.
• Impossibile eseguire il marshalling degli oggetti di archiviazione e di flusso ottenuti da esso.
• Ogni flusso ha una dimensione minima. Se meno dei byte minimi vengono scritti in un flusso quando il flusso viene rilasciato, il flusso viene esteso alle dimensioni minime. Ad esempio, le dimensioni minime per un'implementazione IStream specifica sono 4 KB. Viene creato un flusso e viene scritto 1 KB. Alla versione finale di tale IStream, le dimensioni del flusso verranno estese automaticamente a 4 KB. Successivamente, aprire il flusso e chiamare il metodo IStream::Stat mostrerà una dimensione di 4 KB.
• Non tutti i metodi di IStorage o IStream saranno supportati dall'implementazione. Per altre informazioni, vedere Implementazione di IStorage - File composta e Implementazione di file composti IStream.

Il marshalling è il processo di creazione di pacchetti, scomprimemento e invio di parametri del metodo di interfaccia tra thread o limiti di processo all'interno di una chiamata di procedura remota (RPC). Per altre informazioni, vedere Marshalling dei dettagli e marshalling dell'interfaccia.

Quando un oggetto di archiviazione viene ottenuto da un'operazione Create in modalità semplice:

• È possibile creare elementi di flusso, ma non aperti.
• Quando un elemento di flusso viene creato chiamando IStorage::CreateStream, non è possibile creare un altro flusso finché tale oggetto di flusso non viene rilasciato.
• Dopo aver scritto tutti i flussi, chiamare IStorage::Commit per scaricare le modifiche.

Quando un oggetto di archiviazione viene ottenuto da un'operazione Open in modalità semplice:

• È possibile aprire un solo elemento di flusso alla volta.
• Non è possibile modificare le dimensioni di un flusso chiamando il metodo IStream::SetSize o cercando o scrivendo oltre la fine del flusso. Tuttavia, poiché tutti i flussi sono di dimensioni minime, è possibile usare il flusso fino a tale dimensione, anche se in origine sono stati scritti meno dati. Per determinare le dimensioni di un flusso, usare il metodo IStream::Stat .

Tenere presente che, se un elemento di archiviazione viene modificato da un oggetto di archiviazione che non è in modalità semplice, non sarà possibile, di nuovo, aprire tale elemento di archiviazione in modalità semplice.

Requisiti

Vedi anche

ISequentialStream::Read

IStorage

StgCreateDocfile

StgCreateDocfileOnILockBytes

StgCreateStorageEx

StgOpenStorage

StgOpenStorageEx

StgOpenStorageOnILockBytes