Función NtCreateNamedPipeFile

Crea y abre el identificador de servidor de la primera instancia de una canalización con nombre específica u otra instancia de una canalización con nombre existente. La función devuelve un identificador que se puede usar para acceder a la canalización.

Sintaxis

NTSTATUS NtCreateNamedPipeFile(
  [out]          PHANDLE            FileHandle,
  [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,
  [in]           ULONG              InboundQuota,
  [in]           ULONG              OutboundQuota,
  [in, optional] PLARGE_INTEGER     DefaultTimeout
);

Parámetros

FileHandle [out]

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

DesiredAccess [in]

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

Marca	Descripción
Delete	El archivo se puede eliminar.
FILE_READ_DATA	Se pueden leer datos de este archivo.
FILE_READ_ATTRIBUTES	Las marcas FileAttributes, que se describen a continuación, se pueden leer.
FILE_READ_EA	Se pueden leer los atributos extendidos (EAs) asociados al archivo.
READ_CONTROL	Se puede leer la lista de control de acceso (ACL) y la información de propiedad asociada al archivo.
FILE_WRITE_DATA	En este archivo se pueden escribir datos.
FILE_WRITE_ATTRIBUTES	Se pueden escribir marcas fileAttributes.
FILE_WRITE_EA	Las entidades de certificación asociadas al archivo se pueden escribir.
FILE_APPEND_DATA	Los datos se pueden anexar al archivo.
WRITE_DAC	Se puede escribir la lista de control de acceso discrecional (DACL) asociada al archivo.
WRITE_OWNER	La información de propiedad asociada al archivo se puede escribir.
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 CreateOptionsFILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT .
FILE_EXECUTE	Los datos se pueden leer en la memoria del archivo mediante la E/S de paginación del sistema.

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 de 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.

Acceso deseado a los valores de archivo	Se asigna a las marcas DesiredAccess
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SYNCHRONIZE.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SYNCHRONIZE.
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, SYNCHRONIZE, FILE_READ_ATTRIBUTES, FILE_EXECUTE.

En el caso de los directorios (se establece la FILE_DIRECTORY_FILE marca CreateOptions), puede especificar una o varias de las marcas de ACCESS_MASK siguientes, que también puede combinar con las marcas compatibles descritas anteriormente.

Acceso deseado a los valores de directorio	Descripción
FILE_LIST_DIRECTORY	Los archivos del directorio se pueden enumerar.
FILE_TRAVERSE	Se puede recorrer el directorio; es decir, puede formar parte del nombre de ruta de acceso de un archivo.

Las FILE_READ_DATAmarcas , FILE_EXECUTEFILE_WRITE_DATA, y FILE_APPEND_DATADesiredAccess no son compatibles con la creación o apertura de un archivo de directorio.

ObjectAttributes [in]

Puntero a una OBJECT_ATTRIBUTES estructura ya inicializada por la rutina 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 OBJ_KERNEL_HANDLE atributo en la llamada a InitializeObjectAttributes.

Los miembros de esta estructura para un objeto de archivo incluyen lo siguiente:

Miembro	Valor
Longitud de ULONG	Número de bytes de los datos ObjectAttributes proporcionados . Este valor debe ser al menos sizeof(OBJECT_ATTRIBUTES).
PUNICODE_STRING ObjectName	Puntero a una cadena Unicode almacenada en búfer que contiene el nombre del archivo que se va a crear o abrir. Este valor debe ser una especificación de archivo completa, a menos que sea el nombre de un archivo relativo al directorio especificado por RootDirectory. Por ejemplo, "\Device\Floppy1\myfile.dat" o "?? \B:\myfile.dat" podría ser la especificación de archivo completa, siempre y cuando el controlador de la unidad de disco de disquete y el sistema de archivos que ya estén cargados. (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 NtCreateNamedPipeFile. Si este valor es NULL, el miembro ObjectName debe ser una especificación de archivo completa que incluya la ruta de acceso completa al archivo de destino. Si este valor no es NULL, el miembro ObjectName especifica un nombre de archivo relativo a este directorio.
PSECURITY_DESCRIPTOR SecurityDescriptor	Descriptor de seguridad opcional que se va a aplicar a un archivo. Las ACL especificadas por este descriptor de seguridad solo se aplican al archivo cuando se crea. Si el valor es NULL cuando se crea un archivo, la ACL colocada en el archivo depende del sistema de archivos; la mayoría de los sistemas de archivos propagan parte de este tipo de ACL desde el archivo de directorio primario combinado con la ACL predeterminada del autor de la llamada.
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 OBJ_KERNEL_HANDLE marca . El autor de la llamada también puede establecer opcionalmente la OBJ_CASE_INSENSITIVE marca , 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.

IoStatusBlock [out]

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

• FILE_CREATED
• FILE_OPENED
• FILE_OVERWRITTEN
• FILE_SUPERSEDED
• FILE_EXISTS
• FILE_DOES_NOT_EXIST

ShareAccess [in]

Especifica el tipo de acceso compartido al archivo que el autor de la llamada desea, como cero o uno, o una combinación de las marcas siguientes. Para solicitar acceso exclusivo, establezca este parámetro en cero. Para ayudarle a evitar errores de infracción de uso compartido, especifique todas las siguientes marcas de acceso a recursos compartidos.

Marcas de ShareAccess	Descripción
FILE_SHARE_READ	El archivo se puede abrir para el acceso de lectura mediante las llamadas de creación de archivos de otros subprocesos.
FILE_SHARE_WRITE	El archivo se puede abrir para el acceso de escritura mediante llamadas de creación de archivos de otros subprocesos.
FILE_SHARE_DELETE	El archivo se puede abrir para eliminar el acceso mediante llamadas de creación de archivos de otros subprocesos.

Los controladores de dispositivo y los controladores intermedios suelen establecer ShareAccess en cero, lo que proporciona al autor de la llamada acceso exclusivo al archivo abierto.

CreateDisposition [in]

Valor que determina cómo se debe controlar el archivo cuando el archivo ya existe. CreateDisposition puede ser uno de los siguientes:

Valor	Descripción
FILE_SUPERSEDE	Si el archivo ya existe, reemplácelo por el archivo especificado. Si no existe, cree el archivo especificado.
FILE_CREATE	Si el archivo ya existe, produzca un error en la solicitud y no cree o abra el archivo especificado. Si no existe, cree el archivo especificado.
FILE_OPEN	Si el archivo ya existe, ábralo en lugar de crear un archivo nuevo. Si no existe, produzca un error en la solicitud y no cree un nuevo archivo.
FILE_OPEN_IF	Si el archivo ya existe, ábralo. Si no existe, cree el archivo especificado.
FILE_OVERWRITE	Si el archivo ya existe, ábralo y sobrescriba. Si no existe, se producirá un error en la solicitud.
FILE_OVERWRITE_IF	Si el archivo ya existe, ábralo y sobrescriba. Si no existe, cree el archivo especificado.

CreateOptions [in]

Especifica las opciones que se van a aplicar al crear o abrir el archivo, como una combinación compatible de las marcas siguientes.

Marca CreateOptions	Descripción
FILE_DIRECTORY_FILE (0x00000001)	El archivo que se va a crear o abrir es un archivo de directorio. Con esta marca, el parámetro Disposition debe establecerse en uno de FILE_CREATE, FILE_OPENo FILE_OPEN_IF. Las marcas CreateOptions que son compatibles con esta marca son las siguientes: FILE_SYNCHRONOUS_IO_ALERT, , FILE_SYNCHRONOUS_IO_NONALERTFILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENTy FILE_OPEN_BY_FILE_ID.
FILE_WRITE_THROUGH (0x00000002)	Los servicios del sistema, los sistemas de archivos y los controladores que escriben datos en el archivo deben transferir realmente los datos al archivo antes de que se considere completada cualquier operación de escritura solicitada.
FILE_SEQUENTIAL_ONLY (0x00000004)	Todos los accesos al archivo serán secuenciales.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	El archivo no se puede almacenar en caché ni almacenar en búferes internos de un controlador. Esta marca no es compatible con la marca DesiredAccessFILE_APPEND_DATA .
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	Todas las operaciones del archivo 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 del archivo. Si se establece esta marca, también se debe establecer la marca DesiredAccessSYNCHRONIZE para que el Administrador de E/S use el objeto de archivo como un objeto de sincronización.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Todas las operaciones del archivo 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 DesiredAccessSYNCHRONIZE para que el Administrador de E/S use el objeto de archivo como un objeto de sincronización.
FILE_NON_DIRECTORY_FILE (0x00000040)	El archivo que se abre no debe ser un archivo de directorio o se produce un error en esta llamada. El objeto de archivo que se abre puede representar un archivo de datos; un dispositivo lógico, virtual o físico; o un volumen.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Cree una conexión de árbol para este archivo para abrirlo a través de la red.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Complete esta operación inmediatamente con un código correcto alternativo si el archivo de destino está bloqueado, en lugar de bloquear el subproceso del autor de la llamada. Si el archivo está interbloqueado, otro autor de la llamada ya tiene acceso al archivo a través de la red.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Si los atributos extendidos de un archivo existente que se abre indican que el autor de la llamada debe comprender los atributos extendidos para interpretar correctamente el archivo, produzca un error en esta solicitud porque el autor de la llamada no entiende cómo tratar con atributos extendidos.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Reservado para uso del sistema; no use.
FILE_RANDOM_ACCESS (0x00000800)	Los accesos al archivo pueden ser aleatorios, por lo que los sistemas de archivos o el sistema operativo no deben realizar operaciones de lectura anticipada secuenciales en el archivo.
FILE_DELETE_ON_CLOSE (0x00001000)	Elimine el archivo cuando se pase el último identificador a FltClose.
FILE_OPEN_BY_FILE_ID (0x00002000)	El archivo se abre mediante el identificador. El nombre de archivo contiene el nombre de un dispositivo y un identificador de 64 bits que se usará para abrir el archivo.
FILE_OPEN_FOR_BACKUP_INTENT (0x000004000)	El archivo se está abriendo para la intención de copia de seguridad; por lo tanto, el sistema debe comprobar ciertos derechos de acceso y conceder al autor de la llamada el acceso adecuado al archivo antes de comprobar la entrada DesiredAccess en el descriptor de seguridad del archivo.
FILE_NO_COMPRESSION (0x00008000)	Suprima la herencia del FILE_ATTRIBUTE_COMPRESSED directorio primario. Esto permite la creación de un archivo no comprimido en un directorio marcado como comprimido.
FILE_OPEN_REQUIRING_OPLOCK (0x00010000)	El archivo se está abriendo y se solicita un bloqueo oportunista (oplock) en el archivo como una única operación atómica. El sistema de archivos comprueba si hay interbloqueos antes de realizar la operación de creación y la operación de creación producirá un error con un código de retorno de si la operación de STATUS_CANNOT_BREAK_OPLOCK creación interrumpiría un interbloqueo existente. Esta marca está disponible en windows 7, Windows Server 2008 R2 y sistemas operativos Windows posteriores.
FILE_DISALLOW_EXCLUSIVE (0x00020000)	Al abrir un archivo existente, si FILE_SHARE_READ no se especifica y las comprobaciones de acceso del sistema de archivos no concederían al autor de la llamada acceso de escritura al archivo, no se pudo abrir con STATUS_ACCESS_DENIED. Este era el comportamiento predeterminado anterior a Windows 7.
FILE_SESSION_AWARE (0x00040000)	El archivo o dispositivo se abre con reconocimiento de sesión. Si no se especifica esta marca, los procesos que se ejecutan en la sesión 0 no pueden abrir los dispositivos por sesión (por ejemplo, un dispositivo mediante el redireccionamiento USB de RemoteFX). Esta marca no tiene ningún efecto para los autores de llamadas que no están en la sesión 0. Esta marca solo se admite en las ediciones de servidor de Windows. Esta marca no se admite antes de Windows Server 2012.
FILE_RESERVE_OPFILTER (0x00100000)	Esta marca permite a una aplicación solicitar un bloqueo oportunista de filtro (oplock) para evitar que otras aplicaciones obtengan infracciones de recursos compartidos. Si ya hay identificadores abiertos, se producirá un error en la solicitud de creación con STATUS_OPLOCK_NOT_GRANTED.
FILE_OPEN_REPARSE_POINT (0x00200000)	Abra un archivo con un punto de reanálisis y omita el procesamiento normal del punto de reanálisis para el archivo. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
FILE_OPEN_NO_RECALL (0x00400000)	Indica a los filtros que realizan almacenamiento sin conexión o virtualización que no recuerden el contenido del archivo como resultado de esta apertura.
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000)	Esta marca indica al sistema de archivos que capture el usuario asociado al subproceso que llama. Las llamadas posteriores a FltQueryVolumeInformation o ZwQueryVolumeInformationFile mediante el identificador devuelto asumen que el usuario capturado, en lugar del usuario que realiza la llamada en el momento, con el fin de calcular el espacio libre disponible para el autor de la llamada. Esto se aplica a los siguientes valores de FsInformationClass : FileFsSizeInformation, FileFsFullSizeInformationy FileFsFullSizeInformationEx.

NamedPipeType [in]

Tipo de canalización con nombre que se va a crear (tipo de byte o tipo de mensaje).

ReadMode [in]

Modo en el que se va a leer la canalización (tipo de byte o tipo de mensaje).

CompletionMode [in]

Especifica cómo se va a completar la operación.

MaximumInstances [in]

Número máximo de instancias simultáneas de la canalización con nombre.

InboundQuota [in]

Especifica la cuota de grupo reservada para escrituras en el lado entrante de la canalización con nombre.

OutboundQuota [in]

Especifica la cuota de grupo reservada para escrituras en el lado entrante de la canalización con nombre.

DefaultTimeout [in, opcional]

Puntero opcional a un valor de tiempo de espera que se usa si no se especifica un valor de tiempo de espera al esperar una instancia de una canalización con nombre.

Devoluciones

El valor de la función es el estado final de la operación de creación y apertura.

Comentarios

Para crear una instancia de una canalización con nombre, el usuario debe tener FILE_CREATE_PIPE_INSTANCE acceso al objeto de canalización con nombre. Si se crea una canalización con nombre, la lista de control de acceso (ACL) del parámetro de atributos de seguridad define el control de acceso discrecional para la canalización con nombre.

Todas las instancias de una canalización con nombre deben especificar el mismo tipo de canalización (tipo de byte o tipo de mensaje), acceso de canalización (dúplex, entrante o saliente), recuento de instancias y valor de tiempo de espera. Si se usan valores diferentes, se produce un error en esta función y GetLastError devuelve ERROR_ACCESS_DENIED.

Un proceso de cliente se conecta a una canalización con nombre mediante la función CreateFile o CallNamedPipe . El lado cliente de una canalización con nombre comienza en modo de bytes, incluso si el lado servidor está en modo de mensaje. Para evitar problemas al recibir datos, establezca también el lado cliente en modo de mensaje. Para cambiar el modo de la canalización, el cliente de canalización debe abrir una canalización de solo lectura con GENERIC_READ y acceso FILE_WRITE_ATTRIBUTES .

El servidor de canalización no debe realizar una operación de lectura de bloqueo hasta que se haya iniciado el cliente de canalización. De lo contrario, se puede producir una condición de carrera. Esto suele ocurrir cuando el código de inicialización, como el tiempo de ejecución de C, debe bloquear y examinar los identificadores heredados.

Cada vez que se crea una canalización con nombre, el sistema crea los búferes entrantes o salientes mediante un grupo no paginado, que es la memoria física utilizada por el kernel. El número de instancias de canalización (así como objetos como subprocesos y procesos) que puede crear está limitado por el grupo no paginado disponible. Cada solicitud de lectura o escritura requiere espacio en el búfer para los datos de lectura o escritura, además de espacio adicional para las estructuras de datos internas.

Los tamaños del búfer de entrada y salida son avisos. El tamaño real del búfer reservado para cada extremo de la canalización con nombre es el valor predeterminado del sistema, el mínimo o máximo del sistema, o el tamaño especificado redondeado hasta el siguiente límite de asignación. El tamaño del búfer especificado debe ser lo suficientemente pequeño como para que el proceso no se quede sin grupo de páginas, pero lo suficientemente grande como para dar cabida a las solicitudes típicas.

Cada vez que se produce una operación de escritura de canalización, el sistema intenta cargar primero la memoria con la cuota de escritura de canalización. Si la cuota de escritura de canalización restante es suficiente para cumplir la solicitud, la operación de escritura se completa inmediatamente. Si la cuota de escritura de canalización restante es demasiado pequeña para cumplir la solicitud, el sistema intentará expandir los búferes para dar cabida a los datos mediante el grupo no paginado reservado para el proceso. La operación de escritura se bloqueará hasta que se lean los datos de la canalización para que se pueda liberar la cuota de búfer adicional. Por lo tanto, si el tamaño del búfer especificado es demasiado pequeño, el sistema aumentará el búfer según sea necesario, pero la desventaja es que la operación se bloqueará. Si la operación se superpone, se bloquea un subproceso del sistema; de lo contrario, se bloquea el subproceso de la aplicación.

Para liberar recursos usados por una canalización con nombre, la aplicación siempre debe cerrar los identificadores cuando ya no sean necesarios, lo que se logra llamando a la función CloseHandle o cuando finaliza el proceso asociado con los identificadores de instancia. Tenga en cuenta que una instancia de una canalización con nombre puede tener más de un identificador asociado. Una instancia de una canalización con nombre siempre se elimina cuando se cierra el último identificador de la instancia de la canalización con nombre.

Requisitos

Requisito	Value
Encabezado	ntioapi.h
Biblioteca	ntdll.lib