Função CcCopyReadEx (ntifs.h)

Artigo
02/29/2024

A rotina CcCopyReadEx copia dados de um arquivo armazenado em cache para um buffer de usuário. A contagem de bytes de E/S da operação é cobrada para o thread emissor.

Sintaxe

BOOLEAN CcCopyReadEx(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  BOOLEAN          Wait,
  [out] PVOID            Buffer,
  [out] PIO_STATUS_BLOCK IoStatus,
  [in]  PETHREAD         IoIssuerThread
);

Parâmetros

[in] FileObject

Um ponteiro para um objeto de arquivo para o arquivo armazenado em cache do qual os dados devem ser lidos.

[in] FileOffset

Um ponteiro para uma variável que especifica o deslocamento de bytes inicial dentro do arquivo armazenado em cache.

[in] Length

O comprimento em bytes dos dados a serem lidos.

[in] Wait

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

[out] Buffer

Um ponteiro para um buffer no qual os dados devem ser copiados.

[out] IoStatus

Um ponteiro para uma estrutura alocada pelo chamador que recebe a conclusão final status e informações sobre a operação. Se nem todos os dados forem copiados com êxito, IoStatus.Information conterá o número real de bytes que foram copiados.

[in] IoIssuerThread

O thread que emite a solicitação de leitura. Para um sistema de arquivos com a contabilidade de E/S de disco habilitada, esse é o thread ao qual a E/S é cobrada. Se IoIssuerThread for NULL, a E/S será cobrada para o thread atual.

Retornar valor

A rotina CcCopyReadEx retornará TRUE se os dados tiverem sido copiados com êxito; caso contrário, FALSE.

Comentários

Se Wait for TRUE, ccCopyReadEx tem a garantia de concluir a solicitação de cópia e retornar TRUE. Se as páginas necessárias do arquivo armazenado em cache já estiverem residentes na memória, os dados serão copiados 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 copiados.

Se Wait for FALSE, CcCopyReadEx se recusará a bloquear e retornará FALSE se as páginas necessárias do arquivo armazenado em cache ainda não estiverem residentes na memória.

FileOffset mais Length deve ser menor ou igual ao tamanho do arquivo armazenado em cache ou ocorrerá uma falha de asserção.

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

Para armazenar em cache um arquivo, use CcInitializeCacheMap.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (include Ntifs.h, FltKernel.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL