Função CcMapData (ntifs.h)

Artigo
08/07/2023

A rotina CcMapData mapeia um intervalo de bytes especificado de um arquivo armazenado em cache para um buffer na memória.

Sintaxe

BOOLEAN CcMapData(
  [in]  PFILE_OBJECT   FileObject,
  [in]  PLARGE_INTEGER FileOffset,
  [in]  ULONG          Length,
  [in]  ULONG          Flags,
  [out] PVOID          *Bcb,
  [out] PVOID          *Buffer
);

Parâmetros

[in] FileObject

Ponteiro para um objeto de arquivo para o arquivo cujos dados devem ser mapeados para acesso de leitura.

[in] FileOffset

Ponteiro para uma variável que especifica o deslocamento de bytes inicial dentro do arquivo armazenado em cache onde residem os dados desejados.

[in] Length

Comprimento dos dados desejados em bytes.

[in] Flags

Máscara de bits de sinalizadores especificando como a operação de mapeamento deve ser executada. Essa é uma combinação OR bit a bit de um ou mais dos seguintes valores:

Valor	Significado
MAP_WAIT	O chamador pode ser colocado em um estado de espera até que os dados sejam mapeados.
MAP_NO_READ	Somente as páginas que já residem na memória devem ser mapeadas.

Nota No Windows 2000and anterior, esse parâmetro era um valor BOOLEAN chamado Wait:

Aguarde

Defina como TRUE se o chamador puder ser colocado em um estado de espera até que os dados sejam mapeados, caso contrário, FALSE .

[out] Bcb

Na primeira chamada, isso retorna um ponteiro para uma estrutura bcb (bloco de controle de buffer). Esse ponteiro deve ser fornecido como entrada em todas as chamadas subsequentes para esse buffer.

[out] Buffer

Ponteiro para um buffer que contém os dados mapeados.

Retornar valor

CcMapData retornará TRUE se os dados do arquivo armazenado em cache tiverem sido mapeados com êxito, caso contrário, FALSE .

Comentários

CcMapData mapeia dados em um arquivo armazenado em cache para acesso de leitura. Observe que, depois que CcMapData é chamado, os dados são mapeados; mas não está fixado. Essa distinção é importante. Os dados mapeados, mas não fixados, não podem ser modificados com segurança. Para fixar os dados, use CcPinMappedData, CcPinRead ou CcPreparePinWrite.

Cada chamada bem-sucedida para CcMapData deve ser correspondida por uma chamada subsequente para CcUnpinData.

CcMapData não pode mapear dados entre limites de exibição no gerenciador de cache. O gerenciador de cache gerencia arquivos no sistema em exibições alinhadas a 256 KB. (O tamanho da exibição do gerenciador de cache é especificado pela constante definida pelo sistema VACB_MAPPING_GRANULARITY, que é definida como 256 KB em ntifs.h.) As regiões mapeadas não podem abranger mais de uma exibição de 256 KB. Portanto, a maior região que pode ser mapeada é de 256 KB, começando em um deslocamento alinhado a 256 KB no arquivo.

Mapear um intervalo de bytes em um arquivo armazenado em cache não garante que as páginas permaneçam residentes na memória. Desde que as páginas sejam mapeadas, o intervalo de bytes tem a garantia de permanecer mapeado no espaço de endereço virtual do cache do sistema, mas o gerenciador de memória pode colocar as páginas físicas como a demanda de memória do sistema exige.

Se o sinalizador MAP_WAIT estiver definido (ou Wait for TRUE), CcMapData será garantido para concluir a solicitação de mapeamento e retornar TRUE. Se as páginas necessárias do arquivo armazenado em cache já estiverem residentes na memória, os dados serão mapeados imediatamente e nenhum bloqueio ocorrerá. Se as páginas necessárias não forem residentes, o chamador será colocado em estado de espera até que todas as páginas necessárias sejam residentes e os dados possam ser mapeados. Se o sinalizador MAP_WAIT não estiver definido (ou a espera for FALSE) e os dados não puderem ser mapeados imediatamente, CcMapData retornará FALSE.

O ponteiro retornado em Buffer é válido até CcUnpinData ser chamado. Se CcPinMappedData for chamado enquanto esse ponteiro ainda for válido, o ponteiro permanecerá válido após a chamada para CcPinMappedData (mas somente até CcUnpinData ser chamado).

Se ocorrer alguma falha, CcMapData gerará uma exceção status para essa falha específica. Por exemplo, se ocorrer uma falha de alocação de pool, CcMapData gerará uma exceção STATUS_INSUFFICIENT_RESOURCES; se ocorrer um erro de E/S, CcMapData gerará a exceção status do erro de E/S. Portanto, para obter controle se ocorrer uma falha, o driver deverá encapsular a chamada para CcMapData em uma instrução try-except ou try-finally .

Para armazenar em cache um arquivo, use CcInitializeCacheMap.