Share via


USN_RECORD_V2 구조체(winioctl.h)

USN(업데이트 시퀀스 번호) 변경 저널 버전 2.0 레코드에 대한 정보를 포함합니다. 애플리케이션은 2.0 이전의 변경 저널 버전을 사용하려고 시도해서는 안 됩니다. Windows 8 및 Windows Server 2012 전에 이 구조체의 이름은 USN_RECORD. 이 이름을 사용하여 이전 SDK 및 컴파일러로 컴파일합니다.

구문

typedef struct {
  DWORD         RecordLength;
  WORD          MajorVersion;
  WORD          MinorVersion;
  DWORDLONG     FileReferenceNumber;
  DWORDLONG     ParentFileReferenceNumber;
  USN           Usn;
  LARGE_INTEGER TimeStamp;
  DWORD         Reason;
  DWORD         SourceInfo;
  DWORD         SecurityId;
  DWORD         FileAttributes;
  WORD          FileNameLength;
  WORD          FileNameOffset;
  WCHAR         FileName[1];
} USN_RECORD_V2, *PUSN_RECORD_V2;

멤버

RecordLength

레코드의 총 길이(바이트)입니다.

USN_RECORD_V2 변수 크기이므로 출력 버퍼에서 다음 레코드의 주소를 계산할 때 RecordLength 멤버를 사용해야 합니다(예: USN_RECORD_V2 사용하는 DeviceIoControl 함수에 대한 작업에서 반환되는 버퍼).

변경 저널 레코드의 바이트 크기는 최대 USN_RECORD_V2 구조체의 크기이며 MaximumComponentLength 문자에서 1을 뺀 값(구조체에 선언된 문자의 경우)은 와이드 문자의 크기입니다. MaximumComponentLength 값은 를 호출하여 확인할 수 있습니다.
GetVolumeInformation 함수입니다. C에서는 다음 코드 예제를 사용하여 레코드 크기를 확인할 수 있습니다.

C++
  MaximumChangeJournalRecordSize = 
      ( MaximumComponentLength * sizeof(WCHAR) 
        + sizeof(USN_RECORD)   + sizeof(WCHAR) );
변경 저널 소프트웨어의 버전 변경에서 호환성을 유지하려면 런타임 계산을 사용하여 USN_RECORD_V2 구조의 크기를 결정합니다. 버전 변경 내용 간 호환성에 대한 자세한 내용은 이 항목의 설명 섹션을 참조하세요.

MajorVersion

이 레코드에 대한 변경 저널 소프트웨어의 주 버전 번호입니다.

예를 들어 변경 저널 소프트웨어가 버전 2.0인 경우 주 버전 번호는 2입니다.

의미
2
구조체는 USN_RECORD_V2 구조체이며 나머지 구조체는 해당 레이아웃을 사용하여 구문 분석해야 합니다.
3
구조체는 USN_RECORD_V3 구조체이며 나머지 구조체는 해당 레이아웃을 사용하여 구문 분석해야 합니다.
4
구조체는 [USN_RECORD_V4 구조체](ns-winioctl-usn_record_v4.md)이며 나머지 구조체는 해당 레이아웃을 사용하여 구문 분석해야 합니다.

MinorVersion

이 레코드에 대한 변경 저널 소프트웨어의 부 버전 번호입니다. 예를 들어 변경 저널 소프트웨어가 버전 2.0인 경우 부 버전 번호는 0입니다.

FileReferenceNumber

이 레코드가 변경되는 파일 또는 디렉터리의 서수입니다.

저널 레코드를 파일과 연결하는 임의로 할당된 값입니다.

ParentFileReferenceNumber

이 레코드와 연결된 파일 또는 디렉터리가 있는 디렉터리의 서수입니다.

저널 레코드를 부모 디렉터리에 연결하는 임의로 할당된 값입니다.

Usn

이 레코드의 USN입니다.

