Função ConnectNamedPipe (namedpipeapi.h)

Permite que um processo de servidor de pipe nomeado aguarde um processo de cliente se conectar a uma instância de um pipe nomeado. Um processo de cliente se conecta chamando a função CreateFile ou CallNamedPipe.

Sintaxe

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

Parâmetros

[in] hNamedPipe

Um identificador para o final do servidor de uma instância de pipe nomeada. Esse identificador é retornado pela função CreateNamedPipe.

[in, out, optional] lpOverlapped

Um ponteiro para uma estrutura de OVERLAPPED.

Se hNamedPipe foi aberto com FILE_FLAG_OVERLAPPED, o parâmetro lpOverlapped não deve ser NULL. Ele deve apontar para uma estrutura de OVERLAPPED válida. Se hNamedPipe foi aberto com FILE_FLAG_OVERLAPPED e lpOverlapped é NULL, a função pode relatar incorretamente que a operação de conexão está concluída.

Se hNamedPipe foi criado com FILE_FLAG_OVERLAPPED e lpOverlapped não é NULL, a estrutura de OVERLAPPED deve conter um identificador para um objeto de evento de redefinição manual (que o servidor pode criar usando a função CreateEvent).

Se hNamedPipe não tiver sido aberto com FILE_FLAG_OVERLAPPED, a função não retornará até que um cliente esteja conectado ou ocorra um erro. Operações síncronas bem-sucedidas resultam na função retornando um valor diferente de zero se um cliente se conectar após a função ser chamada.

Valor de retorno

Se a operação for síncrona, ConnectNamedPipe não retornará até que a operação seja concluída. Se a função for bem-sucedida, o valor retornado não será zero. Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Se a operação for assíncrona, ConnectNamedPipe retornará imediatamente. Se a operação ainda estiver pendente, o valor retornado será zero e GetLastError retornará ERROR_IO_PENDING. (Você pode usar a macro HasOverlappedIoCompleted para determinar quando a operação foi concluída.) Se a função falhar, o valor retornado será zero e GetLastError retornará um valor diferente de ERROR_IO_PENDING ou ERROR_PIPE_CONNECTED.

Se um cliente se conectar antes da função ser chamada, a função retornará zero e GetLastError retornará ERROR_PIPE_CONNECTED. Isso pode acontecer se um cliente se conectar no intervalo entre a chamada para CreateNamedPipe e a chamada para ConnectNamedPipe. Nessa situação, há uma boa conexão entre o cliente e o servidor, mesmo que a função retorne zero.

Observações

Um processo de servidor de pipe nomeado pode usar ConnectNamedPipe com uma instância de pipe recém-criada. Ele também pode ser usado com uma instância que foi conectada anteriormente a outro processo de cliente; nesse caso, o processo do servidor deve primeiro chamar a função DisconnectNamedPipe para desconectar o identificador do cliente anterior antes que o identificador possa ser reconectado a um novo cliente. Caso contrário, ConnectNamedPipe retornará zero e GetLastError retornará ERROR_NO_DATA se o cliente anterior tiver fechado seu identificador ou ERROR_PIPE_CONNECTED se não tiver fechado o identificador.

O comportamento de ConnectNamedPipe depende de duas condições: se o modo de espera do identificador de pipe está definido como bloqueio ou não e se a função está definida para ser executada de forma síncrona ou em modo sobreposto. Um servidor especifica inicialmente o modo de espera de um identificador de pipe na função CreateNamedPipe e pode ser alterado usando a função SetNamedPipeHandleState.

O processo do servidor pode usar qualquer uma das funções de espera ou SleepEx – para determinar quando o estado do objeto de evento é sinalizado e, em seguida, pode usar a macro HasOverlappedIoCompleted para determinar quando a operação ConnectNamedPipe é concluída.

Se o identificador de pipe especificado estiver no modo de não desbloqueio, ConnectNamedPipe sempre retornará imediatamente. No modo de não desbloqueio, ConnectNamedPipe retorna um valor diferente de zero na primeira vez que é chamado para uma instância de pipe desconectada de um cliente anterior. Isso indica que o pipe agora está disponível para ser conectado a um novo processo de cliente. Em todas as outras situações em que o identificador de pipe está no modo sem bloqueio, ConnectNamedPipe retorna zero. Nessas situações, GetLastError retornará ERROR_PIPE_LISTENING se nenhum cliente estiver conectado, ERROR_PIPE_CONNECTED se um cliente estiver conectado e ERROR_NO_DATA se um cliente anterior tiver fechado seu identificador de pipe, mas o servidor não tiver se desconectado. Observe que existe uma boa conexão entre o cliente e o servidor somente após o erro de ERROR_PIPE_CONNECTED ser recebido.

Observação modo de não bloqueio tem suporte para compatibilidade com o Microsoft LAN Manager versão 2.0 e não deve ser usado para obter entrada e saída assíncronas (E/S) com pipes nomeados.

 

Windows 10, versão 1709 e posterior: Pipes não podem ser usados para se comunicar entre contêineres de aplicativo; ou seja, de um processo UWP para outro processo UWP que não faz parte do mesmo aplicativo. Além disso, pipes nomeados dentro de contêineres de aplicativo devem usar a sintaxe '\\.\pipe\LOCAL\' para o nome do pipe.

Exemplos

Para obter um exemplo, consulte servidor de pipe multithreaded.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
servidor com suporte mínimo	Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	namedpipeapi.h
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

CallNamedPipe

CreateEvent

CreateFile

CreateNamedPipe

DisconnectNamedPipe

GetOverlappedResult

SOBREPOSTOS

Funções de pipe

Visão geral do Pipes

SetNamedPipeHandleState

SleepEx