Função PeekNamedPipe (namedpipeapi.h)

Artigo
02/29/2024

Copia dados de um pipe nomeado ou anônimo em um buffer sem removê-los do pipe. Ele também retorna informações sobre dados no pipe.

Sintaxe

BOOL PeekNamedPipe(
  [in]            HANDLE  hNamedPipe,
  [out, optional] LPVOID  lpBuffer,
  [in]            DWORD   nBufferSize,
  [out, optional] LPDWORD lpBytesRead,
  [out, optional] LPDWORD lpTotalBytesAvail,
  [out, optional] LPDWORD lpBytesLeftThisMessage
);

Parâmetros

[in] hNamedPipe

Um identificador para o pipe. Esse parâmetro pode ser um identificador para uma instância de pipe nomeada, conforme retornado pela função CreateNamedPipe ou CreateFile , ou pode ser um identificador para a extremidade de leitura de um pipe anônimo, conforme retornado pela função CreatePipe . O identificador deve ter GENERIC_READ acesso ao pipe.

[out, optional] lpBuffer

Um ponteiro para um buffer que recebe dados lidos do pipe. Esse parâmetro poderá ser NULL se nenhum dado for lido.

[in] nBufferSize

O tamanho do buffer especificado pelo parâmetro lpBuffer , em bytes. Esse parâmetro será ignorado se lpBuffer for NULL.

[out, optional] lpBytesRead

Um ponteiro para uma variável que recebe o número de bytes lidos do pipe. Esse parâmetro poderá ser NULL se nenhum dado for lido.

[out, optional] lpTotalBytesAvail

Um ponteiro para uma variável que recebe o número total de bytes disponíveis para leitura do pipe. Esse parâmetro poderá ser NULL se nenhum dado for lido.

[out, optional] lpBytesLeftThisMessage

Um ponteiro para uma variável que recebe o número de bytes restantes nesta mensagem. Esse parâmetro será zero para pipes nomeados do tipo byte ou para pipes anônimos. Esse parâmetro poderá ser NULL se nenhum dado for lido.

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

A função PeekNamedPipe é semelhante à função ReadFile com as seguintes exceções:

Os dados são lidos no modo especificado com CreateNamedPipe. Por exemplo, crie um pipe com PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE. Se você alterar o modo para PIPE_READMODE_BYTE com SetNamedPipeHandleState, ReadFile lerá no modo de byte, mas PeekNamedPipe continuará a ler no modo de mensagem.
Os dados lidos do pipe não são removidos do buffer do pipe.
A função pode retornar informações adicionais sobre o conteúdo do pipe.
A função sempre retorna imediatamente em um aplicativo de thread único, mesmo que não haja dados no pipe. O modo de espera de um identificador de pipe nomeado (bloqueio ou não desbloqueio) não tem efeito sobre a função.

Nota A função PeekNamedPipe pode bloquear a execução de thread da mesma forma que qualquer função de E/S pode quando chamada em um identificador síncrono em um aplicativo com vários threads. Para evitar essa condição, use um identificador de pipe criado para E/S assíncrona.

Se o identificador especificado for um identificador de pipe nomeado no modo de leitura de bytes, a função lerá todos os bytes disponíveis até o tamanho especificado em nBufferSize. Para um identificador de pipe nomeado no modo de leitura de mensagem, a função lê a próxima mensagem no pipe. Se a mensagem for maior que nBufferSize, a função retornará TRUE depois de ler o número especificado de bytes. Nessa situação, lpBytesLeftThisMessage receberá o número de bytes restantes na mensagem.

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.

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