Функция ConnectNamedPipe (namedpipeapi.h)

Статья
11/20/2024

Позволяет серверу именованного канала ожидать подключения клиентского процесса к экземпляру именованного канала. Процесс клиента подключается путем вызова функции CreateFile или CallNamedPipe.

Синтаксис

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

Параметры

[in] hNamedPipe

Дескриптор к концу сервера именованного экземпляра канала. Этот дескриптор возвращается функцией CreateNamedPipe.

[in, out, optional] lpOverlapped

Указатель на структуру OVERLAPPED.

Если hNamedPipe открыт с FILE_FLAG_OVERLAPPED, параметр lpOverlapped не должен быть NULL. Он должен указывать на допустимую структуру OVERLAPPED. Если hNamedPipe был открыт с FILE_FLAG_OVERLAPPED и lpOverlappedNULL, функция может неправильно сообщить о завершении операции подключения.

Если hNamedPipe создан с FILE_FLAG_OVERLAPPED и lpOverlapped не NULL, структура OVERLAPPED должна содержать дескриптор объекта события ручного сброса (который сервер может создать с помощью функции CreateEvent).

Если hNamedPipe не был открыт с FILE_FLAG_OVERLAPPED, функция не возвращается до подключения клиента или возникновения ошибки. Успешные синхронные операции приводят к возврату ненулевого значения, если клиент подключается после вызова функции.

Возвращаемое значение

Если операция синхронна, ConnectNamedPipe не возвращается до завершения операции. Если функция выполнена успешно, возвращаемое значение ненулевое. Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Если операция асинхронна, ConnectNamedPipe немедленно возвращается. Если операция по-прежнему ожидается, возвращаемое значение равно нулю и GetLastError возвращает ERROR_IO_PENDING. (Макрос HasOverlappedIoCompleted можно использовать для определения завершения операции.) Если функция завершается ошибкой, возвращаемое значение равно нулю и GetLastError возвращает значение, отличное от ERROR_IO_PENDING или ERROR_PIPE_CONNECTED.

Если клиент подключается перед вызовом функции, функция возвращает ноль и GetLastError возвращает ERROR_PIPE_CONNECTED. Это может произойти, если клиент подключается в интервале между вызовом CreateNamedPipe и вызовом ConnectNamedPipe. В этой ситуации существует хорошее соединение между клиентом и сервером, даже если функция возвращает ноль.

Замечания

Процесс сервера именованного канала может использовать ConnectNamedPipe с новым экземпляром канала. Его также можно использовать с экземпляром, который ранее был подключен к другому клиентскому процессу; В этом случае серверный процесс должен сначала вызвать функцию DisconnectNamedPipe, чтобы отключить дескриптор от предыдущего клиента, прежде чем дескриптор можно будет повторно подключиться к новому клиенту. В противном случае ConnectNamedPipe возвращает ноль, и GetLastError возвращает ERROR_NO_DATA, если предыдущий клиент закрыл дескриптор или ERROR_PIPE_CONNECTED, если он не закрыл его дескриптор.

Поведение ConnectNamedPipe зависит от двух условий: устанавливается ли режим ожидания дескриптора канала блокировку или неблокировку, а также возможность выполнения функции синхронно или в перекрывающемся режиме. Сервер изначально задает режим ожидания дескриптора канала в функции CreateNamedPipe, и его можно изменить с помощью функции SetNamedPipeHandleState.

Серверный процесс может использовать любой из функций ожидания или SleepEx— чтобы определить, когда сигнализирует о состоянии объекта события, а затем использовать макрос HasOverlappedIoCompleted, чтобы определить, когда выполняется операция ConnectNamedPipe.

Если указанный дескриптор канала находится в режиме неблокировки, ConnectNamedPipe всегда возвращается немедленно. В режиме неблокировки ConnectNamedPipe возвращает ненулевое значение при первом вызове экземпляра канала, отключенного от предыдущего клиента. Это означает, что канал теперь доступен для подключения к новому клиентскому процессу. Во всех других ситуациях, когда дескриптор канала находится в режиме неблокировки, ConnectNamedPipe возвращает ноль. В этих ситуациях GetLastError возвращает ERROR_PIPE_LISTENING, если клиент не подключен, ERROR_PIPE_CONNECTED, если клиент подключен, и ERROR_NO_DATA, если предыдущий клиент закрыл его дескриптор канала, но сервер не отключен. Обратите внимание, что хорошее подключение между клиентом и сервером существует только после получения ошибки ERROR_PIPE_CONNECTED.

Примечание режим неблокировки поддерживается для совместимости с Microsoft LAN Manager версии 2.0, и его не следует использовать для достижения асинхронных входных и выходных данных (ввода-вывода) с именованными каналами.

Windows 10 версии 1709 и более поздних версий: каналы нельзя использовать для обмена данными между контейнерами приложений; Т. е. из одного процесса UWP в другой процесс UWP, который не входит в одно и то же приложение. Кроме того, именованные каналы в контейнерах приложений должны использовать синтаксис "\\.\pipe\LOCAL\" для имени канала.

Примеры

Пример см. в разделе Многопоточный сервер канала.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows 2000 Server [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	namedpipeapi.h
библиотеки	Kernel32.lib
DLL	Kernel32.dll