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

Se hNamedPipe foi aberto com FILE_FLAG_OVERLAPPED, o parâmetro lpOverlapped não deve ser NULL. Ele deve apontar para uma estrutura 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 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.

Retornar valor

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 será diferente de 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.

Comentários

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 ele não tiver fechado seu identificador.

O comportamento do 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 no 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 em 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 o identificador de pipe, mas o servidor não tiver se desconectado. Observe que uma boa conexão entre o cliente e o servidor existe somente após o erro de ERROR_PIPE_CONNECTED ser recebido.

Nota O modo de não desbloqueio 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: só há suporte para pipes em um contêiner de aplicativo; ou seja, de um processo UWP para outro processo UWP que faz parte do mesmo aplicativo. Além disso, os pipes nomeados devem usar a sintaxe "\\.\pipe\LOCAL\" para o nome do pipe.

Exemplos

Para obter um exemplo, consulte o Servidor de Pipe Multithreaded.

Requisitos

   
Cliente mínimo com suporte Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho namedpipeapi.h
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

CallNamedPipe

CreateEvent

CreateFile

CreateNamedPipe

DisconnectNamedPipe

GetOverlappedResult

SOBREPOSTA

Funções de pipe

Visão geral dos pipes

SetNamedPipeHandleState

SleepEx