Função TransactNamedPipe (namedpipeapi.h)

Artigo
03/05/2024

Combina as funções que gravam uma mensagem e leem uma mensagem do pipe nomeado especificado em uma única operação.

Sintaxe

BOOL TransactNamedPipe(
  [in]                HANDLE       hNamedPipe,
  [in]                LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out]               LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out]               LPDWORD      lpBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Parâmetros

[in] hNamedPipe

Um identificador para o pipe nomeado retornado pela função CreateNamedPipe ou CreateFile .

Esse parâmetro também pode ser um identificador para um pipe anônimo, conforme retornado pela função CreatePipe .

[in] lpInBuffer

Um ponteiro para o buffer que contém os dados a serem gravados no pipe.

[in] nInBufferSize

O tamanho, em bytes, do buffer de entrada.

[out] lpOutBuffer

Um ponteiro para o buffer que recebe os dados lidos do pipe.

[in] nOutBufferSize

O tamanho do buffer de saída em bytes.

[out] lpBytesRead

Um ponteiro para a variável que recebe o número de bytes lidos do pipe.

Se lpOverlapped for NULL, lpBytesRead não poderá ser NULL.

Se lpOverlapped não for NULL, lpBytesRead poderá ser NULL. Se essa for uma operação de leitura sobreposta, você poderá obter o número de bytes lidos chamando GetOverlappedResult. Se hNamedPipe estiver associado a uma porta de conclusão de E/S, você poderá obter o número de bytes lidos chamando GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Um ponteiro para uma estrutura OVERLAPPED. Essa estrutura será necessária se hNamedPipe tiver sido aberto com FILE_FLAG_OVERLAPPED.

Se hNamedPipe foi aberto com FILE_FLAG_OVERLAPPED, o parâmetro lpOverlapped não deve ser NULL. Ele deve apontar para uma estrutura OVERLAPPED válida. Se hNamedPipe tiver sido criado com FILE_FLAG_OVERLAPPED e lpOverlapped for NULL, a função poderá relatar incorretamente que a operação foi concluída.

Se hNamedPipe tiver sido aberto com FILE_FLAG_OVERLAPPED e lpOverlapped não for NULL, TransactNamedPipe será executado como uma operação sobreposta. A estrutura OVERLAPPED deve conter um objeto de evento de redefinição manual (que pode ser criado usando a função CreateEvent ). Se a operação não puder ser concluída imediatamente, TransactNamedPipe retornará FALSE e GetLastError retornará ERROR_IO_PENDING. Nessa situação, o objeto de evento é definido como o estado não atribuído antes do retorno de TransactNamedPipe e é definido como o estado sinalizado quando a transação é concluída. Além disso, você pode ser notificado quando uma operação sobreposta for concluída usando as funções GetQueuedCompletionStatus ou GetQueuedCompletionStatusEx . Nesse caso, você não precisa atribuir o evento de redefinição manual na estrutura OVERLAPPED e a conclusão ocorre no hNamedPipe da mesma forma que uma operação assíncrona de leitura ou gravação. Para obter mais informações sobre operações sobrepostas, consulte Pipes.

Se hNamedPipe não tiver sido aberto com FILE_FLAG_OVERLAPPED, TransactNamedPipe não retornará até que a operação seja concluída.

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.

Se a mensagem a ser lida for maior que o buffer especificado pelo parâmetro nOutBufferSize , TransactNamedPipe retornará FALSE e a função GetLastError retornará ERROR_MORE_DATA. O restante da mensagem pode ser lido por uma chamada subsequente para ReadFile, ReadFileEx ou PeekNamedPipe.

Comentários

O TransactNamedPipe falhará se o servidor não tiver criado o pipe como um pipe do tipo mensagem ou se o identificador de pipe não estiver no modo de leitura de mensagem. Por exemplo, se um cliente estiver em execução no mesmo computador que o servidor e usar o formato \.\pipe\pipename para abrir o pipe, o pipe será aberto no modo de byte pelo NPFS (sistema de arquivos de pipe nomeado). Se o cliente usar o formulário \\server\pipe\pipename, o redirecionador abrirá o pipe no modo de mensagem. Um identificador de pipe do modo de byte pode ser alterado para o modo de leitura de mensagem com a função SetNamedPipeHandleState .

A função não pode ser concluída com êxito até que os dados sejam gravados no buffer especificado pelo parâmetro lpOutBuffer . O parâmetro lpOverlapped está disponível para permitir que o thread de chamada execute outras tarefas enquanto a operação está em execução em segundo plano.

O tamanho máximo garantido de uma transação de pipe nomeado é de 64 quilobytes. Em alguns casos limitados, transações além de 64 quilobytes são possíveis, dependendo das versões do sistema operacional que participam das condições de transação e de rede dinâmica. No entanto, não há garantia de que as transações acima de 64 quilobytes serão bem-sucedidas. Portanto, é recomendável que as transações de pipe nomeado sejam limitadas a 64 quilobytes de dados.

Windows 10, versão 1709: os pipes só têm suporte em um app-container; 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 Transações em pipes nomeados.

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