Función FltSetInstanceContext (fltkernel.h)

  • Artículo

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:

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

Consulte también

FltAllocateContext

FltDeleteContext

FltDeleteInstanceContext

FltGetInstanceContext

FltReleaseContext