Condividi tramite


Funzione OpenFileById (winbase.h)

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.

[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)
File system resiliente (ReFS)

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.

Vedi anche

ACCESS_MASK

Closehandle

CreateFile

DeleteFile

FILE_ID_DESCRIPTOR

Funzioni di gestione file

GetFileInformationByHandleEx

GetOverlappedResult

SOVRAPPOSTA

OpenFile

ReadFile

WriteFile