Función FltSetInstanceContext (fltkernel.h)

Artículo
08/07/2023

FltSetInstanceContext establece un contexto para una instancia de controlador de minifiltro.

Sintaxis

NTSTATUS FLTAPI FltSetInstanceContext(
  [in]  PFLT_INSTANCE             Instance,
  [in]  FLT_SET_CONTEXT_OPERATION Operation,
  [in]  PFLT_CONTEXT              NewContext,
  [out] PFLT_CONTEXT              *OldContext
);

Parámetros

[in] Instance

Puntero de instancia opaco para la instancia.

[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 la instancia a la que apunta el parámetro Instance , FltSetInstanceContext reemplazará ese contexto por el contexto especificado en NewContext. De lo contrario, establecerá NewContext como contexto para Instance.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Si ya se ha establecido un contexto para esta instancia, FltSetInstanceContext devuelve STATUS_FLT_CONTEXT_ALREADY_DEFINED y no reemplaza el contexto existente ni incrementa el recuento de referencias. Si aún no se ha establecido un contexto, la rutina establecerá NewContext como contexto para Instance e incrementará el recuento de referencias.

[in] NewContext

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

[out] OldContext

Puntero a una variable asignada por el autor de la llamada que recibe la dirección del contexto de instancia existente, si ya se ha establecido uno. 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

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

Código devuelto	Descripción
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Si se especificó FLT_SET_CONTEXT_KEEP_IF_EXISTS para el parámetro Operation , este código de error indica que un contexto ya está asociado a la instancia. Solo se puede adjuntar un contexto a una instancia.
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 FltSetXxxContext .
STATUS_FLT_DELETING_OBJECT	La instancia especificada en el parámetro Instance se está eliminando. 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 archivo válido o se especificó un valor no válido para el parámetro 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 FltSetInstanceContext para adjuntar un contexto de instancia a una instancia de controlador de minifiltro propiedad del autor de la llamada o para quitar o reemplazar un contexto de instancia existente. Un controlador de minifiltro solo puede adjuntar un contexto a una instancia.

Recuento de referencias

Si FltSetInstanceContext se realiza correctamente:

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

Si se produce un error en FltSetInstanceContext :

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 a la instancia. El filtro que llama a FltSetInstanceContext debe llamar finalmente a FltReleaseContext para OldContext , así como cuando el puntero de contexto ya no es necesario.

Independientemente del éxito:

El filtro que llama a FltSetInstanceContext 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 instancia, llame a FltGetInstanceContext.
Para eliminar un contexto de instancia, llame a FltDeleteInstanceContext 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 versiones posteriores del sistema operativo.
Plataforma de destino	Universal
Encabezado	fltkernel.h (incluya Fltkernel.h)
Library	FltMgr.lib
Archivo DLL	Fltmgr.sys
IRQL	<= APC_LEVEL