TimeStamp

이 레코드의 표준 UTC 타임스탬프를 64비트 형식으로 표시합니다.

Reason

파일 또는 디렉터리가 열린 이후 이 파일 또는 디렉터리 저널 레코드에 누적된 변경 이유를 식별하는 플래그입니다.

파일 또는 디렉터리가 닫히면 USN_REASON_CLOSE 플래그 집합을 사용하여 최종 USN 레코드가 생성됩니다. 다음 변경(예: 다음 열린 작업 또는 삭제 후)은 새 이유 플래그 집합을 사용하여 새 레코드를 시작합니다.

이름 바꾸기 또는 이동 작업은 항목의 이전 부모 디렉터리를 기록하는 레코드와 새 부모를 기록하는 두 개의 USN 레코드를 생성합니다.

다음 표에서는 가능한 플래그를 식별합니다.

참고 사용하지 않는 비트는 예약되어 있습니다.
 
의미
USN_REASON_BASIC_INFO_CHANGE
0x00008000
사용자가 하나 이상의 파일 또는 디렉터리 특성(예: 읽기 전용, 숨겨진, 시스템, 보관 또는 스파스 특성) 또는 하나 이상의 타임스탬프를 변경했습니다.
USN_REASON_CLOSE
0x80000000
파일 또는 디렉터리가 닫힙니다.
USN_REASON_COMPRESSION_CHANGE
0x00020000
파일 또는 디렉터리의 압축 상태가 또는 에서 압축됨으로 변경됩니다.
USN_REASON_DATA_EXTEND
0x00000002
파일 또는 디렉터리가 확장됩니다(에 추가됨).
USN_REASON_DATA_OVERWRITE
0x00000001
파일 또는 디렉터리의 데이터를 덮어씁니다.
USN_REASON_DATA_TRUNCATION
0x00000004
파일 또는 디렉터리가 잘립니다.
USN_REASON_EA_CHANGE
0x00000400
사용자가 파일 또는 디렉터리의 확장 특성을 변경했습니다.

이러한 NTFS 파일 시스템 특성은 Windows 기반 애플리케이션에서 액세스할 수 없습니다.

USN_REASON_ENCRYPTION_CHANGE
0x00040000
파일 또는 디렉터리가 암호화되거나 암호 해독됩니다.
USN_REASON_FILE_CREATE
0x00000100
파일 또는 디렉터리가 처음으로 만들어집니다.
USN_REASON_FILE_DELETE
0x00000200
파일 또는 디렉터리가 삭제됩니다.
USN_REASON_HARD_LINK_CHANGE
0x00010000
NTFS 파일 시스템 하드 링크가 파일 또는 디렉터리에 추가되거나 제거됩니다.

POSIX 하드 링크와 유사한 NTFS 파일 시스템 하드 링크는 동일한 파일 또는 디렉터리를 표시하는 여러 디렉터리 항목 중 하나입니다.

USN_REASON_INDEXABLE_CHANGE
0x00004000
사용자가 FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 특성을 변경합니다.

즉, 사용자는 콘텐츠가 인덱싱될 수 있는 파일 또는 디렉터리를 콘텐츠 인덱싱할 수 없는 디렉터리로 변경하거나 그 반대로 변경합니다. 콘텐츠 인덱싱을 사용하면 선택한 콘텐츠의 데이터베이스를 빌드하여 데이터를 빠르게 검색할 수 있습니다.

USN_REASON_INTEGRITY_CHANGE
0x00800000
사용자가 지정된 스트림에 대한 FILE_ATTRIBUTE_INTEGRITY_STREAM 특성의 상태를 변경했습니다.

ReFS 파일 시스템에서 무결성 스트림은 해당 스트림에 대한 모든 데이터의 체크섬을 유지 관리하므로 읽기 또는 쓰기 작업 중에 파일 내용의 유효성을 검사할 수 있습니다.

