Funzione MapViewOfFile (memoryapi.h)

Esegue il mapping di una visualizzazione di un file nello spazio indirizzi di un processo chiamante.

Per specificare un indirizzo di base suggerito per la visualizzazione, usare la funzione mapViewOfFileEx . Tuttavia, questa pratica non è consigliata.

Sintassi

LPVOID MapViewOfFile(
  [in] HANDLE hFileMappingObject,
  [in] DWORD  dwDesiredAccess,
  [in] DWORD  dwFileOffsetHigh,
  [in] DWORD  dwFileOffsetLow,
  [in] SIZE_T dwNumberOfBytesToMap
);

Parametri

[in] hFileMappingObject

Handle per un oggetto di mapping di file. Le funzioni CreateFileMapping e OpenFileMapping restituiscono questo handle.

[in] dwDesiredAccess

Tipo di accesso a un oggetto di mapping di file, che determina la protezione della pagina delle pagine. Questo parametro può essere uno dei valori seguenti o una combinazione OR bit per bit di più valori, se appropriato.

Usando OR bit per bit, è possibile combinare i valori precedenti con questi valori.

Per gli oggetti di mapping di file creati con l'attributo SEC_IMAGE, il parametro dwDesiredAccess non ha alcun effetto e deve essere impostato su qualsiasi valore valido, ad esempio FILE_MAP_READ.

Per altre informazioni sull'accesso agli oggetti di mapping dei file, vedere Protezione mapping file e Diritti di accesso.

[in] dwFileOffsetHigh

Un DWORD di ordine elevato dell'offset del file in cui inizia la visualizzazione.

[in] dwFileOffsetLow

Un DWORD di basso ordine dell'offset del file in cui deve iniziare la visualizzazione. La combinazione degli offset alti e bassi deve specificare un offset all'interno del mapping dei file. Devono inoltre corrispondere alla granularità dell'allocazione di memoria del sistema. Ovvero, l'offset deve essere un multiplo della granularità di allocazione. Per ottenere la granularità dell'allocazione di memoria del sistema, usare la funzione GetSystemInfo, che riempie i membri di una struttura SYSTEM_INFO.

[in] dwNumberOfBytesToMap

Numero di byte di un mapping di file da mappare alla visualizzazione. Tutti i byte devono essere entro le dimensioni massime specificate da CreateFileMapping. Se questo parametro è 0 (zero), il mapping si estende dall'offset specificato alla fine del mapping di file.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è l'indirizzo iniziale della visualizzazione mappata.

Se la funzione ha esito negativo, il valore restituito è NULL. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

Il mapping di un file rende visibile la parte specificata di un file nello spazio indirizzi del processo chiamante.

Per i file di dimensioni superiori allo spazio indirizzi, è possibile eseguire il mapping di una piccola parte dei dati del file contemporaneamente. Al termine della prima visualizzazione, è possibile annullare il mapping e mappare una nuova visualizzazione.

Per ottenere le dimensioni di una vista, usare la funzione VirtualQuery.

Più visualizzazioni di un file (o di un oggetto di mapping di file e del relativo file mappato) sono coerenti se contengono dati identici in un determinato momento. Ciò si verifica se le visualizzazioni file sono derivate da qualsiasi oggetto di mapping di file supportato dallo stesso file. Un processo può duplicare un handle di oggetto di mapping di file in un altro processo usando la funzione DuplicateHandle oppure un altro processo può aprire un oggetto di mapping di file in base al nome usando la funzione OpenFileMapping.

Con un'eccezione importante, le visualizzazioni file derivate da qualsiasi oggetto di mapping di file supportato dallo stesso file sono coerenti o identici in un momento specifico. La coerenza è garantita per le visualizzazioni all'interno di un processo e per le visualizzazioni mappate da processi diversi.

L'eccezione è correlata ai file remoti. Anche se MapViewOfFile funziona con i file remoti, non li mantiene coerenti. Ad esempio, se due computer eseguono il mapping di un file come scrivibili e entrambi modificano la stessa pagina, ogni computer visualizza solo le proprie scritture nella pagina. Quando i dati vengono aggiornati sul disco, non vengono uniti.

Non è garantito che una visualizzazione mappata di un file sia coerente con un file accessibile dalla funzione ReadFile o WriteFile.

Non archiviare i puntatori nel file mappato alla memoria; archivia gli offset dalla base del mapping dei file in modo che il mapping possa essere usato in qualsiasi indirizzo.

Per evitare EXCEPTION_IN_PAGE_ERROR eccezioni, usare la gestione delle eccezioni strutturate per proteggere qualsiasi codice che scrive o legge da una visualizzazione mappata alla memoria di un file diverso dal file di pagina. Per altre informazioni, vedere Lettura e scrittura da una visualizzazione file.

Quando si modifica un file tramite una visualizzazione mappata, il timestamp dell'ultima modifica potrebbe non essere aggiornato automaticamente. Se necessario, il chiamante deve usare SetFileTime per impostare il timestamp.

Se un oggetto di mapping di file è supportato dal file di paging (createFileMapping viene chiamato con il parametro hFile impostato su INVALID_HANDLE_VALUE), il file di paging deve essere sufficientemente grande da contenere l'intero mapping. In caso contrario, MapViewOfFile ha esito negativo. Il contenuto iniziale delle pagine in un oggetto di mapping di file supportato dal file di paging è 0 (zero).

Quando viene creato un oggetto di mapping di file supportato dal file di paging, il chiamante può specificare se MapViewOfFile deve riservare ed eseguire il commit di pagine contemporaneamente (SEC_COMMIT) o semplicemente riservare pagine (SEC_RESERVE). Il mapping del file rende l'intero intervallo di indirizzi virtuali mappato non disponibile per altre allocazioni nel processo. Dopo il commit di una pagina dall'intervallo riservato, non può essere liberata o decommessa chiamando VirtualFree. Le pagine riservate e di cui è stato eseguito il commit vengono rilasciate quando la visualizzazione viene annullata e l'oggetto di mapping dei file viene chiuso. Per informazioni dettagliate, vedere le funzioni UnmapViewOfFile e CloseHandle.

Per avere un file con autorizzazioni eseguibili, un'applicazione deve chiamare CreateFileMapping con PAGE_EXECUTE_READWRITE o PAGE_EXECUTE_READe quindi chiamare MapViewOfFile con FILE_MAP_EXECUTE | FILE_MAP_WRITE o FILE_MAP_EXECUTE | FILE_MAP_READ.

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

Quando il file CsvFs è in pausa, questa chiamata potrebbe non riuscire con un errore che indica che si è verificato un conflitto di blocco.

Esempi

Per un esempio, vedere Creazione di memoria condivisa denominata.

Fabbisogno

Vedere anche

CreateFileMapping

Creazione di un di visualizzazione file

duplicateHandle

GetSystemInfo

mapViewOfFileEx

funzioni di gestione della memoria

OpenFileMapping

SYSTEM_INFO

unmapViewOfFile