Función FltCreateMailslotFile (fltkernel.h)

Artículo
02/26/2024

Los controladores de minifiltro llaman a FltCreateMailslotFile para crear una canalización o abrir una canalización existente.

Sintaxis

NTSTATUS FLTAPI FltCreateMailslotFile(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ULONG                     DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in]            ULONG                     CreateOptions,
  [in]            ULONG                     MailslotQuota,
  [in]            ULONG                     MaximumMessageSize,
  [in]            PLARGE_INTEGER            ReadTimeout,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Parámetros

[in] Filter

Puntero de filtro opaco para el autor de la llamada.

[in, optional] Instance

Puntero de instancia opaco para la instancia del controlador de minifiltro a la que se enviará la solicitud de creación. La instancia debe adjuntarse al volumen del sistema de archivos mailslot. Este parámetro es opcional y puede ser NULL. Si este parámetro es NULL, la solicitud se envía al objeto de dispositivo en la parte superior de la pila del controlador del sistema de archivos para el volumen. Si no es NULL, la solicitud solo se envía a las instancias del controlador de minifiltro que se adjuntan debajo de la instancia especificada.

[out] FileHandle

Puntero a una variable asignada por el autor de la llamada que recibe el identificador de archivo si la llamada a FltCreateMailslotFile se realiza correctamente.

[out, optional] FileObject

Puntero a una variable asignada por el autor de la llamada que recibe el puntero del objeto de archivo si la llamada a FltCreateMailslotFile es correcta. Este parámetro es opcional y puede ser NULL.

[in] DesiredAccess

Máscara de bits de marcas que especifican el tipo de acceso que requiere el autor de la llamada en el archivo o directorio. El conjunto de marcas DesiredAccess definidas por el sistema determina los siguientes derechos de acceso específicos para los objetos de archivo.

Marca DesiredAccess	Significado
FILE_READ_DATA	Los datos se pueden leer desde el mailslot con nombre.
FILE_READ_ATTRIBUTES	Se pueden leer las marcas FileAttributes. Para obtener más información, vea la tabla de valores de marca válidos en el parámetro FileAttributes de FltCreateFileEx2.
READ_CONTROL	Se puede leer la lista de control de acceso y la información de propiedad asociada a mailslot.
FILE_WRITE_DATA	Los datos se pueden escribir en el mailslot.
FILE_WRITE_ATTRIBUTES	Se pueden escribir marcas FileAttributes.
FILE_APPEND_DATA	Los datos se pueden anexar al gráfico de correspondencia.
WRITE_DAC	Se puede escribir la lista de control de acceso discrecional daCL asociada al gráfico de correo.
WRITE_OWNER	La información de propiedad asociada al mailslot se puede escribir.
ACCESS_SYSTEM_SECURITY	El autor de la llamada tendrá acceso de escritura a la SACL de mailslot.
SYNCHRONIZE	El autor de la llamada puede sincronizar la finalización de una operación de E/S esperando a que fileHandle devuelto se establezca en el estado Señalizado. Esta marca debe establecerse si se establece la marca CreateOptions FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT.

Como alternativa, para cualquier objeto de archivo que no represente un directorio, puede especificar una o varias de las marcas de ACCESS_MASK genéricas siguientes. (Las marcas STANDARD_RIGHTS_XXX son valores del sistema predefinidos que se usan para aplicar la seguridad en los objetos del sistema). También puede combinar estas marcas genéricas con marcas adicionales de la tabla anterior.

DesiredAccess to File Values	Se asigna a las marcas DesiredAccess
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA y SYNCHRONIZE.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_APPEND_DATA y SYNCHRONIZE.

[in] ObjectAttributes

Puntero a una estructura de OBJECT_ATTRIBUTES opaca que ya se ha inicializado con InitializeObjectAttributes. Si el autor de la llamada se ejecuta en el contexto del proceso del sistema, este parámetro puede ser NULL. De lo contrario, el autor de la llamada debe establecer el atributo OBJ_KERNEL_HANDLE en la llamada a InitializeObjectAttributes. Los miembros de esta estructura para un objeto de archivo se enumeran en la tabla siguiente.

