Función CreateNamedPipeA (winbase.h)
Crea una instancia de una canalización con nombre y devuelve un identificador para las operaciones de canalización posteriores. Un proceso de servidor de canalización con nombre usa esta función para crear la primera instancia de una canalización con nombre específica y establecer sus atributos básicos o para crear una nueva instancia de una canalización con nombre existente.
Sintaxis
HANDLE CreateNamedPipeA(
[in] LPCSTR lpName,
[in] DWORD dwOpenMode,
[in] DWORD dwPipeMode,
[in] DWORD nMaxInstances,
[in] DWORD nOutBufferSize,
[in] DWORD nInBufferSize,
[in] DWORD nDefaultTimeOut,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);
Parámetros
[in] lpName
Nombre de canalización único. Esta cadena debe tener el siguiente formato:
\\.\pipe\pipename
La parte pipename del nombre puede incluir cualquier carácter que no sea una barra diagonal inversa, incluidos números y caracteres especiales. Toda la cadena de nombre de canalización puede tener hasta 256 caracteres. Los nombres de canalización no distinguen mayúsculas de minúsculas.
[in] dwOpenMode
Modo abierto.
Se produce un error en la función si dwOpenMode especifica algo distinto de 0 o las marcas enumeradas en las tablas siguientes.
Este parámetro debe especificar uno de los siguientes modos de acceso de canalización. Se debe especificar el mismo modo para cada instancia de la canalización.
| Mode | Significado |
|---|---|
|
La tubería es bidireccional; Tanto los procesos de servidor como de cliente pueden leer y escribir en la canalización. Este modo proporciona al servidor el equivalente de GENERIC_READ y GENERIC_WRITE acceso a la canalización. El cliente puede especificar GENERIC_READ o GENERIC_WRITE, o ambos, cuando se conecta a la canalización mediante la función CreateFile . |
|
El flujo de datos de la canalización solo va de cliente a servidor. Este modo proporciona al servidor el equivalente de GENERIC_READ acceso a la canalización. El cliente debe especificar GENERIC_WRITE acceso al conectarse a la canalización. Si el cliente debe leer la configuración de canalización llamando a las funciones GetNamedPipeInfo o GetNamedPipeHandleState , el cliente debe especificar GENERIC_WRITE y FILE_READ_ATTRIBUTES acceso al conectarse a la canalización. |
|
El flujo de datos de la canalización va solo del servidor al cliente. Este modo proporciona al servidor el equivalente de GENERIC_WRITE acceso a la canalización. El cliente debe especificar GENERIC_READ acceso al conectarse a la canalización. Si el cliente debe cambiar la configuración de canalización llamando a la función SetNamedPipeHandleState , el cliente debe especificar GENERIC_READ y FILE_WRITE_ATTRIBUTES acceso al conectarse a la canalización. |
Este parámetro también puede incluir una o varias de las marcas siguientes, que permiten los modos de escritura a través y superpuestos. Estos modos pueden ser diferentes para diferentes instancias de la misma canalización.
| Mode | Significado |
|---|---|
|
Si intenta crear varias instancias de una canalización con esta marca, la creación de la primera instancia se realiza correctamente, pero se produce un error en la creación de la siguiente instancia con ERROR_ACCESS_DENIED. |
|
El modo de escritura a través está habilitado. Este modo solo afecta a las operaciones de escritura en canalizaciones de tipo byte y, a continuación, solo cuando los procesos de cliente y servidor están en equipos diferentes. Si este modo está habilitado, las funciones que escriben en una canalización con nombre no devuelven hasta que los datos escritos se transmiten a través de la red y se encuentra en el búfer de la canalización en el equipo remoto. Si este modo no está habilitado, el sistema mejora la eficacia de las operaciones de red almacenando en búfer los datos hasta que se acumula un número mínimo de bytes o hasta que transcurre un tiempo máximo. |
|
El modo superpuesto está habilitado. Si este modo está habilitado, las funciones que realizan operaciones de lectura, escritura y conexión que pueden tardar un tiempo significativo en completarse pueden devolverse inmediatamente. Este modo permite que el subproceso que inició la operación realice otras operaciones mientras se ejecuta la operación con mucho tiempo en segundo plano. Por ejemplo, en modo superpuesto, un subproceso puede controlar las operaciones simultáneas de entrada y salida (E/S) en varias instancias de una canalización o realizar operaciones simultáneas de lectura y escritura en el mismo identificador de canalización. Si el modo superpuesto no está habilitado, las funciones que realizan operaciones de lectura, escritura y conexión en el identificador de canalización no devuelven hasta que finalice la operación. Las funciones ReadFileEx y WriteFileEx solo se pueden usar con un identificador de canalización en modo superpuesto. Las funciones ReadFile, WriteFile, ConnectNamedPipe y TransactNamedPipe pueden ejecutarse de forma sincrónica o como operaciones superpuestas. |
Este parámetro puede incluir cualquier combinación de los siguientes modos de acceso de seguridad. Estos modos pueden ser diferentes para diferentes instancias de la misma canalización.
| Mode | Significado |
|---|---|
|
El autor de la llamada tendrá acceso de escritura a la lista de control de acceso discrecional (ACL) de la canalización con nombre. |
|
El autor de la llamada tendrá acceso de escritura al propietario de la canalización con nombre. |
|
El autor de la llamada tendrá acceso de escritura a la SACL de la canalización con nombre. Para obtener más información, consulte Access-Control Listas (ACL) y Derecho de acceso SACL. |
[in] dwPipeMode
Modo de canalización.
Se produce un error en la función si dwPipeMode especifica algo distinto de 0 o las marcas enumeradas en las tablas siguientes.
Se puede especificar uno de los siguientes modos de tipo. Se debe especificar el mismo modo de tipo para cada instancia de la canalización.
| Mode | Significado |
|---|---|
|
Los datos se escriben en la canalización como un flujo de bytes. Este modo no se puede usar con PIPE_READMODE_MESSAGE. La canalización no distingue bytes escritos durante diferentes operaciones de escritura. |
|
Los datos se escriben en la canalización como un flujo de mensajes. La canalización trata los bytes escritos durante cada operación de escritura como una unidad de mensaje. La función GetLastError devuelve ERROR_MORE_DATA cuando un mensaje no se lee completamente. Este modo se puede usar con PIPE_READMODE_MESSAGE o PIPE_READMODE_BYTE. |
Se puede especificar uno de los siguientes modos de lectura. Las distintas instancias de la misma canalización pueden especificar diferentes modos de lectura.
Se puede especificar uno de los siguientes modos de espera. Diferentes instancias de la misma canalización pueden especificar diferentes modos de espera.
| Mode | Significado |
|---|---|
|
El modo de bloqueo está habilitado. Cuando el identificador de canalización se especifica en la función ReadFile, WriteFile o ConnectNamedPipe , las operaciones no se completan hasta que haya datos para leer, se escriben todos los datos o se conecta un cliente. El uso de este modo puede significar esperar indefinidamente en algunas situaciones para que un proceso de cliente realice una acción. |
|
El modo de no bloqueo está habilitado. En este modo, ReadFile, WriteFile y ConnectNamedPipe siempre se devuelven inmediatamente.
Tenga en cuenta que el modo de no bloqueo es compatible con microsoft LAN Manager versión 2.0 y no debe usarse para lograr E/S asincrónica con canalizaciones con nombre. Para obtener más información sobre la E/S de canalización asincrónica, consulte Entrada y salida sincrónicas y superpuestas. |
Se puede especificar uno de los siguientes modos de cliente remoto. Diferentes instancias de la misma canalización pueden especificar diferentes modos de cliente remoto.
[in] nMaxInstances
Número máximo de instancias que se pueden crear para esta canalización. La primera instancia de la canalización puede especificar este valor; se debe especificar el mismo número para otras instancias de la canalización. Los valores aceptables están en el intervalo de 1 a PIPE_UNLIMITED_INSTANCES (255).
Si este parámetro es PIPE_UNLIMITED_INSTANCES, el número de instancias de canalización que se pueden crear solo está limitada por la disponibilidad de los recursos del sistema. Si nMaxInstances es mayor que PIPE_UNLIMITED_INSTANCES, el valor devuelto es INVALID_HANDLE_VALUE y GetLastError devuelve ERROR_INVALID_PARAMETER.
[in] nOutBufferSize
Número de bytes que se van a reservar para el búfer de salida. Para obtener una explicación sobre el ajuste de tamaño de los búferes de canalización con nombre, consulte la siguiente sección Comentarios.
[in] nInBufferSize
Número de bytes que se van a reservar para el búfer de entrada. Para obtener una explicación sobre el ajuste de tamaño de los búferes de canalización con nombre, consulte la siguiente sección Comentarios.
[in] nDefaultTimeOut
Valor de tiempo de espera predeterminado, en milisegundos, si la función WaitNamedPipe especifica NMPWAIT_USE_DEFAULT_WAIT. Cada instancia de una canalización con nombre debe especificar el mismo valor.
Un valor de cero dará como resultado un tiempo de espera predeterminado de 50 milisegundos.
[in, optional] lpSecurityAttributes
Puntero a una estructura de SECURITY_ATTRIBUTES que especifica un descriptor de seguridad para la nueva canalización con nombre y determina si los procesos secundarios pueden heredar el identificador devuelto. Si lpSecurityAttributes es NULL, la canalización con nombre obtiene un descriptor de seguridad predeterminado y el identificador no se puede heredar. Las ACL del descriptor de seguridad predeterminado para una canalización con nombre conceden control total a la cuenta localSystem, los administradores y el propietario del creador. También conceden acceso de lectura a los miembros del grupo Todos y a la cuenta anónima.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es un identificador para el extremo del servidor de una instancia de canalización con nombre.
Si se produce un error en la función, el valor devuelto es INVALID_HANDLE_VALUE. Para obtener información de error extendida, llame a GetLastError.
Comentarios
Para crear una instancia de una canalización con nombre mediante CreateNamedPipe, 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 no paginado, 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.
Windows 10, versión 1709: las canalizaciones solo se admiten en un contenedor de aplicaciones; es decir, desde un proceso de UWP a otro proceso de UWP que forma parte de la misma aplicación. Además, las canalizaciones con nombre deben usar la sintaxis \\.\pipe\LOCAL\ para el nombre de la canalización.
Ejemplos
Para obtener un ejemplo, consulte Servidor de canalización multiproceso.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000 Professional [aplicaciones de escritorio | Aplicaciones para UWP] |
| Servidor mínimo compatible | Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | winbase.h (incluya Windows.h) |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |
Vea también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de