Función ConnectNamedPipe (namedpipeapi.h)

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 llamando 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. Este identificador lo devuelve la función CreateNamedPipe.

[in, out, optional] lpOverlapped

Puntero a una estructura SUPERPUESTA.

Si hNamedPipe se abrió con FILE_FLAG_OVERLAPPED, el parámetro lpOverlapped no debe ser null. Debe apuntar a una estructura de SUPERPUESTA válida. Si hNamedPipe se abrió con FILE_FLAG_OVERLAPPED y lpOverlapped es NULL, la función puede notificar incorrectamente 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 se conecta un cliente 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 ejecuta correctamente, el valor devuelto es distinto de cero. Si se produce un error en la función, 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.

Observaciones

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ó anteriormente a otro proceso de cliente; en este caso, el proceso de 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 bloquear o no bloquear y si la función está establecida para ejecutarse de forma sincrónica o en modo superpuesto. Inicialmente, un servidor especifica el modo de espera de un controlador de canalización en la función createNamedPipe de y se puede cambiar mediante la función SetNamedPipeHandleState .

El proceso de servidor puede usar cualquiera de las funciones de espera de 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 de no bloqueo, ConnectNamedPipe siempre devuelve inmediatamente. En el modo de no 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 controlador 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 existe una buena conexión entre el cliente y el servidor solo después de recibir el error ERROR_PIPE_CONNECTED.

Nota modo de no bloqueo es compatible con la versión 2.0 de Microsoft LAN Manager y no debe usarse para lograr entradas y salidas asincrónicas (E/S) con canalizaciones con nombre.

 

Windows 10, versión 1709 y posteriores: no se pueden usar canalizaciones de para comunicarse entre contenedores de aplicaciones; Es decir, de un proceso de UWP a otro proceso de UWP que no forma parte de la misma aplicación. Además, las canalizaciones con nombre dentro de app-containers 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	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	namedpipeapi.h
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll

Consulte también

callNamedPipe

CreateEvent

CreateFile

CreateNamedPipe

disconnectNamedPipe

GetOverlappedResult

SUPERPUESTAs

funciones de canalización de

de información general de canalizaciones de

SetNamedPipeHandleState

sleepEx