Código de controle SIO_IDEAL_SEND_BACKLOG_CHANGE

Artigo
10/16/2023

Descrição

O código de controle SIO_IDEAL_SEND_BACKLOG_CHANGE notifica um aplicativo quando o valor ISB (ideal da lista de pendências) de envio é alterado para a conexão.

Para executar essa operação, chame a função WSAIoctl ou WSPIoctl com os parâmetros a seguir.

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parâmetros

s

Um descritor que identifica um soquete.

dwIoControlCode

O código de controle da operação. Use SIO_IDEAL_SEND_BACKLOG_CHANGE para esta operação.

lpvInBuffer

Um ponteiro para o buffer de entrada. Esse parâmetro não é usado para esta operação.

cbInBuffer

O tamanho, em bytes, do buffer de entrada. Esse parâmetro não é usado para essa operação.

lpvOutBuffer

Um ponteiro para o buffer de saída. Esse parâmetro não é usado para esta operação.

cbOutBuffer

O tamanho, em bytes, do buffer de saída. Esse parâmetro deve ser definido como zero.

lpcbBytesReturned

Um ponteiro para uma variável que recebe o tamanho em bytes dos dados armazenados no buffer de saída. Esse parâmetro retornado aponta para um valor DWORD de zero para essa operação, pois não há saída.

lpvOverlapped

Um ponteiro para uma estrutura WSAOVERLAPPED.

Se o soquete s foi criado sem o atributo sobreposto, o parâmetro lpOverlapped será ignorado.

Se s foi aberto com o atributo sobreposto e o parâmetro lpOverlapped não é NULL, a operação é executada como uma operação sobreposta (assíncrona). Nesse caso, o parâmetro lpOverlapped deve apontar para uma estrutura WSAOVERLAPPED válida.

Para operações sobrepostas, a função WSAIoctl ou WSPIoctl retorna imediatamente e o método de conclusão apropriado é sinalizado quando a operação é concluída. Caso contrário, a função não será retornada até que a operação seja concluída ou ocorra um erro.

lpCompletionRoutine

Digite: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Um ponteiro para a rotina de conclusão chamada quando a operação foi concluída (ignorado para soquetes não sobrepostos).

lpThreadId

Um ponteiro para uma estrutura WSATHREADID a ser usada pelo provedor em uma chamada subsequente para WPUQueueApc. O provedor deve armazenar a estrutura WSATHREADID referenciada (não o ponteiro para o mesmo) até que a função WPUQueueApc retorne.

Observação Esse parâmetro se aplica somente à função WSPIoctl.

lpErrno

Um ponteiro para o código de erro.

Observação Esse parâmetro se aplica somente à função WSPIoctl.

Retornar valor

Se a operação for concluída com êxito, a função WSAIoctl ou WSPIoctl retornará zero.

Se a operação falhar ou estiver pendente, a função WSAIoctl ou WSPIoctl retornará SOCKET_ERROR. Para obter informações de erro estendidas, chame WSAGetLastError.

Código de erro	Significado
WSA_IO_PENDING	Uma operação sobreposta foi iniciada com sucesso e a conclusão será indicada posteriormente.
WSA_OPERATION_ABORTED	Uma operação sobreposta foi cancelada devido ao fechamento do soquete ou à execução do comando SIO_FLUSH do controle de E/S.
WSAEFAULT	O parâmetro lpOverlapped ou lpCompletionRoutine não está totalmente contido em uma parte válida do espaço de endereço do usuário.
WSAEINPROGRESS	A função é invocada quando um retorno de chamada está em andamento.
WSAEINTR	Uma operação de bloqueio foi interrompida.
WSAEINVAL	O parâmetro dwIoControlCode não é um comando válido, um parâmetro de entrada especificado não é aceitável ou o comando não é aplicável ao tipo de soquete especificado. Esse erro será retornado se o parâmetro cbOutBuffer não for zero.
WSAENETDOWN	O subsistema de rede falhou.
WSAENOPROTOOPT	A opção de soquete não tem suporte no protocolo especificado.
WSAENOTCONN	O soquete s não está conectado.
WSAENOTSOCK	O descritor s não é um soquete.
WSAEOPNOTSUPP	Não há suporte para o comando do controle de E/S especificado. Esse erro será retornado se o controle de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE não for compatível com o provedor de transporte. Esse erro também é retornado quando uma tentativa de usar o controle de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE é feita em um soquete de datagrama.

Comentários

O controle de E/S do SIO_IDEAL_SEND_BACKLOG_CHANGE tem suporte no Windows Server 2008, Windows Vista com Service Pack 1 (SP1) e versões posteriores do sistema operacional.

