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

Статья
11/20/2024

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

Синтаксис

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, которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Если lpPipeAttributesNULL, то дескриптор нельзя наследовать.

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

[in] nSize

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

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

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

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

Замечания

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

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

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

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

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

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

Примеры

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows 2000 Server [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	namedpipeapi.h
библиотеки	Kernel32.lib
DLL	Kernel32.dll