Estrutura WSAMSG (ws2def.h)

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.

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.

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;

Os membros da estrutura WSACMSGHDR são os seguintes:

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

Confira também

IPV6_PKTINFO

IP_PKTINFO

SOCKET_ADDRESS

WSABUF

WSARecv

WSARecvFrom

LPFN_WSARECVMSG (WSARecvMsg)

WSASendMsg