FltAllocateExtraCreateParameterFromLookasideList function (fltkernel.h)

The FltAllocateExtraCreateParameterFromLookasideList routine allocates memory pool from a given lookaside list for an extra create parameter (ECP) context structure and generates a pointer to that structure.

Syntax

NTSTATUS FLTAPI FltAllocateExtraCreateParameterFromLookasideList(
  [in]           PFLT_FILTER                                    Filter,
  [in]           LPCGUID                                        EcpType,
  [in]           ULONG                                          SizeOfContext,
  [in]           FSRTL_ALLOCATE_ECP_FLAGS                       Flags,
  [in, optional] PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK CleanupCallback,
  [in, out]      PVOID                                          LookasideList,
  [out]          PVOID                                          *EcpContext
);

Parameters

[in] Filter

Opaque filter pointer to the minifilter driver. This pointer uniquely identifies the minifilter driver and remains constant as long as the minifilter driver is loaded.

[in] EcpType

Pointer to a GUID that indicates the type of the ECP context structure. See Using GUIDs in Drivers for more information.

[in] SizeOfContext

The size, in bytes, of the ECP context structure.

[in] Flags

Defines pool allocation options. If the value of the SizeOfContext parameter is larger than the size, in bytes, of the given lookaside list, the ECP context structure will be allocated from system pool instead of the lookaside list. In this case, if the Flags parameter contains the FSRTL_ALLOCATE_ECP_FLAG_CHARGE_QUOTA bit flag value, system pool allocated by the routine will be charged against the current process' memory quota. See the Flags parameter of FltAllocateExtraCreateParameter for more information. In the more typical case when memory for the ECP context structure is allocated from the lookaside list, the FSRTL_ALLOCATE_ECP_FLAG_CHARGE_QUOTA bit flag is not used by the routine.

[in, optional] CleanupCallback

Optional pointer to a minifilter-defined cleanup callback routine of type PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. The cleanup callback routine is called when the ECP context structure is deleted. Set this parameter to NULL if a cleanup callback routine is not applicable.

[in, out] LookasideList

Pointer to an initialized lookaside list in which to attempt to allocate pool from (for the ECP context structure). To initialize the lookaside list, use the FltInitExtraCreateParameterLookasideList routine.

[out] EcpContext

Receives a pointer to the allocated ECP context structure. If the routine failed to allocate sufficient pool for the ECP context structure, EcpContext will be NULL and the routine will return status code STATUS_INSUFFICIENT_RESOURCES.

Return value

The FltAllocateExtraCreateParameterFromLookasideList routine can return one of the following values:

Remarks

This routine is available starting with Windows Vista.

The FltAllocateExtraCreateParameterFromLookasideList routine allocates memory pool for an ECP context structure from the given initialized paged or non-paged lookaside list. However, if the size of the ECP context structure (as defined by the SizeOfContext parameter) is larger than the lookaside list, the routine analogously allocates memory from paged or non-paged system pool.

Use the FltInitExtraCreateParameterLookasideList routine to initialize a paged or non-paged pool lookaside list. Use the FltAllocateExtraCreateParameterFromLookasideList routine to allocate an ECP context structure from the lookaside list, and the FltFreeExtraCreateParameter routine to deallocate the ECP context structure.

Use the FltDeleteExtraCreateParameterLookasideList routine to free a lookaside list.

Drivers must free all ECP context structures and lookaside lists they create before unloading. However, if a file system or file system filter driver attaches an ECP to an existing or newly-created ECP_LIST while processing an IRP_MJ_CREATE request, this ECP is automatically cleaned up when the IRP completes. As a result, a filter driver does not have to clean up ECPs that are added dynamically. This allows a filter driver's ECP to be properly propagated across the reparse points--a process that can require multiple IRP_MJ_CREATE requests to be generated.

For more information about using lookaside lists with drivers, see Using Lookaside Lists.

Requirements

See also

ECP_LIST

FltAllocateExtraCreateParameter

FltAllocateExtraCreateParameterList

FltCreateFileEx2

FltDeleteExtraCreateParameterLookasideList

FltFreeExtraCreateParameter

FltFreeExtraCreateParameterList

FltGetEcpListFromCallbackData

FltInitExtraCreateParameterLookasideList

FltInsertExtraCreateParameter

FltRemoveExtraCreateParameter

FltSetEcpListIntoCallbackData

IoCreateFileEx

PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK