IO_DRIVER_CREATE_CONTEXT structure

The IO_DRIVER_CREATE_CONTEXT structure is used to pass additional parameters to the IoCreateFileEx and FltCreateFileEx2 routines. This structure is optional.

Note   The IoCreateFileEx routine is used by legacy filter drivers and the FltCreateFileEx2 routine is used by minifilter drivers.

Syntax


typedef struct _IO_DRIVER_CREATE_CONTEXT {
  CSHORT               Size;
  struct _ECP_LIST  *ExtraCreateParameter;
  PVOID                DeviceObjectHint;
  PTXN_PARAMETER_BLOCK TxnParameters;
} IO_DRIVER_CREATE_CONTEXT, *PIO_DRIVER_CREATE_CONTEXT;

Members

Size

A read-only member initialized by the IoInitializeDriverCreateContext routine.

ExtraCreateParameter

A pointer to an ECP_LIST structure, which contains a list of extra create parameter (ECP) entries. See the following Remarks section for important information.

DeviceObjectHint

If IO_DRIVER_CREATE_CONTEXT is being used to pass additional create parameters to the FltCreateFileEx2 routine, this member must be NULL.

If IO_DRIVER_CREATE_CONTEXT is being used to pass additional create parameters to the IoCreateFileEx routine, this member is a pointer to the device object to which the create request will be sent. The device object must be a legacy filter or file system device object in the file system driver stack for the volume on which the file or directory resides. In the IoCreateFileEx case, this parameter is optional and can be NULL. If this parameter is NULL, the request will be sent to the device object at the top of the driver stack.

TxnParameters

A pointer to a transaction that you want to associate with the create operation. The create operation will be part of the transaction if the value of this member is a valid pointer to the transaction. If the value of this member is NULL, the create operation will not be part of a transaction.

Remarks

The IO_DRIVER_CREATE_CONTEXT structure can be allocated from paged or nonpaged pool. The IoInitializeDriverCreateContext routine must initialize the IO_DRIVER_CREATE_CONTEXT structure before the structure can be used.

The members of the IO_DRIVER_CREATE_CONTEXT structure (excluding the Size member) function as additional parameters to the IoCreateFileEx and FltCreateFileEx2 routines. Relative to the IoCreateFileEx and FltCreateFileEx2 routine's interface, the following information may be helpful:

  • An ECP_LIST structure contains a list of extra create parameter (ECP) entries. Each ECP entry (ECP context structure) in the ECP list (ECP_LIST structure) functions as an additional create parameter to IoCreateFileEx and FltCreateFileEx2.

    To specify an ECP as part of a create operation, initialize the ExtraCreateParameter member of the IO_DRIVER_CREATE_CONTEXT structure with the correct routine:

    • For legacy filter drivers, the FsRtlAllocateExtraCreateParameterList routine must be used to allocate memory pool for the ECP_LIST structure. The operating system does not automatically free ECP_LIST structures. Instead, once the ECP_LIST structure is allocated, it must eventually be freed by using the FsRtlFreeExtraCreateParameterList routine.
    • For minifilter drivers, the FltAllocateExtraCreateParameterList routine must be used to allocate memory pool for the ECP_LIST structure. The operating system does not automatically free ECP_LIST structures. Instead, once the ECP_LIST structure is allocated, it must eventually be freed by using the FltFreeExtraCreateParameterList routine.

    If ECPs are used, they must be created, manipulated, and freed by using the appropriate routines. For example, minifilter drivers use the FltInsertExtraCreateParameter routine to insert an ECP entry into an ECP list. The following See Also section lists many of these required routines.

    Upon return from a call to IoCreateFileEx or FltCreateFileEx2, the ECP list is unchanged and can be passed to additional IoCreateFileEx or FltCreateFileEx2 calls for new create operations.

  • To create or open a file in the context of a transaction, set the TxnParameters member of the IO_DRIVER_CREATE_CONTEXT structure to the value returned by the IoGetTransactionParameterBlock routine. For more information regarding transactions, see Transaction Management (TxF).

Requirements

Version

This structure is available starting with Windows Vista.

Header

Ntddk.h (include Ntddk.h, Ntifs.h, or Fltkernel.h)

See also

ECP_LIST
FltAllocateExtraCreateParameterFromLookasideList
FltAllocateExtraCreateParameterList
FltCreateFileEx2
FltFreeExtraCreateParameter
FltFreeExtraCreateParameterList
FltGetEcpListFromCallbackData
FltInsertExtraCreateParameter
FltRemoveExtraCreateParameter
FltSetEcpListIntoCallbackData
FsRtlAllocateExtraCreateParameterList
FsRtlFreeExtraCreateParameterList
IoCreateFileEx
IoCreateFileSpecifyDeviceObjectHint
IoGetTransactionParameterBlock
IoInitializeDriverCreateContext

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft