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