Funzione StgCreateDocfileOnILockBytes (coml2api.h)

La funzione StgCreateDocfileOnILockBytes crea e apre un nuovo oggetto di archiviazione file composto su un oggetto matrice di byte fornito dal chiamante. L'oggetto di archiviazione supporta l'implementazione di file composta fornita da COM per l'interfaccia IStorage .

Sintassi

HRESULT StgCreateDocfileOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  DWORD      grfMode,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Parametri

[in] plkbyt

Puntatore all'interfaccia ILockBytes nell'oggetto matrice di byte sottostante in cui creare un file composto.

[in] grfMode

Specifica la modalità di accesso da utilizzare quando si apre il nuovo file composto. Per altre informazioni, vedere Costanti STGM e la sezione Osservazioni di seguito.

[in] reserved

Riservato per utilizzi futuri; deve essere zero.

[out] ppstgOpen

Puntatore alla posizione del puntatore IStorage sul nuovo oggetto di archiviazione.

Valore restituito

La funzione StgCreateDocfileOnILockBytes può anche restituire eventuali errori del file system o errori di sistema di cui è stato eseguito il wrapping in un valore HRESULT o i valori restituiti dell'errore di interfaccia ILockBytes . Per altre informazioni, vedere Strategie di gestione degli errori e gestione degli errori sconosciuti.

Commenti

La funzione StgCreateDocfileOnILockBytes crea un oggetto di archiviazione su un oggetto matrice di byte usando l'implementazione com di file composta fornita da COM dell'interfaccia IStorage . StgCreateDocfileOnILockBytes può essere usato per archiviare un documento in un archivio dati arbitrario, ad esempio memoria o database relazionale. La matrice di byte (indicata dal parametro pLkbyt , che punta all'interfaccia ILockBytes nell'oggetto) viene usata per l'archiviazione sottostante al posto di un file del disco.

Ad eccezione della specifica di un oggetto matrice di byte fornito dal programmatore, StgCreateDocfileOnILockBytes è simile alla funzione StgCreateDocfile .

Il file composto appena creato viene aperto in base alle modalità di accesso nel parametro grfMode , soggetto alle restrizioni seguenti:

Il comportamento della modalità di condivisione e l'isolamento transazionale dipendono dall'implementazione di ILockBytes che supporta LockRegion e UnlockRegion con semantica LOCK_ONLYONCE . Le implementazioni possono indicare l'archiviazione strutturata che supportano questa funzionalità impostando il bit LOCK_ONLYONCE nel membro grfLocksSupported di STATSTG. Se un'implementazione ILockBytes non supporta questa funzionalità, le modalità di condivisione non verranno applicate e i commit transazionali a livello radice non si coordinano correttamente con altre istanze transazionali aperte nella stessa matrice di byte. Le applicazioni che usano un'implementazione ILockBytes che non supporta il blocco dell'area, ad esempio l'implementazione CreateStreamOnHGlobal , devono evitare di aprire più istanze simultanee nella stessa matrice di byte.

StgCreateDocfileOnILockBytes non supporta la modalità semplice. Il flag STGM_SIMPLE , se presente, viene ignorato.

Ai fini della conversione, il file viene considerato già esistente. Di conseguenza, non è utile usare il valore STGM_FAILIFTHERE , perché causa la restituzione di un errore. Tuttavia, sia STGM_CREATE che STGM_CONVERT rimangono utili.

La possibilità di compilare un file composto sopra un oggetto matrice di byte viene fornita per supportare la presenza dei dati (sotto una struttura ad albero IStorage e IStream ) in uno spazio non persistente. Data questa funzionalità, non c'è nulla che impedisca a un documento archiviato in un file di usare questa funzionalità. Ad esempio, un contenitore potrebbe eseguire questa operazione per ridurre al minimo l'impatto sul formato di file causato dall'adozione di COM. Tuttavia, è consigliabile che i documenti COM adottino l'interfaccia IStorage per la propria archiviazione a livello esterno. I vantaggi di questo approccio sono i seguenti:

• La struttura di archiviazione del documento corrisponde alla relativa struttura di archiviazione quando è un oggetto incorporato, riducendo il numero di casi in cui l'applicazione deve gestire.
• È possibile scrivere strumenti per accedere agli oggetti ole incorporati e collegati all'interno del documento senza conoscere in modo speciale il formato di file del documento. Un esempio di tale strumento è un'utilità di copia che copia tutti i documenti inclusi in un contenitore contenente oggetti collegati. Un'utilità di copia come questa deve accedere ai collegamenti contenuti per determinare l'estensione dei file da copiare.
• L'implementazione di IStorage risolve il problema relativo al commit delle modifiche apportate al file. Un'applicazione che usa l'interfaccia ILockBytes deve gestire questi problemi.

Requisiti

Vedi anche

StgCreateDocfile