Función CreateNamedPipeA (winbase.h)
Crea una instancia de una canalización con nombre y devuelve un identificador para las operaciones posteriores de canalización. 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 distinto de 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.
| Modo | 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 del cliente al 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 solo va 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 |
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.
| Modo | 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 la operación que consume mucho tiempo se ejecuta 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 ReadFile, WriteFile, ConnectNamedPipey las funciones 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.
[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.
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. Las distintas instancias de la misma canalización pueden especificar diferentes modos de espera.
| Modo | Significado |
|---|---|
|
El modo de bloqueo está habilitado. Cuando se especifica el identificador de canalización en la ReadFile, WriteFileo función 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, WriteFiley 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. Las distintas 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.
Observaciones
Para crear una instancia de una canalización con nombre mediante CreateNamedPipe, el usuario debe tener acceso FILE_CREATE_PIPE_INSTANCE 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 bytes 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, esta función produce un error y GetLastError devuelve ERROR_ACCESS_DENIED.
Un proceso de cliente se conecta a una canalización con nombre mediante la función
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 usada 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 ejecute en un 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 en 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 un 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, el subproceso de la aplicación está bloqueado.
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 a los identificadores de instancia. Tenga en cuenta que una instancia de una canalización con nombre puede tener más de un identificador asociado. Siempre se elimina una instancia de una canalización con nombre cuando se cierra el último identificador de la instancia de la canalización con nombre.
Windows 10, versión 1709: Canalizaciones solo se admiten en un contenedor de aplicaciones; Es decir, de 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 canalización.
Ejemplos
Para obtener un ejemplo, vea servidor de canalización multiproceso.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows 2000 Professional [aplicaciones de escritorio | Aplicaciones para UWP] |
| servidor mínimo admitido | Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP] |
| de la plataforma de destino de |
Windows |
| encabezado de |
winbase.h (incluya Windows.h) |
| biblioteca de |
Kernel32.lib |
| DLL de |
Kernel32.dll |
Consulte también
funciones de canalización de
de información general de canalizaciones de