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

Статья
03/08/2023

Позволяет процессу сервера именованного канала ожидать подключения клиентского процесса к экземпляру именованного канала. Клиентский процесс подключается путем вызова функции 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 и lpOverlapped имеет значение NULL, функция может неправильно сообщить о завершении операции подключения.

Если 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 и не должна использоваться для асинхронного ввода-вывода (I/O) с именованными каналами.

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

Примеры

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	namedpipeapi.h
Библиотека	Kernel32.lib
DLL	Kernel32.dll