Funzione OpenFileById (winbase.h)

Articolo
08/27/2023

Apre il file corrispondente all'identificatore specificato.

Sintassi

HANDLE OpenFileById(
  [in]           HANDLE                hVolumeHint,
  [in]           LPFILE_ID_DESCRIPTOR  lpFileId,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwFlagsAndAttributes
);

Parametri

[in] hVolumeHint

Handle per qualsiasi file in un volume o in una condivisione in cui è archiviato il file.

[in] lpFileId

Puntatore a un FILE_ID_DESCRIPTOR che identifica il file da aprire.

[in] dwDesiredAccess

Accesso all'oggetto. L'accesso può essere letto, scritto o entrambi.

Per altre informazioni, vedere Sicurezza file e diritti di accesso. Non è possibile richiedere una modalità di accesso in conflitto con la modalità di condivisione specificata in una richiesta aperta con un handle aperto.

Se questo parametro è zero (0), l'applicazione può eseguire query su file e attributi del dispositivo senza accedere a un dispositivo. Ciò è utile per un'applicazione per determinare le dimensioni di un'unità disco floppy e i formati supportati senza richiedere un floppy in un'unità. Può essere usato anche per testare l'esistenza di un file o di una directory senza aprirli per l'accesso in lettura o scrittura.

[in] dwShareMode

Modalità di condivisione di un oggetto, che può essere letto, scritto, entrambi o nessuno.

Non è possibile richiedere una modalità di condivisione in conflitto con la modalità di accesso specificata in una richiesta aperta con un handle aperto, perché ciò comporta la violazione di condivisione seguente: (ERROR_SHARING_VIOLATION). Per altre informazioni, vedere Creazione e apertura di file.

Se questo parametro è zero (0) e OpenFileById ha esito positivo, l'oggetto non può essere condiviso e non può essere aperto di nuovo finché l'handle non viene chiuso. Per altre informazioni, vedere la sezione Osservazioni di questo argomento.

Le opzioni di condivisione rimangono effettive fino a chiudere l'handle a un oggetto.

Per consentire a un processo di condividere un oggetto mentre un altro processo ha l'oggetto aperto, usare una combinazione di uno o più dei valori seguenti per specificare la modalità di accesso che possono richiedere di aprire l'oggetto.

Valore	Significato
FILE_SHARE_DELETE 0x00000004	Abilita le operazioni aperte successive su un oggetto per richiedere l'accesso eliminato. In caso contrario, altri processi non possono aprire l'oggetto se richiedono l'accesso. Se questo flag non è specificato, ma l'oggetto è stato aperto per l'accesso eliminato, la funzione ha esito negativo.
FILE_SHARE_READ 0x00000001	Abilita le operazioni aperte successive su un oggetto per richiedere l'accesso in lettura. In caso contrario, altri processi non possono aprire l'oggetto se richiedono l'accesso in lettura. Se questo flag non è specificato, ma l'oggetto è stato aperto per l'accesso in lettura, la funzione ha esito negativo.
FILE_SHARE_WRITE 0x00000002	Abilita le operazioni aperte successive su un oggetto per richiedere l'accesso in scrittura. In caso contrario, altri processi non possono aprire l'oggetto se richiedono l'accesso in scrittura. Se questo flag non è specificato, ma l'oggetto è stato aperto per l'accesso in scrittura o ha un mapping di file con accesso in scrittura, la funzione ha esito negativo.

Valore

Significato

FILE_SHARE_DELETE
0x00000004

Abilita le operazioni aperte successive su un oggetto per richiedere l'accesso eliminato.

In caso contrario, altri processi non possono aprire l'oggetto se richiedono l'accesso.

Se questo flag non è specificato, ma l'oggetto è stato aperto per l'accesso eliminato, la funzione ha esito negativo.

FILE_SHARE_READ
0x00000001

Abilita le operazioni aperte successive su un oggetto per richiedere l'accesso in lettura.

In caso contrario, altri processi non possono aprire l'oggetto se richiedono l'accesso in lettura.

