Funzione StgCreateStorageEx (coml2api.h)

Articolo
11/20/2024

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à avanzate di archiviazione strutturata 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 al file system non interpretato. Può trattarsi di un nome relativo o NULL. Se NULL, viene allocato un file temporaneo con un nome univoco. Se nonNULL, 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 utilizzare 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, verrà ripristinato il contenuto precedente del file. STGM_CREATE e STGM_CONVERT non possono essere combinati con il flag STGM_NOSNAPSHOT, perché è necessaria una copia snapshot quando un file viene sovrascritto o convertito in modalità transazionata.

[in] stgfmt

Valore che specifica il formato di file di archiviazione. Per altre informazioni, vedere l'enumerazione STGFMT .

[in] grfAttrs

Valore che dipende dal valore del parametro stgfmt.

Valori dei parametri	Significato
STGFMT_DOCFILE	0 o FILE_FLAG_NO_BUFFERING. Per altre informazioni, vedere CreateFile. Se le dimensioni del settore del file, specificate in pStgOptions, non è un multiplo intero 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 caratteristiche dell'oggetto di archiviazione, ad esempio le dimensioni del settore. Questo parametro può essere NULL, che crea un oggetto di archiviazione con dimensioni di settore predefinite pari a 512 byte. Se nonNULL, 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

Consente di impostare gli ACL al momento della creazione del file. Se non NULL, deve essere un puntatore alla struttura SECURITY_ATTRIBUTES. Per informazioni su come impostare elenchi di controllo di accesso nei file, vedere CreateFile.

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

[in] riid

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

[out] ppObjectOpen

Puntatore a una variabile del puntatore di 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 del file system o errori di sistema di cui è stato eseguito il wrapping in un HRESULT. Per altre informazioni, vedere strategie di gestione degli errori e gestione degli errori sconosciuti.

Osservazioni

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 usata dal nuovo codice. I miglioramenti futuri all'archiviazione strutturata verranno esposti tramite la funzione stgCreateStorageEx . Per informazioni sulle piattaforme supportate, vedere la sezione Requisiti seguente.

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
'implementazione di file composti IStorage, un'implementazione di file composti IPropertySetStorageo 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 è archiviato il file. Per altre informazioni, vedere l'enumerazione STGFMT .

StgCreateStorageEx crea il file se non esiste. Se esiste, l'uso dei flag STGM_CREATE, STGM_CONVERT e STGM_FAILIFTHERE nel parametro grfMode indica come procedere. Per altre informazioni su questi valori, vedere costanti STGM. Non è valido, in modalità diretta, specificare la modalità STGM_READ nel parametro grfMode (la modalità diretta è indicata non specificando il flag STGM_TRANSACTED). Questa funzione non può essere utilizzata 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 supporta i set di proprietà. Vedere la documentazione STGFMT per informazioni sui tipi DI IID supportati per diversi valori 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 IPropertySetStorage-NTFS Implementazione.

Se viene creato un file composto in modalità transacted (specificando STGM_TRANSACTED) e la modalità di sola lettura (specificando STGM_READ), è possibile apportare modifiche all'oggetto di archiviazione restituito. Ad esempio, è possibile chiamare IStorage::CreateStream. Non è tuttavia possibile eseguire il commit di tali modifiche chiamando IStorage::Commit. Pertanto, tali modifiche andranno perse.

L'impostazione di STGM_SIMPLE offre un'implementazione molto più rapida di un oggetto file composto in un caso limitato, ma usato di frequente che coinvolge applicazioni che richiedono un'implementazione di file composta con più flussi e nessuna risorsa di archiviazione. Per altre informazioni, vedere costanti STGM. Non è valido specificare che STGM_TRANSACTED se viene specificato STGM_SIMPLE.

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

Se il parametro grfMode specifica STGM_TRANSACTED e non esiste ancora alcun 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 non viene specificato STGM_TRANSACTED e STGM_CREATE viene specificato, un file esistente con lo stesso nome viene eliminato definitivamente 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, a meno che non sia stato specificato STGM_DELETEONRELEASE per il parametro grfMode. Per altre informazioni su questi flag, vedere costanti STGM.

Fabbisogno

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	Finestre
intestazione	coml2api.h (include Objbase.h)
libreria	Ole32.lib
dll	Ole32.dll