FltAllocateExtraCreateParameterList function (fltkernel.h)

The FltAllocateExtraCreateParameterList routine allocates paged pool memory for an extra create parameter (ECP) list structure and generates a pointer to that structure.

Syntax

NTSTATUS FLTAPI FltAllocateExtraCreateParameterList(
  [in]  PFLT_FILTER                  Filter,
  [in]  FSRTL_ALLOCATE_ECPLIST_FLAGS Flags,
  [out] PECP_LIST                    *EcpList
);

Parameters

[in] Filter

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

[in] Flags

Defines pool allocation options. If the FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA flag is combined with the Flags parameter by using a bitwise OR operation, any pool allocated by the routine will be charged against the current process' memory quota.

[out] EcpList

Receives a pointer to an initialized ECP list structure. If the routine failed to allocate sufficient pool, *EcpList will be NULL and the routine will return status code STATUS_INSUFFICIENT_RESOURCES.

Return value

FltAllocateExtraCreateParameterList can return one of the following values:

Remarks

Whether the operating system automatically frees memory that FltAllocateExtraCreateParameterList allocates depends on when FltAllocateExtraCreateParameterList is called, as shown in the following situations:

• A caller can invoke FltAllocateExtraCreateParameterList to allocate the ECP_LIST and add one or more ECP context structures before the caller invokes the FltCreateFileEx2 routine. In this situation, the operating system does not free any of the ECP context structures. Therefore, the caller can make multiple calls to FltCreateFileEx2 with the same ECP set. When the caller is done with the ECP_LIST, the caller must call the FltFreeExtraCreateParameterList routine to free the ECP_LIST.

• While a file system filter driver processes an IRP_MJ_CREATE request, the file system filter driver can call FltInsertExtraCreateParameter to attach an ECP to an existing ECP_LIST. If the ECP_LIST does not exist, the caller must call FltAllocateExtraCreateParameterList to create the ECP_LIST. In this situation, the ECP_LIST and the ECP context structure are automatically cleaned up by the I/O manager when the create operation completes. This allows a filter driver's ECP to be properly propagated across the processing of reparse points. This process might require multiple IRP_MJ_CREATE requests to be generated.

If the FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA flag is used with the Flags parameter, as described above, a normal pageable pool is allocated. Otherwise, a pageable pool is allocated by using an internal lookaside list.

ECP_LIST structure

ECP_LIST is an opaque structure that is declared by the operating system. ECP_LIST contains a list of extra create parameter (ECP) entries.

The FltAllocateExtraCreateParameterList routine must be used to allocate memory for the ECP_LIST structure. The memory allocated by FltAllocateExtraCreateParameterList is not automatically freed by the operating system; it must be explicitly deallocated by calling the FltFreeExtraCreateParameterList routine. Note that any remaining ECP list elements will be automatically freed when FltFreeExtraCreateParameterList is called.

The PECP_LIST data type is used to declare a pointer to a variable of type ECP_LIST.

Syntax

struct ECP_LIST {
  ;      // Reserved.
};

The ECP_LIST structure is declared in Ntifs.h (include Ntifs.h).

Requirements

See also

FltAllocateExtraCreateParameter

FltAllocateExtraCreateParameterFromLookasideList

FltCreateFileEx2

FltFreeExtraCreateParameter

FltFreeExtraCreateParameterList

FltGetEcpListFromCallbackData

FltInsertExtraCreateParameter

FltRemoveExtraCreateParameter

FltSetEcpListIntoCallbackData

IoCreateFileEx