Função CreateNamedPipeA (winbase.h)
Cria uma instância de um pipe nomeado e retorna um identificador para operações de pipe subsequentes. Um processo de servidor de pipe nomeado usa essa função para criar a primeira instância de um pipe nomeado específico e estabelecer seus atributos básicos ou criar uma nova instância de um pipe nomeado existente.
Sintaxe
HANDLE CreateNamedPipeA(
[in] LPCSTR lpName,
[in] DWORD dwOpenMode,
[in] DWORD dwPipeMode,
[in] DWORD nMaxInstances,
[in] DWORD nOutBufferSize,
[in] DWORD nInBufferSize,
[in] DWORD nDefaultTimeOut,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);
Parâmetros
[in] lpName
O nome do pipe exclusivo. Essa cadeia de caracteres deve ter o seguinte formulário:
\\.\pipe\pipename
A parte pipename do nome pode incluir qualquer caractere que não seja uma barra invertida, incluindo números e caracteres especiais. A cadeia de caracteres de nome de pipe inteira pode ter até 256 caracteres. Nomes de pipe não diferenciam maiúsculas de minúsculas.
[in] dwOpenMode
O modo aberto.
A função falhará se dwOpenMode especificar algo diferente de 0 ou os sinalizadores listados nas tabelas a seguir.
Esse parâmetro deve especificar um dos seguintes modos de acesso de pipe. O mesmo modo deve ser especificado para cada instância do pipe.
| Modo | Significado |
|---|---|
|
O pipe é bidirecional; os processos de servidor e cliente podem ler e gravar no pipe. Esse modo fornece ao servidor o equivalente a GENERIC_READ e GENERIC_WRITE acesso ao pipe. O cliente pode especificar |
|
O fluxo de dados no pipe vai somente de cliente para servidor. Esse modo fornece ao servidor o equivalente a GENERIC_READ acesso ao pipe. O cliente deve especificar GENERIC_WRITE acesso ao se conectar ao pipe. Se o cliente precisar ler as configurações de pipe chamando o GetNamedPipeInfo ou funções de GetNamedPipeHandleState, o cliente deverá especificar GENERIC_WRITE e FILE_READ_ATTRIBUTES acesso ao se conectar ao pipe. |
|
O fluxo de dados no pipe vai somente de servidor para cliente. Esse modo fornece ao servidor o equivalente a GENERIC_WRITE acesso ao pipe. O cliente deve especificar GENERIC_READ acesso ao se conectar ao pipe. Se o cliente precisar alterar as configurações de pipe chamando a função SetNamedPipeHandleState, o cliente deverá especificar GENERIC_READ e FILE_WRITE_ATTRIBUTES acesso ao se conectar ao pipe. |
Esse parâmetro também pode incluir um ou mais dos sinalizadores a seguir, que habilitam os modos de gravação e sobrepostos. Esses modos podem ser diferentes para instâncias diferentes do mesmo pipe.
| Modo | Significado |
|---|---|
|
Se você tentar criar várias instâncias de um pipe com esse sinalizador, a criação da primeira instância terá êxito, mas a criação da próxima instância falhará com ERROR_ACCESS_DENIED. |
|
O modo de gravação está habilitado. Esse modo afeta apenas as operações de gravação em pipes do tipo byte e, em seguida, somente quando os processos de cliente e servidor estão em computadores diferentes. Se esse modo estiver habilitado, as funções gravadas em um pipe nomeado não retornarão até que os dados gravados sejam transmitidos pela rede e estiverem no buffer do pipe no computador remoto. Se esse modo não estiver habilitado, o sistema aumentará a eficiência das operações de rede armazenando dados em buffer até que um número mínimo de bytes se acumule ou até que o tempo máximo se esvaia. |
|
O modo sobreposto está habilitado. Se esse modo estiver habilitado, as funções que executam operações de leitura, gravação e conexão que podem levar um tempo significativo para serem concluídas poderão retornar imediatamente. Esse modo permite que o thread que iniciou a operação execute outras operações enquanto a operação demorada é executada em segundo plano. Por exemplo, no modo sobreposto, um thread pode lidar com operações simultâneas de E/S (entrada e saída) em várias instâncias de um pipe ou executar operações simultâneas de leitura e gravação no mesmo identificador de pipe. Se o modo sobreposto não estiver habilitado, as funções que executam operações de leitura, gravação e conexão no identificador de pipe não retornarão até que a operação seja concluída. As funções |
Esse parâmetro pode incluir qualquer combinação dos seguintes modos de acesso de segurança. Esses modos podem ser diferentes para instâncias diferentes do mesmo pipe.
[in] dwPipeMode
O modo de pipe.
A função falhará se dwPipeMode especificar algo diferente de 0 ou os sinalizadores listados nas tabelas a seguir.
Um dos seguintes modos de tipo pode ser especificado. O mesmo modo de tipo deve ser especificado para cada instância do pipe.
| Modo | Significado |
|---|---|
|
Os dados são gravados no pipe como um fluxo de bytes. Esse modo não pode ser usado com PIPE_READMODE_MESSAGE. O pipe não distingue bytes gravados durante operações de gravação diferentes. |
|
Os dados são gravados no pipe como um fluxo de mensagens. O pipe trata os bytes gravados durante cada operação de gravação como uma unidade de mensagem. A função GetLastError retorna ERROR_MORE_DATA quando uma mensagem não é lida completamente. Esse modo pode ser usado com PIPE_READMODE_MESSAGE ou PIPE_READMODE_BYTE. |
Um dos seguintes modos de leitura pode ser especificado. Instâncias diferentes do mesmo pipe podem especificar diferentes modos de leitura.
Um dos seguintes modos de espera pode ser especificado. Instâncias diferentes do mesmo pipe podem especificar modos de espera diferentes.
| Modo | Significado |
|---|---|
|
O modo de bloqueio está habilitado. Quando o identificador de pipe é especificado na função ReadFile, WriteFileou função ConnectNamedPipe, as operações não são concluídas até que haja dados a serem lidos, todos os dados sejam gravados ou um cliente esteja conectado. O uso desse modo pode significar aguardar indefinidamente em algumas situações para que um processo de cliente execute uma ação. |
|
O modo de não bloqueio está habilitado. Nesse modo, ReadFile, WriteFilee ConnectNamedPipe sempre retornam imediatamente.
Observe que o modo de desbloqueio tem suporte para compatibilidade com o Microsoft LAN Manager versão 2.0 e não deve ser usado para obter E/S assíncrona com pipes nomeados. Para obter mais informações sobre e/S de pipe assíncrono, consulte de entrada e saída síncronas e sobrepostas. |
Um dos seguintes modos de cliente remoto pode ser especificado. Instâncias diferentes do mesmo pipe podem especificar diferentes modos de cliente remoto.
[in] nMaxInstances
O número máximo de instâncias que podem ser criadas para esse pipe. A primeira instância do pipe pode especificar esse valor; o mesmo número deve ser especificado para outras instâncias do pipe. Os valores aceitáveis estão no intervalo de 1 a PIPE_UNLIMITED_INSTANCES (255).
Se esse parâmetro for PIPE_UNLIMITED_INSTANCES, o número de instâncias de pipe que podem ser criadas será limitado apenas pela disponibilidade de recursos do sistema. Se nMaxInstances for maior que PIPE_UNLIMITED_INSTANCES, o valor retornado será INVALID_HANDLE_VALUE e GetLastError retornará ERROR_INVALID_PARAMETER.
[in] nOutBufferSize
O número de bytes a serem reservados para o buffer de saída. Para obter uma discussão sobre o dimensionamento de buffers de pipe nomeados, consulte a seção Comentários a seguir.
[in] nInBufferSize
O número de bytes a serem reservados para o buffer de entrada. Para obter uma discussão sobre o dimensionamento de buffers de pipe nomeados, consulte a seção Comentários a seguir.
[in] nDefaultTimeOut
O valor de tempo limite padrão, em milissegundos, se a função WaitNamedPipe especificar NMPWAIT_USE_DEFAULT_WAIT. Cada instância de um pipe nomeado deve especificar o mesmo valor.
Um valor zero resultará em um tempo limite padrão de 50 milissegundos.
[in, optional] lpSecurityAttributes
Um ponteiro para uma estrutura SECURITY_ATTRIBUTES que especifica um descritor de segurança para o novo pipe nomeado e determina se os processos filho podem herdar o identificador retornado. Se lpSecurityAttributes for NULL, o pipe nomeado receberá um descritor de segurança padrão e o identificador não poderá ser herdado. As ACLs no descritor de segurança padrão para um pipe nomeado concedem controle total à conta LocalSystem, aos administradores e ao proprietário do criador. Eles também concedem acesso de leitura aos membros do grupo Todos e à conta anônima.
Valor de retorno
Se a função for bem-sucedida, o valor retornado será um identificador para o final do servidor de uma instância de pipe nomeada.
Se a função falhar, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.
Observações
Para criar uma instância de um pipe nomeado usando CreateNamedPipe, o usuário deve ter FILE_CREATE_PIPE_INSTANCE acesso ao objeto de pipe nomeado. Se um novo pipe nomeado estiver sendo criado, a ACL (lista de controle de acesso) do parâmetro de atributos de segurança definirá o controle de acesso discricionário para o pipe nomeado.
Todas as instâncias de um pipe nomeado devem especificar o mesmo tipo de pipe (tipo de byte ou tipo de mensagem), acesso de pipe (duplex, entrada ou saída), contagem de instâncias e valor de tempo limite. Se valores diferentes forem usados, essa função falhará e GetLastError retornará ERROR_ACCESS_DENIED.
Um processo de cliente se conecta a um pipe nomeado usando a função
O servidor de pipe não deve executar uma operação de leitura de bloqueio até que o cliente de pipe seja iniciado. Caso contrário, uma condição de corrida pode ocorrer. Isso normalmente ocorre quando o código de inicialização, como o tempo de execução C, precisa bloquear e examinar identificadores herdados.
Sempre que um pipe nomeado é criado, o sistema cria os buffers de entrada e/ou de saída usando o pool nãopagado, que é a memória física usada pelo kernel. O número de instâncias de pipe (bem como objetos como threads e processos) que você pode criar é limitado pelo pool nãopagado disponível. Cada solicitação de leitura ou gravação requer espaço no buffer para os dados de leitura ou gravação, além de espaço adicional para as estruturas de dados internas.
Os tamanhos do buffer de entrada e saída são consultivos. O tamanho real do buffer reservado para cada extremidade do pipe nomeado é o padrão do sistema, o mínimo ou o máximo do sistema ou o tamanho especificado arredondado para o próximo limite de alocação. O tamanho do buffer especificado deve ser pequeno o suficiente para que seu processo não fique sem pool nãopagado, mas grande o suficiente para acomodar solicitações típicas.
Sempre que ocorre uma operação de gravação de pipe, o sistema tenta primeiro carregar a memória na cota de gravação do pipe. Se a cota de gravação de pipe restante for suficiente para atender à solicitação, a operação de gravação será concluída imediatamente. Se a cota de gravação de pipe restante for muito pequena para atender à solicitação, o sistema tentará expandir os buffers para acomodar os dados usando o pool nãopagado reservado para o processo. A operação de gravação será bloqueada até que os dados sejam lidos do pipe para que a cota de buffer adicional possa ser liberada. Portanto, se o tamanho do buffer especificado for muito pequeno, o sistema aumentará o buffer conforme necessário, mas a desvantagem é que a operação será bloqueada. Se a operação estiver sobreposta, um thread do sistema será bloqueado; caso contrário, o thread do aplicativo será bloqueado.
Para liberar recursos usados por um pipe nomeado, 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 à instância for encerrado. Observe que uma instância de um pipe nomeado pode ter mais de um identificador associado a ele. Uma instância de um pipe nomeado é sempre excluída quando o último identificador para a instância do pipe nomeado é fechado.
Windows 10, versão 1709: Pipes só têm suporte em um contêiner de aplicativo; ou seja, de um processo UWP para outro processo UWP que faz parte do mesmo aplicativo. Além disso, os pipes nomeados devem usar a sintaxe \\.\pipe\LOCAL\ para o nome do pipe.
Exemplos
Para obter um exemplo, consulte servidor de pipe multithreaded.
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 | winbase.h (inclua Windows.h) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |
Consulte também
Visão geral do Pipes