Ao enviar dados por uma conexão TCP usando Windows Sockets, é importante manter uma quantidade suficiente de dados pendentes (enviados, mas ainda não reconhecidos) no TCP para obter a taxa de transferência mais alta. O valor ideal para a quantidade de dados pendentes para obter a melhor taxa de transferência para a conexão TCP é chamado de tamanho ISB (ideal da lista de pendências de envio). O valor ISB é uma função do produto de atraso de largura de banda da conexão TCP e da janela de recebimento anunciada do receptor (e em parte da quantidade de congestionamento na rede).

O valor ISB por conexão está disponível na implementação do protocolo TCP no Windows Server 2008, Windows Vista com SP1 e versões posteriores do sistema operacional. O controle de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE pode ser usado por um aplicativo para obter uma notificação quando o valor de ISB muda dinamicamente para uma conexão.

No Windows Server 2008, Windows Vista com SP1 e versões posteriores do sistema operacional, os controles de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE e SIO_IDEAL_SEND_BACKLOG_QUERY têm suporte em soquetes orientados a fluxo que estão em um estado conectado.

O intervalo para o valor ISB para uma conexão TCP pode teoricamente variar de 0 a 16 megabytes.

Consulte na página de referência do controle de E/S SIO_IDEAL_SEND_BACKLOG_QUERY o uso típico do mecanismo ISB para obter a melhor taxa de transferência em conexões de produto com grande atraso de largura de banda.

O controle de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE é permitido somente em um soquete de fluxo que esteja no estado conectado. Caso contrário, a função WSAIoctl ou WSPIoctl falhará com WSAENOTCONN.

O controle de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE não usa buffers de entrada ou saída e torna pendente ou bloqueia até que uma alteração ISB ocorra na conexão subjacente. Quando esse controle de E/S é concluído, um aplicativo Winsock pode usar o controle de E/S SIO_IDEAL_SEND_BACKLOG_QUERY para recuperar o novo valor ISB na conexão.

O controle de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE não oferece suporte ao modo sem bloqueio. Um aplicativo tem permissão para emitir esse controle de E/S em um soquete sem bloqueio, mas o controle de E/S simplesmente bloqueará ou aguardará até que o valor de ISB mude.

Se os parâmetros lpOverlapped e lpCompletionRoutine forem NULL, o soquete nessa função será tratado como um soquete não sobreposto. Para um soquete não sobreposto, os parâmetros lpOverlapped and lpCompletionRoutine são ignorados, exceto que a função pode bloquear se o soquete s estiver no modo de bloqueio. Se o soquete s estiver no modo sem bloqueio, essa função ainda será bloqueada, pois esse controle de E/S específico não oferece suporte ao modo sem bloqueio.

Para soquetes sobrepostos, as operações que não podem ser concluídas imediatamente serão iniciadas e a conclusão será indicada posteriormente.

Qualquer controle de E/S pode bloquear indefinidamente, dependendo da implementação do provedor de serviços. Se o aplicativo não puder tolerar o bloqueio em uma chamada de função WSAIoctl ou WSPIoctl, a E/S sobreposta será recomendada para controles de E/S que são especialmente propensos a bloqueio.

O controle de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE fornece uma notificação e espera-se que bloqueie ou aguarde até que o valor ISB seja alterado. Portanto, ele normalmente seria chamado de forma assíncrona com o parâmetro lpOverlapped definido como uma estrutura WSAOVERLAPPED válida.

O controle de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE pode falhar com WSAEINTR ou WSA_OPERATION_ABORTED nos seguintes casos:

A conexão TCP é normalmente desconectada na direção de envio. Isso pode ocorrer como resultado de uma chamada para a função de desligamento com o parâmetro how definido como SD_SEND, uma chamada para a função DisconnectEx ou uma chamada para a função TransmitFile ou TransmitPackets com o parâmetro dwFlags definido como TF_DISCONNECT ou TF_REUSE.
A conexão TCP foi redefinida ou anulada.
O aplicativo emite um controle de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE quando já há uma solicitação de notificação pendente. Apenas um pedido SIO_IDEAL_SEND_BACKLOG_CHANGE pendente é permitido por vez.
A solicitação é cancelada pelo Gerente de E/S.
O soquete está fechado.

Duas funções de encapsulamento embutidas para esses controles de E/S são definidos no arquivo de cabeçalho Ws2tcpip.h. Recomenda-se que essas funções embutidas sejam usadas em vez dos controles de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE e SIO_IDEAL_SEND_BACKLOG_QUERY diretamente.

A função de encapsulamento embutida para o controle de E/S SIO_IDEAL_SEND_BACKLOG_CHANGE é a função idealsendbacklognotify.

A função de encapsulamento embutida para o controle de E/S SIO_IDEAL_SEND_BACKLOG_QUERY é a função idealsendbacklogquery.