Estrutura WSAMSG (ws2def.h)

Artigo
08/28/2023

A estrutura WSAMSG é usada com as funções LPFN_WSARECVMSG (WSARecvMsg) e WSASendMsg para armazenar informações de endereço e controle opcional sobre soquetes conectados e não conectados, bem como uma matriz de buffers usados para armazenar dados de mensagens.

Sintaxe

typedef struct _WSAMSG {
  LPSOCKADDR name;
  INT        namelen;
  LPWSABUF   lpBuffers;
#if ...
  ULONG      dwBufferCount;
#else
  DWORD      dwBufferCount;
#endif
  WSABUF     Control;
#if ...
  ULONG      dwFlags;
#else
  DWORD      dwFlags;
#endif
} WSAMSG, *PWSAMSG, *LPWSAMSG;

Membros

name

Tipo: LPSOCKADDR

Um ponteiro para uma estrutura de SOCKET_ADDRESS que armazena informações sobre o endereço remoto. Usado somente com soquetes não conectados.

namelen

Tipo: INT

O comprimento, em bytes, da estrutura SOCKET_ADDRESS apontada no membro pAddr . Usado somente com soquetes não conectados.

lpBuffers

Tipo: LPWSABUF

Uma matriz de estruturas WSABUF usadas para receber os dados da mensagem. A capacidade do membro lpBuffers de conter vários buffers permite o uso de E/S de dispersão/coleta.

dwBufferCount

Tipo: DWORD

O número de buffers apontados no membro lpBuffers .

Control

Tipo: WSABUF

Uma estrutura do tipo WSABUF usada para especificar dados de controle opcionais. Consulte Observações.

dwFlags

Tipo: DWORD

Um ou mais sinalizadores de controle, especificados como o OR lógico dos valores. Os valores possíveis para o membro dwFlags na entrada são definidos no arquivo de cabeçalho Winsock2.h. Os valores possíveis para o membro dwFlags na saída são definidos no arquivo de cabeçalho Ws2def.h que é incluído automaticamente pelo arquivo de cabeçalho Winsock2.h.

Sinalizadores na entrada	Significado
MSG_PEEK	Inspeção dos dados de entrada. Os dados são copiados para o buffer, mas não são removidos da fila de entrada. Esse sinalizador é válido apenas para soquetes não sobrepostos.

Sinalizador retornado	Significado
MSG_BCAST	O datagrama foi recebido como uma transmissão de camada de link ou com um endereço IP de destino que é um endereço de difusão.
MSG_MCAST	O datagrama foi recebido com um endereço IP de destino que é um endereço multicast.
MSG_TRUNC	O datagrama foi truncado. Mais dados estavam presentes do que a sala alocada para o processo.
MSG_CTRUNC	Os dados de controle (auxiliares) foram truncados. Mais dados de controle estavam presentes do que a sala alocada para o processo.

Comentários

No Microsoft Software Development Kit do Windows (SDK do Windows) (SDK), a versão dessa estrutura para uso no Windows Vista é definida com o tipo de dados para os membros dwBufferCount e dwFlags como um ULONG. Ao compilar um aplicativo se a plataforma de destino for Windows Vista e posterior (NTDDI_VERSION >= NTDDI_LONGHORN, _WIN32_WINNT >= 0x0600 ou WINVER >= 0x0600), o tipo de dados para os membros dwBufferCount e dwFlags é um ULONG.

Windows Server 2003 e Windows XP: Ao compilar um aplicativo, o tipo de dados para os membros dwBufferCount e dwFlags é um DWORD.

Na SDK do Windows lançada para o Windows Vista e posterior, a estrutura WSAMSG é definida no arquivo de cabeçalho Ws2def.h. Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente no Winsock2.h e nunca deve ser usado diretamente

Se os dados de datagrama ou controle forem truncados durante a transmissão, a função que está sendo usada em associação com a estrutura WSAMSG retornará SOCKET_ERROR e uma chamada para a função WSAGetLastError retornará WSAEMSGSIZE. Cabe ao aplicativo determinar o que foi truncado verificando MSG_TRUNC e/ou sinalizadores de MSG_CTRUNC.

Uso do membro de controle

A tabela a seguir resume os vários usos de dados de controle disponíveis para uso no membro Control para IPv4 e IPv6.

Protocolo	cmsg_level	cmsg_type	Descrição
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	Recebe a interface de chegada IPv4 original em que o pacote foi recebido para soquetes de datagrama. Esses dados de controle são usados por firewalls quando um túnel Teredo, 6to4 ou ISATAP é usado para passagem NAT IPv4. O membro cmsg_data[] na estrutura WSAMSG é um ULONG que contém o IF_INDEX definido no arquivo de cabeçalho Ifdef.h. Para obter mais informações, consulte as opções de soquete IPPROTO_IP para a opção de soquete IP_ORIGINAL_ARRIVAL_IF. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para o cmsg_type de IP_ORIGINAL_ARRIVAL_IF .
IPv4	IPPROTO_IP	IP_PKTINFO	Especifica/recebe informações de pacote para um soquete IPv4. Para obter mais informações, consulte a opção de soquete IP_PKTINFO .
IPv4	IPPROTO_IP	IP_ECN	Especifica/recebe o ponto de código ECN no campo de cabeçalho IPv4 do Tipo de Serviço (TOS). Para obter mais informações, consulte WSASetRecvIPEcn.
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 um soquete IPv6. Para obter mais informações, consulte a opção de soquete IPV6_PKTINFO .
IPv6	IPPROTO_IPV6	IPV6_RTHDR	Especifica/recebe o cabeçalho de roteamento.
IPv6	IPPROTO_IPV6	IPV6_ECN	Especifica/recebe o ponto de código ECN no campo cabeçalho IPv6 da Classe de Tráfego. Para obter mais informações, consulte WSASetRecvIPEcn.

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 a seguir.

struct wsacmsghdr {
  UINT        cmsg_len;
  INT         cmsg_level;
  INT         cmsg_type;
  /* followed by UCHAR cmsg_data[] */
} WSACMSGHDR;

Nota O transporte, não o aplicativo, preenche as informações de cabeçalho na estrutura WSACMSGHDR . O aplicativo simplesmente define as opções de soquete necessárias e fornece o tamanho adequado do buffer.

Os membros da estrutura WSACMSGHDR são os seguintes:

Termo	Descrição
cmsg_len	O número de bytes de dados desde o início do WSACMSGHDR até o final dos dados (excluindo bytes de preenchimento que podem seguir 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.

As macros a seguir são usadas para navegar pelos objetos de dados:


#define LPCMSGHDR *WSA_CMSG_FIRSTHDR(LPWSAMSG msg);

Retorna um ponteiro para o primeiro objeto de dados de controle. Retorna um ponteiro NULL se não houver dados de controle na estrutura WSAMSG , como quando o membro Control é um ponteiro NULL .


#define LPCMSGHDR *WSA_CMSG_NXTHDR(LPWSAMSG msg, LPWSACMSGHDR cmsg);

Retorna um ponteiro para o próximo objeto de dados de controle ou NULL se não houver mais objetos de dados. Se o parâmetro pcmsg for NULL, um ponteiro para o primeiro objeto de dados de controle será retornado.


#define UCHAR *WSA_CMSG_DATA(LPWSACMSGHDR pcmsg);

Retorna um ponteiro para o primeiro byte de dados (chamado de membro cmsg_data , embora não esteja definido na estrutura).


#define UINT WSA_CMSG_SPACE(UINT length);

Retorna o tamanho total de um objeto de dados de controle, dada a quantidade de dados. Usado para alocar a quantidade correta de espaço em buffer. Inclui preenchimento de alinhamento.


#define UINT WSA_CMSG_LEN(UINT length);

Retorna o valor em cmsg_len dada a quantidade de dados. Inclui preenchimento de alinhamento.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Cabeçalho	ws2def.h (inclua Winsock2.h)