Metodo IStorage::Commit (objidl.h)

  • Articolo

Il metodo Commit garantisce che tutte le modifiche apportate a un oggetto di archiviazione aperte in modalità transazionali vengano riflesse nella risorsa di archiviazione padre. Per gli oggetti di archiviazione nonroot in modalità diretta, questo metodo non ha alcun effetto. Per un archivio radice, riflette le modifiche nel dispositivo effettivo; ad esempio un file su disco. Per un oggetto di archiviazione radice aperto in modalità diretta, chiamare sempre il metodo IStorage::Commit prima di Release. IStorage::Commit scarica tutti i buffer di memoria sul disco per una risorsa di archiviazione radice in modalità diretta e restituirà un codice di errore in caso di errore. Anche se Release scarica anche i buffer di memoria su disco, non ha capacità di restituire eventuali codici di errore in caso di errore. Pertanto, la chiamata a Release senza prima chiamare commit causa risultati indeterminato.

Sintassi

HRESULT Commit(
  [in] DWORD grfCommitFlags
);

Parametri

[in] grfCommitFlags

Controlla la modalità di commit delle modifiche nell'oggetto di archiviazione. Per una definizione di questi valori, vedere l'enumerazione STGC .

Valore restituito

Questo metodo può restituire uno di questi valori.

Codice restituito Descrizione
S_OK È stato eseguito il commit delle modifiche apportate all'oggetto di archiviazione al livello padre. Se è stato specificato STGC_CONSOLIDATE, lo spazio di archiviazione è stato consolidato correttamente o lo spazio di archiviazione era già troppo compatto per consolidare ulteriormente.
STG_S_MULTIPLEOPENS L'operazione di commit è riuscita, ma non è stato possibile consolidare lo spazio di archiviazione perché è stato aperto più volte usando il flag STGM_NOSNAPSHOT.
STG_S_CANNOTCONSOLIDATE L'operazione di commit è riuscita, ma non è stato possibile consolidare lo spazio di archiviazione a causa di una modalità di archiviazione non corretta. Per i file composti, è possibile che l'archiviazione sia stata aperta usando il flag di STGM_NOSCRATCH oppure che l'archiviazione non sia il livello transazionato più esterno.
STG_S_CONSOLIDATIONFAILED L'operazione di commit ha avuto esito positivo, ma non è stato possibile consolidare lo spazio di archiviazione a causa di un errore interno, ad esempio un errore di allocazione della memoria.
E_PENDING Solo archiviazione asincrona: parte o tutti i dati di cui eseguire il commit non sono attualmente disponibili.
STG_E_INVALIDFLAG Il valore per il parametro grfCommitFlags non è valido.
STG_E_INVALIDPARAMETER Uno dei parametri non è valido.
STG_E_NOTCURRENT Un'altra istanza aperta dell'oggetto di archiviazione ha eseguito il commit delle modifiche. Di conseguenza, l'operazione di commit corrente può sovrascrivere le modifiche precedenti.
STG_E_MEDIUMFULL Nessuno spazio lasciato nel dispositivo per il commit.
STG_E_TOOMANYOPENFILES Impossibile completare l'operazione di commit perché sono presenti troppi file aperti.
STG_E_REVERTED L'oggetto di archiviazione è stato invalidato da un'operazione di ripristino sopra di essa nell'albero delle transazioni.

Commenti

IStorage::Commit apporta modifiche permanenti a un oggetto di archiviazione in modalità transazionata, in cui le modifiche vengono accumulate in un buffer e non vengono riflesse nell'oggetto di archiviazione finché non viene eseguita una chiamata a questo metodo. L'alternativa consiste nell'aprire un oggetto in modalità diretta, in cui le modifiche vengono immediatamente riflesse nell'oggetto di archiviazione. Un oggetto aperto in modalità diretta non richiede la chiamata di IStorage::Commit per apportare modifiche permanenti nell'oggetto di archiviazione. La chiamata al metodo IStorage::Commit in una risorsa di archiviazione nonroot aperta in modalità diretta non ha alcun effetto. L'apertura di un oggetto di archiviazione radice in modalità diretta garantisce che le modifiche nei buffer di memoria vengano scritte nel dispositivo di archiviazione sottostante.

L'operazione di commit pubblica le modifiche correnti in questo oggetto di archiviazione e i relativi elementi figlio al livello successivo della gerarchia di archiviazione. Per annullare le modifiche correnti prima di eseguirne il commit, chiamare IStorage::Revert per eseguire il rollback alla versione di cui è stato eseguito l'ultimo commit.

La chiamata a IStorage::Commit non ha alcun effetto sugli elementi annidati attualmente aperti di questo oggetto di archiviazione. Rimangono validi e possono essere utilizzati. Tuttavia, il metodo IStorage::Commit non esegue automaticamente il commit delle modifiche apportate a questi elementi annidati. L'operazione di commit pubblica solo le modifiche note al livello superiore successivo nella gerarchia di archiviazione. Pertanto, è necessario eseguire il commit delle transazioni a livelli annidati in questo oggetto di archiviazione prima di poter eseguire il commit a livelli più elevati.

Nelle operazioni di commit è necessario eseguire passaggi per assicurarsi che i dati siano protetti durante il processo di commit:

  • Quando si esegue il commit delle modifiche apportate agli oggetti di archiviazione radice, il chiamante deve controllare il valore restituito per determinare se l'operazione è stata completata correttamente e, in caso contrario, che il contenuto precedente di cui è stato eseguito il commit di IStorage è ancora intatto e può essere ripristinato.
  • Se questo oggetto di archiviazione è stato aperto con alcuni degli elementi esclusi, il chiamante è responsabile della riscrittura prima di chiamare il commit. La modalità di scrittura è necessaria nell'apertura dello spazio di archiviazione affinché il commit abbia esito positivo.
  • A meno che non venga vietato più writer simultanei nello stesso oggetto di archiviazione, un'applicazione che chiama questo metodo deve specificare almeno STGC_ONLYIFCURRENT nel parametro grfCommitFlags per impedire che le modifiche apportate da un writer sovrascrivano inavvertitamente le modifiche apportate da un altro.
Se il flag STGC_CONSOLIDATE non è supportato da un'implementazione di archiviazione, chiamando IStorage::Commit con STGC_CONSOLIDATE specificato nel parametro grfCommitFlags restituisce il valore STG_E_INVALIDFLAG.

Requisiti

Requisito Valore
Client minimo supportato Windows 2000 Professional [app desktop | App UWP]
Server minimo supportato Windows 2000 Server [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione objidl.h
Libreria Uuid.lib
DLL Ole32.dll

Vedi anche

IStorage - Implementazione di file composti

IStorage::Revert

STGC