Función FltSetVolumeContext (fltkernel.h)

Artículo
08/07/2023

FltSetVolumeContext establece un contexto para un volumen.

Sintaxis

NTSTATUS FLTAPI FltSetVolumeContext(
  [in]            PFLT_VOLUME               Volume,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Parámetros

[in] Volume

Puntero de volumen opaco para el volumen.

[in] Operation

Marca que especifica los detalles de la operación que se va a realizar. Este parámetro debe ser uno de los siguientes:

Marca	Significado
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Si ya se ha establecido un contexto para Volume, FltSetVolumeContext lo reemplazará por NewContext>. De lo contrario, insertará NewContext en la lista de contextos del volumen.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Si ya se ha establecido un contexto para este volumen, FltSetVolumeContext devolverá STATUS_FLT_CONTEXT_ALREADY_DEFINED y no reemplazará el contexto existente ni incrementará el recuento de referencias. Si aún no se ha establecido un contexto, la rutina insertará NewContext en la lista de contextos del volumen e incrementará el recuento de referencias.

[in] NewContext

Puntero al nuevo contexto que se va a establecer para el volumen. Este parámetro es obligatorio y no puede ser NULL.

[out, optional] OldContext

Puntero a una variable asignada por el autor de la llamada que recibe la dirección del contexto de volumen existente para Volume. Este parámetro es opcional y puede ser NULL. Para obtener más información sobre este parámetro, vea la siguiente sección Comentarios.

Valor devuelto

FltSetVolumeContext devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes:

Código devuelto	Descripción
STATUS_FLT_CONTEXT_ALREADY_DEFINED	IF FLT_SET_CONTEXT_KEEP_IF_EXISTS se especificó para Operation, este código de error indica que un contexto ya está asociado al volumen.
STATUS_FLT_CONTEXT_ALREADY_LINKED	El contexto al que apunta el parámetro NewContext ya está vinculado a un objeto . En otras palabras, este código de error indica que NewContext ya está en uso debido a una llamada previa correcta de una rutina de contextoFltSetXxx.
STATUS_FLT_DELETING_OBJECT	El volumen especificado se está descomponiéndose. Se trata de un código de error.
STATUS_INVALID_PARAMETER	Se pasó un parámetro no válido. Por ejemplo, el parámetro NewContext no apunta a un contexto de volumen válido o se especificó un valor no válido para Operation. Se trata de un código de error.

Comentarios

Para obtener más información sobre los contextos, vea Acerca de los contextos de minifiltro.

Un controlador de minifiltro llama a FltSetVolumeContext para adjuntar un contexto a un volumen, o para quitar o reemplazar un contexto de volumen existente. Un controlador de minifiltro solo puede adjuntar un contexto a un volumen.

Recuento de referencias

Si FltSetVolumeContext se realiza correctamente:

El recuento de referencias de NewContext se incrementa. Cuando NewContext ya no es necesario, el minifiltro debe llamar a FltReleaseContext para disminuir su recuento de referencias.

De lo contrario, si se produce un error en FltSetVolumeContext :

El recuento de referencias de NewContext permanece sin cambios.
Si OldContext no es NULL y no apunta a NULL_CONTEXT, OldContext es un puntero al contexto asociado actualmente al volumen. El filtro que llama a FltSetVolumeContext debe llamar a FltReleaseContext para OldContext , así como cuando el puntero de contexto ya no es necesario.

Independientemente del éxito:

El filtro que llama a FltSetVolumeContext debe llamar a FltReleaseContext para disminuir el recuento de referencias en el objeto NewContext incrementado por FltAllocateContext.

Para obtener más información, vea Referencia a contextos.

Otras operaciones de contexto

Para obtener más información, vea Establecer contextos y Liberar contextos:

Para asignar un nuevo contexto, llame a FltAllocateContext.
Para obtener un contexto de volumen, llame a FltGetVolumeContext.
Para eliminar un contexto de volumen, llame a FltDeleteVolumeContext o FltDeleteContext.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible y compatible con el paquete acumulativo de actualizaciones 1 de Microsoft Windows 2000 para SP4, Windows XP SP2, Windows Server 2003 SP1 y sistemas operativos posteriores.
Plataforma de destino	Universal
Encabezado	fltkernel.h (incluya Fltkernel.h)
Library	FltMgr.lib
Archivo DLL	Fltmgr.sys
IRQL	<= APC_LEVEL