Compartilhar via


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 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 membro lpSecurityDescriptor 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 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

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 eles não forem mais necessários, o que é feito chamando a função CloseHandle ou quando o processo associado às alças da instância terminar. 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 com entrada e saída redirecionadas.

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

Confira também

Funções de pipe

Visão geral de pipes

ReadFile

SECURITY_ATTRIBUTES

WriteFile