Función FltCreateNamedPipeFile (fltkernel.h)
Los controladores de minifiltro llaman a FltCreateNamedPipeFile para crear una canalización o abrir una canalización existente.
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
);
[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:
[in] ReadMode
Modo que se va a leer de la canalización.
[in] CompletionMode
Modo de finalización para lecturas y escrituras de canalización.
[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.
FltCreateNamedPipeFile devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes.
Código devuelto | Descripción |
---|---|
|
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. |
|
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. |
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.
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 |
FltAllocateExtraCreateParameterList