FLT_CREATEFILE_TARGET_ECP_CONTEXT 结构 (fltkernel.h)
FLT_CREATEFILE_TARGET_ECP_CONTEXT 结构是一个额外的 create 参数， (ECP) 用于将重新分析目标信息返回给 FltCreateFileEx2 的调用方。
语法
typedef struct _FLT_CREATEFILE_TARGET_ECP_CONTEXT {
PFLT_INSTANCE Instance;
PFLT_VOLUME Volume;
PFLT_FILE_NAME_INFORMATION FileNameInformation;
FLT_CREATEFILE_TARGET_FLAGS Flags;
} FLT_CREATEFILE_TARGET_ECP_CONTEXT, *PFLT_CREATEFILE_TARGET_ECP_CONTEXT;
成员
Instance
附加到调整后目标的筛选器实例。
Volume
调整后的目标卷。
FileNameInformation
调整后目标的文件信息。
Flags
控制重新分析操作的标志。 此值可以是 0 或以下值。
| 值 | 含义 |
|---|---|
|
请求在找不到包含原始文件信息的目标时， FltCreateFileEx2 尝试重新分析操作。 |
注解
当 FltCreateFileEx2 的调用方希望为卷目标启用重新分析时， 可以将FLT_CREATEFILE_TARGET_ECP_CONTEXT 作为 ECP 包含在 DriverContext 参数中的 ECP 列表中。 如果存在此 ECP，FltCreateFileEx2 将调整创建操作的目标设备，并尝试查找适合给定文件信息的卷的筛选实例。 如果筛选器管理器在目标卷上找不到调用方对应的实例，它将为新目标设置 FLT_CREATEFILE_TARGET_ECP_CONTEXT 的 Volume 和 FileNameInformation 成员。 然后，调用方可以使用此信息来决定如何以最佳方式继续。
如果 FltCreateFileEx2 的调用方打算处理重新分析操作本身，则会从 Flags 成员中清除FLTTCFL_AUTO_REPARSE标志。 在这种情况下， FltCreateFileEx2 会将初始目标调整信息放在 ECP 中，然后返回 ，以结束文件创建尝试。
如果在已确认的 ECP 中设置了 Instance、 Volume 或 FileNameInformation 中的值，则它们是引用对象。 FltCreateFileEx2 的调用方负责为 Instance 和 Volume 调用 FltObjectDereference，并为 FileNameInformation 调用 FltReleaseFileNameInformation。
以下示例例程演示了微筛选器如何通过FLT_CREATEFILE_TARGET_ECP_CONTEXT调用 FltCreateFileEx2，以在需要查找文件目标时处理对不同卷的重新分析。
NTSTATUS
CrossVolumeCreate(
_In_ PUNICODE_STRING FileName,
_In_ PFLT_FILTER Filter,
_In_ PFLT_INSTANCE Instance,
_Inout_ PIO_STATUS_BLOCK IoStatus,
_Out_ PHANDLE Handle,
_Outptr_ PFILE_OBJECT *FileObject
)
/*++
Routine Description:
Issues a targeted create and handles cross volume reparse.
Arguments:
FileName - The name of the file to open
Filter – The filter issuing the create
Instance - The filter instance for the targeted create
IoStatus - Receives the operation status
Handle - Receives the file handle
FileObject - Receives the file object
Return Value:
status of the operation
--*/
{
PFLT_CREATEFILE_TARGET_ECP_CONTEXT ecpContext;
PECP_LIST ecpList;
PFLT_FILE_NAME_INFORMATION fileNameInformation;
IO_DRIVER_CREATE_CONTEXT myCreateContext;
OBJECT_ATTRIBUTES objAttr;
NTSTATUS status;
ecpContext = NULL;
ecpList = NULL;
fileNameInformation = NULL;
status = STATUS_SUCCESS;
InitializeObjectAttributes( &objAttr,
FileName,
OBJ_KERNEL_HANDLE,
NULL,
NULL );
//
// First we optimistically send a targeted create that is not
// setup to handle cross-volume reparse.
//
status = FltCreateFileEx2( Filter,
Instance,
Handle,
FileObject,
FILE_READ_DATA|FILE_WRITE_DATA,
&objAttr,
IoStatus,
NULL,
0,
FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
FILE_OPEN_IF,
FILE_NON_DIRECTORY_FILE | FILE_SYNCHRONOUS_IO_NONALERT,
NULL,
0,
IO_IGNORE_SHARE_ACCESS_CHECK,
NULL );
if (!NT_SUCCESS(status)) {
if ((status != STATUS_INVALID_DEVICE_OBJECT_PARAMETER) &&
(status != STATUS_MOUNT_POINT_NOT_RESOLVED)) {
goto CrossVolumeCreateExit;
}
} else {
//
// The create succeeded. There must not have been a cross-volume
// reparse.
//
goto CrossVolumeCreateExit;
}
//
// The create failed traversing a cross-volume link.
// Issue another create with a targeting ECP so that
// we can handle cross-volume reparse.
//
status = FltAllocateExtraCreateParameterList( Filter,
0,
&ecpList );
if (!NT_SUCCESS( status )) {
goto CrossVolumeCreateExit;
}
status = FltAllocateExtraCreateParameter( Filter,
&GUID_ECP_FLT_CREATEFILE_TARGET,
sizeof(FLT_CREATEFILE_TARGET_ECP_CONTEXT),
0,
NULL,
POOL_TAG,
&ecpContext );
if (!NT_SUCCESS( status )) {
goto CrossVolumeCreateExit;
}
//
// Initialize the ECP with the FLTTCFL_AUTO_REPARSE flag which
// tells filter manager to handle the cross-volume reparse
// internally when possible (when it can find our instance
// on the target volume). If this flag is not set, the filter will
// be responsible for calling FltCreateFileEx2 with appropriate
// Instance parameter.
//
ecpContext->Flags = FLTTCFL_AUTO_REPARSE;
ecpContext->Instance = NULL;
ecpContext->Volume = NULL;
ecpContext->FileNameInformation = NULL;
status = FltInsertExtraCreateParameter( Filter,
ecpList,
ecpContext );
if (!NT_SUCCESS( status )) {
goto CrossVolumeCreateExit;
}
IoInitializeDriverCreateContext( &myCreateContext );
myCreateContext.ExtraCreateParameter = ecpList;
InitializeObjectAttributes( &objAttr,
FileName,
OBJ_KERNEL_HANDLE,
NULL,
NULL );
status = FltCreateFileEx2( Filter,
Instance,
Handle,
FileObject,
FILE_READ_DATA|FILE_WRITE_DATA,
&objAttr,
IoStatus,
NULL,
0,
FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
FILE_OPEN_IF,
FILE_NON_DIRECTORY_FILE | FILE_SYNCHRONOUS_IO_NONALERT,
NULL,
0,
IO_IGNORE_SHARE_ACCESS_CHECK,
&myCreateContext );
if (!NT_SUCCESS(status)) {
if ((status != STATUS_INVALID_DEVICE_OBJECT_PARAMETER) &&
(status != STATUS_MOUNT_POINT_NOT_RESOLVED)) {
goto CrossVolumeCreateExit;
}
} else {
goto CrossVolumeCreateExit;
}
//
// Filter manager should have acknowledged the ECP. If it
// is not acknowledged, it does not contain any cross-volume
// targeting information.
//
if (!FltIsEcpAcknowledged( Filter, ecpContext)) {
goto CrossVolumeCreateExit;
}
//
// Filter manager could not automatically handle the
// cross-volume traversal. We choose to send the create
// to the top of the stack on the target volume indicated
// in the targeting ECP.
//
//
// The ECP may contain pointers to referenced objects. We
// need to deal with those references before reusing the
// ECP.
//
if (ecpContext->Volume != NULL) {
FltObjectDereference( ecpContext->Volume );
ecpContext->Volume = NULL;
}
//
// Note: since we flagged the ECP to automatically handle
// cross-volume reparse, the create should have failed after
// we traversed a mountpoint only if our filter did not have
// an instance on the target volume. In that case we would
// expect the Instance field in the ECP to be NULL. We still
// demonstrate derefing the instance for the general case.
//
if (ecpContext->Instance != NULL) {
FltObjectDereference( ecpContext->Instance );
ecpContext->Instance = NULL;
}
fileNameInformation = ecpContext->FileNameInformation;
ecpContext->FileNameInformation = NULL;
//
// Tell filter manager to not handle the cross-volume
// reparse itself. Presumably a filter would do this if it
// did not want the create automatically targeted at its
// instance on another volume.
//
ecpContext->Flags = 0;
//
// Reinitialize the targeting ECP to it can be reused.
//
FltPrepareToReuseEcp( Filter, ecpContext );
IoInitializeDriverCreateContext( &myCreateContext );
myCreateContext.ExtraCreateParameter = ecpList;
InitializeObjectAttributes( &objAttr,
&fileNameInformation->Name,
OBJ_KERNEL_HANDLE,
NULL,
NULL );
status = FltCreateFileEx2( Filter,
NULL,
Handle,
FileObject,
FILE_READ_DATA|FILE_WRITE_DATA,
&objAttr,
IoStatus,
NULL,
0,
FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
FILE_OPEN_IF,
FILE_NON_DIRECTORY_FILE | FILE_SYNCHRONOUS_IO_NONALERT,
NULL,
0,
IO_IGNORE_SHARE_ACCESS_CHECK,
&myCreateContext );
if (!NT_SUCCESS(status)) {
if ((status != STATUS_INVALID_DEVICE_OBJECT_PARAMETER) &&
(status != STATUS_MOUNT_POINT_NOT_RESOLVED)) {
goto CrossVolumeCreateExit;
}
//
// We hit another cross-volume link. For the purposes of
// this example we are just giving up. An actual filter
// would determine the next target instance based on the
// information provided in the targeting ECP. Some of the
// possibilities are:
// 1) If the Instance field in the ECP is available, target
// the create to this instance.
// 2) If the Instance field is NULL, attempt to attach
// an instance based on the Volume parameter in the ECP
// and then target that new instance.
// 3) Use the FileNameInformation provided in the ECP and a
// NULL instance to target the top of the other
// volume's stack.
//
} else {
goto CrossVolumeCreateExit;
}
CrossVolumeCreateExit:
if (ecpContext != NULL &&
FltIsEcpAcknowledged( Filter, ecpContext)) {
FltRemoveExtraCreateParameter( Filter,
ecpList,
&GUID_ECP_FLT_CREATEFILE_TARGET,
&ecpContext,
NULL );
if (ecpContext->Instance != NULL) {
FltObjectDereference( ecpContext->Instance );
}
if (ecpContext->Volume != NULL) {
FltObjectDereference( ecpContext->Volume );
}
if (ecpContext->FileNameInformation != NULL) {
FltReleaseFileNameInformation( ecpContext->FileNameInformation );
}
FltFreeExtraCreateParameter( Filter, ecpContext );
}
if (ecpList != NULL) {
FltFreeExtraCreateParameterList( Filter, ecpList );
}
if (fileNameInformation != NULL) {
FltReleaseFileNameInformation( fileNameInformation );
}
return status;
}
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | 此结构从Windows 8开始可用。 |
| 标头 | fltkernel.h (包括 FltKernel.h) |