Funzione StgOpenStorageOnILockBytes (coml2api.h)

La funzione StgOpenStorageOnILockBytes apre un oggetto di archiviazione esistente che non risiede in un file disco, ma ha invece una matrice di byte sottostante fornita dal chiamante.

Sintassi

HRESULT StgOpenStorageOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  IStorage   *pstgPriority,
  [in]  DWORD      grfMode,
  [in]  SNB        snbExclude,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Parametri

[in] plkbyt

Puntatore ILockBytes all'oggetto matrice di byte sottostante contenente l'oggetto di archiviazione da aprire.

[in] pstgPriority

Puntatore all'interfaccia IStorage che deve essere NULL. In caso contrario , questo parametro viene usato come descritto di seguito nella sezione Osservazioni.

Dopo aver restituito StgOpenStorageOnILockBytes , l'oggetto di archiviazione specificato in pStgPriority potrebbe essere stato rilasciato e non deve più essere usato.

[in] grfMode

Specifica la modalità di accesso da usare per aprire l'oggetto di archiviazione. Per altre informazioni, vedere Costanti STGM e la sezione Osservazioni di seguito.

[in] snbExclude

Può essere NULL. In caso contrario, questo parametro punta a un blocco di elementi in questa risorsa di archiviazione da escludere perché l'oggetto di archiviazione viene aperto. Questa esclusione si verifica indipendentemente dal fatto che si verifichi una copia snapshot all'apertura.

[in] reserved

Indica riservato per l'uso futuro; deve essere zero.

[out] ppstgOpen

Punta alla posizione di un puntatore IStorage all'archiviazione aperta in caso di restituzione riuscita.

Valore restituito

La funzione StgOpenStorageOnILockBytes può anche restituire eventuali errori del file system o errori di sistema inclusi in un errore di interfaccia HRESULT o ILockBytes restituisce valori restituiti. Vedere Gestione degli errori e gestione degli errori sconosciuti.

Commenti

StgOpenStorageOnILockBytes apre l'oggetto di archiviazione radice specificato. Viene fornito un puntatore all'interfaccia IStorage nell'oggetto di archiviazione aperto tramite il parametro ppstgOpen .

L'oggetto di archiviazione deve essere stato creato in precedenza dalla funzione StgCreateDocfileOnILockBytes .

Ad eccezione della specifica di un oggetto byte-array fornito dal programmatore, StgOpenStorageOnILockBytes è simile alla funzione StgOpenStorage . L'oggetto di archiviazione 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 all'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 coordinateranno correttamente con altre istanze transazionali aperte nella stessa matrice di byte. Le applicazioni che usano un'implementazione ILockBytes che non supporta il blocco delle aree, ad esempio l'implementazione createStreamOnHGlobal , devono evitare di aprire più istanze simultanee nella stessa matrice di byte.

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

Il parametro pStgPriority è destinato ai chiamanti che sostituisce un oggetto di archiviazione esistente, spesso aperto in modalità priorità, con un nuovo oggetto di archiviazione aperto nella stessa matrice di byte. A differenza del parametro pStgPriority di StgOpenStorage, questo parametro non influisce sull'operazione aperta eseguita da StgOpenStorageOnILockBytes ed è semplicemente un oggetto di archiviazione esistente che il chiamante vuole rilasciare. I chiamanti devono sempre passare NULL per questo parametro perché StgOpenStorageOnILockBytes rilascia l'oggetto in alcune circostanze e non lo rilascia in altre circostanze. L'uso del parametro pStgPriority può essere duplicato dal chiamante in modo più sicuro rilasciando invece l'oggetto prima di chiamare StgOpenStorageOnILockBytes, come illustrato nell'esempio seguente:

// Replacement for:
// HRESULT hr = StgOpenStorageOnILockBytes(
//         plkbyt, pStgPriority, grfMode, NULL, 0, &pstgNew);

pStgPriority->Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &pstgNew);
    

Per altre informazioni, vedere StgOpenStorage.

Requisiti

Vedi anche

StgCreateDocfileOnILockBytes

StgOpenStorage