CcInitializeCacheMap routine

File systems call the CcInitializeCacheMap routine to cache a file.

Syntax


VOID CcInitializeCacheMap(
  _In_  PFILE_OBJECT FileObject,
  _In_  PCC_FILE_SIZES FileSizes,
  _In_  BOOLEAN PinAccess,
  _In_  PCACHE_MANAGER_CALLBACKS Callbacks,
  _In_  PVOID LazyWriteContext
);

Parameters

FileObject [in]

Pointer to a file object for the file.

FileSizes [in]

Pointer to a CC_FILE_SIZES structure containing AllocationSize, FileSize, and ValidDataLength for the file. This structure is defined as follows:


typedef struct _CC_FILE_SIZES {
    LARGE_INTEGER AllocationSize;
    LARGE_INTEGER FileSize;
    LARGE_INTEGER ValidDataLength;
} CC_FILE_SIZES, *PCC_FILE_SIZES;

MemberMeaning

AllocationSize

New section object size for the file. Ignored if less than or equal to the current section size.

FileSize

New file size for the file.

ValidDataLength

New valid data length for the file.

 

PinAccess [in]

Set to TRUE if CcPinXxx routines will be used on the file.

Callbacks [in]

Pointer to a structure allocated from nonpaged pool, containing entry points of caller-supplied read-ahead and write-behind callback routines.This structure and its members are defined as follows:


typedef struct _CACHE_MANAGER_CALLBACKS {
    PACQUIRE_FOR_LAZY_WRITE AcquireForLazyWrite;
    PRELEASE_FROM_LAZY_WRITE ReleaseFromLazyWrite;
    PACQUIRE_FOR_READ_AHEAD AcquireForReadAhead;
    PRELEASE_FROM_READ_AHEAD ReleaseFromReadAhead;
} CACHE_MANAGER_CALLBACKS, *PCACHE_MANAGER_CALLBACKS;
typedef
BOOLEAN (*PACQUIRE_FOR_LAZY_WRITE) (
             IN PVOID Context,
             IN BOOLEAN Wait
             );
typedef
VOID (*PRELEASE_FROM_LAZY_WRITE) (
             IN PVOID Context
             );
typedef
BOOLEAN (*PACQUIRE_FOR_READ_AHEAD) (
             IN PVOID Context,
             IN BOOLEAN Wait
             );
typedef
VOID (*PRELEASE_FROM_READ_AHEAD) (
             IN PVOID Context
             );

LazyWriteContext [in]

Pointer to context information to be passed to the callback routines specified in Callbacks.

Return value

None

Remarks

CcInitializeCacheMap creates the data structures required for file data caching.

If any failure occurs, CcInitializeCacheMap raises a status exception for that particular failure. For example, if a pool allocation failure occurs, CcInitializeCacheMap raises a STATUS_INSUFFICIENT_RESOURCES exception. Therefore, to gain control if a failure occurs, the driver should wrap the call to CcInitializeCacheMap in a try-except or try-finally statement.

File systems must call CcInitializeCacheMap to cache a file before using any other cache manager routines on the file, unless the file was created with data caching disabled. In most file systems, file caching is enabled by default, but can be disabled by setting the FILE_NO_INTERMEDIATE_BUFFERING flag to TRUE in the file create options.

After calling CcInitializeCacheMap, the file system can call CcSetAdditionalCacheAttributes to disable read-ahead or write-behind, if desired.

When closing a file, every file system that supports file caching must call CcUninitializeCacheMap on that file, whether the file is cached or not. Even if the file was created with caching disabled, the file system still must call CcUninitializeCacheMap.

Requirements

Header

Ntifs.h (include Ntifs.h)

Library

Ntoskrnl.lib

See also

CcSetAdditionalCacheAttributes
CcUninitializeCacheMap

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft