Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

MARK_HANDLE_INFO structure

Contains information that is used to mark a specified file or directory, and its update sequence number (USN) change journal record with data about changes. It is used by the FSCTL_MARK_HANDLE control code.

Syntax


typedef struct {
#if (_WIN32_WINNT >= 0x0602)
  union {
    DWORD UsnSourceInfo;
    DWORD CopyNumber;
  };
#else 
  DWORD  UsnSourceInfo;
#endif 
  HANDLE VolumeHandle;
  DWORD  HandleInfo;
} MARK_HANDLE_INFO, *PMARK_HANDLE_INFO;

Members

UsnSourceInfo

The type of changes being made.

The operation does not modify the file or directory externally from the point of view of the application that created it.

When a thread writes a new USN record, the source information flags in the prior record continues to be present only if the thread also sets those flags. Therefore, the source information structure allows applications to filter out USN records that are set only by a known source, such as an antivirus filter.

The following values are defined.

ValueMeaning
USN_SOURCE_DATA_MANAGEMENT
0x00000001

The operation provides information about a change to the file or directory made by the operating system.

A typical use is when Remote Storage moves data from external to local storage. Remote Storage is the hierarchical storage management software. Such a move usually at a minimum adds the USN_REASON_DATA_OVERWRITE flag to a USN record. However, the data has not changed from the user point of view. By noting USN_SOURCE_DATA_MANAGEMENT in the SourceInfo member of the USN_RECORD structure that holds the record, you can determine that although a write operation is performed on the item, data has not changed.

USN_SOURCE_AUXILIARY_DATA
0x00000002

The operation adds a private data stream to a file or directory.

An example might be a virus detector adding checksum information. As the virus detector modifies the item, the system generates USN records. USN_SOURCE_AUXILIARY_DATA indicates that the modifications did not change the application data.

USN_SOURCE_REPLICATION_MANAGEMENT
0x00000004

The operation creates or updates the contents of a replicated file.

For example, the file replication service sets this flag when it creates or updates a file in a replicated directory.

 

CopyNumber

The zero-based copy number to use for subsequent reads. This is for use on on Storage Spaces and Streams on NTFS and ReFS and non-integrity streams on ReFS (streams with integrity on ReFS handle this automatically.)

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP:  This member is not supported before Windows 8 and Windows Server 2012.

UsnSourceInfo
VolumeHandle

The volume handle to the volume where the file or directory resides. For more information on obtaining a volume handle, see the Remarks section.

This handle is required to check the privileges for this operation.

The caller must have the SE_MANAGE_VOLUME_NAME privilege. For more information, see Privileges.

HandleInfo

The flag that specifies additional information about the file or directory identified by the handle value in the VolumeHandle member.

ValueMeaning
MARK_HANDLE_PROTECT_CLUSTERS
0x00000001

The file is marked as unable to be defragmented until the handle is closed.

MARK_HANDLE_TXF_SYSTEM_LOG
0x00000004

The file is marked as unable to be defragmented until the handle is closed.

Windows Server 2003:  This flag is not supported until Windows Server 2003 with SP1.

Windows XP:  This flag is not supported.

MARK_HANDLE_NOT_TXF_SYSTEM_LOG
0x00000008

The file is marked as unable to be defragmented until the handle is closed.

Windows Server 2003:  This flag is not supported until Windows Server 2003 with SP1.

Windows XP:  This flag is not supported.

MARK_HANDLE_REALTIME
0x00000020

The file is marked for real-time read behavior regardless of the actual file type. Files marked with this flag must be opened for unbuffered I/O.

Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP:  This flag is not supported.

MARK_HANDLE_NOT_REALTIME
0x00000040

The file previously marked for real-time read behavior using the MARK_HANDLE_REALTIME flag can be unmarked using this flag, removing the real-time behavior. Files marked with this flag must be opened for unbuffered I/O.

Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP:  This flag is not supported.

MARK_HANDLE_READ_COPY
0x00000080

Indicates the copy number specified in the CopyNumber member should be used for reads. Files marked with this flag must be opened for unbuffered I/O.

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP:  This flag is not supported until Windows 8 and Windows Server 2012.

MARK_HANDLE_NOT_READ_COPY
0x00000100

The file previously marked for read-copy behavior using the MARK_HANDLE_READ_COPY flag can be unmarked using this flag, removing the read-copy behavior. Files marked with this flag must be opened for unbuffered I/O.

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP:  This flag is not supported until Windows 8 and Windows Server 2012.

 

Remarks

To retrieve a handle to a volume, call CreateFile with the lpFileName parameter set to a string in the following form:

"\\.\X:"

In the preceding string, X is the letter identifying the drive on which the volume appears.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

WinIoCtl.h (include Windows.h)

See also

FSCTL_MARK_HANDLE
USN_RECORD

 

 

Community Additions

Show:
© 2014 Microsoft