Структура WSAMSG (ws2def.h)

Статья
08/28/2023

Структура WSAMSG используется с функциями LPFN_WSARECVMSG (WSARecvMsg) и WSASendMsg для хранения сведений об адресе и необязательных элементах управления подключенных и неподключенных сокетах, а также массива буферов, используемых для хранения данных сообщений.

Синтаксис

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;

Члены

name

Тип: LPSOCKADDR

Указатель на структуру SOCKET_ADDRESS , в котором хранятся сведения об удаленном адресе. Используется только с несвязанными сокетами.

namelen

Тип: INT

Длина в байтах структуры SOCKET_ADDRESS , на который указывает элемент pAddr . Используется только с несвязанными сокетами.

lpBuffers

Тип: LPWSABUF

Массив структур WSABUF , используемых для получения данных сообщения. Возможность элемента lpBuffers содержать несколько буферов позволяет использовать точечный/сборный ввод-вывод.

dwBufferCount

Тип: DWORD

Количество буферов, на которые указывает элемент lpBuffers .

Control

Тип: WSABUF

Структура типа WSABUF , используемая для указания необязательных данных элемента управления. См. заметки.

dwFlags

Тип: DWORD

Один или несколько флагов элемента управления, указанных в качестве логического ИЛИ значений. Возможные значения для элемента dwFlags во входных данных определяются в файле заголовка Winsock2.h. Возможные значения для элемента dwFlags в выходных данных определяются в файле заголовка Ws2def.h, который автоматически включается в файл заголовка Winsock2.h.

Флаги для входных данных	Значение
MSG_PEEK	Обзор во входящих данных. Данные копируются в буфер, но не удаляются из входной очереди. Этот флаг действителен только для неперекрывающихся сокетов.

Возвращенный флаг	Значение
MSG_BCAST	Датаграмма была получена в виде широковещательного канала или с IP-адресом назначения, который является широковещательным адресом.
MSG_MCAST	Датаграмма получена с IP-адресом назначения, который является адресом многоадресной рассылки.
MSG_TRUNC	Датаграмма была усечена. Было больше данных, чем выделено процессом.
MSG_CTRUNC	Данные элемента управления (вспомогательные) были усечены. Было больше данных управления, чем выделено процессом.

В microsoft пакет средств разработки программного обеспечения для Windows (SDK) версия этой структуры для использования в Windows Vista определяется с типом данных для членов dwBufferCount и dwFlags как ULONG. При компиляции приложения, если целевой платформой является Windows Vista и более поздних версий (NTDDI_VERSION >= NTDDI_LONGHORN, _WIN32_WINNT >= 0x0600 или WINVER >= 0x0600), типом данных для членов dwBufferCount и dwFlags является ULONG.

Windows Server 2003 и Windows XP: При компиляции приложения типом данных для членов dwBufferCount и dwFlags является DWORD.

На Windows SDK, выпущенном для Windows Vista и более поздних версий, структура WSAMSG определена в файле заголовка Ws2def.h. Обратите внимание, что файл заголовка Ws2def.h автоматически включается в Winsock2.h и никогда не должен использоваться напрямую.

Если датаграмма или управляющие данные усекаются во время передачи, функция, используемая в связи со структурой WSAMSG , возвращает SOCKET_ERROR а вызов функции WSAGetLastError возвращает WSAEMSGSIZE . Приложение определяет, что было усечено, проверив наличие флагов MSG_TRUNC и (или) MSG_CTRUNC.

Использование элемента управления

В следующей таблице перечислены различные варианты использования данных управления, доступных для использования в элементе Control для IPv4 и IPv6.

