Operações de pipe nomeadas

A primeira vez que o servidor de pipe chama a funçãoCreateNamedPipe, ele usa o parâmetro nMaxInstances para especificar o número máximo de instâncias do pipe que podem existir simultaneamente. O servidor pode chamar CreateNamedPipe repetidamente para criar instâncias adicionais do pipe, desde que não exceda o número máximo de instâncias. Se a função for bem-sucedida, cada chamada retornará um identificador para a extremidade do servidor de uma instância de pipe nomeada.

Assim que o servidor de pipe cria uma instância de pipe, um cliente de pipe pode se conectar a ele chamando oCreateFileou função de CallNamedPipe. Se uma instância de pipe estiver disponível, CreateFile retornará um identificador para a extremidade do cliente da instância de pipe. Se nenhuma instância do pipe estiver disponível, um cliente de pipe pode usar a funçãoWaitNamedPipe para aguardar até que um pipe fique disponível.

Um servidor de pipe pode determinar quando um cliente de pipe está conectado a uma instância de pipe chamando a funçãoConnectNamedPipe. Se a alça do pipe estiver no modo de espera de bloqueio, ConnectNamedPipe não retornará até que um cliente esteja conectado.

Clientes e servidores de pipe podem chamar uma das várias funções — além de CallNamedPipe — para ler e gravar em um pipe nomeado. O comportamento dessas funções depende do tipo de tubo e dos modos em vigor para a alça de tubo especificada, da seguinte forma:

• As funções ReadFile e WriteFile podem ser usadas com pipes do tipo byte ou do tipo mensagem.
• As funções ReadFileEx e WriteFileEx podem ser usadas com pipes do tipo byte ou do tipo mensagem se o identificador do pipe foi aberto para operações sobrepostas.
• A funçãoPeekNamedPipe pode ser usada para ler sem remover o conteúdo de um pipe do tipo byte ou de um pipe do tipo mensagem. PeekNamedPipe também pode retornar informações adicionais sobre a instância do pipe.
• A função deTransactNamedPipepode ser usada com pipes duplex do tipo mensagem se o identificador de pipe para o processo de chamada estiver definido para o modo de leitura de mensagem. A função grava uma mensagem de solicitação e lê uma mensagem de resposta em uma única operação, melhorando o desempenho da rede.

O servidor de pipe não deve executar uma operação de leitura de bloqueio até que o cliente de pipe tenha iniciado. Caso contrário, pode ocorrer uma condição de corrida. Isso normalmente ocorre quando o código de inicialização, como o da biblioteca de tempo de execução C, precisa bloquear e examinar identificadores herdados.

Quando um cliente e um servidor terminarem de usar uma instância de pipe, o servidor deve primeiro chamar a funçãoFlushFileBuffers, para garantir que todos os bytes ou mensagens gravadas no pipe sejam lidos pelo cliente. FlushFileBuffers não retorna até que o cliente tenha lido todos os dados do pipe. Em seguida, o servidor chama a função DisconnectNamedPipe para fechar a conexão com o cliente de pipe. Esta função torna o identificador do cliente inválido, se ainda não tiver sido fechado. Todos os dados não lidos no tubo são descartados. Depois que o cliente é desconectado, o servidor chama a funçãoCloseHandle para fechar seu identificador para a instância do pipe. Como alternativa, o servidor pode usar ConnectNamedPipe para permitir que um novo cliente se conecte a essa instância do pipe.

Um processo pode recuperar informações sobre um pipe nomeado chamando o função GetNamedPipeInfo, que retorna o tipo do pipe, o tamanho dos buffers de entrada e saída e o número máximo de instâncias de pipe que podem ser criadas. A funçãoGetNamedPipeHandleState relata os modos de leitura e espera de uma alça de pipe, o número atual de instâncias de pipe e informações adicionais para pipes que se comunicam através de uma rede. A funçãoSetNamedPipeHandleStatedefine o modo de leitura e os modos de espera de uma alça de tubo. Para clientes de pipe que se comunicam com um servidor remoto, a função também controla o número máximo de bytes a coletar ou o tempo máximo de espera antes de transmitir uma mensagem (supondo que o identificador do cliente não foi aberto com o modo de gravação habilitado).