Função TransmitFile (mswsock.h)

Artigo
08/25/2023

A função TransmitFile transmite dados de arquivo por um identificador de soquete conectado. Essa função usa o gerenciador de cache do sistema operacional para recuperar os dados do arquivo e fornece transferência de dados de arquivo de alto desempenho por soquetes.

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

Sintaxe

BOOL TransmitFile(
  SOCKET                  hSocket,
  HANDLE                  hFile,
  DWORD                   nNumberOfBytesToWrite,
  DWORD                   nNumberOfBytesPerSend,
  LPOVERLAPPED            lpOverlapped,
  LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers,
  DWORD                   dwReserved
);

Parâmetros

hSocket

Um identificador para um soquete conectado. A função TransmitFile transmitirá os dados do arquivo por esse soquete. O soquete especificado pelo parâmetro hSocket deve ser um soquete orientado à conexão do tipo SOCK_STREAM, SOCK_SEQPACKET ou SOCK_RDM.

hFile

Um identificador para o arquivo aberto que a função TransmitFile transmite. Como o sistema operacional lê os dados do arquivo sequencialmente, você pode melhorar o desempenho do cache abrindo o identificador com FILE_FLAG_SEQUENTIAL_SCAN.

O parâmetro hFile é opcional. Se o parâmetro hFile for NULL, somente os dados no cabeçalho e/ou no buffer final serão transmitidos. Qualquer ação adicional, como desconexão ou reutilização de soquete, é executada conforme especificado pelo parâmetro dwFlags .

nNumberOfBytesToWrite

O número de bytes no arquivo a ser transmitido. A função TransmitFile é concluída quando envia o número especificado de bytes ou quando ocorre um erro, o que ocorrer primeiro.

Defina esse parâmetro como zero para transmitir todo o arquivo.

nNumberOfBytesPerSend

O tamanho, em bytes, de cada bloco de dados enviados em cada operação de envio. Esse parâmetro é usado pela camada de soquetes do Windows para determinar o tamanho do bloco para operações de envio. Para selecionar o tamanho de envio padrão, defina esse parâmetro como zero.

O parâmetro nNumberOfBytesPerSend é útil para protocolos que têm limitações no tamanho de solicitações de envio individuais.

lpOverlapped

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

Você pode usar o parâmetro lpOverlapped para especificar um deslocamento de 64 bits dentro do arquivo no qual iniciar a transferência de dados de arquivo definindo o membro Offset e OffsetHigh da estrutura OVERLAPPED . Se lpOverlapped for um ponteiro NULL , a transmissão de dados sempre será iniciada no deslocamento de bytes atual no arquivo.

Quando o lpOverlapped não é NULL, a E/S sobreposta pode não ser concluída antes do retorno do TransmitFile . Nesse caso, a função TransmitFile retorna FALSE e WSAGetLastError retorna ERROR_IO_PENDING ou WSA_IO_PENDING. Isso permite que o chamador continue processando enquanto a operação de transmissão de arquivo é concluída. O Windows definirá o evento especificado pelo membro hEvent da estrutura OVERLAPPED ou o soquete especificado por hSocket para o estado sinalizado após a conclusão da solicitação de transmissão de dados.

lpTransmitBuffers

Um ponteiro para um TRANSMIT_FILE_BUFFERS estrutura de dados que contém ponteiros para os dados a serem enviados antes e depois que os dados do arquivo são enviados. Esse parâmetro deve ser definido como um ponteiro NULL se você quiser transmitir apenas os dados do arquivo.

dwReserved

Um conjunto de sinalizadores usados para modificar o comportamento da chamada de função TransmitFile . O parâmetro dwFlags pode conter uma combinação das seguintes opções definidas no arquivo de cabeçalho Mswsock.h :

