implementazione del file IStorage-Compound

  • Articolo

L'implementazione di file composta di IStorage consente di creare e gestire sottostorage e flussi all'interno di un oggetto di archiviazione che risiede in un oggetto file composto. Per creare un oggetto file composto e ottenere un puntatore IStorage , chiamare la funzione API StgCreateStorageEx. Per aprire un oggetto file composto esistente e ottenere il puntatore IStorage radice, chiamare StgOpenStorageEx.

Le applicazioni che usano l'archiviazione composta devono essere registrate in HKEY_CLASSES_ROOT\SystemFileAssociations e devono fornire i gestori delle proprietà personali. Per altre informazioni, vedere la sezione "Registrazione verbi e altre informazioni sull'associazione file" della registrazione dell'applicazione.

Utilizzo

La maggior parte delle applicazioni usa questa implementazione per creare e gestire archiviazioni e flussi.

Metodi

IStorage::CreateStream

Crea e apre un oggetto di flusso con il nome specificato contenuto in questo oggetto di archiviazione. Il nome non deve superare i 31 caratteri in lunghezza (non incluso il terminatore stringa). I caratteri da 000 a 01f, che fungono da primo carattere del nome del flusso/archivio, sono riservati all'OLE. Si tratta di una limitazione del file composto, non della restrizione di un archivio strutturato. L'implementazione del file composto fornito da COM del metodo IStorage::CreateStream non supporta i comportamenti seguenti:

  • Il flag STGM_DELETEONRELEASE non è supportato.
  • La modalità transacted (STGM_TRANSACTED) non è supportata per gli oggetti di flusso.
  • L'apertura dello stesso flusso più di una volta dalla stessa risorsa di archiviazione non è supportata. Il flag STGM_SHARE_EXCLUSIVE modalità di condivisione deve essere specificato nel parametro grfMode .

IStorage::OpenStream

Apre un oggetto di flusso esistente all'interno di questo oggetto di archiviazione usando le modalità di accesso specificate nel parametro grfMode . I caratteri da 000 a 01f, che fungono da primo carattere del nome del flusso/archivio, sono riservati all'OLE. Si tratta di una limitazione del file composto, non della restrizione di un archivio strutturato. L'implementazione del file composto fornito da COM del metodo IStorage::OpenStream non supporta il comportamento seguente:

  • Flag di STGM_DELETEONRELEASE.
  • Modalità transacted (STGM_TRANSACTED) per gli oggetti di flusso.
  • Apertura dello stesso flusso più di una volta dalla stessa risorsa di archiviazione. È necessario specificare il flag STGM_SHARE_EXCLUSIVE.

IStorage::CreateStorage

Crea e apre un nuovo oggetto di archiviazione con il nome specificato nella modalità di accesso specificata. Il nome non deve superare i 31 caratteri in lunghezza (non incluso il terminatore stringa). I caratteri da 000 a 01f, che fungono da primo carattere del nome del flusso/archivio, sono riservati all'OLE. Si tratta di una limitazione del file composto, non della restrizione di un archivio strutturato. L'implementazione del file composto fornito da COM del metodo IStorage::CreateStorage non supporta il comportamento seguente:

  • Flag di STGM_PRIORITY per le risorse di archiviazione nonroot.
  • Apertura dello stesso oggetto di archiviazione più di una volta dalla stessa risorsa di archiviazione padre. È necessario specificare il flag STGM_SHARE_EXCLUSIVE.
  • Flag di STGM_DELETEONRELEASE. Se viene specificato questo flag, la funzione restituisce STG_E_INVALIDFLAG.

IStorage::OpenStorage

Apre un oggetto di archiviazione esistente con il nome specificato nella modalità di accesso specificata. I caratteri da 000 a 01f, che fungono da primo carattere del nome del flusso/archivio, sono riservati all'OLE. Si tratta di una limitazione del file composto, non della restrizione di un archivio strutturato. L'implementazione del file composto fornito da COM del metodo IStorage::OpenStorage non supporta il comportamento seguente:

  • Flag di STGM_PRIORITY per le risorse di archiviazione nonroot.
  • Apertura dello stesso oggetto di archiviazione più di una volta dalla stessa risorsa di archiviazione padre. È necessario specificare il flag STGM_SHARE_EXCLUSIVE.
  • Flag di STGM_DELETEONRELEASE. Se viene specificato questo flag, la funzione restituisce STG_E_INVALIDFUNCTION.

IStorage::CopyTo

Copia solo le sottostorage e i flussi di questo oggetto di archiviazione aperto in un altro oggetto di archiviazione. Il parametro rgiidExclude può essere impostato su IID_IStream per copiare solo sottostorage o per IID_IStorage per copiare solo i flussi.

IStorage::MoveElementTo

Copia o sposta un sottostorage o un flusso da questo oggetto di archiviazione a un altro oggetto di archiviazione.

