Función ConnectNamedPipe (namedpipeapi.h)

Artículo
08/25/2023

Permite que un proceso de servidor de canalización con nombre espere a que un proceso de cliente se conecte a una instancia de una canalización con nombre. Un proceso de cliente se conecta mediante una llamada a la función CreateFile o CallNamedPipe .

Sintaxis

BOOL ConnectNamedPipe(
  [in]                HANDLE       hNamedPipe,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Parámetros

[in] hNamedPipe

Identificador del extremo del servidor de una instancia de canalización con nombre. La función CreateNamedPipe devuelve este identificador.

[in, out, optional] lpOverlapped

Puntero a una estructura OVERLAPPED.

Si hNamedPipe se abrió con FILE_FLAG_OVERLAPPED, el parámetro lpOverlapped no debe ser NULL. Debe apuntar a una estructura SUPERPUESTA válida. Si hNamedPipe se abrió con FILE_FLAG_OVERLAPPED y lpOverlapped es NULL, la función puede informar incorrectamente de que se ha completado la operación de conexión.

Si hNamedPipe se creó con FILE_FLAG_OVERLAPPED y lpOverlapped no es NULL, la estructura SUPERPUESTA debe contener un identificador para un objeto de evento de restablecimiento manual (que el servidor puede crear mediante la función CreateEvent ).

Si hNamedPipe no se abrió con FILE_FLAG_OVERLAPPED, la función no devuelve hasta que un cliente está conectado o se produce un error. Las operaciones sincrónicas correctas provocan que la función devuelva un valor distinto de cero si un cliente se conecta después de llamar a la función.

Valor devuelto

Si la operación es sincrónica, ConnectNamedPipe no devuelve hasta que se haya completado la operación. Si la función se realiza correctamente, el valor devuelto es distinto de cero. Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Si la operación es asincrónica, ConnectNamedPipe devuelve inmediatamente. Si la operación sigue pendiente, el valor devuelto es cero y GetLastError devuelve ERROR_IO_PENDING. (Puede usar la macro HasOverlappedIoCompleted para determinar cuándo ha finalizado la operación). Si se produce un error en la función, el valor devuelto es cero y GetLastError devuelve un valor distinto de ERROR_IO_PENDING o ERROR_PIPE_CONNECTED.

Si un cliente se conecta antes de llamar a la función, la función devuelve cero y GetLastError devuelve ERROR_PIPE_CONNECTED. Esto puede ocurrir si un cliente se conecta en el intervalo entre la llamada a CreateNamedPipe y la llamada a ConnectNamedPipe. En esta situación, hay una buena conexión entre el cliente y el servidor, aunque la función devuelve cero.

Comentarios

Un proceso de servidor de canalización con nombre puede usar ConnectNamedPipe con una instancia de canalización recién creada. También se puede usar con una instancia que se conectó previamente a otro proceso de cliente; en este caso, el proceso del servidor primero debe llamar a la función DisconnectNamedPipe para desconectar el identificador del cliente anterior antes de que el identificador se pueda volver a conectar a un nuevo cliente. De lo contrario, ConnectNamedPipe devuelve cero y GetLastError devuelve ERROR_NO_DATA si el cliente anterior ha cerrado su identificador o ERROR_PIPE_CONNECTED si no ha cerrado su identificador.

El comportamiento de ConnectNamedPipe depende de dos condiciones: si el modo de espera del controlador de canalización está establecido en bloqueo o no de bloqueo y si la función se establece para ejecutarse de forma sincrónica o en modo superpuesto. Un servidor especifica inicialmente el modo de espera de un identificador de canalización en la función CreateNamedPipe y se puede cambiar mediante la función SetNamedPipeHandleState .

El proceso de servidor puede usar cualquiera de las funciones de espera o SleepEx: para determinar cuándo se señala el estado del objeto de evento y, a continuación, puede usar la macro HasOverlappedIoCompleted para determinar cuándo se completa la operación ConnectNamedPipe .

Si el identificador de canalización especificado está en modo sin bloqueo, ConnectNamedPipe siempre devuelve inmediatamente. En el modo sin bloqueo, ConnectNamedPipe devuelve un valor distinto de cero la primera vez que se llama para una instancia de canalización que está desconectada de un cliente anterior. Esto indica que la canalización ahora está disponible para conectarse a un nuevo proceso de cliente. En todas las demás situaciones en las que el identificador de canalización está en modo de bloqueo, ConnectNamedPipe devuelve cero. En estas situaciones, GetLastError devuelve ERROR_PIPE_LISTENING si no hay ningún cliente conectado, ERROR_PIPE_CONNECTED si un cliente está conectado y ERROR_NO_DATA si un cliente anterior ha cerrado su identificador de canalización, pero el servidor no se ha desconectado. Tenga en cuenta que solo existe una buena conexión entre el cliente y el servidor después de recibir el error ERROR_PIPE_CONNECTED.

Nota El modo de no bloqueo es compatible con Microsoft LAN Manager versión 2.0 y no debe usarse para lograr entradas y salidas asincrónicas (E/S) con canalizaciones 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, vea 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	namedpipeapi.h
Library	Kernel32.lib
Archivo DLL	Kernel32.dll