Sinalizador	Significado
TF_DISCONNECT	Inicie uma desconexão de nível de transporte depois que todos os dados do arquivo forem colocados em fila para transmissão.
TF_REUSE_SOCKET	Prepare o identificador do soquete para ser reutilizado. Esse sinalizador só será válido se TF_DISCONNECT também for especificado. Quando a solicitação TransmitFile for concluída, o identificador de soquete poderá ser passado para a chamada de função usada anteriormente para estabelecer a conexão, como AcceptEx ou ConnectEx. Essa reutilização é mutuamente exclusiva; por exemplo, se a função AcceptEx foi chamada para o soquete, a reutilização é permitida apenas para chamadas subsequentes para a função AcceptEx e não é permitida para uma chamada subsequente para ConnectEx. Nota A transmissão de arquivo 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 TransmitFile seja atrasada.
TF_USE_DEFAULT_WORKER	Direciona o provedor de serviços do Windows Sockets para usar o thread padrão do sistema para processar solicitações de TransmitFile longas. O thread padrão do sistema pode ser ajustado usando o seguinte parâmetro do Registro como um REG_DWORD: HKEY_LOCAL_MACHINE\Currentcontrolset\Serviços\AFD\Parâmetros\TransmitWorker
TF_USE_SYSTEM_THREAD	Direciona o provedor de serviços do Windows Sockets para usar threads do sistema para processar solicitações de TransmitFile longas.
TF_USE_KERNEL_APC	Direciona o driver a usar APCs (chamadas de procedimento assíncronas) do kernel em vez de threads de trabalho para processar solicitações de TransmitFile longas. As solicitações Long TransmitFile são definidas como solicitações que exigem mais de uma única leitura do arquivo ou de um cache; portanto, a solicitação depende do tamanho do arquivo e do comprimento especificado do pacote de envio. O uso de TF_USE_KERNEL_APC pode oferecer benefícios significativos de desempenho. É possível (embora improvável), no entanto, que o thread no qual o Contexto TransmitFile é iniciado esteja sendo usado para cálculos pesados; essa situação pode impedir a inicialização de APCs. Observe que o driver do modo kernel Winsock usa APCs de kernel normais, que são iniciadas sempre que um thread está em um estado de espera, que difere das APCs do modo de usuário, que são iniciadas sempre que um thread está em um estado de espera alertável iniciado no modo de usuário).
TF_WRITE_BEHIND	Conclua a solicitação TransmitFile imediatamente, sem pendências. Se esse sinalizador for especificado e TransmitFile for bem-sucedido, os dados serão aceitos pelo sistema, mas não necessariamente reconhecidos pelo extremidade remoto. Não use essa configuração com os sinalizadores TF_DISCONNECT e TF_REUSE_SOCKET. Nota Se o arquivo que está sendo enviado não estiver no cache do sistema de arquivos, a solicitação será pendente.

Retornar valor

Se a função TransmitFile 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 parâmetro lpTransmitBuffers ou 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 hSocket especificar um soquete do tipo SOCK_DGRAM ou SOCK_RAW. 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 parâmetro nNumberOfBytesToWrite for definido como 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.
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.
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 o soquete tiver sido desligado para envio. Não é possível chamar TransmitFile em um soquete 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 TransmitFile usa o gerenciador de cache do sistema operacional para recuperar os dados do arquivo e fornecer transferência de dados de arquivo de alto desempenho por soquetes.

A função TransmitFile só dá suporte a soquetes orientados à conexão do tipo SOCK_STREAM, SOCK_SEQPACKET e SOCK_RDM. Não há suporte para soquetes do tipo SOCK_DGRAM e SOCK_RAW . A função TransmitPackets pode ser usada com soquetes do tipo SOCK_DGRAM.

O número máximo de bytes que podem ser transmitidos usando uma única chamada para a função TransmitFile é 2.147.483.646, o valor máximo para um inteiro de 32 bits menos 1. O número máximo de bytes a serem enviados em uma única chamada inclui todos os dados enviados antes ou depois dos dados de arquivo apontados pelo parâmetro lpTransmitBuffers mais o valor especificado no parâmetro nNumberOfBytesToWrite para o comprimento dos dados de arquivo a serem enviados. Se um aplicativo precisar transmitir um arquivo maior que 2.147.483.646 bytes, várias chamadas para a função TransmitFile poderão ser usadas com cada chamada transferindo não mais do que 2.147.483.646 bytes. Definir o parâmetro nNumberOfBytesToWrite como zero para um arquivo maior que 2.147.483.646 bytes também falhará, pois, nesse caso, a função TransmitFile usará o tamanho do arquivo como o valor do número de bytes a serem transmitidos.

