able/windows-nt
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
windows-nt/Source/XPSP1/NT/base/published/ntfsexp.w

1630 lines
43 KiB
OpenEdge ABL
Raw Normal View History

Add source files
2020-09-26 03:20:57 -05:00
/*++
Copyright (c) Microsoft Corporation. All rights reserved.
Module Name:
NtfsExp.h
Abstract:
This module defines the exports from NtOfs.SYS for use exclusively by
Transactions and Encryption.
*********************************
*No other clients are supported.*
*********************************
Author:
Mark Zbikowski [MarkZ] 7-Dec-1995
Jeff Havens [JHavens]
Brian Andrew [BrianAn]
Gary Kimura [GaryKi]
Tom Miller [TomM]
Revision History:
--*/
#ifndef _NTFS_
//
// The MFT Segment Reference is an address in the MFT tagged with
// a circularly reused sequence number set at the time that the MFT
// Segment Reference was valid. Note that this format limits the
// size of the Master File Table to 2**48 segments. So, for
// example, with a 1KB segment size the maximum size of the master
// file would be 2**58 bytes, or 2**28 gigabytes.
//
typedef struct _FILE_REFERENCE {
//
// First a 48 bit segment number.
//
ULONG SegmentNumberLowPart; // offset = 0x000
USHORT SegmentNumberHighPart; // offset = 0x004
//
// Now a 16 bit nonzero sequence number. A value of 0 is
// reserved to allow the possibility of a routine accepting
// 0 as a sign that the sequence number check should be
// repressed.
//
USHORT SequenceNumber; // offset = 0x006
} FILE_REFERENCE, *PFILE_REFERENCE; // sizeof = 0x008
#endif
//
// Big picture view of the interaction between extensions and NtOfs:
//
// NtOfs exports a number of interfaces that give abstract access to
// on-disk structures and attempt to hide, as much as possible, the
// implementation details.
//
// V/Q/X are implemented as DLL's that link to NtOfs.Sys. NtOfs can load
// and function in absence of these DLL's.
//
// All communication between user-mode code and V/Q/X occurs via the
// Nt Io API which is routed through NtOfs. Client code will open either
// an NtOfs Volume, Directory, or File and will issue NtIo calls to the
// resultant handle.
//
// NtOfs will create an IrpContext, decode the file object appropriately,
// and call out to entry points in V/Q/X that are registered at load-time.
//
// V/Q/X will perform whatever actions are necessary utilizing NtOfs exports
// and then return from the original call from NtOfs an NTSTATUS code. NtOfs
// will perform the appropriate CompleteIrp calls, posting for STATUS_PENDING,
// etc.
//
// No exceptions can be raised across the NtOfs export or NtOfs import
// interfaces. All user-buffer access and validation will occur in the
// code that uses it. Since user buffers may disappear at any time, any
// client of these buffers must wrap access to the buffers in an exception
// clause.
//
// V/Q/X may perform activities in threads separate from the original
// requestor. For these cases, NtOfs will provide a means where calls separate
// from a user-mode request can be accepted. Typically, this means "cloning"
// an IrpContext.
//
//
// Opaque handle definitions.
//
//
// ISSUE: Most NtOfs internal routines rely on having an IrpContext passed in
// along with FCB and SCB pointers. Rather than exposing FCB and IrpContext
// as separate contexts, should we wrap these up into a separate structure and
// pass it along?
//
typedef struct _FCB *OBJECT_HANDLE;
typedef struct _SCB *ATTRIBUTE_HANDLE;
typedef struct _SCB *INDEX_HANDLE;
typedef struct _READ_CONTEXT *PREAD_CONTEXT;
typedef ULONG SECURITY_ID;
typedef struct _CI_CALL_BACK CI_CALL_BACK, *PCI_CALL_BACK;
typedef struct _VIEW_CALL_BACK VIEW_CALL_BACK, *PVIEW_CALL_BACK;
typedef struct _IRP_CONTEXT *PIRP_CONTEXT;
//
// Map Handle. This structure defines a byte range of the file which is mapped
// or pinned, and stores the Bcb returned from the Cache Manager.
//
typedef struct _MAP_HANDLE {
//
// Range being mapped or pinned
//
LONGLONG FileOffset;
ULONG Length;
//
// Virtual address corresponding to FileOffset
//
PVOID Buffer;
//
// Bcb pointer returned from Cache Manager
//
PVOID Bcb;
} MAP_HANDLE, *PMAP_HANDLE;
//
// Quick Index Hint. This is stream offset information returned by
// NtOfsFindRecord, and taken as input to NtOfsUpdateRecord, to allow
// quick updates to index records in the event that they have not
// moved. This structure must always have the same size and alignment
// as QUICK_INDEX in ntfsstru.h.
//
typedef struct _QUICK_INDEX_HINT {
LONGLONG HintData[3];
} QUICK_INDEX_HINT, *PQUICK_INDEX_HINT;
//
// Index structures
//
typedef struct {
ULONG KeyLength;
PVOID Key;
} INDEX_KEY, *PINDEX_KEY;
typedef struct {
ULONG DataLength;
PVOID Data;
} INDEX_DATA, *PINDEX_DATA;
typedef struct {
INDEX_KEY KeyPart;
INDEX_DATA DataPart;
} INDEX_ROW, *PINDEX_ROW;
//
// COLLATION_FUNCTION returns LessThan if Key1 precedes Key2
// EqualTo if Key1 is identical to Key2
// GreaterThan if Key1 follows Key2
//
typedef FSRTL_COMPARISON_RESULT (*PCOLLATION_FUNCTION) (
IN PINDEX_KEY Key1,
IN PINDEX_KEY Key2,
IN PVOID CollationData
);
typedef struct _UPCASE_TABLE_AND_KEY {
//
// Pointer to a table of upcased unicode characters indexed by character to
// be upcased.
//
PWCH UpcaseTable;
//
// Size of UpcaseTable in unicode characters
//
ULONG UpcaseTableSize;
//
// Optional addtional pointer.
//
INDEX_KEY Key;
} UPCASE_TABLE_AND_KEY, *PUPCASE_TABLE_AND_KEY;
//
// Wait for new length block used to synchronize a thread with FileSize
// exceeding the specified Length.
//
typedef struct _WAIT_FOR_NEW_LENGTH {
//
// Link words for multiple waiters on the Scb.
//
LIST_ENTRY WaitList;
//
// Set event when FileSize exceeds this length.
//
LONGLONG Length;
//
// Event to set when new length achieved.
//
KEVENT Event;
//
// Irp to complete when new length achieved. (If Irp present, Event is
// ignored.)
//
PIRP Irp;
//
// Stream we are waiting on.
//
ATTRIBUTE_HANDLE Stream;
//
// Status code for operation that caused the new length to be satisfied.
// It may be STATUS_CANCELLED, STATUS_TIMEOUT or STATUS_SUCCESS
// or a request specific status.
//
NTSTATUS Status;
//
// Flags.
//
ULONG Flags;
} WAIT_FOR_NEW_LENGTH, *PWAIT_FOR_NEW_LENGTH;
#define NTFS_WAIT_FLAG_ASYNC (0x00000001)
//
// Standard collation functions for simple indices
//
FSRTL_COMPARISON_RESULT
NtOfsCollateUlong ( // Both must be single Ulong
IN PINDEX_KEY Key1,
IN PINDEX_KEY Key2,
IN PVOID CollationData // Don't care, may be NULL
);
FSRTL_COMPARISON_RESULT
NtOfsCollateUlongs ( // Lengths do not have to be equal
IN PINDEX_KEY Key1,
IN PINDEX_KEY Key2,
IN PVOID CollationData // Don't care, may be NULL
);
FSRTL_COMPARISON_RESULT
NtOfsCollateSid (
IN PINDEX_KEY Key1,
IN PINDEX_KEY Key2,
IN PVOID CollationData // Don't care, may be NULL
);
FSRTL_COMPARISON_RESULT
NtOfsCollateUnicode (
IN PINDEX_KEY Key1,
IN PINDEX_KEY Key2,
IN PVOID CollationData // PUPCASE_TABLE_AND_KEY (with no key)
);
//
// Standard match functions for simple indices
//
NTSTATUS
NtOfsMatchAll (
IN PINDEX_ROW IndexRow,
IN OUT PVOID MatchData // Don't care, may be NULL
);
NTSTATUS
NtOfsMatchUlongExact (
IN PINDEX_ROW IndexRow, // Both must be single Ulong
IN OUT PVOID MatchData // PINDEX_KEY describing Ulong
);
NTSTATUS
NtOfsMatchUlongsExact ( // Lengths do not have to be equal
IN PINDEX_ROW IndexRow,
IN OUT PVOID MatchData // PINDEX_KEY describing Ulongs
);
NTSTATUS
NtOfsMatchUnicodeExpression (
IN PINDEX_ROW IndexRow,
IN OUT PVOID MatchData // PUPCASE_TABLE_AND_KEY with Uni expression (must have wildcards)
);
NTSTATUS
NtOfsMatchUnicodeString (
IN PINDEX_ROW IndexRow,
IN OUT PVOID MatchData // PUPCASE_TABLE_AND_KEY with Uni string (no wildcards)
);
//
// MATCH_FUNCTION returns
// STATUS_SUCCESS if the IndexRow matches
// STATUS_NO_MATCH if the IndexRow does not match, but the enumeration should
// continue
// STATUS_NO_MORE_MATCHES if the IndexRow does not match, and the enumeration
// should terminate
//
typedef NTSTATUS (*PMATCH_FUNCTION) (IN PINDEX_ROW IndexRow, IN OUT PVOID MatchData);
//
// CREATE_OPTIONS - common flags governing creation/opening of objects
//
typedef enum _CREATE_OPTIONS
{
CREATE_NEW = 0,
CREATE_OR_OPEN = 1,
OPEN_EXISTING = 2
} CREATE_OPTIONS;
//
// EXCLUSION - Form of exclusion desired when opening an object
//
typedef enum _EXCLUSION
{
SHARED = 0,
EXCLUSIVE
} EXCLUSION;
//
// Additional Dos Attribute indicating Content Index status of an object.
// If this is set on a document, it suppresses indexing. It is inherited
// from a parent directory at create time. This is stored in the
// DUPLICATED_INFORMATION structure.
//
#define SUPPRESS_CONTENT_INDEX (0x20000000)
//
// Define the size of the index buffer/bucket for view indexes, in bytes.
//
#define NTOFS_VIEW_INDEX_BUFFER_SIZE (0x1000)
//
// Exported constants.
//
//
// NtOfsContentIndexSystemFile is the repository for all CI related data on the
// disk.
extern FILE_REFERENCE NtOfsContentIndexSystemFile;
#if defined(_NTFSPROC_)
#define NTFSAPI
#else
#define NTFSAPI //DECLSPEC_IMPORT
#endif
////////////////////////////////////////////////////////////////////////////////
//
// Index API - These encapsulate the NtOfs BTree mechanisms.
//
//
// NtOfsCreateIndex creates or opens a named index attribute in an object. The
// ObjectHandle has been acquired exclusive and the returned handle is not
// acquired. The collation data is interpreted only by the CollationFunction.
//
// IndexHandles retain a "seek" position where enumerations (NtOfsReadRecords)
// may continue. This seek position may be updated by the routines as described
// below.
//
// If DeleteCollationData is 1, ExFreePool will be called on CollationData, either
// immediately if the index already exists, or when the index is deleted some time
// after the final close. If NtOfsCreateIndex returns an error, then CollationData
// must be deleted by the caller. If specified as 0, then ColloationData will not
// be deleted.
//
NTFSAPI
NTSTATUS
NtOfsCreateIndex (
IN PIRP_CONTEXT IrpContext,
IN OBJECT_HANDLE ObjectHandle,
IN UNICODE_STRING Name,
IN CREATE_OPTIONS CreateOptions,
IN ULONG DeleteCollationData,
IN ULONG CollationRule,
IN PCOLLATION_FUNCTION CollationFunction,
IN PVOID CollationData OPTIONAL,
OUT INDEX_HANDLE *IndexHandle
);
//
// NtOfsFindRecord finds a single record in an index stream for read-only access
// or in preparation for calling NtOfsUpdateRecord.
//
NTFSAPI
NTSTATUS
NtOfsFindRecord (
IN PIRP_CONTEXT IrpContext,
IN INDEX_HANDLE IndexHandle,
IN PINDEX_KEY IndexKey,
OUT PINDEX_ROW IndexRow,
OUT PMAP_HANDLE MapHandle,
IN OUT PQUICK_INDEX_HINT QuickIndexHint OPTIONAL
);
//
// NtOfsFindRecord finds a single record in an index stream for read-only access
// or in preparation for calling NtOfsUpdateRecord.
//
NTFSAPI
NTSTATUS
NtOfsFindLastRecord (
IN PIRP_CONTEXT IrpContext,
IN INDEX_HANDLE IndexHandle,
IN PINDEX_KEY MaxIndexKey,
OUT PINDEX_ROW IndexRow,
OUT PMAP_HANDLE MapHandle
);
//
// NtOfsAddRecords performs bulk, logged inserts into an index. The index will
// be acquired exclusive for this call. Each record added must have a unique
// (with regards to the collation function) key. No maps are currently
// outstanding on this index. If SequentialInsertMode is nonzero, this is a hint
// to the index package to keep all BTree buffers as full as possible, by splitting
// as close to the end of the buffer as possible. If specified as zero, random
// inserts are assumed, and buffers are always split in the middle for better balance.
//
// This call may update the IndexHandle seek position
//
NTFSAPI
VOID
NtOfsAddRecords (
IN PIRP_CONTEXT IrpContext,
IN INDEX_HANDLE IndexHandle,
IN ULONG Count,
IN PINDEX_ROW IndexRow,
IN ULONG SequentialInsertMode
);
//
// NtOfsDeleteRecords performs bulk, logged deletion from an index. The index
// will be acquired exclusive for this call. No maps are currently outstanding
// on this index.
//
// This call may update the IndexHandle seek position
//
NTFSAPI
VOID
NtOfsDeleteRecords (
IN PIRP_CONTEXT IrpContext,
IN INDEX_HANDLE IndexHandle,
IN ULONG Count,
IN PINDEX_KEY IndexKey
);
//
// NtOfsReadRecords applies a match function to a block of contiguous records in
// the BTree starting either at a given IndexKey or beginning where it last left
// off.
//
// IndexKey is an optional point at which to begin the enumeration. The
// seek position of IndexHandle is set to return the next logical record
// on the next NtOfsReadRecords call.
//
// NtOfsReadRecords will seek to the appropriate point in the BTree (as defined
// by the IndexKey or saved position and the CollateFunction) and begin calling
// MatchFunction for each record. It continues doing this while MatchFunction
// returns STATUS_SUCCESS. If MatchFunction returns STATUS_NO_MORE_MATCHES,
// NtOfsReadRecords will cache this result and not call MatchFunction again until
// called with a non-NULL IndexKey.
//
// NtOfsReadRecords returns the last status code returned by MatchFunction.
//
// The IndexHandle does not have to be acquired as it is acquired shared for the
// duration of the call. NtOfsReadRecords may
// return with STATUS_SUCCESS without filling the output buffer (say, every 10
// index pages) to reduce lock contention.
//
// NtOfsReadRecords will read up to Count rows, comprising up to BufferLength
// bytes in total and will fill in the Rows[] array for each row returned.
//
// Note that this call is self-synchronized, such that successive calls to
// the routine are guaranteed to make progress through the index and to return
// items in Collation order, in spite of Add and Delete record calls being
// interspersed with Read records calls.
//
NTFSAPI
NTSTATUS
NtOfsReadRecords (
IN PIRP_CONTEXT IrpContext,
IN INDEX_HANDLE IndexHandle,
IN OUT PREAD_CONTEXT *ReadContext,
IN OPTIONAL PINDEX_KEY IndexKey,
IN PMATCH_FUNCTION MatchFunction,
IN PVOID MatchData,
IN OUT ULONG *Count,
OUT PINDEX_ROW Rows,
IN ULONG BufferLength,
OUT PVOID Buffer
);
NTFSAPI
VOID
NtOfsFreeReadContext (
IN PREAD_CONTEXT ReadContext
);
//
// NtOfsUpdateRecord updates a single record in place. It is guaranteed that the
// length of the data/key portion of the record does not change. The index will
// be acquired exclusive for this call.
//
// This call may update the IndexHandle seek position
//
NTFSAPI
VOID
NtOfsUpdateRecord (
IN PIRP_CONTEXT IrpContext,
IN INDEX_HANDLE IndexHandle,
IN ULONG Count,
IN PINDEX_ROW IndexRow,
IN OUT PQUICK_INDEX_HINT QuickIndexHint OPTIONAL,
IN OUT PMAP_HANDLE MapHandle OPTIONAL
);
//
// NtOfsCloseIndex closes an index handle. The index must not be acquired for this
// call. No outstanding maps are allowed.
//
NTFSAPI
VOID
NtOfsCloseIndex (
IN PIRP_CONTEXT IrpContext,
IN INDEX_HANDLE IndexHandle
);
//
// NtOfsDeleteIndex removes an index attribute from an object. The object will be
// acquired exclusive for this call.
//
NTFSAPI
VOID
NtOfsDeleteIndex (
IN PIRP_CONTEXT IrpContext,
IN OBJECT_HANDLE ObjectHandle,
IN INDEX_HANDLE IndexHandle
);
////////////////////////////////////////////////////////////////////////////////
//
// Map API - These encapsulate the NtOfs/Cache manager interactions
//
//
// NtOfsInitializeMapHandle initializes a map handle so it can be safely
// released at any time.
//
// NTFSAPI
// VOID
// NtOfsInitializeMapHandle (
// IN PMAP_HANDLE Map
// );
//
#define NtOfsInitializeMapHandle( M ) { (M)->Bcb = NULL; }
//
// NtOfsMapAttribute maps a portion of the specified attribute and returns a pointer
// to the memory. The memory mapped may not span a mapping window. Multiple maps
// are allowed through different handles in different threads. The data is not
// preread nor is the memory pinned.
//
#ifndef _NTFSPROC_
NTFSAPI
VOID
NtOfsMapAttribute (
IN PIRP_CONTEXT IrpContext,
IN ATTRIBUTE_HANDLE Attribute,
IN LONGLONG Offset,
IN ULONG Length,
OUT PVOID *Buffer,
OUT PMAP_HANDLE MapHandle
);
#else
#ifdef MAPCOUNT_DBG
#define NtOfsMapAttribute(I,S,O,L,B,M) ( \
CcMapData((S)->FileObject, (PLARGE_INTEGER)&(O), (L), TRUE, &(M)->Bcb, (B)), \
(I)->MapCount++, \
(M)->FileOffset = (O), \
(M)->Length = (L), \
(M)->Buffer = *(PVOID *)(B) \
)
#else
#define NtOfsMapAttribute(I,S,O,L,B,M) ( \
CcMapData((S)->FileObject, (PLARGE_INTEGER)&(O), (L), TRUE, &(M)->Bcb, (B)), \
(M)->FileOffset = (O), \
(M)->Length = (L), \
(M)->Buffer = *(PVOID *)(B) \
)
#endif
#endif
//
// NtOfsPreparePinWrite maps and pins a portion of the specified attribute and
// returns a pointer to the memory. This is equivalent to doing a NtOfsMapAttribute
// followed by NtOfsPinRead and NtOfsDirty but is more efficient.
//
#ifndef _NTFSPROC_
NTFSAPI
VOID
NtOfsPreparePinWrite (
IN PIRP_CONTEXT IrpContext,
IN ATTRIBUTE_HANDLE Attribute,
IN LONGLONG Offset,
IN ULONG Length,
OUT PVOID *Buffer,
OUT PMAP_HANDLE MapHandle
);
#else
#ifdef MAPCOUNT_DBG
#define NtOfsPreparePinWrite(I,S,O,L,B,M) { \
if (((O) + (L)) > (S)->Header.AllocationSize.QuadPart) { \
ExRaiseStatus(STATUS_END_OF_FILE); \
} \
CcPreparePinWrite((S)->FileObject, (PLARGE_INTEGER)&(O), (L), FALSE, TRUE, &(M)->Bcb, (B)); \
(I)->MapCount++; \
(M)->FileOffset = (O); \
(M)->Length = (L); \
(M)->Buffer = (B); \
}
#else
#define NtOfsPreparePinWrite(I,S,O,L,B,M) { \
if (((O) + (L)) > (S)->Header.AllocationSize.QuadPart) { \
ExRaiseStatus(STATUS_END_OF_FILE); \
} \
CcPreparePinWrite((S)->FileObject, (PLARGE_INTEGER)&(O), (L), FALSE, TRUE, &(M)->Bcb, (B)); \
(M)->FileOffset = (O); \
(M)->Length = (L); \
(M)->Buffer = (B); \
}
#endif
#endif
//
// NtOfsPinRead pins a section of a map and read in all pages from the mapped
// attribute. Offset and Length must describe a byte range which is equal to
// or included by the original mapped range.
//
#ifndef _NTFSPROC_
NTFSAPI
VOID
NtOfsPinRead(
IN PIRP_CONTEXT IrpContext,
IN ATTRIBUTE_HANDLE Attribute,
IN LONGLONG Offset,
IN ULONG Length,
OUT PMAP_HANDLE MapHandle
);
#else
#ifdef MAPCOUNT_DBG
#define NtOfsPinRead(I,S,O,L,M) { \
ASSERT((M)->Bcb != NULL); \
ASSERT(((O) >= (M)->FileOffset) && (((O) + (L)) <= ((M)->FileOffset + (M)->Length))); \
CcPinMappedData((S)->FileObject, (PLARGE_INTEGER)&(O), (L), TRUE, &(M)->Bcb); \
(I)->MapCount++; \
(M)->FileOffset = (O); \
(M)->Length = (L); \
}
#else
#define NtOfsPinRead(I,S,O,L,M) { \
ASSERT((M)->Bcb != NULL); \
ASSERT(((O) >= (M)->FileOffset) && (((O) + (L)) <= ((M)->FileOffset + (M)->Length))); \
CcPinMappedData((S)->FileObject, (PLARGE_INTEGER)&(O), (L), TRUE, &(M)->Bcb); \
(M)->FileOffset = (O); \
(M)->Length = (L); \
}
#endif
#endif
//
// NtOfsDirty marks a map as being dirty (eligible for lazy writer access) and
// marks the pages with an optional LSN for coordination with LFS. This call
// is invalid unless the map has been pinned.
//
// NTFSAPI
// NtOfsDirty (
// IN PIRP_CONTEXT IrpContext,
// IN PMAP_HANDLE MapHandle,
// PLSN Lsn OPTIONAL
// );
#define NtOfsDirty(I,M,L) {CcSetDirtyPinnedData((M)->Bcb,(L));}
//
// NtOfsReleaseMap unmaps/unpins a mapped portion of an attribute.
//
#ifndef _NTFSPROC_
NTFSAPI
VOID
NtOfsReleaseMap (
IN PIRP_CONTEXT IrpContext,
IN PMAP_HANDLE MapHandle
);
#else
#ifdef MAPCOUNT_DBG
#define NtOfsReleaseMap(IC,M) { \
if ((M)->Bcb != NULL) { \
CcUnpinData((M)->Bcb); \
(IC)->MapCount--; \
(M)->Bcb = NULL; \
} \
}
#else
#define NtOfsReleaseMap(IC,M) { \
if ((M)->Bcb != NULL) { \
CcUnpinData((M)->Bcb); \
(M)->Bcb = NULL; \
} \
}
#endif
#endif
//
// NtOfsPutData writes data into an attribute in a recoverable fashion. The
// caller must have opened the attribute with LogNonresidentToo.
//
// NtOfsPutData will write the data atomically and update the mapped image,
// subject to the normal lazy commit of the transaction.
//
NTFSAPI
VOID
NtOfsPutData (
IN PIRP_CONTEXT IrpContext,
IN ATTRIBUTE_HANDLE Attribute,
IN LONGLONG Offset,
IN ULONG Length,
IN PVOID Data OPTIONAL
);
////////////////////////////////////////////////////////////////////////////////
//
// Attribute API - These encapsulate access to attributes on files/directories
// and summary catalogs
//
//
// NtOfsCreateAttribute will create or open a data attribute and return a handle
// that will allow mapping operations.
//
// For attributes that wish to have logging behavior, LogNonresidentToo must be
// set to true. See the discussion on NtOfsPutData (in the mapping section
// above).
//
NTFSAPI
NTSTATUS
NtOfsCreateAttribute (
IN PIRP_CONTEXT IrpContext,
IN OBJECT_HANDLE ObjectHandle,
IN UNICODE_STRING Name,
IN CREATE_OPTIONS CreateOptions,
IN ULONG LogNonresidentToo,
OUT ATTRIBUTE_HANDLE *AttributeHandle
);
//
// NtOfsCreateAttributeEx will create or open an attribute and return a handle
// that will allow mapping operations. If a standard data attribute is to be
// used, call NtOfsCreateAttribute instead. This function is here for callers
// who need to use a different attribute type code.
//
// For attributes that wish to have logging behavior, LogNonresidentToo must be
// set to true. See the discussion on NtOfsPutData (in the mapping section
// above).
//
NTFSAPI
NTSTATUS
NtOfsCreateAttributeEx (
IN PIRP_CONTEXT IrpContext,
IN OBJECT_HANDLE ObjectHandle,
IN UNICODE_STRING Name,
IN ULONG AttributeTypeCode,
IN CREATE_OPTIONS CreateOptions,
IN ULONG LogNonresidentToo,
OUT ATTRIBUTE_HANDLE *AttributeHandle
);
//
// Valid AttributeTypeCode values for NtOfsCreateAttributeEx:
//
#define $LOGGED_UTILITY_STREAM (0x100)
//
// NtOfsCloseAttribute releases the attribute. The attribute is not acquired. No
// outstanding maps are active.
//
NTFSAPI
VOID
NtOfsCloseAttribute (
IN PIRP_CONTEXT IrpContext,
IN ATTRIBUTE_HANDLE AttributeHandle
);
//
// NtOfsDeleteAttribute releases all storage associated with the attribute. The
// object will be acquired exclusive. The attribute will be acquired exclusive.
// No outstanding maps are active.
//
NTFSAPI
VOID
NtOfsDeleteAttribute (
IN PIRP_CONTEXT IrpContext,
IN OBJECT_HANDLE ObjectHandle,
IN ATTRIBUTE_HANDLE AttributeHandle
);
//
// NtOfsQueryLength returns the current length of user data within the attribute.
// The attribute may be mapped. The attribute may be acquired.
//
NTFSAPI
LONGLONG
NtOfsQueryLength (
IN ATTRIBUTE_HANDLE AttributeHandle
);
//
// NtOfsSetLength sets the current EOF on the given attribute. The attribute
// may not be mapped to the view containing Length, or any subsequent view.
// The attribute will be acquired exclusive.
//
NTFSAPI
VOID
NtOfsSetLength (
IN PIRP_CONTEXT IrpContext,
IN ATTRIBUTE_HANDLE Attribute,
IN LONGLONG Length
);
//
// NtOfsWaitForNewLength allows the caller to wait for the specified length to
// be exceeded, or optionally timeout, if the specified Irp has not been cancelled.
//
NTFSAPI
NTSTATUS
NtOfsWaitForNewLength (
IN ATTRIBUTE_HANDLE Attribute,
IN LONGLONG Length,
IN ULONG Async,
IN PIRP Irp,
IN PDRIVER_CANCEL CancelRoutine,
IN PLARGE_INTEGER Timeout OPTIONAL
);
//
// This routine may be called any time FileSize has changed to wake any threads
// waiting for a particular FileSize change. Or specify WakeAll to unconditionally
// wake all waiters.
//
VOID
NtOfsPostNewLength (
IN PIRP_CONTEXT IrpContext OPTIONAL,
IN ATTRIBUTE_HANDLE Attribute,
IN BOOLEAN WakeAll
);
//
// NtOfsDecommit releases storage associated with a range of the attribute. It does
// not change the EOF marker nor does it change the logical position of data within
// the attribute. The range of the attribute being released may be mapped or
// pinned.
//
// Reads from decommitted ranges should return zero (although Query will never read
// from these ranges).
//
// Writes to decommitted pages should fail or be nooped (although Query will never
// write to these ranges).
//
// This call will purge, so none of the views overlapping the specified range may
// be mapped.
//
NTFSAPI
VOID
NtOfsDecommit (
IN PIRP_CONTEXT IrpContext,
IN ATTRIBUTE_HANDLE Attribute,
IN LONGLONG Offset,
IN LONGLONG Length
);
//
// NtOfsFlushAttribute flushes all cached data to the disk and returns upon
// completion. If the attribute is LogNonresidentToo, then only the log file
// is flushed. Optionally, the range may be purged as well. If the attribute
// is purged, then there can be no mapped views.
//
NTFSAPI
VOID
NtOfsFlushAttribute (
IN PIRP_CONTEXT IrpContext,
IN ATTRIBUTE_HANDLE Attribute,
IN ULONG Purge
);
//
// NtOfsQueryAttributeSecurityId returns the security ID for the attribute if
// present.
//
NTFSAPI
VOID
NtOfsQueryAttributeSecurityId (
IN PIRP_CONTEXT IrpContext,
IN ATTRIBUTE_HANDLE Attribute,
OUT SECURITY_ID *SecurityId
);
////////////////////////////////////////////////////////////////////////////////
//
// Concurrency control API
//
// As a rule, these routines are not required. All NtOfs routines are
// self-synchronized as atomic actions, or as parts of a top-level action when
// called within a top-level action routine.
//
// ISSUE: In particular, supporting the exclusive access call is an implementation
// problem for Ntfs. Wrapping top-level actions is the best way to preserve
// exclusive access across calls.
//
VOID
NtOfsAcquireObjectShared (
HANDLE ObjectHandle
);
// VOID
// NtOfsAcquireObjectExclusive (
// HANDLE ObjectHandle
// );
VOID
NtOfsReleaseObject (
HANDLE ObjectHandle
);
// Debugging routines
BOOLEAN
NtOfsIsObjectAcquiredExclusive (
HANDLE ObjectHandle
);
BOOLEAN
NtOfsIsObjectAcquiredShared (
HANDLE ObjectHandle
);
////////////////////////////////////////////////////////////////////////////////
//
// File/Directory/Etc API
//
//
// NtOfsOpenByFileReference opens an object given a file reference. The file is
// assumed to exist; this call cannot be used to create a file. The returned
// handle is acquired according to the input exclusion.
//
NTFSAPI
NTSTATUS
NtOfsOpenByFileReference (
IN PIRP_CONTEXT IrpContext,
IN FILE_REFERENCE FileReference,
IN EXCLUSION Exclusion,
OUT OBJECT_HANDLE *ObjectHandle
);
//
// NtOfsCreateRelativeObject opens or creates an object relative to a specified
// parent object. The parent will be acquired exclusive. The child is opened
// acquired according to the input exclusion.
//
// ISSUE: When creating an object, is the transaction committed before this
// call returns?
//
NTFSAPI
NTSTATUS
NtOfsCreateRelativeObject (
IN PIRP_CONTEXT IrpContext,
IN OBJECT_HANDLE ParentObjectHandle,
IN UNICODE_STRING Name,
IN CREATE_OPTIONS CreateOptions,
IN EXCLUSION Exclusion,
OUT OBJECT_HANDLE *ObjectHandle
);
//
// NtOfsCloseObject releases the object handle.
//
NTFSAPI
NTSTATUS
NtOfsCloseObject (
IN PIRP_CONTEXT IrpContext,
IN OBJECT_HANDLE ObjectHandle
);
//
// NtOfsDeleteObject deletes the object. No user-mode handle is attached to
// the object. No attributes are currently open. The object is acquired
// exclusive.
//
NTFSAPI
NTSTATUS
NtOfsDeleteObject (
IN PIRP_CONTEXT IrpContext,
IN OBJECT_HANDLE ObjectHandle
);
//
// NtOfsDeleteAllAttributes deletes all attributes of the object. No attribute
// is open. The object is acquired exclusive.
//
NTFSAPI
NTSTATUS
NtOfsDeleteAllAttributes (
IN PIRP_CONTEXT IrpContext,
IN OBJECT_HANDLE ObjectHandle
);
//
// NtOfsQueryPathFromRoot returns *A* path from the root to a node. In the
// presence of hard links, several paths may exist, however, only one needs
// to be returned. Memory for the file name is provided by the caller.
//
NTFSAPI
NTSTATUS
NtOfsQueryPathFromRoot (
IN PIRP_CONTEXT IrpContext,
IN FILE_REFERENCE FileReference,
OUT UNICODE_STRING *PathName
);
//
// NtOfsQueryFileName returns the final component in the path name into a
// caller-supplied buffer. In the presence of hard links, several names
// may exist, however, only one needs to be returned.
//
NTFSAPI
NTSTATUS
NtOfsQueryFileName (
IN PIRP_CONTEXT IrpContext,
IN FILE_REFERENCE FileReference,
OUT UNICODE_STRING *FileName
);
//
// NtOfsQueryFileReferenceFromName returns the file reference named by the path
//
NTFSAPI
NTSTATUS
NtOfsQueryFileReferenceFromName (
IN PIRP_CONTEXT IrpContext,
IN UNICODE_STRING Name,
OUT FILE_REFERENCE *FileReference
);
//
// This call must be very fast; it is a very common call made by CI/Query.
//
NTFSAPI
NTSTATUS
NtOfsQueryFileReferenceFromHandle (
IN OBJECT_HANDLE Object,
OUT FILE_REFERENCE *FileReference
);
//
// NtOfsQueryObjectSecurityId returns the security Id associated with an object.
// The object is acquired shared or exclusive. This call must be very fast
//
NTFSAPI
NTSTATUS
NtOfsQueryObjectSecurityId (
IN PIRP_CONTEXT IrpContext,
IN OBJECT_HANDLE ObjectHandle,
OUT SECURITY_ID *SecurityId
);
////////////////////////////////////////////////////////////////////////////////
//
// Scope API
//
//
// NtOfsIsAncestorOf must quickly tell if one file is an ancestor of the given
// child. In the presence of hard links, we may pick a "preferred" path (i.e.
// we don't have to travel to all ancestors). This call must be reasonably fast
// since this is a very frequent call from Query.
//
NTFSAPI
NTSTATUS
NtOfsIsAncestorOf (
IN PIRP_CONTEXT IrpContext,
IN FILE_REFERENCE Ancestor,
IN FILE_REFERENCE Child
);
//
// NtOfsGetParentFileReferenceFromHandle is used to retrieve the FileReference
// of the parent of the named object. With hard links the "first" parent may
// be chosen. This call needs to be reasonably efficient.
//
NTFSAPI
NTSTATUS
NtOfsGetParentFileReferenceFromHandle (
IN PIRP_CONTEXT IrpContext,
IN OBJECT_HANDLE ChildObject,
OUT FILE_REFERENCE *ParentFileReference
);
////////////////////////////////////////////////////////////////////////////////
//
// Security API
//
// NtOfs maintains a "per-IrpContext" cache that speeds up security validation.
// Clients clear the cache (at the beginning of a query, say) and then do
// successive probes which may populate the cache.
//
//
// NtOfsClearSecurityCache clears the cache.
//
NTFSAPI
NTSTATUS
NtOfsClearSecurityCache (
IN PIRP_CONTEXT IrpContext
);
//
// NtOfsIsAccessGranted uses the Se routines to validate access and caches the
// result for the specified SecurityId and DesiredAccess. The cache is first
// probed to see if the access can be granted immediately. If the SecurityId is
// not found, the corresponding ACL is retrieved and tested with the supplied
// access state and DesiredAccess. The result of this test is cached and
// returned.
//
NTFSAPI
NTSTATUS
NtOfsIsAccessGranted (
IN PIRP_CONTEXT IrpContext,
IN SECURITY_ID SecurityId,
IN ACCESS_MASK DesiredAccess,
IN ACCESS_STATE *SecurityAccessState
);
////////////////////////////////////////////////////////////////////////////////
//
// Worker thread stuff. Worker threads are needed for building new indexes
//
////////////////////////////////////////////////////////////////////////////////
//
// Miscellaneous information query/set
//
//
// Content Index may need to mark the volume as dirty to allow garbage collection
// of orphan objects by CHKDSK.
//
NTFSAPI
NTSTATUS
NtOfsMarkVolumeCorrupt (
IN PIRP_CONTEXT IrpContext,
IN ULONG NewState,
IN ULONG StateMask,
OUT ULONG *OldState
);
//
// NtOfsQueryVolumeStatistics returns the current capacity and free space on a
// volume. Ci uses this for heuristics to decide on when to trigger master merge,
// when to suppress master merge, etc.
//
NTFSAPI
NTSTATUS
NtOfsQueryVolumeStatistics (
IN PIRP_CONTEXT IrpContext,
OUT LONGLONG *TotalClusters,
OUT LONGLONG *FreeClusters
);
//
// Query needs to retain some state in the NtOfs Ccb.
//
NTFSAPI
NTSTATUS
NtOfsQueryHandleState (
IN PIRP_CONTEXT IrpContext,
OUT VOID *OldData
);
NTFSAPI
NTSTATUS
NtOfsSetHandleState (
IN PIRP_CONTEXT IrpContext,
IN VOID *Data
);
//
// Generic unwrapping routines that get access to SCB/IRPC and FCB/IRPC
// pairs.
//
NTFSAPI
NTSTATUS
NtOfsQueryAttributeHandle (
IN PIRP_CONTEXT IrpContext,
OUT ATTRIBUTE_HANDLE *AttributeHandle
);
NTFSAPI
NTSTATUS
NtOfsQueryObjectHandle (
IN PIRP_CONTEXT IrpContext,
OUT OBJECT_HANDLE *ObjectHandle
);
//
// Create a context in which the caller can perform I/O in separate.
// threads. This means creating an IRP/IRP_CONTEXT. Each IrpContext corresponds
// to one I/O activity at a time. Multiple IrpContexts may be active in a thread
// at a single time.
//
NTFSAPI
NTSTATUS
NtOfsCloneIrpContext (
IN PIRP_CONTEXT IrpContext,
OUT PIRP_CONTEXT *NewIrpContext
);
//
// NtOfsCompleteRequest completes an IrpContext that has been previously cloned.
// All other FsCtl Irps are completed by Ntfs.
//
NTFSAPI
NTSTATUS
NtOfsCompleteRequest (
IN PIRP_CONTEXT IrpContext,
NTSTATUS Status
);
////////////////////////////////////////////////////////////////////////////////
//
// Iterators. While each iterator is created through a separate API, each one
// must support two operations:
// Next - this fills a buffer with as many records as possible
// Close - this releases the iterator.
//
typedef struct _BASE_FILE_SEGMENT_ITERATOR BASE_FILE_SEGMENT_ITERATOR;
typedef struct _USN_ITERATOR USN_ITERATOR;
//
// The types of iterators are:
//
// Scope iterate over a directory (optionally RECURSIVE)
// (implemented in Query)
// View iterate over the rows in a view with a partial key match
// (implemented in View)
// BaseFileSegment iterate over all base file record segments
// (implemented in NtOfs)
// SummaryCatalog iterate over all rows in a summary catalog
// Usn iterate over all objects with Usn's in a specific range
// (implmented in NtOfs)
//
// Each iteration is passed a buffer which is filled (as much as possible) with
// a packed array of:
// FILE_REFERENCE
// DUPLICATED_INFORMATION
// STAT_INFORMATION
// for each enumerated object. The output length is the length in bytes that
// was filled in with the enumeration request.
NTFSAPI
NTSTATUS
NtOfsCreateBaseFileSegmentIterator (
IN PIRP_CONTEXT IrpContext,
OUT BASE_FILE_SEGMENT_ITERATOR *Iterator
);
NTFSAPI
NTSTATUS
NtOfsNextBaseFileSegmentIteration (
IN PIRP_CONTEXT IrpContext,
IN BASE_FILE_SEGMENT_ITERATOR *Iterator,
IN OUT ULONG *BufferLength,
IN OUT PVOID Buffer
);
NTFSAPI
NTSTATUS
NtOfsCloseBaseFileSegmentIterator (
IN PIRP_CONTEXT IrpContext,
IN BASE_FILE_SEGMENT_ITERATOR *Iterator
);
NTFSAPI
NTSTATUS
NtOfsCreateUsnIterator (
IN PIRP_CONTEXT IrpContext,
IN USN BeginningUsn,
IN USN EndingUsn,
OUT USN_ITERATOR *Iterator
);
NTFSAPI
NTSTATUS
NtOfsNextUsnIteration (
IN PIRP_CONTEXT IrpContext,
IN USN_ITERATOR *Iterator,
IN OUT ULONG *BufferLength,
IN OUT PVOID Buffer
);
NTFSAPI
NTSTATUS
NtOfsCloseUsnIterator (
IN PIRP_CONTEXT IrpContext,
IN USN_ITERATOR *Iterator
);
////////////////////////////////////////////////////////////////////////////////
//
// Infrastructure support.
//
// V/C/X register callbacks with NtOfs when they are loaded. Until they are loaded
// NtOfs will call default routines (that do nothing).
//
typedef enum _NTFS_ADDON_TYPES {
Encryption = 3
} NTFS_ADDON_TYPES;
////////////////////////////////////////////////////////////////////////////////
//
// Encryption
//
//
// Stream Create Status for FileDirFlag
//
#define STREAM_NEW_OR_EXIST_MASK 0x000f0000
#define FILE_DIR_TYPE_MASK 0x000000ff
#define FILE_NEW 0x00000001
#define FILE_EXISTING 0x00000002
#define DIRECTORY_NEW 0x00000004
#define DIRECTORY_EXISTING 0x00000008
#define EXISTING_FILE_ENCRYPTED 0x00000010
#define STREAM_NEW 0x00010000
#define STREAM_EXISTING 0x00020000
//
// Encryption flag for EncryptionFlag
//
#define STREAM_ENCRYPTED 0x00000001
#define FILE_ENCRYPTED 0x00000002
//
// Access flags
//
// NB -- These values are NOT arbitrary. Notice also that they are not
// in value order, they are grouped according to their meaning.
// Their values correspond to FILE_READ_DATA, etc. and
// TOKEN_HAS_BACKUP_PRIVILEGE, etc.
//
#define READ_DATA_ACCESS 0x01
#define WRITE_DATA_ACCESS 0x02
#define APPEND_DATA_ACCESS 0x04
#define EXECUTE_ACCESS 0x20
#define READ_ATTRIBUTES_ACCESS 0x80
#define WRITE_ATTRIBUTES_ACCESS 0x100
#define BACKUP_ACCESS 0x08
#define RESTORE_ACCESS 0x10
#define TRAVERSE_ACCESS 0x40
#define MANAGE_VOLUME_ACCESS 0x200
//
// Volume State
//
#define READ_ONLY_VOLUME 0x00000001
typedef NTSTATUS
(*ENCRYPTED_FILE_CREATE) (
IN OBJECT_HANDLE FileHdl,
IN OBJECT_HANDLE ParentDir OPTIONAL,
IN PIO_STACK_LOCATION IrpSp,
IN ULONG FileDirFlag,
IN ULONG VolumeState,
IN PIRP_CONTEXT IrpContext,
IN PDEVICE_OBJECT VolDo,
IN PVOID FileKeyContext,
IN OUT PVOID *PKeyContext,
IN OUT ULONG *ContextLength,
IN OUT PVOID *PCreateContext,
IN OUT PBOOLEAN Reserved
);
typedef NTSTATUS
(*ENCRYPTED_FILE_PRE_CREATE) (
IN PDEVICE_OBJECT VolDo,
IN PIRP Irp,
IN PFILE_OBJECT FileObject
);
typedef NTSTATUS
(*ENCRYPTED_FILE_POST_CREATE) (
IN PDEVICE_OBJECT VolDo,
IN PIRP Irp,
IN PFILE_OBJECT FileObject,
IN NTSTATUS Status,
IN OUT PVOID *PCreateContext
);
typedef NTSTATUS
(*ENCRYPTED_FILE_SYSTEM_CONTROL) (
IN PVOID PInputBuffer OPTIONAL,
IN ULONG InputDataLength,
OUT PVOID OutputBuffer OPTIONAL,
IN OUT ULONG *OutputBufferLength OPTIONAL,
IN ULONG EncryptionFlag,
IN ULONG AccessFlag,
IN ULONG VolumeState,
IN ULONG FsControlCode,
IN OBJECT_HANDLE FileHdl,
IN PIRP_CONTEXT IrpContext,
IN PDEVICE_OBJECT VolDo,
IN ATTRIBUTE_HANDLE Attribute,
IN OUT PVOID *PContext OPTIONAL,
IN OUT ULONG *ContextLength OPTIONAL
);
typedef NTSTATUS
(*ENCRYPTED_FILE_PRE_FILE_SYSTEM_CONTROL) (
IN PDEVICE_OBJECT VolDo,
IN PIRP Irp,
IN PFILE_OBJECT FileObject
);
typedef NTSTATUS
(*ENCRYPTED_FILE_READ)(
IN OUT PUCHAR InOutBuffer,
IN PLARGE_INTEGER Offset,
IN ULONG BufferSize,
IN PVOID Context
);
typedef NTSTATUS
(*ENCRYPTED_FILE_WRITE)(
IN PUCHAR InBuffer,
OUT PUCHAR OutBuffer,
IN PLARGE_INTEGER Offset,
IN ULONG BufferSize,
IN PUCHAR Context
);
typedef VOID
(*ENCRYPTED_FILE_CLEANUP)(
IN OUT PVOID *Context
);
#define ENCRYPTION_CURRENT_INTERFACE_VERSION 3
#define ENCRYPTION_ALL_STREAMS 0x00000001
#define ENCRYPTION_ALLOW_COMPRESSION 0x00000002
typedef struct _ENCRYPTION_CALL_BACK {
ULONG InterfaceVersion;
ULONG ImplementationFlags;
ENCRYPTED_FILE_CREATE FileCreate;
ENCRYPTED_FILE_PRE_CREATE PreCreate;
ENCRYPTED_FILE_POST_CREATE PostCreate;
ENCRYPTED_FILE_SYSTEM_CONTROL FileSystemControl_1;
ENCRYPTED_FILE_SYSTEM_CONTROL FileSystemControl_2;
ENCRYPTED_FILE_PRE_FILE_SYSTEM_CONTROL PreFileSystemControl;
ENCRYPTED_FILE_READ AfterReadProcess;
ENCRYPTED_FILE_WRITE BeforeWriteProcess;
ENCRYPTED_FILE_CLEANUP CleanUp;
} ENCRYPTION_CALL_BACK, *PENCRYPTION_CALL_BACK;
//
// NtOfsRegisterCallBacks supplies a call table to NtOfs. Each table has an
// interface version number. If the interface version does not exactly match
// what NtOfs expects, the call will fail.
//
NTFSAPI
NTSTATUS
NtOfsRegisterCallBacks (
NTFS_ADDON_TYPES NtfsAddonType,
PVOID CallBackTable
);
Reference in a new issue Copy permalink