Miembro	Valor
Longitud de ULONG	Número de bytes de datos contenidos en la estructura a la que apunta ObjectAttributes. Este valor debe ser al menos `sizeof(OBJECT_ATTRIBUTES)`.
PUNICODE_STRING ObjectName	Puntero a una estructura de UNICODE_STRING que contiene el nombre del mailslot que se va a crear o abrir. Este nombre debe ser una especificación de archivo completa o el nombre de un objeto de dispositivo a menos que sea el nombre de un archivo relativo al directorio especificado por RootDirectory. Por ejemplo, "\Device\Mailslot\myslot" o "?? \mailslot\myslot" podría ser especificaciones de archivo válidas. (Nota: "??" reemplaza "\DosDevices" como nombre del espacio de nombres del objeto Win32. "\DosDevices" sigue funcionando, pero "??" se traduce más rápido por el administrador de objetos.
HANDLE RootDirectory	Identificador opcional de un directorio, obtenido por una llamada anterior a FltCreateFileEx2. Si este valor es NULL, el miembro ObjectName debe ser una especificación de archivo completa que incluya la ruta de acceso completa al mailslot de destino. Si este valor no es NULL, el miembro ObjectName especifica un nombre de mailslot relativo a este directorio.
PSECURITY_DESCRIPTOR SecurityDescriptor	Opcional SECURITY_DESCRIPTOR aplicar a un mailslot. Las ACL especificadas por este descriptor de seguridad solo se aplican al gráfico de correspondencia cuando se crea. Si el valor es NULL cuando se crea un mailslot, la ACL colocada en el mailslot depende del sistema de archivos mailslot y puede permitir que un cliente tenga acceso para crear una instancia.
Atributos de ULONG	Conjunto de marcas que controla los atributos del objeto de archivo. Si el autor de la llamada se ejecuta en el contexto del proceso del sistema, este parámetro puede ser cero. De lo contrario, el autor de la llamada debe establecer la marca OBJ_KERNEL_HANDLE. El autor de la llamada también puede establecer opcionalmente la marca OBJ_CASE_INSENSITIVE, que indica que el código de búsqueda de nombres debe omitir el caso de ObjectName en lugar de realizar una búsqueda de coincidencia exacta.

[out] IoStatusBlock

Puntero a una estructura de IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación solicitada. Al devolver de FltCreateMailslotFile, el miembro Information de la variable contiene uno de los siguientes valores:

FILE_CREATED
FILE_OPENED

[in] CreateOptions

Las opciones que se aplicarán al crear o abrir el mailslot, como una combinación compatible de las marcas siguientes.

Marcas	Significado
FILE_WRITE_THROUGH	Los servicios del sistema, los sistemas de archivos y los controladores que escriben datos en mailslot deben transferir realmente los datos al mailslot antes de que se considere completada cualquier operación de escritura solicitada. Esta marca se establece automáticamente si se establece la marca CreateOptions FILE_NO_INTERMEDIATE_BUFFERING.
FILE_SYNCHRONOUS_IO_ALERT	Todas las operaciones del mailslot se realizan de forma sincrónica. Cualquier espera en nombre del autor de la llamada está sujeta a la terminación prematura de las alertas. Esta marca también hace que el sistema de E/S mantenga el contexto de posición de mailslot. Si se establece esta marca, también se debe establecer la marca DesiredAccess SYNCHRONIZE para que el Administrador de E/S use el objeto de archivo como un objeto de sincronización.
FILE_SYNCHRONOUS_IO_NONALERT	Todas las operaciones del mailslot se realizan de forma sincrónica. Las esperas en el sistema para sincronizar la puesta en cola de E/S y la finalización no están sujetas a alertas. Esta marca también hace que el sistema de E/S mantenga el contexto de posición del archivo. Si se establece esta marca, también se debe establecer la marca DesiredAccess SYNCHRONIZE para que el Administrador de E/S use el objeto de archivo como un objeto de sincronización.

[in] MailslotQuota

Tamaño, en bytes, del búfer para las escrituras en el gráfico de correspondencia.

[in] MaximumMessageSize

Tamaño máximo, en bytes, de un mensaje que se va a escribir en el mailslot. El valor 0 especifica un mensaje de cualquier tamaño.

[in] ReadTimeout

La hora en que una operación de lectura espera a que un mensaje esté disponible en el mailslot. El tiempo de espera predeterminado se expresa en incrementos de 100 nanosegundos como un entero negativo. Por ejemplo, se especifican 250 milisegundos como –10*1000*250. Además, los valores siguientes tienen significados especiales.

Valor	Significado
0	Devuelve inmediatamente si no hay ningún mensaje presente.
-1	Espera para siempre un mensaje.

[in, optional] DriverContext

Puntero opcional a una estructura de IO_DRIVER_CREATE_CONTEXT ya inicializada por IoInitializeDriverCreateContext.

Valor devuelto

FltCreateMailslotFile devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes.

Código devuelto	Descripción
STATUS_FLT_DELETING_OBJECT	El filtro o instancia especificado en los parámetros Filter o Instance se está descomponendo. Este código de estado se puede recibir si la solicitud abierta cruza un punto de montaje de volumen y el parámetro Instance no es NULL. Se trata de un código de error.
STATUS_OBJECT_PATH_SYNTAX_BAD	El parámetro ObjectAttributes no contenía un miembro RootDirectory , pero el miembro ObjectName de la estructura OBJECT_ATTRIBUTES era una cadena vacía o no contenía un carácter OBJECT_NAME_PATH_SEPARATOR. Este código de error indica una sintaxis incorrecta para la ruta de acceso del objeto.

Comentarios

La función FltCreateMailslotFile permite a los controladores de minifiltro crear o abrir instancias de mailslot. Esto es útil para crear gráficos de correo virtuales o para crear un grupo de mailslot que se distribuya a otros gráficos de correo.

El parámetro Instance es NULL o se establece previamente adjuntando al volumen mailslot. Se obtiene un puntero de volumen pasando "\Device\Mailslot" como nombre del volumen a FltGetVolumeFromName.

Para especificar un parámetro de creación adicional (ECP) como parte de una operación de creación, inicialice el miembro ExtraCreateParameter de la estructura IO_DRIVER_CREATE_CONTEXT con la rutina FltAllocateExtraCreateParameterList . Si se usan ECP, se deben asignar, inicializar y liberar mediante sus rutinas de soporte técnico asociadas. Al volver de la llamada de FltCreateMailslotFile, la lista ECP no cambia y se puede pasar a llamadas adicionales de FltCreateMailslotFile para otras operaciones de creación. La estructura de la lista ECP no se desasigna automáticamente. El llamador de FltCreateMailslotFile debe desasignar esta estructura llamando a la rutina FltFreeExtraCreateParameterList .

Si Instance no es NULL, la solicitud create de FltCreateMailslotFile solo se envía a las instancias adjuntas debajo de la instancia de controlador de minifiltro especificada y al sistema de archivos mailslot. La instancia especificada y las instancias adjuntas encima no reciben la solicitud de creación. Si no se especifica ninguna instancia, la solicitud va a la parte superior de la pila y la reciben todas las instancias y el sistema de archivos mailslot.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows 8.
Plataforma de destino	Universal
Encabezado	fltkernel.h (incluya FltKernel.h)
Library	Fltmgr.lib
IRQL	PASSIVE_LEVEL