Протокол	cmsg_level	cmsg_type	Описание
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	Получает исходный интерфейс поступления IPv4, в котором был получен пакет для сокетов датаграмм. Эти управляющие данные используются брандмауэрами при использовании туннеля Teredo, 6to4 или ISATAP для обхода NAT IPv4. Элемент cmsg_data[] в структуре WSAMSG — это ULONG , содержащий IF_INDEX, определенный в файле заголовка Ifdef.h. Дополнительные сведения см. в разделе Параметры сокета IPPROTO_IP для параметра сокета IP_ORIGINAL_ARRIVAL_IF. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: cmsg_type IP_ORIGINAL_ARRIVAL_IF не поддерживается.
IPv4	IPPROTO_IP	IP_PKTINFO	Указывает или получает сведения о пакете для сокета IPv4. Дополнительные сведения см. в разделе параметр сокета IP_PKTINFO .
IPv4	IPPROTO_IP	IP_ECN	Указывает или получает кодовую точку ECN в поле заголовка IPv4 типа службы (TOS). Дополнительные сведения см. в разделе WSASetRecvIPEcn.
IPv6	IPPROTO_IPV6	IPV6_DSTOPTS	Задает и получает параметры назначения.
IPv6	IPPROTO_IPV6	IPV6_HOPLIMIT	Указывает ограничение прыжков и их получение. Дополнительные сведения см. в разделе Параметры сокета IPPROTO_IPV6 для параметра сокета IPV6_HOPLIMIT.
IPv6	IPPROTO_IPV6	IPV6_HOPOPTS	Задает и получает параметры перехода за прыжком.
IPv6	IPPROTO_IPV6	IPV6_NEXTHOP	Указывает адрес следующего прыжка.
IPv6	IPPROTO_IPV6	IPV6_PKTINFO	Указывает или получает сведения о пакете для сокета IPv6. Дополнительные сведения см. в разделе параметр сокета IPV6_PKTINFO .
IPv6	IPPROTO_IPV6	IPV6_RTHDR	Указывает/получает заголовок маршрутизации.
IPv6	IPPROTO_IPV6	IPV6_ECN	Указывает или получает кодовую точку ECN в поле заголовка IPv6 класса трафика. Дополнительные сведения см. в разделе WSASetRecvIPEcn.

Управляющие данные состоят из одного или нескольких объектов данных управления, каждый из которых начинается со структуры WSACMSGHDR , определенной следующим образом.

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

Примечание Транспорт, а не приложение, заполняет сведения о заголовке в структуре WSACMSGHDR . Приложение просто задает необходимые параметры сокета и предоставляет достаточный размер буфера.

Ниже приведены элементы структуры WSACMSGHDR :

Термин	Описание
cmsg_len	Число байтов данных, начиная с начала WSACMSGHDR и до конца данных (за исключением байтов заполнения, которые могут следовать за данными).
cmsg_level	Протокол, который является источником сведений об элементе управления.
cmsg_type	Тип сведений об элементах управления для конкретного протокола.

Для навигации по объектам данных используются следующие макросы:


#define LPCMSGHDR *WSA_CMSG_FIRSTHDR(LPWSAMSG msg);

Возвращает указатель на первый объект данных элемента управления. Возвращает указатель NULL , если в структуре WSAMSG отсутствуют управляющие данные, например, если элемент control является указателем NULL .


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

Возвращает указатель на следующий объект данных элемента управления или значение NULL , если больше нет объектов данных. Если параметр pcmsg имеет значение NULL, возвращается указатель на первый объект данных элемента управления.


#define UCHAR *WSA_CMSG_DATA(LPWSACMSGHDR pcmsg);

Возвращает указатель на первый байт данных (который называется элементом cmsg_data , хотя он не определен в структуре).


#define UINT WSA_CMSG_SPACE(UINT length);

Возвращает общий размер объекта данных элемента управления с учетом объема данных. Используется для выделения правильного объема буферного пространства. Включает заполнение выравнивания.


#define UINT WSA_CMSG_LEN(UINT length);

Возвращает значение в cmsg_len с учетом объема данных. Включает заполнение выравнивания.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Верхняя часть	ws2def.h (включая Winsock2.h)