função de retorno de chamada LPFN_TRANSMITPACKETS (mswsock.h)

Artigo
03/15/2023

A função TransmitPackets transmite dados na memória ou dados de arquivo por meio de um soquete conectado. A função TransmitPackets usa o gerenciador de cache do sistema operacional para recuperar dados de arquivo, bloqueando a memória pelo tempo mínimo necessário para transmitir e resultando em transmissão eficiente e de alto desempenho.

Nota Essa função é uma extensão específica da Microsoft para a especificação do Windows Sockets.

Sintaxe

LPFN_TRANSMITPACKETS LpfnTransmitpackets;

BOOL LpfnTransmitpackets(
  SOCKET hSocket,
  LPTRANSMIT_PACKETS_ELEMENT lpPacketArray,
  DWORD nElementCount,
  DWORD nSendSize,
  LPOVERLAPPED lpOverlapped,
  DWORD dwFlags
)
{...}

Parâmetros

hSocket

Um identificador para o soquete conectado a ser usado na transmissão. Embora o soquete não precise ser um circuito orientado à conexão, o destino/par padrão deve ter sido estabelecido usando a função connect, WSAConnect, accept, WSAAccept, AcceptEx ou WSAJoinLeaf .

lpPacketArray

Uma matriz do tipo TRANSMIT_PACKETS_ELEMENT, descrevendo os dados a serem transmitidos.

nElementCount

O número de elementos em lpPacketArray.

nSendSize

O tamanho, em bytes, do bloco de dados usado na operação de envio . Defina nSendSize como zero para permitir que a camada de soquetes selecione um tamanho de envio padrão.

Definir nSendSize como 0xFFFFFFF permite que o chamador controle o tamanho e o conteúdo de cada solicitação de envio , obtida usando o sinalizador TP_ELEMENT_EOP na matriz TRANSMIT_PACKETS_ELEMENT apontada no parâmetro lpPacketArray . Essa funcionalidade é útil para protocolos de mensagem que colocam limitações no tamanho de solicitações de envio individuais.

lpOverlapped

Um ponteiro para uma estrutura OVERLAPPED. Se o identificador de soquete especificado no parâmetro hSocket tiver sido aberto como sobreposto, use esse parâmetro para obter a operação de E/S assíncrona (sobreposta). Os identificadores de soquete são abertos como sobrepostos por padrão.

dwFlags

Um conjunto de sinalizadores usados para personalizar o processamento da função TransmitPackets . A tabela a seguir descreve o uso do parâmetro dwFlags .

Valor	Significado
TF_DISCONNECT	Inicia uma desconexão no nível do transporte depois que todos os dados do arquivo são enfileirados para transmissão. Aplica-se somente a soquetes orientados à conexão. Especificar esse sinalizador para soquetes que não dão suporte à semântica de desconexão (como soquetes de datagrama) resulta em um erro.
TF_REUSE_SOCKET	Prepara o identificador de soquete a ser reutilizado. Quando a função TransmitPackets for concluída, o identificador de soquete poderá ser passado para a função AcceptEx . Válido somente quando um soquete orientado à conexão e TF_DISCONNECT são especificados. Nota A transmissão de pacote no nível do soquete está sujeita ao comportamento do transporte subjacente. Por exemplo, um soquete TCP pode estar sujeito ao estado de TIME_WAIT TCP, fazendo com que a chamada TransmitPackets seja atrasada.
TF_USE_DEFAULT_WORKER	Direciona Winsock para usar o thread padrão do sistema para processar solicitações de TransmitPackets longas. As solicitações Long TransmitPackets são definidas como solicitações que exigem mais de uma única leitura do arquivo ou de um cache; portanto, a definição de solicitação longa depende do tamanho do arquivo e do comprimento especificado do pacote de envio. O thread padrão do sistema pode ser ajustado usando o seguinte parâmetro do Registro como umTransmissor de ParâmetrosAFD\ dosServiços\ REG_DWORD:HKEY_LOCAL_MACHINE\CurrentControlSet\Services\
TF_USE_SYSTEM_THREAD	Direciona Winsock para usar threads do sistema para processar solicitações de TransmitPackets longas. As solicitações Long TransmitPackets são definidas como solicitações que exigem mais de uma única leitura do arquivo ou de um cache; portanto, a definição de solicitação longa depende do tamanho do arquivo e do comprimento especificado do pacote de envio.
TF_USE_KERNEL_APC	Direciona Winsock para usar APCs ( Chamadas de Procedimento Assíncrono ) do kernel em vez de threads de trabalho para processar solicitações de TransmitPackets longas. As solicitações Long TransmitPackets são definidas como solicitações que exigem mais de uma única leitura do arquivo ou de um cache; portanto, a definição de solicitação longa depende do tamanho do arquivo e do comprimento especificado do pacote de envio. Confira Comentários para obter mais informações.

