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

Статья
08/25/2023

Создает анонимный канал и возвращает дескрипторы концам канала для чтения и записи.

Синтаксис

BOOL CreatePipe(
  [out]          PHANDLE               hReadPipe,
  [out]          PHANDLE               hWritePipe,
  [in, optional] LPSECURITY_ATTRIBUTES lpPipeAttributes,
  [in]           DWORD                 nSize
);

Параметры

[out] hReadPipe

Указатель на переменную, получающую дескриптор чтения для канала.

[out] hWritePipe

Указатель на переменную, получающую дескриптор записи для канала.

[in, optional] lpPipeAttributes

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

Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового канала. Если lpPipeAttributes имеет значение NULL, канал получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для канала поступают из основного маркера или токена олицетворения создателя.

[in] nSize

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

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

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

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

CreatePipe создает канал, присваивая буферу хранилища указанный размер канала. CreatePipe также создает дескрипторы, используемые процессом для чтения и записи в буфер в последующих вызовах функций ReadFile и WriteFile .

Для чтения из канала процесс использует дескриптор чтения в вызове функции ReadFile . ReadFile возвращает значение, если выполняется одно из следующих значений: операция записи завершается в конце канала записи, количество запрошенных байтов было прочитано или возникает ошибка.

Если процесс использует WriteFile для записи в анонимный канал, операция записи не завершается до тех пор, пока не будут записаны все байты. Если буфер канала заполнен до записи всех байтов, writeFile не возвращается до тех пор, пока другой процесс или поток не использует ReadFile для выделения дополнительного буферного пространства.

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

Если CreatePipe завершается ошибкой , содержимое выходных параметров является неопределенным. В этом случае не следует делать никаких предположений относительно их содержимого.

Чтобы освободить ресурсы, используемые каналом, приложение всегда должно закрывать дескрипторы, когда они больше не нужны, что выполняется путем вызова функции CloseHandle или при завершении процесса, связанного с дескрипторами экземпляра. Обратите внимание, что экземпляр канала может иметь несколько связанных дескрипторов. Экземпляр канала всегда удаляется при закрытии последнего дескриптора экземпляра именованного канала.

Примеры

Пример см. в разделе Создание дочернего процесса с перенаправленными входными и выходными данными.

Требования

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