Función FltSetFileContext (fltkernel.h)
La rutina FltSetFileContext establece un contexto para un archivo.
Sintaxis
NTSTATUS FLTAPI FltSetFileContext(
[in] PFLT_INSTANCE Instance,
[in] PFILE_OBJECT FileObject,
[in] FLT_SET_CONTEXT_OPERATION Operation,
[in] PFLT_CONTEXT NewContext,
[out] PFLT_CONTEXT *OldContext
);
Parámetros
[in] Instance
Puntero opaco a una instancia de controlador de minifiltro para el autor de la llamada. Este parámetro es obligatorio y no puede ser NULL.
[in] FileObject
Puntero a un objeto de archivo para el archivo. Este parámetro es obligatorio y no puede ser NULL.
[in] Operation
Marca que especifica el tipo de operación que se va a realizar fltSetFileContext . Este parámetro debe ser una de las marcas siguientes:
| Marca | Significado |
|---|---|
| FLT_SET_CONTEXT_REPLACE_IF_EXISTS | Si ya hay un contexto establecido para el archivo al que apunta el parámetro FileObject , FltSetFileContext reemplazará ese contexto por el contexto especificado en NewContext. De lo contrario, insertará NewContext en la lista de contextos del archivo. |
| FLT_SET_CONTEXT_KEEP_IF_EXISTS | Si ya hay un contexto establecido para el archivo al que apunta FileObject , FltSetFileContext 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á el contexto especificado en NewContext en la lista de contextos del archivo e incrementará el recuento de referencias. |
[in] NewContext
Puntero al nuevo contexto que se va a establecer para el archivo. 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 archivo existente para la instancia a la que apunta el parámetro Instance , 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
La rutina FltSetFileContext devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes:
| Código devuelto | Descripción |
|---|---|
| STATUS_FLT_CONTEXT_ALREADY_DEFINED | Si FLT_SET_CONTEXT_KEEP_IF_EXISTS se especificó para el parámetro Operation , este código de error indica que un contexto ya está asociado al archivo. |
| 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. |
| STATUS_NOT_SUPPORTED | No se admiten contextos de archivo para este archivo. 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 FltSetFileContext para establecer o reemplazar su propio contexto de archivo en un archivo. Un controlador de minifiltro solo puede adjuntar un contexto por instancia de controlador de minifiltro al archivo.
No se puede llamar a FltSetFileContext en un FileObject sin abrir. Por lo tanto, no se puede llamar a FltSetFileContext desde una devolución de llamada previa a la creación de un archivo porque el archivo no se ha abierto en ese momento. Sin embargo, un controlador de minifiltro puede asignar y configurar el contexto de archivo 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 de archivo en el archivo correspondiente a esa secuencia en la devolución de llamada posterior a la creación.
Recuento de referencias
Si FltSetFileContext 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.
Si se produce un error en FltSetFileContext :
- 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 archivo. El filtro que llama a FltSetFileContext 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 FltSetFileContext 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 archivo, llame a FltGetFileContext.
Para eliminar un contexto de archivo, llame a FltDeleteFileContext o FltDeleteContext.
Para determinar si se admiten contextos de archivo para un archivo determinado, llame a FltSupportsFileContexts o FltSupportsFileContextsEx.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Disponible y compatible a partir de Windows Vista. |
| Plataforma de destino | Universal |
| Encabezado | fltkernel.h (incluya Fltkernel.h) |
| Library | Fltmgr.lib |
| Archivo DLL | Fltmgr.sys |
| IRQL | <= APC_LEVEL |