Export (0) Print
Expand All
Expand Minimize

FsRtlAllocateExtraCreateParameter routine

The FsRtlAllocateExtraCreateParameter routine allocates memory for a user-defined extra create parameter (ECP) context structure and generates a pointer to that structure.

Syntax


NTSTATUS FsRtlAllocateExtraCreateParameter(
  _In_      LPCGUID EcpType,
  _In_      ULONG SizeOfContext,
  _In_      FSRTL_ALLOCATE_ECP_FLAGS Flags,
  _In_opt_  PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK CleanupCallback,
  _In_      ULONG PoolTag,
  _Out_     PVOID *EcpContext
);

Parameters

EcpType [in]

A pointer to a user-defined GUID that indicates the type of the ECP context structure. See Using GUIDs in Drivers for more information.

SizeOfContext [in]

The size, in bytes, of the user-defined context structure.

Flags [in]

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 FsRtlAllocateExtraCreateParameter 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.

CleanupCallback [in, optional]

Optional pointer to a filter-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 FsRtlAllocateExtraCreateParameter routine) is deleted. Set this parameter to NULL if a cleanup callback routine is not applicable.

PoolTag [in]

Specifies the pool tag for the allocated memory. For more information, see the Tag parameter of ExAllocatePoolWithTag.

EcpContext [out]

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

Return value

FltAllocateExtraCreateParameter can return one of the following values:

Return codeDescription
STATUS_INSUFFICIENT_RESOURCES

FsRtlAllocateExtraCreateParameter was unable to allocate sufficient memory for an ECP structure. In this case, EcpContext is 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 FsRtlAllocateExtraCreateParameter 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 in the Flags parameter, a non-paged memory pool is allocated. After 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).

If the caller allocates ECP_LIST and one or more ECPs are used in a call to IoCreateFileEx, the previous description is correct. In this case, the system does not free any of the ECPs, so the caller can make multiple calls to IoCreateFileEx with the same ECP set. 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

Version

The FsRtlAllocateExtraCreateParameter routine is available starting with Windows Vista.

Header

Ntifs.h (include Ntifs.h)

Library

Ntoskrnl.lib

IRQL

<= APC_LEVEL

See also

ECP_LIST
FltAllocateExtraCreateParameterList
FltAllocateExtraCreateParameterFromLookasideList
FltCreateFileEx2
FltFreeExtraCreateParameter
FltFreeExtraCreateParameterList
FltGetEcpListFromCallbackData
FltInsertExtraCreateParameter
FltRemoveExtraCreateParameter
FltSetEcpListIntoCallbackData
IoCreateFileEx
PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft