Funzione StgOpenStorage (coml2api.h)

La funzione StgOpenStorage apre un oggetto di archiviazione radice esistente nel file system. Usare questa funzione per aprire file composti. Non usarlo per aprire directory, file o cataloghi di riepilogo. Gli oggetti di archiviazione nidificati possono essere aperti solo usando il metodo IStorage::OpenStorage padre.

Nota Le applicazioni devono usare la nuova funzione , StgOpenStorageEx, anziché StgOpenStorage, per sfruttare le funzionalità di archiviazione strutturate e avanzate di Windows. Questa funzione , StgOpenStorage, esiste ancora per la compatibilità con le applicazioni in esecuzione in Windows 2000.

 

Sintassi

HRESULT StgOpenStorage(
  [in]  const WCHAR *pwcsName,
  [in]  IStorage    *pstgPriority,
  [in]  DWORD       grfMode,
  [in]  SNB         snbExclude,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

Parametri

[in] pwcsName

Puntatore al percorso del file di stringa Unicode con terminazione Null contenente l'oggetto di archiviazione da aprire. Questo parametro viene ignorato se il parametro pstgPriority non è NULL.

[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 StgOpenStorage , 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.

[in] snbExclude

Se non NULL, puntatore a un blocco di elementi nell'archiviazione da escludere perché l'oggetto di archiviazione viene aperto. L'esclusione si verifica indipendentemente dal fatto che una copia snapshot si verifichi sull'apertura. Può essere NULL.

[in] reserved

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

[out] ppstgOpen

Puntatore a una variabile puntatore IStorage* che riceve il puntatore dell'interfaccia all'archiviazione aperta.

Valore restituito

La funzione StgOpenStorage può anche restituire eventuali errori di file system o errori di sistema inclusi in un'istanza di HRESULT. Per altre informazioni, vedere Gestione degli errori e gestione degli errori sconosciuti.

Commenti

La funzione StgOpenStorage apre l'oggetto di archiviazione radice specificato in base alla modalità di accesso nel parametro grfMode e, se ha esito positivo, fornisce un puntatore IStorage all'oggetto di archiviazione aperto nel parametro ppstgOpen .

Per supportare la modalità semplice per salvare un oggetto di archiviazione senza sottostorage, la funzione StgOpenStorage accetta una delle due combinazioni di flag seguenti come modalità valide nel parametro grfMode .

    STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE

Per supportare il writer singolo, multireader, modalità diretta, la prima combinazione flag è il parametro grfMode valido per il writer. La seconda combinazione di flag è valida per i lettori.

    STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

    STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

In modalità diretta, una delle tre combinazioni seguenti è valida.

    STGM_DIRECT | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_DIRECT | STGM_READ | STGM_SHARE_DENY_WRITE

    STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE

Nota L'apertura di un oggetto di archiviazione in modalità di lettura/scrittura senza negare l'autorizzazione di scrittura ad altri utenti (il parametro grfMode specifica STGM_SHARE_DENY_WRITE) può essere un'operazione che richiede tempo perché la chiamata StgOpenStorage deve creare uno snapshot dell'intero oggetto di archiviazione.

 

Le applicazioni spesso tentano di aprire oggetti di archiviazione con le autorizzazioni di accesso seguenti. Se l'applicazione ha esito positivo, non deve mai creare una copia snapshot.

STGM_READWRITE | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition 

L'applicazione può ripristinare l'uso delle autorizzazioni e creare una copia snapshot, se le autorizzazioni di accesso precedenti hanno esito negativo. L'applicazione deve richiedere all'utente prima di eseguire una copia che richiede tempo.

STGM_READWRITE 
    // transacted versus direct mode omitted for exposition 

Se la semantica di condivisione documento implicita dalle modalità di accesso è appropriata, l'applicazione potrebbe provare ad aprire l'archiviazione come indicato di seguito. In questo caso, se l'applicazione ha esito positivo, non sarà stata eseguita una copia snapshot (perché STGM_SHARE_DENY_WRITE è stata specificata, negando altri accessi in scrittura).

STGM_READ | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition 

Nota Per ridurre le spese di creazione di una copia snapshot, le applicazioni possono aprire oggetti di archiviazione in modalità priorità (grfMode specifica STGM_PRIORITY).

 

Il parametro snbExclude specifica un set di nomi di elementi in questo oggetto di archiviazione che devono essere svuotati quando l'oggetto di archiviazione viene aperto: i flussi vengono impostati su una lunghezza pari a zero; gli oggetti di archiviazione hanno tutti gli elementi rimossi. Escludendo determinati flussi, la spesa per la creazione di una copia snapshot può essere notevolmente ridotta. Quasi sempre, questo approccio viene usato dopo aver aperto prima l'oggetto di archiviazione in modalità priorità, quindi leggere completamente gli elementi ora esclusi in memoria. Questa precedente apertura in modalità priorità dell'oggetto di archiviazione deve essere passata tramite il parametro pstgPriority per rimuovere l'esclusione implicita dalla modalità priorità. L'applicazione chiamante è responsabile della riscrittura del contenuto degli elementi esclusi prima del commit. Questa tecnica è quindi più probabile utile solo per le applicazioni i cui documenti non richiedono l'accesso costante agli oggetti di archiviazione mentre sono attivi.

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 nello stesso file ma in modalità diversa. Quando pstgPriority non è NULL, viene usato per specificare il nome del file anziché pwcsName, che viene ignorato. È tuttavia consigliabile che le applicazioni passino sempre NULL per pstgPriority perché StgOpenStorage rilascia l'oggetto in alcune circostanze e non lo rilascia in altre circostanze. In particolare, se la funzione restituisce un risultato di errore, non è possibile che il chiamante determini se l'oggetto di archiviazione è stato rilasciato o meno.

La funzionalità del parametro pstgPriority può essere duplicata dal chiamante in modo più sicuro, come illustrato nell'esempio seguente:

// Replacement for:
// HRESULT hr = StgOpenStorage(
//         NULL, pstgPriority, grfMode, NULL, 0, &pstgNew);

STATSTG statstg;
HRESULT hr = pstgPriority->Stat(&statstg, 0);
pStgPriority->Release();
pStgPriority = NULL;
if (SUCCEEDED(hr))
{
    hr = StgOpenStorage(statstg.pwcsName, NULL, grfMode, NULL, 0, &pstgNew);
}     

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	coml2api.h (include Objbase.h)
Libreria	Ole32.lib
DLL	Ole32.dll

Vedi anche

IStorage

StgCreateDocfile

StgOpenStorageEx