Retornar valor

Se a função TransmitPackets for bem-sucedida, o valor retornado será TRUE. Caso contrário, o valor retornado será FALSE. Para obter informações de erro estendidas, chame WSAGetLastError. Um código de erro de WSA_IO_PENDING ou ERROR_IO_PENDING indica que a operação sobreposta foi iniciada com êxito e que a conclusão será indicada posteriormente. Qualquer outro código de erro indica que a operação sobreposta não foi iniciada com êxito e nenhuma indicação de conclusão ocorrerá. Os aplicativos devem lidar com ERROR_IO_PENDING ou WSA_IO_PENDING nesse caso.

Código de retorno	Descrição
WSAECONNABORTED	Uma conexão estabelecida foi interrompida pelo software na sua máquina host. Esse erro será retornado se o circuito virtual tiver sido encerrado devido a um tempo limite ou outra falha.
WSAECONNRESET	uma conexão existente foi fechada forçadamente pelo host remoto. Esse erro é retornado para um soquete de fluxo quando o circuito virtual foi redefinido pelo lado remoto. O aplicativo deve fechar o soquete porque ele não pode ser mais usado.
WSAEFAULT	O sistema detectou um endereço de ponteiro inválido ao tentar usar um argumento de ponteiro em uma chamada. Esse erro será retornado se o lpPacketArray ou o parâmetro lpOverlapped não estiver totalmente contido em uma parte válida do espaço de endereço do usuário.
WSAEINVAL	Foi fornecido um argumento inválido. Esse erro será retornado se o parâmetro dwFlags tiver o sinalizador TF_REUSE_SOCKET definido, mas o sinalizador TF_DISCONNECT não estiver definido. Esse erro também será retornado se o deslocamento especificado na estrutura OVERLAPPED apontada pelo lpOverlapped não estiver dentro do arquivo. Esse erro também será retornado se o número total de bytes a serem transmitidos for um valor maior que 2.147.483.646, o valor máximo para um inteiro de 32 bits menos 1.
WSAENETDOWN	Uma operação de soquete encontrou uma rede morta. Esse erro será retornado se o subsistema de rede falhar.
WSAENETRESET	A conexão foi interrompida porque a atividade de manutenção de funcionamento detectou uma falha enquanto a operação estava em andamento. Esse erro é retornado para um soquete de fluxo em que a conexão foi interrompida devido à atividade keep alive detectando uma falha.
WSAENOBUFS	Não foi possível executar uma operação em um soquete porque o sistema não tinha espaço suficiente no buffer ou porque uma fila estava cheia. Esse erro também será retornado se o provedor do Windows Sockets relatar um deadlock de buffer.
WSAENOTCONN	Uma solicitação para enviar ou receber dados não foi permitida porque o soquete não está conectado. Esse erro é retornado para um soquete de fluxo.
WSAENOTSOCK	Houve uma tentativa de executar uma operação em algo que não é um soquete. Esse erro será retornado se o parâmetro hSocket não for um soquete.
WSAESHUTDOWN	Uma solicitação para enviar ou receber dados não foi permitida, pois o soquete já havia sido desligado nessa direção com uma chamada de desligamento anterior. Esse erro será retornado se um soquete de fluxo tiver sido desligado para envio. Não é possível chamar TransmitFile em um soquete de fluxo depois que a função de desligamento tiver sido chamada no soquete com o parâmetro how definido como SD_SEND ou SD_BOTH.
WSANOTINITIALISED	O aplicativo não chamou a função WSAStartup ou WSAStartup falhou. Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar a função TransmitFile .
WSA_IO_PENDING	Uma operação de E/S sobreposta está em andamento. Esse valor será retornado se uma operação de E/S sobreposta tiver sido iniciada com êxito e indicar que a conclusão será indicada posteriormente.
WSA_OPERATION_ABORTED	A operação de E/S foi anulada devido ao encerramento de um thread ou a uma solicitação de aplicativo. Esse erro será retornado se a operação sobreposta tiver sido cancelada devido ao fechamento do soquete, à execução do comando "SIO_FLUSH" no WSAIoctl ou ao thread que iniciou a solicitação sobreposta encerrada antes da conclusão da operação. Nota Todas as E/S iniciadas por um determinado thread são canceladas quando esse thread é encerrado. Para soquetes sobrepostos, as operações assíncronas pendentes podem falhar se o thread for fechado antes da conclusão das operações assíncronas. Para obter mais informações, consulte ExitThread.

