Função ConnectNamedPipe (namedpipeapi.h)

Artigo
08/25/2023

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 a extremidade do servidor de uma instância de pipe nomeado. 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 tiver sido aberto com FILE_FLAG_OVERLAPPED e lpOverlapped for NULL, a função poderá relatar incorretamente que a operação de conexão foi concluída.

Se hNamedPipe tiver sido criado com FILE_FLAG_OVERLAPPED e lpOverlapped não for NULL, a estrutura OVERLAPPED deverá 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 não tiver fechado seu 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 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 sem bloqueio, ConnectNamedPipe sempre retornará imediatamente. No modo sem bloqueio, 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.

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

Windows 10, versão 1709: os pipes só têm suporte em um app-container; 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 Servidor de Pipe Multithreaded.

Requisitos

Requisito	Valor
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