Função SetNamedPipeHandleState (namedpipeapi.h)

Artigo
03/08/2023

Define o modo de leitura e o modo de bloqueio do pipe nomeado especificado. Se o identificador especificado estiver na extremidade do cliente de um pipe nomeado e se o processo do servidor de pipe nomeado estiver em um computador remoto, a função também poderá ser usada para controlar o buffer local.

Sintaxe

BOOL SetNamedPipeHandleState(
  [in]           HANDLE  hNamedPipe,
  [in, optional] LPDWORD lpMode,
  [in, optional] LPDWORD lpMaxCollectionCount,
  [in, optional] LPDWORD lpCollectDataTimeout
);

Parâmetros

[in] hNamedPipe

Um identificador para a instância de pipe nomeada. Esse parâmetro pode ser um identificador para a extremidade do servidor do pipe, conforme retornado pela função CreateNamedPipe ou para o final do cliente do pipe, conforme retornado pela função CreateFile . O identificador deve ter GENERIC_WRITE acesso ao pipe nomeado para um pipe somente gravação ou leitura/gravação ou deve ter acesso GENERIC_READ e FILE_WRITE_ATTRIBUTES para um pipe somente leitura.

Esse parâmetro também pode ser um identificador para um pipe anônimo, conforme retornado pela função CreatePipe .

[in, optional] lpMode

O novo modo de pipe. O modo é uma combinação de um sinalizador de modo de leitura e um sinalizador de modo de espera. Esse parâmetro poderá ser NULL se o modo não estiver sendo definido. Especifique um dos modos a seguir.

Mode	Significado
PIPE_READMODE_BYTE 0x00000000	Os dados são lidos do pipe como um fluxo de bytes. Esse modo será o padrão se nenhum sinalizador de modo de leitura for especificado.
PIPE_READMODE_MESSAGE 0x00000002	Os dados são lidos do pipe como um fluxo de mensagens. A função falhará se esse sinalizador for especificado para um pipe do tipo byte.

Um dos seguintes modos de espera pode ser especificado.

Mode	Significado
PIPE_WAIT 0x00000000	O modo de bloqueio está habilitado. Esse modo será o padrão se nenhum sinalizador de modo de espera for especificado. Quando um identificador de pipe do modo de bloqueio é especificado na função ReadFile, WriteFile ou ConnectNamedPipe , as operações não são concluídas até que haja dados para leitura, todos os dados são gravados ou um cliente está conectado. O uso desse modo pode significar aguardar indefinidamente em algumas situações para que um processo de cliente execute uma ação.
PIPE_NOWAIT 0x00000001	O modo de não desbloqueio está habilitado. Nesse modo, ReadFile, WriteFile e ConnectNamedPipe sempre retornam imediatamente. Observe que o modo de 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.

Mode

Significado

PIPE_WAIT
0x00000000

O modo de bloqueio está habilitado. Esse modo será o padrão se nenhum sinalizador de modo de espera for especificado. Quando um identificador de pipe do modo de bloqueio é especificado na função ReadFile, WriteFile ou ConnectNamedPipe , as operações não são concluídas até que haja dados para leitura, todos os dados são gravados ou um cliente está conectado. O uso desse modo pode significar aguardar indefinidamente em algumas situações para que um processo de cliente execute uma ação.

PIPE_NOWAIT
0x00000001

O modo de não desbloqueio está habilitado. Nesse modo, ReadFile, WriteFile e ConnectNamedPipe sempre retornam imediatamente. Observe que o modo de 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.

[in, optional] lpMaxCollectionCount

O número máximo de bytes coletados no computador cliente antes da transmissão para o servidor. Esse parâmetro deverá ser NULL se o identificador de pipe especificado for para a extremidade do servidor de um pipe nomeado ou se os processos de cliente e servidor estiverem no mesmo computador. Esse parâmetro será ignorado se o processo do cliente especificar o sinalizador FILE_FLAG_WRITE_THROUGH na função CreateFile quando o identificador foi criado. Esse parâmetro poderá ser NULL se a contagem de coleções não estiver sendo definida.

[in, optional] lpCollectDataTimeout

O tempo máximo, em milissegundos, que pode passar antes que um pipe nomeado remoto transfira informações pela rede. Esse parâmetro deve ser NULL se o identificador de pipe especificado for para a extremidade do servidor de um pipe nomeado ou se os processos de cliente e servidor estiverem no mesmo computador. Esse parâmetro será ignorado se o processo do cliente tiver especificado o sinalizador FILE_FLAG_WRITE_THROUGH na função CreateFile quando o identificador foi criado. Esse parâmetro poderá ser NULL se a contagem de coleções não estiver sendo definida.

Valor retornado

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.

Comentários

Windows 10, versão 1709: os pipes só têm suporte 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 Cliente pipe nomeado.

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