FltAllocateExtraCreateParameter function (fltkernel.h)
The FltAllocateExtraCreateParameter routine allocates paged memory pool for a user-defined extra create parameter (ECP) context structure and generates a pointer to that structure.
Syntax
NTSTATUS FLTAPI FltAllocateExtraCreateParameter(
[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] ULONG PoolTag,
[out] PVOID *EcpContext
);
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] EcpType
Pointer to a user-defined GUID indicating the type of the ECP context structure. See Using GUIDs in Drivers for more information.
[in] SizeOfContext
The size, in bytes, of the user-defined context structure.
[in] Flags
Defines pool allocation options. The following describes how pool will be allocated when one or more of the listed flag values are combined with the Flags parameter by using a bitwise OR operation:
FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL - Non-paged pool will be allocated. If this flag value is not used, paged pool will be allocated.
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA - All pool allocated by this routine will be charged against the current process' memory quota.
If more than one flag is used, all of the effects associated with the utilized flag values will occur.
[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 structure (created by the FltAllocateExtraCreateParameter routine) is deleted. Set this parameter to NULL if a cleanup callback routine is not applicable.
[in] PoolTag
Specifies the pool tag for the allocated memory. For more information, see the Tag parameter of ExAllocatePoolWithTag.
[out] EcpContext
Receives a pointer to the allocated ECP context structure. If the routine failed to allocate sufficient pool, *EcpContext will be NULL and the routine will return status code STATUS_INSUFFICIENT_RESOURCES.
Return value
FltAllocateExtraCreateParameter can return one of the following values:
| Return code | Description |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | FltAllocateExtraCreateParameter was unable to allocate sufficient memory for an ECP structure. In this case, EcpContext will be NULL. |
| STATUS_SUCCESS | The ECP structure was successfully allocated. In this case, a pointer to the allocated structure is returned in the EcpContext parameter. |
Remarks
By default, the FltAllocateExtraCreateParameter routine allocates paged memory pool for a user-defined ECP context structure. If the FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL bitmask is used as described above, a non-paged memory pool is allocated. Once this pool has been allocated and the ECP context structure has been initialized, the FltInsertExtraCreateParameter routine is used to insert the ECP context structure (ECP list element) into an ECP list structure (ECP list).
Memory pool that is allocated by the FltAllocateExtraCreateParameter routine is not automatically freed by the operating system. This memory pool must eventually be released by using one of the following methods:
Call the FltRemoveExtraCreateParameter routine to remove the ECP context structure from the ECP list and then call the FltFreeExtraCreateParameter routine to free the ECP context structure itself. The ECP list remains in existence.
Call the FltFreeExtraCreateParameterList routine - this frees the ECP list including any list elements (ECP context structures). The ECP list is destroyed.
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.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Header | fltkernel.h (include Fltkernel.h) |
| Library | FltMgr.lib |
| IRQL | <= APC_LEVEL |
See also
FltAllocateExtraCreateParameterFromLookasideList
FltAllocateExtraCreateParameterList