Функция PeekNamedPipe (namedpipeapi.h)

Статья
03/08/2023

Копирует данные из именованного или анонимного канала в буфер, не удаляя их из канала. Он также возвращает сведения о данных в канале.

Синтаксис

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

Параметры

[in] hNamedPipe

Дескриптор канала. Этот параметр может быть дескриптором для экземпляра именованного канала, возвращаемого функцией CreateNamedPipe или CreateFile , или дескриптором для конца чтения анонимного канала, возвращаемого функцией CreatePipe . Дескриптор должен иметь GENERIC_READ доступ к каналу.

[out, optional] lpBuffer

Указатель на буфер, который получает данные, считываемые из канала. Этот параметр может иметь значение NULL , если данные не должны считываться.

[in] nBufferSize

Размер буфера, заданного параметром lpBuffer , в байтах. Этот параметр игнорируется, если lpBuffer имеет значение NULL.

[out, optional] lpBytesRead

Указатель на переменную, которая получает количество байтов, считанных из канала. Этот параметр может иметь значение NULL , если данные не должны считываться.

[out, optional] lpTotalBytesAvail

Указатель на переменную, которая получает общее количество байтов, доступных для чтения из канала. Этот параметр может иметь значение NULL , если данные не должны считываться.

[out, optional] lpBytesLeftThisMessage

Указатель на переменную, которая получает количество байтов, оставшихся в этом сообщении. Этот параметр будет равен нулю для именованных каналов типа byte или для анонимных каналов. Этот параметр может иметь значение NULL , если данные не должны считываться.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Данные считываются в режиме, указанном в параметре CreateNamedPipe. Например, создайте канал с PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE. Если вы измените режим на PIPE_READMODE_BYTE с SetNamedPipeHandleState, ReadFile будет считываться в режиме байтов, но PeekNamedPipe продолжит чтение в режиме сообщений.
Данные, считанные из канала, не удаляются из буфера канала.
Функция может возвращать дополнительные сведения о содержимом канала.
Функция всегда возвращается немедленно в однопотоковом приложении, даже если в канале нет данных. Режим ожидания дескриптора именованного канала (блокирующий или неблокирующий) не влияет на функцию.

Примечание Функция PeekNamedPipe может блокировать выполнение потока так же, как любая функция ввода-вывода при вызове для синхронного дескриптора в многопотоковом приложении. Чтобы избежать этого условия, используйте дескриптор канала, созданный для асинхронного ввода-вывода.

Если указанный дескриптор является дескриптором именованного канала в режиме чтения байтов, функция считывает все доступные байты до размера, указанного в nBufferSize. Для дескриптора именованного канала в режиме чтения сообщений функция считывает следующее сообщение в канале. Если сообщение больше nBufferSize, функция возвращает TRUE после считывания указанного числа байтов. В этом случае lpBytesLeftThisMessage получит количество байтов, оставшихся в сообщении.

Windows 10 версии 1709: каналы поддерживаются только в контейнере приложений, т. е. от одного процесса UWP к другому процессу UWP, который является частью того же приложения. Кроме того, именованные каналы должны использовать синтаксис \\.\pipe\LOCAL\ для имени канала.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	namedpipeapi.h
Библиотека	Kernel32.lib
DLL	Kernel32.dll