Função CcPinRead (ntifs.h)
A rotina CcPinRead fixa o intervalo de bytes especificado de um arquivo armazenado em cache e lê os dados fixados em um buffer na memória.
Sintaxe
BOOLEAN CcPinRead(
[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 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 no 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 que especifica 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 bloco de controle de buffer (BCB) 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 serão fixados somente se um BCB já existir. Caso contrário, o pino falhará e bcb será definido como NULL. |
[out] Bcb
Na primeira chamada, isso retorna um ponteiro para um bloco de controle de buffer (BCB). 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 fixados.
Valor de retorno
CcPinRead retornará verdadeiro se os dados do arquivo armazenado em cache tiverem sido fixados e lidos com êxito, false caso contrário.
Observações
Se o sinalizador de PIN_WAIT estiver definido, ccPinRead será garantido para concluir a solicitação de fixação e retornar verdadeiro. Se as páginas necessárias do arquivo armazenado em cache já estiverem residentes na memória, os dados serão fixados imediatamente e nenhum bloqueio ocorrerá. Se as páginas necessárias não forem residentes, o chamador será colocado em um estado de espera até que todas as páginas necessárias sejam residentes e os dados possam ser fixados. Se o sinalizador PIN_WAIT não estiver definido, mas os dados não puderem ser fixados imediatamente, CcPinRead retornará FALSE e seus valores de parâmetro de saída não serão sentidos.
Se o chamador modificar posteriormente os dados lidos pelo CcPinRead, ele também deverá chamar CcSetDirtyPinnedData para que os dados modificados eventualmente sejam gravados em disco.
Cada chamada bem-sucedida para CcPinRead deve ser correspondida por uma chamada subsequente para ccUnpinData.
O ponteiro retornado em buffer é válido até que CcUnpinData seja 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é que ccUnpinData seja chamado).
CcPinRead 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 é 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, CcPinRead gerará uma exceção de status para essa falha específica. Por exemplo, se ocorrer uma falha de alocação de pool, CcPinRead gerará uma exceção STATUS_INSUFFICIENT_RESOURCES; se ocorrer um erro de E/S, CcPinRead gerará a exceção de status do erro de E/S. Portanto, para obter controle se ocorrer uma falha, o driver deverá encapsular a chamada para CcPinRead em uma instrução try-except ou try-finally.
Para mapear dados para um arquivo armazenado em cache, use a rotina de CcMapData. Para armazenar em cache um arquivo, use CcInitializeCacheMap.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino |
Universal |
| cabeçalho | ntifs.h (inclua Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL |
NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL |