Funzione StgCreateStorageEx (coml2api.h)

Articolo
08/22/2023

La funzione StgCreateStorageEx crea un nuovo oggetto di archiviazione usando un'implementazione fornita per le interfacce IStorage o IPropertySetStorage . Per aprire un file esistente, usare invece la funzione StgOpenStorageEx .

Le applicazioni scritte per Windows 2000, Windows Server 2003 e Windows XP devono usare StgCreateStorageEx anziché StgCreateDocfile per sfruttare le funzionalità di archiviazione strutturate di Windows 2000 e Windows XP.

Sintassi

HRESULT StgCreateStorageEx(
  [in]  const WCHAR          *pwcsName,
  [in]  DWORD                grfMode,
  [in]  DWORD                stgfmt,
  [in]  DWORD                grfAttrs,
  [in]  STGOPTIONS           *pStgOptions,
  [in]  PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]  REFIID               riid,
  [out] void                 **ppObjectOpen
);

Parametri

[in] pwcsName

Puntatore al percorso del file da creare. Viene passato non interpretato al file system. Può trattarsi di un nome relativo o NULL. Se NULL, un file temporaneo viene allocato con un nome univoco. Se non NULL, le dimensioni della stringa non devono superare MAX_PATH caratteri.

Windows 2000: A differenza della funzione CreateFile , non è possibile superare il limite di MAX_PATH usando il prefisso "\?".

[in] grfMode

Valore che specifica la modalità di accesso da usare quando si apre 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 avviene 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.

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

Valori di parametri	Significato
STGFMT_DOCFILE	0 o FILE_FLAG_NO_BUFFERING. Per altre informazioni, vedere CreateFile. Se la dimensione del settore del file, specificata in pStgOptions, non è un numero intero multiplo delle dimensioni del settore fisico del disco sottostante, questa operazione avrà esito negativo.
Tutti gli altri valori di stgfmt	Deve essere 0.

[in] pStgOptions

Il parametro pStgOptions è valido solo se il parametro stgfmt è impostato su STGFMT_DOCFILE. Se il parametro stgfmt è impostato su STGFMT_DOCFILE, pStgOptions punta alla struttura STGOPTIONS , che specifica le funzionalità dell'oggetto di archiviazione, ad esempio le dimensioni del settore. Questo parametro può essere NULL, che crea un oggetto di archiviazione con dimensioni predefinite del settore pari a 512 byte. Se non NULL, il membro ulSectorSize deve essere impostato su 512 o 4096. Se impostato su 4096, STGM_SIMPLE potrebbe non essere specificato nel parametro grfMode . Il membro usVersion deve essere impostato prima di chiamare StgCreateStorageEx. Per altre informazioni, vedere STGOPTIONS.

[in] pSecurityDescriptor

Abilita gli ACL da impostare al momento della creazione del file. In caso contrario, deve essere un puntatore alla struttura SECURITY_ATTRIBUTES . Vedere CreateFile per informazioni su come impostare gli elenchi di controllo di accesso nei file.

Windows Server 2003, Windows 2000 Server, Windows XP e Windows 2000 Professional: Il valore deve essere NULL.

[in] riid

Valore che specifica l'identificatore dell'interfaccia (IID) del puntatore dell'interfaccia da restituire. Questo IID può essere per l'interfaccia IStorage o l'interfaccia IPropertySetStorage .

[out] ppObjectOpen

Puntatore a una variabile del puntatore dell'interfaccia che riceve un puntatore per un'interfaccia sul nuovo oggetto di archiviazione; 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

Quando un'applicazione modifica il file, in genere crea una copia dell'originale. La funzione StgCreateStorageEx è un modo per creare una copia. Questa funzione funziona indirettamente con l'API di duplicazione EFS (Encrypting File System). Quando si usa questa funzione, è necessario impostare le opzioni per l'archiviazione file nella struttura STGOPTIONS .

StgCreateStorageEx è un superset della funzione StgCreateDocfile e deve essere usato dal nuovo codice. I miglioramenti futuri all'archiviazione strutturata verranno esposti tramite la funzione StgCreateStorageEx . Per informazioni sulle piattaforme supportate, vedere la sezione Requisiti seguenti.

La funzione StgCreateStorageEx crea un nuovo oggetto di archiviazione usando una delle implementazioni di archiviazione strutturate fornite dal sistema. Questa funzione può essere usata per ottenere un oggetto
Implementazione di file composti IStorage, implementazione di file composti IPropertySetStorage o per ottenere un'implementazione IPropertySetStorage NTFS.

Quando viene creato un nuovo file, l'implementazione di archiviazione usata dipende dal flag specificato e dal tipo di unità in cui viene archiviato il file. Per altre informazioni, vedere l'enumerazione STGFMT .

StgCreateStorageEx crea il file se non esiste. Se esiste, l'uso del STGM_CREATE, STGM_CONVERT e STGM_FAILIFTHERE flag nel parametro grfMode indicano come procedere. Per altre informazioni su questi valori, vedere Costanti STGM. Non è valido, in modalità diretta, per specificare la modalità STGM_READ nel parametro grfMode (la modalità diretta è indicata non specificando il flag di STGM_TRANSACTED). Questa funzione non può essere usata per aprire un file esistente; usare invece la funzione StgOpenStorageEx .

È possibile usare la funzione StgCreateStorageEx per ottenere l'accesso all'archiviazione radice di un documento di archiviazione strutturata o all'archiviazione del set di proprietà di qualsiasi file che supporti i set di proprietà. Per informazioni su quali ID ID sono supportati per valori STGFMT diversi, vedere la documentazione di STGFMT.

Quando viene creato un file 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 viene creato un file composto in modalità transacted (specificando STGM_TRANSACTED) e modalità di sola lettura (specificando STGM_READ), è possibile apportare modifiche all'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.

La specifica di STGM_SIMPLE fornisce un'implementazione molto più veloce di un oggetto file composto in un caso limitato, ma spesso usato che implica applicazioni che richiedono un'implementazione composta di file con più flussi e nessuna risorsa di archiviazione. Per altre informazioni, vedere Costanti STGM. Non è valido specificare che STGM_TRANSACTED se è specificato STGM_SIMPLE.

La modalità semplice non supporta tutti i metodi in IStorage. In particolare, in modalità semplice, i metodi IStorage supportati sono CreateStream, Commit e SetClass e i metodi COM IUnknown di QueryInterface, AddRef e Release. Inoltre, SetElementTimes è supportato con un nome NULL, consentendo alle applicazioni di impostare i tempi in un'archiviazione radice. Tutti gli altri metodi di IStorage restituiscono STG_E_INVALIDFUNCTION.

Se il parametro grfMode specifica STGM_TRANSACTED e non esiste ancora un file con il nome specificato dal parametro pwcsName , il file viene creato immediatamente. In un file system controllato dall'accesso, il chiamante deve disporre delle autorizzazioni di scrittura per la directory del file system in cui viene creato il file composto. Se STGM_TRANSACTED non è specificato e viene specificato STGM_CREATE, un file esistente con lo stesso nome viene eliminato prima di creare il nuovo file.

È anche possibile usare StgCreateStorageEx per creare un file composto temporaneo passando un valore NULL per il parametro pwcsName . Tuttavia, questi file sono temporanei solo nel senso che hanno un nome univoco fornito dal sistema, uno probabilmente senza significato per l'utente. Il chiamante è responsabile dell'eliminazione del file temporaneo al termine dell'operazione, a meno che non sia stato specificato STGM_DELETEONRELEASE per il parametro grfMode . Per altre informazioni su questi flag, vedere Costanti STGM.

Requisiti


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