CcMapData 함수(ntifs.h)

아티클
08/07/2023

CcMapData 루틴은 캐시된 파일의 지정된 바이트 범위를 메모리의 버퍼에 매핑합니다.

구문

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

매개 변수

[in] FileObject

읽기 액세스를 위해 데이터를 매핑할 파일의 파일 개체에 대한 포인터입니다.

[in] FileOffset

원하는 데이터가 있는 캐시된 파일 내에서 시작 바이트 오프셋을 지정하는 변수에 대한 포인터입니다.

[in] Length

원하는 데이터의 길이(바이트)입니다.

[in] Flags

매핑 작업을 수행하는 방법을 지정하는 플래그의 비트 마스크입니다. 다음 값 중 하나 이상의 비트 OR 조합입니다.

값	의미
MAP_WAIT	데이터가 매핑될 때까지 호출자를 대기 상태로 전환할 수 있습니다.
MAP_NO_READ	메모리에 이미 상주하는 페이지만 매핑됩니다.

참고 Windows 2000 및 이전 버전에서 이 매개 변수는 Wait라는 BOOLEAN 값이었습니다.

연결 시도 간격

데이터가 매핑될 때까지 호출자를 대기 상태로 전환할 수 있으면 TRUE 로 설정하고, 그렇지 않으면 FALSE 로 설정합니다.

[out] Bcb

첫 번째 호출에서 BCB(버퍼 제어 블록) 구조체에 대한 포인터를 반환합니다. 이 포인터는 이 버퍼에 대한 모든 후속 호출에 대한 입력으로 제공되어야 합니다.

[out] Buffer

매핑된 데이터를 포함하는 버퍼에 대한 포인터입니다.

반환 값

캐시된 파일의 데이터가 성공적으로 매핑된 경우 CcMapData는 TRUE를 반환하고, 그렇지 않으면 FALSE를 반환합니다.

설명

CcMapData 는 읽기 액세스를 위해 캐시된 파일에 데이터를 매핑합니다. CcMapData가 호출되면 데이터가 매핑됩니다. 고정되지 않았습니다. 이러한 구분이 중요합니다. 매핑되었지만 고정되지 않은 데이터는 안전하게 수정할 수 없습니다. 데이터를 고정하려면 CcPinMappedData, CcPinRead 또는 CcPreparePinWrite를 사용합니다.

CcMapData에 대한 모든 성공적인 호출은 CcUnpinData에 대한 후속 호출과 일치해야 합니다.

CcMapData 는 캐시 관리자의 보기 경계를 넘어 데이터를 매핑할 수 없습니다. 캐시 관리자는 256KB로 정렬된 보기에서 시스템의 파일을 관리합니다. (캐시 관리자의 뷰 크기는 ntifs.h에서 256KB로 설정된 시스템 정의 상수 VACB_MAPPING_GRANULARITY 의해 지정됩니다. 매핑된 지역은 둘 이상의 256KB 뷰에 걸쳐 있습니다. 따라서 매핑할 수 있는 가장 큰 지역은 파일의 256KB 정렬 오프셋에서 시작하여 256KB입니다.

캐시된 파일에서 바이트 범위를 매핑해도 페이지가 메모리에 상주하지 않습니다. 페이지가 매핑되는 한 바이트 범위는 시스템 캐시 가상 주소 공간에 매핑된 상태를 유지하지만 메모리 관리자는 시스템의 메모리 요구 사항에 따라 실제 페이지를 페이징할 수 있습니다.

MAP_WAIT 플래그가 설정되거나 Wait가 TRUE인 경우 CcMapData는 매핑 요청을 완료하고 TRUE를 반환하도록 보장됩니다. 캐시된 파일의 필수 페이지가 이미 메모리에 상주하는 경우 데이터가 즉시 매핑되고 차단이 발생하지 않습니다. 필요한 페이지가 상주하지 않으면 모든 필수 페이지가 상주하고 데이터를 매핑할 수 있을 때까지 호출자가 대기 상태가 됩니다. MAP_WAIT 플래그가 설정되지 않았거나 Wait가 FALSE이고 데이터를 즉시 매핑할 수 없는 경우 CcMapData는 FALSE를 반환합니다.

버퍼에 반환된 포인터는 CcUnpinData가 호출될 때까지 유효합니다. 이 포인터가 유효한 동안 CcPinMappedData 가 호출되면 CcPinMappedData 를 호출한 후에도 포인터가 유효한 상태로 유지됩니다( CcUnpinData 가 호출될 때까지만).

오류가 발생하면 CcMapData는 해당 특정 오류에 대한 상태 예외를 발생합니다. 예를 들어 풀 할당 오류가 발생하면 CcMapData에서 STATUS_INSUFFICIENT_RESOURCES 예외가 발생합니다. I/O 오류가 발생하면 CcMapData는 I/O 오류의 상태 예외를 발생합니다. 따라서 오류가 발생하는 경우 제어하려면 드라이버는 try-except 또는try-finally 문에서 CcMapData에 대한 호출을 래핑해야 합니다.

파일을 캐시하려면 CcInitializeCacheMap을 사용합니다.