Funzione StgOpenStorageEx (coml2api.h)
La funzione StgOpenStorageEx apre un oggetto di archiviazione radice esistente nel file system. Usare questa funzione per aprire file composti e file regolari. Per creare un nuovo file, usare la funzione StgCreateStorageEx .
Sintassi
HRESULT StgOpenStorageEx(
[in] const WCHAR *pwcsName,
[in] DWORD grfMode,
[in] DWORD stgfmt,
[in] DWORD grfAttrs,
[in, out] STGOPTIONS *pStgOptions,
[in] PSECURITY_DESCRIPTOR pSecurityDescriptor,
[in] REFIID riid,
[out] void **ppObjectOpen
);
Parametri
[in] pwcsName
Puntatore al percorso del file di stringa Unicode con terminazione null contenente l'oggetto di archiviazione. Questa dimensione della stringa non può superare i caratteri MAX_PATH .
Windows Server 2003 e Windows XP/2000: A differenza della funzione CreateFile , il limite di MAX_PATH non può essere superato usando il prefisso "\?".
[in] grfMode
Valore che specifica la modalità di accesso per aprire il nuovo oggetto di archiviazione. Per altre informazioni, vedere Costanti STGM. Se il chiamante specifica la modalità transazionata insieme a STGM_CREATE o STGM_CONVERT, la sovrascrittura o la conversione si verifica quando viene chiamata l'operazione di commit per l'archiviazione radice. Se IStorage::Commit non viene chiamato per l'oggetto di archiviazione radice, il contenuto precedente del file verrà ripristinato. STGM_CREATE e STGM_CONVERT non possono essere combinati con il flag di STGM_NOSNAPSHOT , perché è necessaria una copia snapshot quando un file viene sovrascritto o convertito in modalità transazionata.
Se l'oggetto di archiviazione viene aperto in modalità diretta (STGM_DIRECT) con accesso a STGM_WRITEo STGM_READWRITE, la modalità di condivisione deve essere STGM_SHARE_EXCLUSIVE a meno che non sia specificata la modalità STGM_DIRECT_SWMR. Per altre informazioni, vedere la sezione Osservazioni. Se l'oggetto di archiviazione viene aperto in modalità diretta con accesso a STGM_READ, la modalità di condivisione deve essere STGM_SHARE_EXCLUSIVE o STGM_SHARE_DENY_WRITE, a meno che non sia specificato STGM_PRIORITY o STGM_DIRECT_SWMR. Per altre informazioni, vedere la sezione Osservazioni.
La modalità in cui viene aperto un file può influire sulle prestazioni dell'implementazione. Per altre informazioni, vedere Limiti di implementazione di file composti.
[in] stgfmt
Valore che specifica il formato del file di archiviazione. Per altre informazioni, vedere l'enumerazione STGFMT .
[in] grfAttrs
Valore che dipende dal valore del parametro stgfmt .
STGFMT_DOCFILE deve essere zero (0) o FILE_FLAG_NO_BUFFERING. Per altre informazioni su questo valore, vedere CreateFile. Se le dimensioni del settore del file, specificate in pStgOptions, non sono un numero intero multiplo delle dimensioni del settore fisico del disco sottostante, questa operazione avrà esito negativo. Tutti gli altri valori di stgfmt devono essere zero.
[in, out] pStgOptions
Puntatore a una struttura STGOPTIONS che contiene dati sull'oggetto di archiviazione aperto. Il parametro pStgOptions è valido solo se il parametro stgfmt è impostato su STGFMT_DOCFILE. Il membro usVersion deve essere impostato prima di chiamare StgOpenStorageEx. Per altre informazioni, vedere la struttura STGOPTIONS .
[in] pSecurityDescriptor
Riservati; deve essere zero.
[in] riid
Valore che specifica il GUID del puntatore dell'interfaccia da restituire. Può anche essere il valore specificato dall'intestazione per IID_IStorage per ottenere l'interfaccia IStorage o per IID_IPropertySetStorage per ottenere l'interfaccia IPropertySetStorage .
[out] ppObjectOpen
Indirizzo di una variabile del puntatore dell'interfaccia che riceve un puntatore per un'interfaccia sull'oggetto di archiviazione aperto; contiene NULL se l'operazione non è riuscita.
Valore restituito
Questa funzione può anche restituire eventuali errori di file system o errori di sistema incapsulati in un HRESULT. Per altre informazioni, vedere Gestione degli errori e gestione degli errori sconosciuti.
Commenti
StgOpenStorageEx è un superset della funzione StgOpenStorage e deve essere usato dal nuovo codice. I miglioramenti futuri all'archiviazione strutturata verranno esposti tramite questa funzione. Per altre informazioni sulle piattaforme supportate, vedere la sezione Requisiti.
La funzione StgOpenStorageEx apre l'oggetto di archiviazione radice specificato in base alla modalità di accesso nel parametro grfMode e, se ha esito positivo, fornisce un puntatore di interfaccia per l'oggetto di archiviazione aperto nel parametro ppObjectOpen . Questa funzione può essere usata per ottenere un'implementazione di file composta IStorage, un'implementazionedi file composta IPropertySetStorage o un
Implementazione del file system NTFS di IPropertySetStorage.
Quando si apre un file, il sistema seleziona un'implementazione di archiviazione strutturata a seconda del flag STGFMT specificato sul tipo di file e sul tipo di unità in cui viene archiviato il file.
Usare la funzione StgOpenStorageEx per accedere all'archiviazione radice di un documento di archiviazione strutturato o all'archiviazione del set di proprietà di qualsiasi file che supporti i set di proprietà. Per altre informazioni su quali identificatori di interfaccia (IID) sono supportati per i diversi valori STGFMT , vedere STGFMT.
Quando un file viene aperto con questa funzione per accedere all'implementazione del set di proprietà NTFS, si applicano regole di condivisione speciali. Per altre informazioni, vedere Implementazione IPropertySetStorage-NTFS.
Se un file composto viene aperto in modalità transazionata, specificando STGM_TRANSACTED e modalità di sola lettura, specificando STGM_READ, è possibile modificare l'oggetto di archiviazione restituito. Ad esempio, è possibile chiamare IStorage::CreateStream. Tuttavia, non è possibile eseguire il commit di tali modifiche chiamando IStorage::Commit. Pertanto, tali modifiche verranno perse.
Non è valido usare i flagdi STGM_CREATE, STGM_DELETEONRELEASE o STGM_CONVERT nel parametro grfMode per questa funzione.
Per supportare la modalità semplice per salvare un oggetto di archiviazione senza sottostorage, la funzione StgOpenStorageEx 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
Per altre informazioni sulla modalità semplice e sulle modalità single-writer/multiple-reader, vedere Costanti STGM.
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 |