Función FltSetStreamHandleContext (fltkernel.h)
La rutina FltSetStreamHandleContext establece un contexto para un identificador de secuencia.
Sintaxis
NTSTATUS FLTAPI FltSetStreamHandleContext(
[in] PFLT_INSTANCE Instance,
[in] PFILE_OBJECT FileObject,
[in] FLT_SET_CONTEXT_OPERATION Operation,
[in] PFLT_CONTEXT NewContext,
[out, optional] PFLT_CONTEXT *OldContext
);
Parámetros
[in] Instance
Puntero de instancia opaco para la instancia del controlador de minifiltro cuyo contexto se va a insertar, quitar o reemplazar en la lista de contextos adjuntos al identificador de secuencia.
[in] FileObject
Puntero a un objeto de archivo para la secuencia de archivos. Este parámetro es necesario y no se puede null.
[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:
Valor | Significado |
---|---|
FLT_SET_CONTEXT_REPLACE_IF_EXISTS | Si ya se ha establecido un contexto para esta instancia de , fltSetStreamHandleContext reemplazará por el contexto especificado en NewContext. De lo contrario, insertará NewContext en la lista de contextos para el identificador de secuencia. |
FLT_SET_CONTEXT_KEEP_IF_EXISTS | Si ya se ha establecido un contexto para esta instancia de , fltSetStreamHandleContext 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 para el identificador de flujo e incrementará el recuento de referencias. |
[in] NewContext
Puntero al nuevo contexto que se va a establecer para el identificador de secuencia. Este parámetro es necesario y no se puede null.
[out, optional] OldContext
Puntero a una variable asignada por el autor de la llamada que recibe la dirección del contexto del controlador de flujo existente para el parámetro instancia de, si ya se ha establecido uno. Este parámetro es opcional y se puede NULL. Para obtener más información sobre este parámetro, vea la siguiente sección Comentarios.
Valor devuelto
La rutina FltSetStreamHandleContext devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes códigos de error:
Código devuelto | Descripción |
---|---|
STATUS_FLT_CONTEXT_ALREADY_DEFINED | Si FLT_SET_CONTEXT_KEEP_IF_EXISTS se especificó para Operation, este código de error indica que un contexto ya está asociado al identificador de secuencia. |
STATUS_FLT_CONTEXT_ALREADY_LINKED | El contexto al que newContext apunta 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 FltSetXxxContext. |
STATUS_FLT_DELETING_OBJECT | El de instancia 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 identificador de flujo válido o se especificó un valor no válido para Operation. |
STATUS_NOT_SUPPORTED | Se produjo una situación no admitida, como el sistema de archivos, no admite contextos por secuencia para esta secuencia de archivos o el autor de la llamada proporcionó un objeto FileObject NULL. |
Observaciones
Para obtener más información sobre los contextos, vea Acerca de los contextos de minifiltro.
La rutina de FltSetStreamHandleContext agrega, quita o reemplaza un contexto para una instancia de controlador de minifiltro en un identificador de flujo. Un controlador de minifiltro puede adjuntar un contexto por instancia del controlador de minifiltro al identificador de secuencia.
FltSetStreamHandleContext no se puede llamar a en una FileObject sin abrir. Por lo tanto, fltSetStreamHandleContext no se puede llamar desde una devolución de llamada previa a la creación de una secuencia porque la secuencia no se ha abierto en ese momento. Sin embargo, un minifiltro puede asignar y configurar el contexto del controlador de flujo en la devolución de llamada anterior a la creación, pasarlo a la devolución de llamada posterior a la creación mediante el parámetro de contexto de finalización y establecer el contexto del controlador de flujo en la secuencia en la devolución de llamada posterior a la creación.
Recuento de referencias
Si fltSetStreamHandleContext se realiza correctamente:
- Se incrementa el recuento de referencias de NewContext. Cuando ya no se necesita NewContext, el minifiltro debe llamar a FltReleaseContext para disminuir su recuento de referencias.
De lo contrario, si se produce un error en fltSetStreamHandleContext:
- 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 identificador de secuencia. El filtro que llama a FltSetStreamHandleContext 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 FltSetStreamHandleContext debe llamar a FltReleaseContext para reducir el recuento de referencias en el objeto NewContext que se incrementó FltAllocateContext.
Para obtener más información, vea Referencia a contextos.
Otras operaciones de contexto
Para obtener más información, vea Configuración de contextosy liberar contextos:
Para determinar si se admiten contextos de identificador de flujo para un archivo determinado, llame a FltSupportsStreamHandleContexts
Para asignar un nuevo contexto, llame a FltAllocateContext.
Para obtener un contexto de identificador de flujo, llame a FltGetStreamHandleContext.
Para eliminar un contexto de identificador de flujo, llame a FltDeleteStreamHandleContext o FltDeleteContext.
Requisitos
Requisito | Valor |
---|---|
cliente mínimo admitido | 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. |
de la plataforma de destino de | Universal |
encabezado de | fltkernel.h (incluya Fltkernel.h) |
biblioteca de | Fltmgr.lib |
DLL de | Fltmgr.sys |
irQL | <= APC_LEVEL |