USN_REASON_NAMED_DATA_EXTEND
0x00000020
파일에 대한 하나 이상의 명명된 데이터 스트림이 확장됩니다(에 추가됨).
USN_REASON_NAMED_DATA_OVERWRITE
0x00000010
파일에 대한 하나 이상의 명명된 데이터 스트림의 데이터를 덮어씁니다.
USN_REASON_NAMED_DATA_TRUNCATION
0x00000040
파일에 대한 하나 이상의 명명된 데이터 스트림이 잘립니다.
USN_REASON_OBJECT_ID_CHANGE
0x00080000
파일 또는 디렉터리의 개체 식별자가 변경됩니다.
USN_REASON_RENAME_NEW_NAME
0x00002000
파일 또는 디렉터리의 이름이 바뀌고 USN_RECORD_V2 구조의 파일 이름이 새 이름입니다.
USN_REASON_RENAME_OLD_NAME
0x00001000
파일 또는 디렉터리의 이름이 바뀌고 USN_RECORD_V2 구조의 파일 이름이 이전 이름입니다.
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
파일 또는 디렉터리에 포함된 재분석 지점이 변경되거나 파일 또는 디렉터리에서 재분석 지점이 추가되거나 삭제됩니다.
USN_REASON_SECURITY_CHANGE
0x00000800
파일 또는 디렉터리에 대한 액세스 권한에서 변경됩니다.
USN_REASON_STREAM_CHANGE
0x00200000
명명된 스트림이 파일에 추가되거나 파일에서 제거되거나 명명된 스트림의 이름이 바뀝니다.
USN_REASON_TRANSACTED_CHANGE
0x00400000
지정된 스트림은 TxF 트랜잭션을 통해 수정됩니다.

SourceInfo

DeviceIoControl 작업의 FSCTL_MARK_HANDLE 설정되는 변경 원본에 대한 추가 정보입니다.

스레드가 새 USN 레코드를 작성할 때 스레드가 해당 플래그를 설정하는 경우에만 이전 레코드의 원본 정보 플래그가 계속 존재합니다. 따라서 원본 정보 구조를 사용하면 애플리케이션이 알려진 원본(예: 바이러스 백신 필터)에 의해서만 설정된 USN 레코드를 필터링할 수 있습니다.

다음 두 값 중 하나를 설정할 수 있습니다.

의미
USN_SOURCE_AUXILIARY_DATA
0x00000002
작업은 파일 또는 디렉터리에 프라이빗 데이터 스트림을 추가합니다.

예를 들어 체크섬 정보를 추가하는 바이러스 탐지기가 있을 수 있습니다. 바이러스 탐지기가 항목을 수정하면 시스템에서 USN 레코드를 생성합니다. USN_SOURCE_AUXILIARY_DATA 수정으로 인해 애플리케이션 데이터가 변경되지 않았음을 나타냅니다.

USN_SOURCE_DATA_MANAGEMENT
0x00000001
이 작업은 운영 체제에서 수행한 파일 또는 디렉터리의 변경 내용에 대한 정보를 제공합니다.

일반적인 용도는 원격 스토리지 시스템이 데이터를 외부에서 로컬 스토리지로 이동하는 경우입니다. 원격 스토리지는 계층적 스토리지 관리 소프트웨어입니다. 이러한 이동은 일반적으로 최소한 USN 레코드에 USN_REASON_DATA_OVERWRITE 플래그를 추가합니다. 그러나 데이터는 사용자의 관점에서 변경되지 않았습니다. SourceInfo 멤버의 USN_SOURCE_DATA_MANAGEMENT 기록 작업을 수행하지만 데이터가 변경되지 않은 것을 확인할 수 있습니다.

USN_SOURCE_REPLICATION_MANAGEMENT
0x00000004
작업은 복제본(replica) 집합의 다른 멤버에 있는 동일한 파일의 내용과 일치하도록 파일을 수정합니다.
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT
0x00000008
작업은 클라우드에 있는 동일한 파일의 내용과 일치하도록 클라이언트 시스템의 파일을 수정하는 것입니다.