IStorage::Commit

Assicura che tutte le modifiche apportate a un oggetto di archiviazione aperte in modalità transacted vengano riflesse nell'archiviazione padre; per un'archiviazione radice, riflette le modifiche nel dispositivo effettivo; ad esempio, un file su disco. Per un oggetto di archiviazione radice aperto in modalità diretta, questo metodo non ha alcun effetto, tranne per scaricare tutti i buffer di memoria sul disco. Per gli oggetti di archiviazione nonroot in modalità diretta, questo metodo non ha alcun effetto.

L'implementazione dei file composti forniti da COM usa un processo di commit a due fasi, a meno che non sia specificato STGC_OVERWRITE nel parametro grfCommitFlags . Questo processo in due fasi garantisce la robustezza dei dati, nel caso in cui l'operazione di commit non riesca. Prima di tutto, tutti i nuovi dati vengono scritti nello spazio inutilizzato nel file sottostante. Se necessario, viene allocato nuovo spazio al file. Al termine di questo passaggio, viene aggiornata una tabella nel file usando un'operazione di scrittura a singolo settore per indicare che i nuovi dati devono essere usati al posto del precedente. I dati precedenti diventano spazio libero da usare all'operazione di commit successiva. Pertanto, i dati precedenti sono disponibili e possono essere ripristinati se si verifica un errore durante il commit delle modifiche. Se viene specificato STGC_OVERWRITE, viene usata un'operazione di commit di una singola fase. Per altre informazioni sui flag di modalità transacted, vedere enumerazione STGC .

IStorage::Revert

Rimuove tutte le modifiche apportate all'oggetto di archiviazione dall'ultima operazione di commit.

IStorage::EnumElements

Crea e recupera un puntatore a un oggetto enumeratore che può essere usato per enumerare gli oggetti di archiviazione e di flusso contenuti in questo oggetto di archiviazione. L'implementazione del file composto fornita da COM accetta uno snapshot di tali informazioni. Pertanto, le modifiche ai flussi e alle risorse di archiviazione non vengono riflesse nell'enumeratore fino a quando non viene ottenuto un nuovo enumeratore.

IStorage::D estroyElement

Rimuove l'elemento specificato (sottostorage o flusso) da questo oggetto di archiviazione.

IStorage::RenameElement

Rinomina la sottostorage o il flusso specificati in questo oggetto di archiviazione. I caratteri da 000 a 01f, che fungono da primo carattere del nome del flusso/archivio, sono riservati all'OLE. Si tratta di una limitazione del file composto, non della restrizione di un archivio strutturato.

IStorage::SetElementTimes

Imposta i tempi di modifica, accesso e creazione dell'elemento di archiviazione specificato. L'implementazione del file composto fornita da COM gestisce i tempi di modifica e modifica per gli oggetti di archiviazione interni. Gli oggetti di archiviazione radice supportano qualsiasi elemento supportato dal file system sottostante (o da ILockBytes). L'implementazione del file composto non mantiene i timestamp per i flussi interni. I timestamp non supportati vengono segnalati come zero, che consente al chiamante di testare il supporto.

IStorage::SetClass

Assegna il CLSID specificato a questo oggetto di archiviazione.

IStorage::SetStateBits

Archivia fino a 32 bit di informazioni sullo stato in questo oggetto di archiviazione. Lo stato impostato da questo metodo è solo per l'uso esterno. L'implementazione del file composto fornita da COM non esegue alcuna azione in base allo stato.

IStorage::Stat

Recupera la struttura STATSTG per questo oggetto di archiviazione aperto.

Commenti

Se l'oggetto di archiviazione viene aperto in modalità semplice, l'uso dei metodi precedenti è limitato. Una risorsa di archiviazione è in modalità semplice se viene aperta con l'elemento STGM_SIMPLE specificato nel parametro grfMode della funzione StgCreateStorageEx o StgOpenStorageEx. Per altre informazioni sulle risorse di archiviazione in modalità semplice, vedere Costanti STGM. Se l'oggetto di archiviazione in modalità semplice è stato ottenuto dalla funzione StgCreateStorageEx , il metodo CreateStream può essere chiamato ma il metodo OpenStream non può. Se l'oggetto di archiviazione in modalità semplice è stato ottenuto dalla funzione StgOpenStorageEx , il metodo OpenStream può essere chiamato ma il metodo CreateStream non può essere chiamato.

Quando un oggetto di archiviazione in modalità semplice viene usato per creare un flusso, le dimensioni minime del flusso in genere sono 4096 byte. Se il flusso viene scritto meno dati, le dimensioni sono arrotondate fino a 4096 byte.

Limiti di implementazione di file composti

IFillLockBytes

ILockBytes

IRootStorage

IStorage

IStream

StgCreateDocfile

StgCreateStorageEx

StgOpenStorage

StgOpenStorageEx