Função CcPinMappedData (ntifs.h)

Artigo
08/07/2023

A rotina CcPinMappedData fixa o intervalo de bytes especificado de um arquivo armazenado em cache.

Sintaxe

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

Parâmetros

[in] FileObject

Ponteiro para um objeto de arquivo para o arquivo armazenado em cache no qual um intervalo de dados deve ser fixado.

[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 em bytes dos dados a serem fixados.

[in] Flags

Máscara de bits de sinalizadores especificando como a operação de fixação deve ser executada. Combinação ORed de um ou mais dos seguintes valores:

Sinalizador	Significado
PIN_WAIT	O chamador pode ser colocado em um estado de espera até que os dados sejam fixados.
PIN_EXCLUSIVE	O BCB (bloco de controle de buffer) deve ser adquirido exclusivamente. Se esse sinalizador estiver definido, PIN_WAIT também deverá ser definido.
PIN_NO_READ	Somente as páginas que já residem na memória devem ser fixadas. Se esse sinalizador estiver definido, PIN_WAIT também deverá ser definido.
PIN_IF_BCB	Os dados devem ser fixados somente se um BCB já existir. Caso contrário, o pino falhará e Bcb será definido como NULL.

[in, out] Bcb

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

Retornar valor

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

Comentários

Um retorno bem-sucedido de CcPinMappedData garante que os dados mapeados anteriormente em uma chamada para CcMapData sejam fixados no cache e os dados no intervalo especificado possam ser modificados com segurança. Se o chamador modificar posteriormente os dados fixados por CcPinMappedData, ele também deverá chamar CcSetDirtyPinnedData para que os dados modificados eventualmente sejam gravados em disco.

CcPinMappedData não pode fixar dados entre os 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 fixadas não podem abranger mais de uma exibição de 256 KB. Portanto, a maior região que pode ser fixada é de 256 KB, começando em um deslocamento alinhado a 256 KB no arquivo.

Fixar 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 fixadas, 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 ocorrer alguma falha, CcPinMappedData gerará uma exceção status para essa falha específica. Por exemplo, se ocorrer uma falha de alocação de pool, CcPinMappedData gerará uma exceção STATUS_INSUFFICIENT_RESOURCES; se ocorrer um erro de E/S, CcPinMappedData 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 CcPinMappedData em uma instrução try-except ou try-finally .

Para mapear dados para um arquivo armazenado em cache, use a rotina CcMapData . Para armazenar em cache um arquivo, use CcInitializeCacheMap.

Não é necessário chamar CcUnpinData depois de chamar CcPinMappedData , pois a referência de pin é correspondida a CcMapData.