Función FltCreateNamedPipeFile (fltkernel.h)

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

Sintaxis

NTSTATUS FLTAPI FltCreateNamedPipeFile(
  [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                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in]            ULONG                     NamedPipeType,
  [in]            ULONG                     ReadMode,
  [in]            ULONG                     CompletionMode,
  [in]            ULONG                     MaximumInstances,
                  ULONG                     InboundQuota,
                  ULONG                     OutboundQuota,
  [in, optional]  PLARGE_INTEGER            DefaultTimeout,
  [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 de canalización con nombre. 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 de controladores del sistema de archivos para el volumen. Si no es NULL, la solicitud solo se envía a las instancias de 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 FltCreateNamedPipeFile 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 FltCreateNamedPipeFile se realiza correctamente. Este parámetro es opcional y puede ser NULL.

[in] DesiredAccess

Máscara de bits de marcas que especifican el tipo de acceso que el autor de la llamada requiere para 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.

Marcas desiredAccess Significado
FILE_READ_DATA Los datos se pueden leer desde la canalización 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 (ACL) y la información de propiedad asociada a la canalización con nombre.
FILE_WRITE_DATA Los datos se pueden escribir en la canalización con nombre.
FILE_WRITE_ATTRIBUTES Se pueden escribir marcas fileAttributes.
FILE_APPEND_DATA Los datos se pueden anexar al archivo.
WRITE_DAC Se puede escribir la lista de control de acceso discrecional (DACL) asociada a la canalización con nombre.
WRITE_OWNER La información de propiedad asociada a la canalización con nombre se puede escribir.
ACCESS_SYSTEM_SECURITY El autor de la llamada tendrá acceso de escritura a la SACL de la canalización con nombre.
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 Signaled. 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 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 UNICODE_STRING que contiene el nombre de la canalización 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\NamedPipe\mypipe" o "\?? \pipe\mypipe" podría ser especificaciones de archivo válidas. (Nota: "\??" reemplaza "\DosDevices" como nombre del espacio de nombres de 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 ObjectNamedebe ser una especificación de archivo completa que incluya la ruta de acceso completa a la canalización de destino. Si este valor no es NULL, el miembro ObjectName especifica un nombre de canalización relativo a este directorio.
PSECURITY_DESCRIPTOR SecurityDescriptor Descriptor de seguridad opcional (SECURITY_DESCRIPTOR) que se va a aplicar a una canalización. Las ACL especificadas por este descriptor de seguridad solo se aplican a la canalización cuando se crea. Si el valor es NULL cuando se crea una canalización, la ACL colocada en la canalización depende del sistema de archivos de canalización con nombre y puede permitir que un cliente con cualquier acceso cree 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, lo 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 FltCreateNamedPipeFile, el miembro Information de la variable contiene uno de los siguientes valores:

FILE_CREATED

FILE_OPENED

[in] ShareAccess

Tipo de acceso compartido al archivo que el autor de la llamada requiere como una o una combinación de las marcas siguientes. Para mayor probabilidad de evitar errores de infracción de uso compartido, especifique todas las marcas de acceso de recurso compartido siguientes.

Marcas de ShareAccess Significado
FILE_SHARE_READ El archivo se puede abrir para el acceso de lectura mediante las llamadas de otros subprocesos a FltCreateNamedPipeFile.
FILE_SHARE_WRITE El archivo se puede abrir para el acceso de escritura mediante llamadas de otros subprocesos a FltCreateNamedPipeFile.

[in] CreateDisposition

Valor que determina la acción que se va a realizar, en función de si el archivo ya existe. El valor puede ser cualquiera de los descritos en la tabla siguiente.

Valores createDisposition Significado
FILE_CREATE Si el archivo ya existe, produzca un error en la solicitud y no cree ni abra el archivo especificado. Si no es así, cree el archivo.
FILE_OPEN Si el archivo ya existe, ábralo en lugar de crear un nuevo archivo. Si no es así, produzca un error en la solicitud y no cree un nuevo archivo.
FILE_OPEN_IF Si el archivo ya existe, ábralo. Si no es así, cree el archivo.

[in] CreateOptions

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

Marcas CreateOptions Significado
FILE_WRITE_THROUGH Los servicios del sistema, los sistemas de canalización y los controladores que escriben datos en la canalización deben transferir realmente los datos a la canalización 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 de la canalización se realizan de forma sincrónica. Cualquier espera en nombre del autor de la llamada está sujeta a la finalización prematura de las alertas. Esta marca también hace que el sistema de E/S mantenga el contexto de posición de la canalización. 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 de la canalización se realizan de forma sincrónica. Las esperas en el sistema para sincronizar la 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] NamedPipeType

Tipo de canalización con nombre que se va a crear. Puede ser uno de los siguientes valores:

Valor Significado
FILE_PIPE_BYTE_STREAM_TYPE
Los datos se escriben en la canalización como una secuencia de bytes. Para usar este tipo, ReadMode no debe ser FILE_PIPE_MESSAGE_MODE.
FILE_PIPE_MESSAGE_TYPE
Los datos se escriben en la canalización como un mensaje.

[in] ReadMode

Modo que se va a leer de la canalización.

Valor Significado
FILE_PIPE_BYTE_STREAM_MODE
Los datos de canalización se leen como un flujo de bytes.
FILE_PIPE_MESSAGE_MODE
Los datos de canalización se leen como mensajes. Para usar este modo, NamedPipeType debe ser FILE_PIPE_MESSAGE_TYPE.

[in] CompletionMode

Modo de finalización para lecturas y escrituras de canalización.

Valor Significado
FILE_PIPE_QUEUE_OPERATION
Las solicitudes de lectura y escritura de canalización se ponen en cola y pueden bloquearse hasta que se completen.
FILE_PIPE_COMPLETE_OPERATION
Las solicitudes de lectura y escritura de canalización se completan inmediatamente.

[in] MaximumInstances

Número máximo de instancias permitidas para esta canalización con nombre.

InboundQuota

Número de bytes que se van a reservar para el búfer de entrada.

OutboundQuota

Número de bytes que se van a reservar para el búfer de salida.

[in, optional] DefaultTimeout

Tiempo de espera predeterminado en incrementos de 100 nanosegundos. Este valor se expresa como un entero negativo. Por ejemplo, se especifican 250 milisegundos como –10 * 1000 * 250.

[in, optional] DriverContext

Puntero opcional a una estructura IO_DRIVER_CREATE_CONTEXT ya inicializada por IoInitializeDriverCreateContext.

Valor devuelto

FltCreateNamedPipeFile 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 la instancia especificados en los parámetros Filter o Instance se está descomponiéndose. 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 FltCreateNamedPipeFile permite a los controladores de minifiltro crear o abrir instancias de canalización. Esto es útil para crear canalizaciones virtuales o para crear uniones de canalización para la E/S de multiplexación.

El parámetro de instancia es NULL o se establece previamente mediante la asociación al volumen de canalización con nombre. Se obtiene un puntero de volumen pasando "\Device\NamedPipe" como nombre de 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 FltCreateNamedPipeFile, la lista ECP no cambia y se puede pasar a llamadas adicionales de FltCreateNamedPipeFile para otras operaciones de creación. La estructura de la lista ECP no se desasigna automáticamente. El llamador de FltCreateNamedPipeFile debe desasignar esta estructura llamando a la rutina FltFreeExtraCreateParameterList .

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

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

Consulte también

FltAllocateExtraCreateParameterList

FltFreeExtraCreateParameterList

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoInitializeDriverCreateContext