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 para 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 diferente de uma barra invertida, incluindo números e caracteres especiais. Toda a cadeia de caracteres de nome do pipe 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.
| Mode | 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 GENERIC_READ ou GENERIC_WRITE, ou ambos, quando se conecta ao pipe usando a função CreateFile . |
|
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 as funções GetNamedPipeInfo ou 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 do servidor para o 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 sobreposição. Esses modos podem ser diferentes para instâncias diferentes do mesmo pipe.
| Mode | 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 um tempo máximo se exiba. |
|
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 ReadFileEx e WriteFileEx só podem ser usadas com um identificador de pipe no modo sobreposto. As funções ReadFile, WriteFile, ConnectNamedPipe e TransactNamedPipe podem ser executadas de forma síncrona ou como operações sobrepostas. |
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.
| Mode | Significado |
|---|---|
|
O chamador terá acesso de gravação à ACL (lista de controle de acesso discricionário) do pipe nomeado. |
|
O chamador terá acesso de gravação ao proprietário do pipe nomeado. |
|
O chamador terá acesso de gravação ao SACL do pipe nomeado. Para obter mais informações, confira ACLs (Listas de Controle de Acesso) e Direito de Acesso à SACL. |
[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.
| Mode | 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 modos de leitura diferentes.
Um dos seguintes modos de espera pode ser especificado. Instâncias diferentes do mesmo pipe podem especificar modos de espera diferentes.
| Mode | Significado |
|---|---|
|
O modo de bloqueio está habilitado. Quando o identificador de pipe é especificado na função ReadFile, WriteFile ou ConnectNamedPipe , as operações não são concluídas até que haja dados para leitura, 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 desbloqueio está habilitado. Nesse modo, ReadFile, WriteFile e ConnectNamedPipe sempre retornam imediatamente.
Observe que o modo sem bloqueio 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 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 reservar 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 WaitNamedPipeespecificar 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.
Retornar valor
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 houver falha na função, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.
Comentários
Para criar uma instância de um pipe nomeado usando CreateNamedPipe, o usuário deve ter FILE_CREATE_PIPE_INSTANCE acesso ao objeto 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 CreateFile ou CallNamedPipe . O lado do cliente de um pipe nomeado começa no modo de byte, mesmo que o lado do servidor esteja no modo de mensagem. Para evitar problemas de recebimento de dados, defina o lado do cliente para o modo de mensagem também. Para alterar o modo do pipe, o cliente de pipe deve abrir um pipe somente leitura com GENERIC_READ e acesso FILE_WRITE_ATTRIBUTES .
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 um 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 o 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 primeiro tenta 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 aos identificadores de instância terminar. 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: os 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 |
|---|---|
| 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 | winbase.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |