Função CcPinMappedData (ntifs.h)
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 no 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 que especifica como a operação de fixação deve ser executada. Combinação ORed de um ou mais dos seguintes valores:
| Bandeira | 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. |
[in, 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.
Valor de retorno
CcPinMappedData retornará verdadeiro se os dados do arquivo armazenado em cache tiverem sido fixados com êxito, false caso contrário.
Observações
Um retorno bem-sucedido de CcPinMappedData garante que os dados mapeados anteriormente em uma chamada para ccMapData está fixado no cache e os dados no intervalo especificado podem 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 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, CcPinMappedData gerará uma exceção de 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 de 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 de CcMapData. Para armazenar em cache um arquivo, use CcInitializeCacheMap.
Não é necessário chamar ccUnpinData depois de chamar ccPinMappedData, uma vez que a referência de pino é correspondida a ccMapData.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino |
Universal |
| cabeçalho | ntifs.h (inclua Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL |
NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |