Compartilhar via

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

  • Artigo

A função RIOSendEx envia dados de rede em um soquete TCP de E/S registrado conectado ou em um soquete UDP de E/S registrado associado com opções adicionais para uso com as extensões de E/S registradas do Winsock.

Sintaxe

LPFN_RIOSENDEX LpfnRiosendex;

BOOL LpfnRiosendex(
  RIO_RQ SocketQueue,
  PRIO_BUF pData,
  ULONG DataBufferCount,
  PRIO_BUF pLocalAddress,
  PRIO_BUF pRemoteAddress,
  PRIO_BUF pControlContext,
  PRIO_BUF pFlags,
  DWORD Flags,
  PVOID RequestContext
)
{...}

Parâmetros

SocketQueue

Um descritor que identifica um soquete TCP de E/S registrado conectado ou um soquete UDP de E/S associado.

pData

Um segmento de buffer de um buffer registrado do qual enviar dados. A estrutura RIO_BUF apontada por esse parâmetro pode representar uma parte de um buffer registrado ou um buffer registrado completo.

Esse parâmetro poderá ser NULL para um soquete UDP de E/S associado se o aplicativo não precisar enviar uma carga de dados no datagrama UDP.

DataBufferCount

Um parâmetro de contagem de buffer de dados que indica se os dados devem ser enviados no buffer apontado pelo parâmetro pData .

Esse parâmetro deverá ser definido como zero se o pData for NULL. Caso contrário, esse parâmetro deve ser definido como 1.

pLocalAddress

Esse parâmetro é reservado e deve ser NULL.

pRemoteAddress

Um segmento de buffer de um buffer registrado que na entrada contém o endereço remoto para o qual os dados de rede devem ser enviados.

Esse parâmetro poderá ser NULL se o soquete estiver conectado.

pControlContext

Uma fatia de buffer que, após a conclusão, conterá informações de controle adicionais sobre a operação de envio.

Esse parâmetro poderá ser NULL se o aplicativo não quiser receber as informações de controle adicionais.

pFlags

Uma fatia de buffer que, após a conclusão, conterá informações adicionais sobre o conjunto de sinalizadores para a operação de envio.

Esse parâmetro poderá ser NULL se o aplicativo não quiser receber as informações de sinalizadores adicionais.

Flags

Um conjunto de sinalizadores que modificam o comportamento da função RIOSendEx .

O parâmetro Flags pode conter uma combinação das seguintes opções, definidas no arquivo de Mswsockdef.h cabeçalho:

RIO_MSG_COMMIT_ONLY

As solicitações anteriores adicionadas com RIO_MSG_DEFER sinalizador serão confirmadas.

Quando o sinalizador RIO_MSG_COMMIT_ONLY é definido, nenhum outro sinalizador pode ser especificado. Quando o sinalizador RIO_MSG_COMMIT_ONLY é definido, os argumentos pData, pLocalAddress, pRemoteAddress, pControlContext, pFlags e RequestContext devem ser NULL e o argumento DataBufferCount deve ser zero.

Normalmente, esse sinalizador seria usado ocasionalmente depois que várias solicitações fossem emitidas com o sinalizador RIO_MSG_DEFER definido. Isso elimina a necessidade ao usar o sinalizador RIO_MSG_DEFER para fazer a última solicitação sem o sinalizador RIO_MSG_DEFER , o que faz com que a última solicitação seja concluída muito mais lentamente do que outras solicitações.

Ao contrário de outras chamadas para a função RIOSendEx , quando o sinalizador RIO_MSG_COMMIT_ONLY é definido, as chamadas para a função RIOSendEx não precisam ser serializadas. Para um único RIO_RQ, a função RIOSendEx pode ser chamada com RIO_MSG_COMMIT_ONLY em um thread ao chamar a função RIOSendEx em outro thread.

RIO_MSG_DONT_NOTIFY

A solicitação não deve disparar a função RIONotify quando a conclusão da solicitação é inserida em sua fila de conclusão.

RIO_MSG_DEFER

A solicitação não precisa ser executada imediatamente. Isso inserirá a solicitação na fila de solicitações, mas pode ou não disparar a execução da solicitação.

O envio de dados pode ser atrasado até que uma solicitação de envio seja feita na RIO_RQ passada no parâmetro SocketQueue sem o sinalizador RIO_MSG_DEFER definido. Para disparar a execução de todos os envios em uma fila de envio, chame a função RIOSend ou RIOSendEx sem o sinalizador RIO_MSG_DEFER definido.

Observação

A solicitação de envio é cobrada contra a capacidade de E/S pendente na RIO_RQ passada no parâmetro SocketQueue , independentemente de RIO_MSG_DEFER ser definida.

RequestContext

O contexto de solicitação a ser associado a essa operação de envio.

Retornar valor

Se nenhum erro ocorrer, a função RIOSendEx retornará TRUE. Nesse caso, a operação de envio foi iniciada com êxito e a conclusão já terá sido enfileirada ou a operação foi iniciada com êxito e a conclusão será enfileirada posteriormente.

Um valor false indica que a função falhou, a operação não foi iniciada com êxito e nenhuma indicação de conclusão será enfileirada. Um código de erro específico pode ser recuperado chamando a função WSAGetLastError .

Código de retorno Descrição
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 um identificador de buffer for desregistrado ou um buffer for liberado para qualquer uma das estruturas de RIO_BUF passadas em parâmetros antes que a operação seja enfileirada ou invocada.
WSAEINVAL Um parâmetro inválido foi passado para a função.
Esse erro será retornado se o parâmetro SocketQueue não for válido, o parâmetro Flags contiver um valor inválido para uma operação de envio ou a integridade da fila de conclusão tiver sido comprometida. Esse erro também pode ser retornado para outros problemas com parâmetros.
WSAENOBUFS Não foi possível alocar memória suficiente. Esse erro será retornado se a fila de conclusão de E/S associada ao parâmetro SocketQueue estiver cheia ou a fila de conclusão de E/S tiver sido criada sem entradas de envio.
WSA_IO_PENDING A operação foi iniciada com êxito e a conclusão será enfileirada posteriormente.

Comentários

Um aplicativo pode usar a função RIOSendEx para enviar dados de rede de qualquer buffer completamente contido em um único buffer registrado. Os membros Offset e Length da estrutura RIO_BUF apontada pelo parâmetro pData determinam os dados de rede a serem enviados do buffer.

O buffer associado a uma operação de envio não deve ser usado simultaneamente com outra operação de envio ou recebimento. O buffer e o registro de buffer devem permanecer válidos durante uma operação de envio. Isso significa que você não deve passar a mesma PRIO_BUF para uma solicitação RIOSend(Ex) quando uma já está pendente. Somente depois que uma solicitação RIOSend(Ex) for concluída, você deverá reutilize o mesmo PRIO_BUF (com o mesmo deslocamento ou com um deslocamento e comprimento diferentes). Além disso, quando o envio de dados faz referência a um buffer registrado (uma parte ou o buffer inteiro), todo o buffer registrado não deve ser usado até que o envio seja concluído. Isso inclui o uso de uma parte do buffer registrado para uma operação de recebimento ou outra operação de envio.

O parâmetro pLocalAddress pode ser usado para recuperar o endereço local do qual os dados foram enviados. O parâmetro pRemoteAddress pode ser usado para recuperar o endereço remoto para o qual os dados foram enviados. Os endereços locais e remotos são retornados como estruturas SOCKADDR_INET . Como resultado, o membro Length do RIO_BUF apontado pelos parâmetros pLocalAddress ou pRemoteAddress deve ser igual ou maior que o tamanho de uma estrutura SOCKADDR_INET .

A tabela a seguir resume os vários usos de dados de controle disponíveis para uso com as informações de controle no membro pControlContext .

Protocolo cmsg_level cmsg_type Descrição
IPv4 IPPROTO_IP IP_PKTINFO Especifica/recebe informações de pacote.
Para obter mais informações, consulte as Opções de soquete IPPROTO_IP para a opção de soquete IP_PKTINFO.
IPv6 IPPROTO_IPV6 IPV6_DSTOPTS Especifica/recebe opções de destino.
IPv6 IPPROTO_IPV6 IPV6_HOPLIMIT Especifica/recebe o limite de salto.
Para obter mais informações, consulte as Opções de soquete IPPROTO_IPV6 para a opção de soquete IPV6_HOPLIMIT.
IPv6 IPPROTO_IPV6 IPV6_HOPOPTS Especifica/recebe opções de salto por salto.
IPv6 IPPROTO_IPV6 IPV6_NEXTHOP Especifica o endereço do próximo salto.
IPv6 IPPROTO_IPV6 IPV6_PKTINFO Especifica/recebe informações de pacote.
Para obter mais informações, consulte as Opções de soquete IPPROTO_IPV6 para a opção de soquete IPV6_PKTINFO.
IPv6 IPPROTO_IPV6 IPV6_RTHDR Especifica/recebe o cabeçalho de roteamento.

Os dados de controle são compostos por um ou mais objetos de dados de controle, cada um começando com uma estrutura WSACMSGHDR , definida como o seguinte:

} WSACMSGHDR;

Os membros da estrutura WSACMSGHDR são os seguintes:

Termo Descrição
cmsg_len O número de bytes de dados que começam desde o início do WSACMSGHDR até o final dos dados (excluindo bytes de preenchimento que podem seguir os dados).
cmsg_level O protocolo que originou as informações de controle.
cmsg_type O tipo específico de protocolo de informações de controle.

O parâmetro Flags pode ser usado para influenciar o comportamento da função RIOSendEx além das opções especificadas para o soquete associado. O comportamento dessa função é determinado por uma combinação de todas as opções de soquete definidas no soquete associado ao parâmetro SocketQueue e aos valores especificados no parâmetro Flags .

Observação

O ponteiro de função para a função RIOSendEx deve ser obtido em tempo de execução fazendo uma chamada para a função WSAIoctl com o SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode especificado. O buffer de entrada passado para a função WSAIoctl deve conter WSAID_MULTIPLE_RIO, um GUID (identificador global exclusivo) cujo valor identifica as funções de extensão de E/S registradas do Winsock. Em caso de êxito, a saída retornada pela função WSAIoctl contém um ponteiro para a estrutura RIO_EXTENSION_FUNCTION_TABLE que contém ponteiros para as funções de extensão de E/S registradas do Winsock. O SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL é definido no arquivo de cabeçalho Ws2def.h . O GUID WSAID_MULTIPLE_RIO é definido no arquivo de cabeçalho Mswsock.h .

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
Cabeçalho mswsock.h