Funzione StgCreateDocfile (coml2api.h)

La funzione StgCreateDocfile crea un nuovo oggetto di archiviazione file composto usando l'implementazione del file composto fornito da COM per l'interfaccia IStorage .

Sintassi

HRESULT StgCreateDocfile(
  [in]  const WCHAR *pwcsName,
  [in]  DWORD       grfMode,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

Parametri

[in] pwcsName

Puntatore a un nome di stringa Unicode con terminazione Null per il file composto creato. Viene passato non interpretato al file system. Può trattarsi di un nome relativo o NULL. Se NULL, viene allocato un file composto temporaneo con un nome univoco.

[in] grfMode

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] reserved

Riservato per utilizzi futuri; deve essere zero.

[out] ppstgOpen

Puntatore alla posizione del puntatore IStorage al nuovo oggetto di archiviazione.

Valore restituito

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

Commenti

La funzione StgCreateDocfile crea un nuovo oggetto di archiviazione usando l'implementazione di file composta fornita da COM per l'interfaccia IStorage . Il nome del file composto aperto può essere recuperato chiamando il metodo IStorage::Stat .

StgCreateDocfile crea il file se non esiste. Se esiste, l'uso dei flag STGM_CREATE, STGM_CONVERT e STGM_FAILIFTHERE nel parametro grfMode indicano come procedere. Per altre informazioni, vedere Costanti STGM.

Se il file composto viene aperto in modalità transacted (il parametro grfMode specifica STGM_TRANSACTED) e esiste già un file con questo nome, il file esistente non viene modificato finché non viene eseguito il commit di tutte le modifiche in sospeso. Se il processo chiamante non dispone dell'accesso in scrittura al file esistente (a causa del controllo di accesso nel file system), il parametro grfMode può specificare solo STGM_READ e non STGM_WRITE o STGM_READWRITE. Il nuovo file composto aperto risultante può comunque essere scritto in , ma un'operazione di commit successiva avrà esito negativo (in modalità transazionata, le autorizzazioni di scrittura vengono applicate al momento del commit).

La specifica di STGM_SIMPLE fornisce un'implementazione molto più veloce di un oggetto file composto in un caso limitato, ma usato di frequente. Questa operazione può essere usata dalle applicazioni che richiedono un'implementazione di file composta con più flussi e nessuna risorsa di archiviazione. La modalità semplice non supporta tutti i metodi in IStorage. Per altre informazioni, vedere Costanti STGM.

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 nella directory del file system in cui viene creato il file composto. Se non viene specificato STGM_TRANSACTED e viene specificato STGM_CREATE, un file esistente con lo stesso nome viene eliminato definitivamente prima della creazione del nuovo file.

StgCreateDocfile può essere usato 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, probabilmente uno 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 .

Requisiti

Vedi anche

Costanti STGM

StgCreateDocFileOnILockBytes

StgCreateStorageEx