READ_USN_JOURNAL_DATA_V1 구조체(winioctl.h)
호출 프로세스에 반환할 USN(업데이트 시퀀스 번호) 변경 저널 레코드 세트를 정의하는 정보를 포함합니다. FSCTL_QUERY_USN_JOURNAL 및 FSCTL_READ_USN_JOURNAL 제어 코드에서 사용됩니다. Windows 8 및 Windows Server 2012 전에 이 구조체의 이름은 READ_USN_JOURNAL_DATA. 이 이름을 사용하여 이전 SDK 및 컴파일러로 컴파일합니다. Windows Server 2012 ReFS에서 사용하는 128비트 파일 식별자를 지원하는 READ_USN_JOURNAL_DATA_V1 도입되었습니다.
구문
typedef struct {
USN StartUsn;
DWORD ReasonMask;
DWORD ReturnOnlyOnClose;
DWORDLONG Timeout;
DWORDLONG BytesToWaitFor;
DWORDLONG UsnJournalID;
WORD MinMajorVersion;
WORD MaxMajorVersion;
} READ_USN_JOURNAL_DATA_V1, *PREAD_USN_JOURNAL_DATA_V1;
멤버
StartUsn
변경 저널 읽기를 시작할 USN입니다.
저널의 첫 번째 레코드에서 읽기 작업을 시작하려면 StartUsn 멤버를 0으로 설정합니다. USN은 모든 저널 레코드에 포함되어 있으므로 출력 버퍼는 읽기 작업이 실제로 시작된 레코드를 알려줍니다.
특정 레코드에서 읽기 작업을 시작하려면 StartUsn 을 해당 레코드 USN으로 설정합니다.
변경 저널의 첫 번째 USN보다 작은 0이 아닌 USN을 지정하면 오류가 발생하고 ERROR_JOURNAL_ENTRY_DELETED 오류 코드가 반환됩니다. 이 코드는 지정된 USN이 한 번에 유효하지만 이후 삭제된 경우를 나타낼 수 있습니다.
READ_USN_JOURNAL_DATA_V0 반환된 변경 저널 버퍼 탐색에 대한 자세한 내용은 변경 저널 레코드 버퍼 걷기를 참조하세요.
ReasonMask
파일 또는 디렉터리에 변경 저널의 레코드가 있는 변경 사항을 나타내는 각 플래그인 플래그 마스크입니다. FSCTL_READ_USN_JOURNAL 작업에서 반환하려면 변경 저널 레코드에 이러한 플래그 중 하나 이상이 설정되어 있어야 합니다.
유효한 플래그 목록은 다음과 같습니다. 사용하지 않는 비트는 예약되어 있습니다.
| 값 | 의미 |
|---|---|
|
사용자가 하나 이상의 파일 또는 디렉터리 특성(예: 읽기 전용, 숨겨진, 시스템, 보관 또는 스파스 특성) 또는 하나 이상의 타임스탬프를 변경했습니다. |
|
파일 또는 디렉터리가 닫힙니다. |
|
파일 또는 디렉터리의 압축 상태가 또는 에서 압축됨으로 변경됩니다. |
|
파일 또는 디렉터리가 에 추가됩니다. |
|
파일 또는 디렉터리의 데이터를 덮어씁니다. |
|
파일 또는 디렉터리가 잘립니다. |
|
사용자가 파일 또는 디렉터리 확장 특성을 변경합니다. 이러한 NTFS 파일 시스템 특성은 Windows 기반 애플리케이션에서 액세스할 수 없습니다. |
|
파일 또는 디렉터리가 암호화되거나 암호 해독됩니다. |
|
파일 또는 디렉터리가 처음으로 만들어집니다. |
|
파일 또는 디렉터리가 삭제됩니다. |
|
NTFS 파일 시스템 하드 링크가 파일 또는 디렉터리에 추가되거나 제거됩니다. POSIX 하드 링크와 유사한 NTFS 파일 시스템 하드 링크는 동일한 파일 또는 디렉터리를 표시하는 여러 디렉터리 항목 중 하나입니다. |
|
사용자가 FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 특성을 변경했습니다. 즉, 사용자가 콘텐츠 인덱싱할 수 있는 파일 또는 디렉터리를 사용할 수 없는 디렉터리 또는 그 반대로 변경했습니다. (콘텐츠 인덱싱을 사용하면 선택한 콘텐츠의 데이터베이스를 빌드하여 데이터를 빠르게 검색할 수 있습니다.) |
|
파일에 대한 하나 이상의 명명된 데이터 스트림이 추가되었습니다. |
|
파일에 대한 하나 이상의 명명된 데이터 스트림의 데이터를 덮어씁니다. |
|
파일에 대한 하나 이상의 명명된 데이터 스트림이 잘립니다. |
|
파일 또는 디렉터리의 개체 식별자가 변경됩니다. |
|
파일 또는 디렉터리의 이름이 바뀌고 이 저널 레코드가 있는 USN_RECORD_V2 또는 USN_RECORD_V3 구조체의 파일 이름이 새 이름입니다. |
|
파일 또는 디렉터리의 이름이 바뀌고 이 저널 레코드가 있는 USN_RECORD_V2 또는 USN_RECORD_V3 구조체의 파일 이름이 이전 이름입니다. |
|
파일 또는 디렉터리에 포함된 재분석 지점이 변경되거나 파일 또는 디렉터리에서 재분석 지점이 추가되거나 삭제됩니다. |
|
파일 또는 디렉터리에 대한 액세스 권한에서 변경됩니다. |
|
명명된 스트림이 파일 또는 디렉터리에 추가되거나 제거되거나 명명된 스트림의 이름이 바뀝니다. |
ReturnOnlyOnClose
변경 저널 레코드를 반환할 시기를 지정하는 값입니다.
변경된 파일 또는 디렉터리에 대한 최종 핸들이 변경될 때가 아니라 닫힌 경우 알림을 받으려면 ReturnOnlyOnClose를 0이 아닌 값으로 설정하고 ReasonMask 멤버에서 USN_REASON_CLOSE 플래그를 지정합니다.
ReasonMask 플래그로 표시된 모든 변경 내용은 결국 파일이 닫히면 변경 저널 소프트웨어에 대한 호출을 생성합니다. DeviceIoControl 호출이 파일이 닫히기를 기다리는 경우 해당 호출을 통해 DeviceIoControl 호출이 반환될 수 있습니다. 볼륨 오류, 운영 체제 오류 또는 종료 전에 파일 또는 디렉터리가 닫혀 있지 않은 경우 다음에 볼륨이 탑재될 때 변경 저널 소프트웨어에 대한 정리 호출이 발생합니다. 시스템 재시작이 중간되는 경우에도 호출이 발생합니다.
각 변경 내용이 처음 기록될 때와 정리 시 알림을 받으려면 ReturnOnlyOnClose 를 0으로 설정합니다.
ReturnOnlyOnClose가 0이든 0이 아니든 관계없이 변경 저널 내의 정리 로그에서 생성된 레코드는 파일 또는 디렉터리에 발생한 USN 변경의 모든 이유입니다. 항목에 대한 최종 닫기 작업이 발생할 때마다 USN 닫기 레코드가 변경 저널에 기록되고 항목에 대한 ReasonMask 플래그가 모두 다시 설정됩니다.
사용자 데이터가 없는 파일 또는 디렉터리(예: 탑재된 폴더)의 경우 최종 닫기 작업은 항목에 대한 마지막 사용자 핸들에서 CloseHandle 함수를 호출할 때 발생합니다.
Timeout
BytesToWaitFor 멤버와 함께 사용되는 시간 제한 값(초)은 FSCTL_READ_USN_JOURNAL 작업이 변경 저널에 있는 것보다 더 많은 데이터를 요청하는 경우 운영 체제에 수행할 작업을 알려줍니다.
Timeout이 0이고 BytesToWaitFor가 0이 아닌 경우 FSCTL_READ_USN_JOURNAL 작업 호출이 반환할 데이터를 찾지 않고 변경 저널의 끝에 도달하면 FSCTL_READ_USN_JOURNAL 필터링되지 않은 데이터의 BytesToWaitFor 바이트가 변경 저널에 추가될 때까지 대기한 다음 지정된 레코드를 검색합니다.
Timeout이 0이 아니고 BytesToWaitFor가 0이 아닌 경우 FSCTL_READ_USN_JOURNAL 작업 호출이 반환할 데이터를 찾지 않고 변경 저널의 끝에 도달하면 FSCTL_READ_USN_JOURNAL시간 제한 초를 기다린 다음 지정된 레코드를 반환하려고 시도합니다. 제한 시간(초) 후에 FSCTL_READ_USN_JOURNAL 지정된 범위 내에서 사용할 수 있는 모든 레코드를 검색합니다.
두 경우 모두 제한 시간 이후에 변경 저널에 추가된 새 데이터가 처리됩니다. 지정된 집합에서 반환할 레코드가 아직 없으면 제한 시간이 반복됩니다. 이 모드에서는 하나 이상의 레코드가 반환되거나 I/O가 취소될 때까지 FSCTL_READ_USN_JOURNAL 미해결 상태로 유지됩니다.
BytesToWaitFor가 0이면 시간 제한이 무시됩니다. 비동기적으로 열린 핸들의 경우 시간 제한도 무시됩니다.
BytesToWaitFor
변경 저널에 추가된 필터링되지 않은 데이터의 바이트 수입니다. 시간 제한과 함께 이 값을 사용하여 FSCTL_READ_USN_JOURNAL 작업이 변경 저널에 있는 것보다 더 많은 데이터를 요청하는 경우 운영 체제에 수행할 작업을 알려줍니다.
BytesToWaitFor가 0이면 시간 제한이 무시됩니다. 이 경우 변경 저널 파일의 끝에 도달하면 FSCTL_READ_USN_JOURNAL 작업이 항상 성공적으로 반환됩니다. 또한 다음 FSCTL_READ_USN_JOURNAL 작업에 사용해야 하는 USN을 검색합니다. 반환된 다음 USN이 제공된 StartUsn 과 같으면 사용할 수 있는 레코드가 없습니다. 호출 프로세스는 즉시 FSCTL_READ_USN_JOURNAL 다시 사용하면 안 됩니다.
BytesToWaitFor가 0일 때 반환되는 데이터 양을 예측할 수 없으므로 출력 버퍼가 오버플로될 위험이 있습니다. 이러한 위험을 줄이려면 변경 저널의 모든 레코드가 소진될 때까지 반복되는 FSCTL_READ_USN_JOURNAL 작업에서 0이 아닌 BytesToWaitFor 값을 지정합니다. 그런 다음, 0을 지정하여 새 레코드를 대기합니다.
또는 FSCTL_READ_USN_JOURNAL 작업 호출에서 DeviceIoControl의 lpBytesReturned 매개 변수를 사용하여 사용 가능한 데이터의 양을 확인하고 출력 버퍼를 재할당하고(새 레코드를 위한 여유 공간이 있음) DeviceIoControl을 다시 호출합니다.
UsnJournalID
볼륨에 대한 현재 저널의 instance 식별자입니다.
변경 저널을 중지하고 다시 시작하거나 삭제하고 다시 만든 경우 NTFS 파일 시스템은 변경 저널에 이벤트 배치를 놓칠 수 있습니다. 이러한 이벤트 중 하나가 발생하는 경우 NTFS 파일 시스템은 저널에 새 식별자를 제공합니다. 저널 식별자가 현재 저널 식별자에 동의하지 않으면 DeviceIoControl 호출이 실패하고 적절한 오류 코드를 반환합니다. 새 저널 식별자를 검색하려면 FSCTL_QUERY_USN_JOURNAL 작업을 사용하여 DeviceIoControl을 호출합니다.
MinMajorVersion
MaxMajorVersion
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 머리글 | winioctl.h(Windows.h 포함) |