Using ECPs to process IRP_MJ_CREATE operations in a file system filter driver

You can use extra create parameters (ECPs) in your file system filter driver to process IRP_MJ_CREATE operations. Your file system filter driver can call the routines in the following sections to retrieve, set (add), acknowledge, and remove ECPs for the IRP_MJ_CREATE operation. You can also determine the operating-system space from which the ECPs originated.

Retrieving ECPs

To retrieve ECPs for the IRP_MJ_CREATE operation:

1. Call FltGetEcpListFromCallbackData (or FsRtlGetEcpListFromIrp) to retrieve a pointer to the ECP_LIST that is associated with the create operation.

2. Perform either of the following operations:

   • Call FltGetNextExtraCreateParameter (or FsRtlGetNextExtraCreateParameter) to retrieve a pointer to the next (or first) ECP context structure in the ECP list.
   • Call FltFindExtraCreateParameter (or FsRtlFindExtraCreateParameter) to search the ECP list for an ECP context structure of a given type. Either routine returns a pointer to the ECP context structure if the structure is found.

Setting ECPs

To set ECPs for the IRP_MJ_CREATE operation, your file system filter driver will either:

• Set ECPs in an existing ECP_LIST.

• Set ECPs in a newly created ECP_LIST.

Setting ECPs in an existing ECP_LIST

To set ECPs in an existing ECP_LIST that is associated with the create operation:

1. Call FltGetEcpListFromCallbackData (or FsRtlGetEcpListFromIrp) to retrieve a pointer to the ECP_LIST that is associated with the create operation.

2. Call FltAllocateExtraCreateParameter (or FsRtlAllocateExtraCreateParameter) to allocate paged memory pool for an ECP context structure and to generate a pointer to that structure.

3. Call FltInsertExtraCreateParameter (or FsRtlInsertExtraCreateParameter) to insert ECP context structures into the ECP_LIST structure.

Setting ECPs in a newly created ECP_LIST

If an ECP_LIST is not currently associated with the create operation, you'll need to create one and then set ECPs in it:

1. Call FltAllocateExtraCreateParameterList (or FsRtlAllocateExtraCreateParameterList) to allocate memory for an ECP_LIST structure.

2. Call FltAllocateExtraCreateParameter (or FsRtlAllocateExtraCreateParameter) to allocate paged memory pool for an ECP context structure and to generate a pointer to that structure.

3. Call FltInsertExtraCreateParameter (or FsRtlInsertExtraCreateParameter) to insert ECP context structures into the ECP_LIST.

4. Call FltSetEcpListIntoCallbackData (or FsRtlSetEcpListIntoIrp) to attach an ECP list to the create operation.

Removing ECPs

To remove ECPs for the IRP_MJ_CREATE operation:

1. Call FltRemoveExtraCreateParameter (or FsRtlRemoveExtraCreateParameter) to search an ECP list for an ECP context structure. If the ECP context structure is found, the routine detaches the ECP context structure from the ECP list.

2. To free the memory for the detached ECP context structure, call FltFreeExtraCreateParameter (or FsRtlFreeExtraCreateParameter). You can call these routines to free memory for the ECP context structure if you allocated the memory in one of the following ways:

   • You called FltAllocateExtraCreateParameter (or FsRtlAllocateExtraCreateParameter) to allocate paged memory pool
   • You called FltAllocateExtraCreateParameterFromLookasideList (or FsRtlAllocateExtraCreateParameterFromLookasideList) to allocate memory pool from a lookaside list

Marking ECPs as acknowledged, or determining acknowledge status

Call the following routines to either mark ECPs as acknowledged or determine whether the ECPs are marked as acknowledged:

• Call FltAcknowledgeEcp (or FsRtlAcknowledgeEcp) to mark an ECP context structure as acknowledged. The ECP can be marked as looked at, used, processed, or any other condition of the ECP.

• Call FltIsEcpAcknowledged (or FsRtlIsEcpAcknowledged) to determine whether an ECP context structure is marked as acknowledged.

Determining origination mode

Call FltIsEcpFromUserMode (or FsRtlIsEcpFromUserMode) to determine whether an ECP context structure originated from user mode. A file system filter driver can refuse to accept an ECP context structure that originated from user mode.

Using lookaside lists to allocate ECPs

Call the following routines to allocate ECPs from lookaside lists and to manage the lookaside lists and ECPs:

• Call FltInitExtraCreateParameterLookasideList (or FsRtlInitExtraCreateParameterLookasideList) to initialize a paged or nonpaged pool lookaside list that is used for the allocation of one or more ECP context structures of fixed size.

• Call FltDeleteExtraCreateParameterLookasideList (or FsRtlDeleteExtraCreateParameterLookasideList) to free the lookaside list.

• Call FltAllocateExtraCreateParameterFromLookasideList (or FsRtlAllocateExtraCreateParameterFromLookasideList) to allocate memory pool from the lookaside list for an ECP context structure and to generate a pointer to that structure.

• Call FltFreeExtraCreateParameter (or FsRtlFreeExtraCreateParameter) to free the memory for the ECP context structures.