Função CreatePipe (namedpipeapi.h)

Cria um pipe anônimo e retorna identificadores para as extremidades de leitura e gravação do pipe.

Sintaxe

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

Parâmetros

[out] hReadPipe

Um ponteiro para uma variável que recebe o identificador de leitura do pipe.

[out] hWritePipe

Um ponteiro para uma variável que recebe o identificador de gravação do pipe.

[in, optional] lpPipeAttributes

Um ponteiro para uma estrutura de SECURITY_ATTRIBUTES que determina se o identificador retornado pode ser herdado por processos filho. Se lpPipeAttributes for NULL, o identificador não poderá ser herdado.

O lpSecurityDescriptor membro da estrutura especifica um descritor de segurança para o novo pipe. Se lpPipeAttributes for NULL, o pipe receberá um descritor de segurança padrão. As ACLs no descritor de segurança padrão para um pipe vêm do token primário ou de representação do criador.

[in] nSize

O tamanho do buffer para o pipe, em bytes. O tamanho é apenas uma sugestão; o sistema usa o valor para calcular um mecanismo de buffer apropriado. Se esse parâmetro for zero, o sistema usará o tamanho do buffer padrão.

Valor de retorno

Se a função for bem-sucedida, o valor retornado não será zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Observações

CreatePipe cria o pipe, atribuindo o tamanho do pipe especificado ao buffer de armazenamento. CreatePipe também cria identificadores que o processo usa para ler e gravar no buffer em chamadas subsequentes para as funções ReadFile e WriteFile.

Para ler do pipe, um processo usa o identificador de leitura em uma chamada para a função ReadFile. ReadFile retorna quando um dos seguintes é verdadeiro: uma operação de gravação é concluída na extremidade de gravação do pipe, o número de bytes solicitados foi lido ou ocorre um erro.

Quando um processo usa WriteFile para gravar em um pipe anônimo, a operação de gravação não é concluída até que todos os bytes sejam gravados. Se o buffer de pipe estiver cheio antes de todos os bytes serem gravados, WriteFile não retornará até que outro processo ou thread use ReadFile para disponibilizar mais espaço de buffer.

Pipes anônimos são implementados usando um pipe nomeado com um nome exclusivo. Portanto, muitas vezes você pode passar um identificador para um pipe anônimo para uma função que requer um identificador para um pipe nomeado.

Se CreatePipe falhar, o conteúdo dos parâmetros de saída será indeterminado. Nenhuma suposição deve ser feita sobre seu conteúdo neste evento.

Para liberar recursos usados por um pipe, o aplicativo sempre deve fechar identificadores quando não forem mais necessários, o que é feito chamando a função CloseHandle ou quando o processo associado à instância for encerrado. Observe que uma instância de um pipe pode ter mais de um identificador associado a ele. Uma instância de um pipe é sempre excluída quando o último identificador para a instância do pipe nomeado é fechado.

Exemplos

Para obter um exemplo, consulte Criando um processo filho comde entrada e saída redirecionados.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
servidor com suporte mínimo	Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	namedpipeapi.h
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

Funções de pipe

Visão geral do Pipes

ReadFile

SECURITY_ATTRIBUTES

writefile