Se questo flag non è specificato, ma l'oggetto è stato aperto per l'accesso in lettura, la funzione ha esito negativo.

FILE_SHARE_WRITE
0x00000002

Abilita le operazioni aperte successive su un oggetto per richiedere l'accesso in scrittura.

In caso contrario, altri processi non possono aprire l'oggetto se richiedono l'accesso in scrittura.

Se questo flag non è specificato, ma l'oggetto è stato aperto per l'accesso in scrittura o ha un mapping di file con accesso in scrittura, la funzione ha esito negativo.

[in, optional] lpSecurityAttributes

Riservato.

[in] dwFlagsAndAttributes

Flag di file.

Quando OpenFileById apre un file, combina i flag di file con gli attributi di file esistenti e ignora gli attributi dei file specificati. Questo parametro può includere qualsiasi combinazione dei flag seguenti.

Valore	Significato
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	Un file viene aperto per un'operazione di backup o ripristino. Il sistema garantisce che il processo chiamante esegue l'override della sicurezza dei file quando il processo ha SE_BACKUP_NAME e SE_RESTORE_NAME privilegi. Per altre informazioni, vedere Modifica dei privilegi in un token. È necessario impostare questo flag per ottenere un handle in una directory. Un handle di directory può essere passato a alcune funzioni anziché a un handle di file. Per altre informazioni, vedere Handle directory.
FILE_FLAG_NO_BUFFERING 0x20000000	Il sistema apre un file senza memorizzazione nella cache del sistema. Questo flag non influisce sulla memorizzazione nella cache del disco rigido. Se combinato con FILE_FLAG_OVERLAPPED, il flag offre prestazioni asincrone massime, perché l'I/O non si basa sulle operazioni sincrone della gestione memoria. Tuttavia, alcune operazioni di I/O richiedono più tempo, perché i dati non vengono mantenuti nella cache. Inoltre, i metadati dei file possono comunque essere memorizzati nella cache. Per scaricare i metadati sul disco, usare la funzione FlushFileBuffers . Un'applicazione deve soddisfare determinati requisiti quando si riguardano i file aperti con FILE_FLAG_NO_BUFFERING: L'accesso ai file deve iniziare a offset di byte all'interno di un file che sono numeri interi delle dimensioni del settore del volume. L'accesso ai file deve essere per i numeri di byte interi delle dimensioni del settore del volume. Ad esempio, se la dimensione del settore è pari a 512 byte, un'applicazione può richiedere letture e scritture di 512, 1024, 1536 o 2048 byte, ma non di 335, 981 o 7171 byte. Gli indirizzi del buffer per le operazioni di lettura e scrittura devono essere allineati al settore, che significa allineati agli indirizzi in memoria che sono più interi delle dimensioni del settore del volume. A seconda del disco, questo requisito potrebbe non essere applicato. Un modo per allineare i buffer su più interi delle dimensioni del settore del volume consiste nell'usare VirtualAlloc per allocare i buffer. Alloca memoria allineata agli indirizzi che sono numeri interi delle dimensioni della pagina di memoria del sistema operativo. Poiché entrambe le dimensioni della pagina della memoria e del settore del volume sono poteri pari a 2, questa memoria è allineata anche agli indirizzi che sono interi multipli di dimensioni del settore del volume. Le pagine di memoria sono di dimensioni pari a 4-8 KB; i settori sono 512 byte (dischi rigidi) o 2048 byte (CD) e quindi i settori del volume non possono mai essere più grandi delle pagine di memoria. Un'applicazione può determinare una dimensione del settore del volume chiamando la funzione GetDiskFreeSpace .
FILE_FLAG_OPEN_NO_RECALL 0x00100000	I dati del file vengono richiesti, ma devono continuare a trovarsi nell'archiviazione remota. Non deve essere trasportato nuovamente all'archiviazione locale. Questo flag è usato dai sistemi di archiviazione remoti.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	Quando viene usato questo flag, l'elaborazione normale del punto di ripristino non si verifica e OpenFileById tenta di aprire il punto di riparse. Quando viene aperto un file, viene restituito un handle di file, indipendentemente dal fatto che il filtro che controlla il punto di ripristino sia operativo. Questo flag non può essere usato con il flag di CREATE_ALWAYS . Se il file non è un punto di correzione, questo flag viene ignorato.
FILE_FLAG_OVERLAPPED 0x40000000	Il file è aperto o creato per gli I/O asincroni. Al termine dell'operazione, l'evento specificato alla chiamata nella struttura OVERLAPPED viene impostato sullo stato segnalato. Operazioni che richiedono un tempo significativo per elaborare ERROR_IO_PENDING. Se questo flag è specificato, il file può essere usato per operazioni di lettura e scrittura simultanee. Il sistema non mantiene il puntatore al file, pertanto è necessario passare la posizione del file alle funzioni di lettura e scrittura nella struttura OVERLAPPED o aggiornare il puntatore del file. Se questo flag non è specificato, le operazioni di I/O vengono serializzate, anche se le chiamate alle funzioni di lettura e scrittura specificano una struttura OVERLAPPED .
FILE_FLAG_RANDOM_ACCESS 0x10000000	L'accesso al un file viene eseguito in modo casuale. Il sistema può interpretare questa situazione come hint per l'ottimizzazione della memorizzazione del file nella cache.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	L'accesso a un file viene eseguito in sequenza, partendo dall'inizio e fino alla fine. Il sistema può interpretare questa situazione come hint per l'ottimizzazione della memorizzazione del file nella cache. Se un'applicazione sposta il puntatore al file per l'accesso casuale, la memorizzazione nella cache ottimale potrebbe non verificarsi. Tuttavia, l'operazione corretta è ancora garantita. Specificando questo flag è possibile aumentare le prestazioni per le applicazioni che leggeno file di grandi dimensioni usando l'accesso sequenziale. I miglioramenti delle prestazioni possono essere ancora più evidenti per le applicazioni che leggono file di grandi dimensioni principalmente in sequenza, ma occasionalmente ignorano intervalli di byte di piccole dimensioni.
FILE_FLAG_WRITE_THROUGH 0x80000000	Il sistema scrive tramite qualsiasi cache intermedia e passa direttamente al disco. Se FILE_FLAG_NO_BUFFERING non è specificato anche, in modo che la memorizzazione nella cache del sistema sia effettiva, i dati vengono scritti nella cache di sistema, ma vengono scaricati su disco senza ritardo. Se FILE_FLAG_NO_BUFFERING viene specificato anche, in modo che la memorizzazione nella cache del sistema non sia effettiva, i dati vengono immediatamente scaricati su disco senza passare dalla cache di sistema. Il sistema operativo richiede anche una scrittura tramite la cache del disco rigido per supporti persistenti. Tuttavia, non tutti gli hardware supportano questa funzionalità di scrittura.

Valore restituito

Se la funzione viene eseguita correttamente, il valore restituito è un handle aperto per il file specificato.

Se la funzione ha esito negativo, il valore restituito è INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Utilizzare la funzione CloseHandle per chiudere un handle oggetto restituito da OpenFileById .

Se si chiama OpenFileById in un file in sospeso come risultato di una chiamata precedente a DeleteFile, la funzione ha esito negativo. Il sistema operativo ritarda l'eliminazione del file fino a quando non vengono chiusi tutti gli handle del file. GetLastError restituisce ERROR_ACCESS_DENIED.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Supportato
Protocollo SMB (Server Message Block) 3.0	No
Failover trasparente SMB 3.0 (TFO)	No
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	No
File system del volume condiviso del cluster (CsvFS)	Sì
File system resiliente (ReFS)	Sì

Requisiti


Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib; FileExtd.lib in Windows Server 2003 e Windows XP
DLL	Kernel32.dll
Componente ridistribuibile	Windows SDK in Windows Server 2003 e Windows XP.