Nota O ponteiro de função para a função TransmitFile 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_TRANSMITFILE, um GUID (identificador global exclusivo) cujo valor identifica a função de extensão TransmitFile . Com êxito, a saída retornada pela função WSAIoctl contém um ponteiro para a função TransmitFile . O GUID WSAID_TRANSMITFILE é definido no arquivo de cabeçalho Mswsock.h .

ObservaçãoTransmitFile não está funcional em transportes que executam seu próprio buffer. Os transportes com o sinalizador TDI_SERVICE_INTERNAL_BUFFERING definido, como ADSP, executam seu próprio buffer. Como o TransmitFile obtém seus ganhos de desempenho enviando dados diretamente do cache de arquivos. Os transportes que ficam sem espaço de buffer em uma conexão específica não são tratados pelo TransmitFile e, como resultado da execução do espaço fora do buffer na conexão, o TransmitFile retorna STATUS_DEVICE_NOT_READY.

A função TransmitFile foi adicionada principalmente ao Winsock para uso por aplicativos de servidor de alto desempenho (servidores Web e ftp, por exemplo).

As versões de estação de trabalho e cliente do Windows otimizam a função TransmitFile para memória mínima e utilização de recursos limitando o número de operações simultâneas de TransmitFile permitidas no sistema a um máximo de duas. No Windows Vista, Windows XP, Windows 2000 Professional e Windows NT Workstation 3.51 e posteriores, apenas duas solicitações de TransmitFile pendentes são tratadas simultaneamente; a terceira solicitação aguardará até que uma das solicitações anteriores seja concluída.

As versões de servidor do Windows otimizam a função TransmitFile para alto desempenho. Nas versões do servidor, não há limites padrão colocados no número de operações simultâneas do TransmitFile permitidas no sistema. Espere melhores resultados de desempenho ao usar o TransmitFile em versões de servidor do Windows. Em versões de servidor do Windows, é possível definir um limite no número máximo de operações simultâneas do TransmitFile criando uma entrada do Registro e definindo um valor para o seguinte REG_DWORD:

HKEY_LOCAL_MACHINE\Currentcontrolset\Serviços\AFD\Parâmetros\MaxActiveTransmitFileCount

Se a função TransmitFile for chamada com soquete TCP (protocolo de IPPROTO_TCP) com os sinalizadores TF_DISCONNECT e TF_REUSE_SOCKET especificados, a chamada não será concluída até que as duas condições a seguir sejam atendidas.

Todos os dados de recebimento pendentes enviados pelo lado remoto (recebidos antes de uma FIN do lado remoto) no soquete TCP foram lidos.
O lado remoto fechou a conexão (concluiu o fechamento normal da conexão TCP).

Se a função TransmitFile for chamada com o parâmetro lpOverlapped definido como NULL, a operação será executada como E/S síncrona. A função não será concluída até que o arquivo seja enviado.

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.

Notas para QoS

A função TransmitFile permite a configuração de dois sinalizadores, TF_DISCONNECT ou TF_REUSE_SOCKET, que retornam o soquete a um estado "desconectado e reutilizável" após a transmissão do arquivo. Esses sinalizadores não devem ser usados em um soquete em que a qualidade do serviço foi solicitada, pois o provedor de serviços pode excluir imediatamente qualquer qualidade de serviço associada ao soquete antes que a transferência de arquivo seja concluída. A melhor abordagem para um soquete habilitado para QoS é simplesmente chamar a função closesocket quando a transferência de arquivo for concluída, em vez de depender desses sinalizadores.

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 (inclua Mswsock.h)
Biblioteca	Mswsock.lib
DLL	Mswsock.dll