Comentários

A função TransmitPackets é otimizada de acordo com o sistema operacional no qual ela é usada:

Nas edições do Windows Server, a função TransmitPackets é otimizada para alto desempenho.
Nas edições do cliente Windows, a função TransmitPackets é otimizada para utilização mínima de memória e recursos.

O número máximo de bytes que podem ser transmitidos usando uma única chamada para a função TransmitPackets é 2.147.483.646, o valor máximo para um inteiro de 32 bits menos 1. Se um aplicativo precisar transmitir dados maiores que 2.147.483.646 bytes, várias chamadas para a função TransmitPackets poderão ser usadas com cada chamada transferindo no máximo 2.147.483.646 bytes.

Nota O ponteiro de função para a função TransmitPackets deve ser obtido em tempo de execução fazendo uma chamada para a função WSAIoctl com o SIO_GET_EXTENSION_FUNCTION_POINTER opcode especificado. O buffer de entrada passado para a função WSAIoctl deve conter WSAID_TRANSMITPACKETS, um GUID (identificador global exclusivo) cujo valor identifica a função de extensão TransmitPackets . Em caso de êxito, a saída retornada pela função WSAIoctl contém um ponteiro para a função TransmitPackets . O GUID WSAID_TRANSMITPACKETS é definido no arquivo de cabeçalho Mswsock.h .

Espere melhores resultados de desempenho ao usar a função TransmitPackets no Windows Server 2003.

Quando lpOverlapped não é NULL, a E/S sobreposta pode não ser concluída antes que a função TransmitPackets retorne. Quando isso ocorre, a função TransmitPackets retorna falha e uma chamada para a função WSAGetLastError retorna ERROR_IO_PENDING, permitindo que o chamador continue processando enquanto a transmissão é concluída.

Nota Todas as E/S iniciadas por um determinado thread são canceladas quando esse thread é encerrado. Para soquetes sobrepostos, as operações assíncronas pendentes poderão falhar se o thread for fechado antes da conclusão das operações. Consulte ExitThread para obter mais informações.

Quando a função TransmitPackets retorna TRUE ou retorna FALSE e WSAGetLastError retorna ERROR_IO_PENDING, o Windows define o evento especificado pelo membro hEvent da estrutura OVERLAPPED ou o soquete especificado por hSocket para o estado sinalizado e, após a conclusão, entrega notificação a qualquer porta de conclusão associada ao soquete. Use GetOverlappedResult ou WSAGetOverlappedResult ou GetQueuedCompletionStatus para recuperar o status final e o número de bytes transmitidos.

ApCs (chamadas de procedimento assíncrono) e TransmitPackets

O uso do sinalizador TF_USE_KERNEL_APC pode oferecer benefícios significativos de desempenho. Se o thread que inicia a chamada de função TransmitPackets estiver sendo usado para cálculos pesados, é possível, embora improvável, que as APCs possam ser impedidas de iniciar.

Nota Há uma diferença entre as APCs do kernel e do modo de usuário:

As APCs de kernel são iniciadas quando um thread está em um estado de espera.
As APCs no modo de usuário são iniciadas quando um thread está em um estado de espera alertável.

Windows Phone 8: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8.1, Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	mswsock.h