Função CcPreparePinWrite (ntifs.h)

Artigo
08/07/2023

A rotina CcPreparePinWrite fixa o intervalo de bytes especificado de um arquivo armazenado em cache para acesso de gravação.

Sintaxe

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

Parâmetros

[in] FileObject

Ponteiro para um objeto de arquivo para o arquivo armazenado em cache no qual os dados devem ser gravados.

[in] FileOffset

Ponteiro para uma variável que especifica o deslocamento de bytes inicial dentro do arquivo em que os dados devem ser gravados.

[in] Length

Comprimento dos dados desejados em bytes.

[in] Zero

Defina como TRUE se o buffer deve ser zerado no retorno. Esse parâmetro será ignorado se o sinalizador PIN_CALLER_TRACKS_DIRTY_DATA estiver definido no parâmetro Flags .

[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:

Valor	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.
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 nenhum BCB será retornado.
PIN_CALLER_TRACKS_DIRTY_DATA	O chamador é responsável por acompanhar sujo páginas. Se esse sinalizador estiver definido, todos os outros sinalizadores serão ignorados. Esse sinalizador está disponível no Microsoft Windows Server 2003 SP1 e posterior.

[out] Bcb

Ponteiro opaco para um BCB (bloco de controle de buffer fixado). Esse ponteiro deve ser fornecido como entrada em todas as chamadas subsequentes para CcPreparePinWrite ou CcUnpinData para esse buffer.

[out] Buffer

Retorna o ponteiro para os dados desejados, válidos até que o buffer seja desafixado ou liberado.

Retornar valor

CcPreparePinWrite retornará TRUE se o arquivo armazenado em cache tiver sido fixado com êxito, caso contrário, FALSE .

Comentários

CcPreparePinWrite fixa as páginas de arquivo especificadas no cache do sistema. As páginas a serem completamente substituídas podem ser satisfeitas com páginas de zeros.

Se o sinalizador PIN_WAIT estiver definido, o CcPreparePinWrite deverá concluir a solicitação de preparação e retornar TRUE. Se todas as páginas puderem ser preparadas imediatamente, 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 as páginas possam ser preparadas. Se o sinalizador PIN_WAIT não estiver definido, mas nem todas as páginas puderem ser preparadas imediatamente, CcPreparePinWrite retornará FALSE e seus valores de parâmetro de saída não serão sentido.

Microsoft Windows Server 2003 SP1 e posterior: O sinalizador PIN_CALLER_TRACKS_DIRTY_DATA é comumente usado nos casos em que um sistema de arquivos está gerenciando um arquivo de log que é gravado, mas não lido. Como os dados de arquivo existentes serão substituídos e não lidos, o gerenciador de cache pode retornar páginas de zeros em vez de falhar nas páginas reais dos dados de arquivo do disco. Se esse sinalizador estiver definido, o gerenciador de cache não acompanhará sujo páginas. O chamador é responsável por controlar qualquer sujo páginas. Observe que CcPreparePinWrite só deve ser usado para fixar dados dessa maneira se o buffer eventualmente for liberado para o disco. Antes de chamar CcFlushCache para liberar o buffer para o disco, o chamador deve primeiro chamar MmSetAddressRangeModified para notificar o gerenciador de memória de que as páginas especificadas no buffer de cache do sistema são sujo e devem ser gravadas.

Cada chamada bem-sucedida para CcPreparePinWrite deve ser correspondida por uma chamada subsequente para CcUnpinData. Se CcPreparePinWrite for chamado várias vezes para os mesmos dados, CcUnpinData deverá ser chamado do mesmo número de vezes.

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).

CcPreparePinWrite não pode fixar 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 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.

Não é necessário chamar CcSetDirtyPinnedData depois de chamar CcPreparePinWrite. Se CcPreparePinWrite retornar TRUE, o BCB já estará marcado como sujo.

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