SecurityId

이 레코드와 연결된 파일 또는 디렉터리에 할당된 고유 보안 식별자입니다.

FileAttributes

GetFileAttributes 함수에서 반환한 이 레코드와 연결된 파일 또는 디렉터리의 특성입니다. 파일 또는 디렉터리에 연결된 스트림의 특성은 제외됩니다.

FileNameLength

이 레코드와 연결된 파일 또는 디렉터리의 이름 길이(바이트)입니다. FileName 멤버에는 이 이름이 포함됩니다. 파일 이름에서 파일 이름을 구분하려면 후행 '\0'에 의존하지 않고 이 멤버를 사용하여 파일 이름 길이를 결정합니다.

FileNameOffset

구조체의 시작 부분에서 FileName 멤버의 오프셋입니다.

FileName[1]

이 레코드와 연결된 파일 또는 디렉터리의 이름(유니코드 형식)입니다. 이 파일 또는 디렉터리 이름은 가변 길이입니다.

FileName을 사용하는 경우 후행 '\0' 구분 기호가 포함된 파일 이름을 계산하지 않고 대신 FileNameLength를 사용하여 파일 이름의 길이를 결정합니다.

FileName을 사용하여 컴파일 시간 포인터 산술 연산을 수행하지 마세요. 대신 FileNameOffset 멤버의 값을 사용하여 런타임에 필요한 계산을 합니다. 이렇게 하면 코드가 향후 버전의 USN_RECORD_V2 호환되도록 할 수 있습니다.

설명

USN_RECORD_V2 사용하는 DeviceIoControl 작업에서 반환된 출력 버퍼에서 모든 레코드는 버퍼 시작부터 64비트 경계에 정렬됩니다.

변경 저널 클라이언트에서 상향 호환성을 위한 경로를 제공하기 위해 Microsoft는 USN_RECORD_V2 구조에서 변경 저널 소프트웨어의 주 버전 및 부 버전 번호를 제공합니다. 코드는 이러한 값을 검사하고, 변경 저널 소프트웨어와의 자체 호환성을 검색하고, 필요한 경우 비호환성을 정상적으로 처리해야 합니다.

부 버전 번호가 변경되면 기존 USN_RECORD_V2 구조체 멤버가 여전히 유효하지만 가변 길이 문자열인 마지막 멤버와 마지막 멤버 사이에 새 멤버가 추가되었을 수 있음을 나타냅니다.

이러한 변경을 정상적으로 처리하기 위해 코드는 마지막 멤버의 위치에 의존하는 컴파일 시간 포인터 산술 연산을 수행해서는 안 됩니다. 예를 들어 C 코드를 sizeof(USN_RECORD) 신뢰할 수 없게 만듭니다. 대신 RecordLength 멤버를 사용하여 런타임 계산을 사용합니다.

변경 저널 소프트웨어의 주 버전 수가 증가하면 USN_RECORD_V2 구조가 크게 변경되었을 수 있으며 현재 정의가 신뢰할 수 없음을 나타냅니다. 코드가 변경 저널 소프트웨어의 주 버전 번호 변경을 감지하는 경우 변경 저널과 함께 작동하지 않아야 합니다.

자세한 내용은 변경 저널 만들기, 수정 및 삭제를 참조하세요.

요구 사항

요구 사항
지원되는 최소 클라이언트 Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버 Windows Server 2003 [데스크톱 앱만 해당]
머리글 winioctl.h(Windows.h 포함)

추가 정보

FSCTL_MARK_HANDLE

FSCTL_READ_USN_JOURNAL

GetFileAttributes

GetVolumeInformation

READ_USN_JOURNAL_DATA

USN_RECORD_V3

USN_RECORD_V4 구조체