Estructura WSAMSG (ws2def.h)

Artículo
08/28/2023

La estructura WSAMSG se usa con las funciones LPFN_WSARECVMSG (WSARecvMsg) y WSASendMsg para almacenar la dirección y la información de control opcional sobre sockets conectados y no conectados, así como una matriz de búferes usados para almacenar datos de mensajes.

Sintaxis

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;

Miembros

name

Tipo: LPSOCKADDR

Puntero a una estructura de SOCKET_ADDRESS que almacena información sobre la dirección remota. Solo se usa con sockets no conectados.

namelen

Tipo: INT

Longitud, en bytes, de la estructura SOCKET_ADDRESS a la que apunta el miembro pAddr . Solo se usa con sockets no conectados.

lpBuffers

Tipo: LPWSABUF

Matriz de estructuras WSABUF usadas para recibir los datos del mensaje. La funcionalidad del miembro lpBuffers para contener varios búferes permite el uso de E/S de dispersión/recopilación.

dwBufferCount

Tipo: DWORD

Número de búferes a los que apunta el miembro lpBuffers .

Control

Tipo: WSABUF

Estructura del tipo WSABUF utilizado para especificar datos de control opcionales. Vea la sección Comentarios.

dwFlags

Tipo: DWORD

Una o varias marcas de control, especificadas como or lógico de valores. Los valores posibles para el miembro dwFlags en la entrada se definen en el archivo de encabezado Winsock2.h. Los valores posibles para el miembro dwFlags en la salida se definen en el archivo de encabezado Ws2def.h que el archivo de encabezado Winsock2.h incluye automáticamente.

Marcas en la entrada	Significado
MSG_PEEK	Inspecciona los datos entrantes. Los datos se copian en el búfer, pero no se quitan de la cola de entrada. Esta marca solo es válida para sockets no superpuestos.

Marca devuelta	Significado
MSG_BCAST	El datagrama se recibió como una difusión de capa de vínculo o con una dirección IP de destino que es una dirección de difusión.
MSG_MCAST	El datagrama se recibió con una dirección IP de destino que es una dirección de multidifusión.
MSG_TRUNC	El datagrama se ha truncado. Había más datos que el espacio asignado para el proceso.
MSG_CTRUNC	Los datos de control (auxiliares) se truncaron. Había más datos de control que el espacio asignado para el proceso.

Comentarios

En Microsoft Kit de desarrollo de software de Windows (SDK), la versión de esta estructura para su uso en Windows Vista se define con el tipo de datos para los miembros dwBufferCount y dwFlags como ULONG. Al compilar una aplicación si la plataforma de destino es Windows Vista y versiones posteriores (NTDDI_VERSION = NTDDI_LONGHORN >, _WIN32_WINNT >= 0x0600 o WINVER >= 0x0600), el tipo de datos para los miembros dwBufferCount y dwFlags es un ULONG.

Windows Server 2003 y Windows XP: Al compilar una aplicación, el tipo de datos para los miembros dwBufferCount y dwFlags es un DWORD.

En el Windows SDK publicado para Windows Vista y versiones posteriores, la estructura WSAMSG se define en el archivo de encabezado Ws2def.h. Tenga en cuenta que el archivo de encabezado Ws2def.h se incluye automáticamente en Winsock2.h y nunca se debe usar directamente.

Si los datos del datagrama o control se truncan durante la transmisión, la función que se usa en asociación con la estructura WSAMSG devuelve SOCKET_ERROR y una llamada a la función WSAGetLastError devuelve WSAEMSGSIZE. Es necesario que la aplicación determine qué se ha truncado comprobando las marcas de MSG_TRUNC o MSG_CTRUNC.

Uso del miembro de control

En la tabla siguiente se resumen los distintos usos de los datos de control disponibles para su uso en el miembro Control para IPv4 e IPv6.

Protocolo	cmsg_level	cmsg_type	Descripción
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	Recibe la interfaz de llegada IPv4 original donde se recibió el paquete para los sockets de datagrama. Los firewalls usan estos datos de control cuando se usa un túnel Teredo, 6to4 o ISATAP para el recorrido NAT de IPv4. El miembro cmsg_data[] de la estructura WSAMSG es un ULONG que contiene el IF_INDEX definido en el archivo de encabezado Ifdef.h. Para obtener más información, consulte IPPROTO_IP Opciones de socket para la opción de socket IP_ORIGINAL_ARRIVAL_IF. Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: No se admite el cmsg_type de IP_ORIGINAL_ARRIVAL_IF .
IPv4	IPPROTO_IP	IP_PKTINFO	Especifica o recibe información de paquetes para un socket IPv4. Para obtener más información, consulte la opción IP_PKTINFO socket.
IPv4	IPPROTO_IP	IP_ECN	Especifica o recibe el punto de código ECN en el campo de encabezado IPv4 tipo de servicio (TOS). Para obtener más información, consulta WSASetRecvIPEcn.
IPv6	IPPROTO_IPV6	IPV6_DSTOPTS	Especifica o recibe opciones de destino.
IPv6	IPPROTO_IPV6	IPV6_HOPLIMIT	Especifica o recibe el límite de saltos. Para obtener más información, consulte IPPROTO_IPV6 Opciones de socket para la opción de socket IPV6_HOPLIMIT.
IPv6	IPPROTO_IPV6	IPV6_HOPOPTS	Especifica o recibe opciones de salto a salto.
IPv6	IPPROTO_IPV6	IPV6_NEXTHOP	Especifica la dirección del próximo salto.
IPv6	IPPROTO_IPV6	IPV6_PKTINFO	Especifica o recibe información de paquetes para un socket IPv6. Para obtener más información, consulte la opción IPV6_PKTINFO socket.
IPv6	IPPROTO_IPV6	IPV6_RTHDR	Especifica o recibe el encabezado de enrutamiento.
IPv6	IPPROTO_IPV6	IPV6_ECN	Especifica o recibe el punto de código ECN en el campo de encabezado IPv6 de clase de tráfico. Para obtener más información, vea WSASetRecvIPEcn.

Los datos de control se componen de uno o varios objetos de datos de control, cada uno empezando por una estructura WSACMSGHDR , definida como la siguiente.

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

Nota El transporte, no la aplicación, rellena la información de encabezado en la estructura WSACMSGHDR . La aplicación simplemente establece las opciones de socket necesarias y proporciona el tamaño de búfer adecuado.

Los miembros de la estructura WSACMSGHDR son los siguientes:

Término	Descripción
cmsg_len	Número de bytes de datos que comienzan desde el principio del WSACMSGHDR hasta el final de los datos (excepto los bytes de relleno que pueden seguir los datos).
cmsg_level	Protocolo que originó la información del control.
cmsg_type	Tipo específico del protocolo de información de control.

Las macros siguientes se usan para navegar por los objetos de datos:


#define LPCMSGHDR *WSA_CMSG_FIRSTHDR(LPWSAMSG msg);

Devuelve un puntero al primer objeto de datos de control. Devuelve un puntero NULL si no hay datos de control en la estructura WSAMSG , como cuando el miembro Control es un puntero NULL .


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

Devuelve un puntero al siguiente objeto de datos de control o NULL si no hay más objetos de datos. Si el parámetro pcmsg es NULL, se devuelve un puntero al primer objeto de datos de control.


#define UCHAR *WSA_CMSG_DATA(LPWSACMSGHDR pcmsg);

Devuelve un puntero al primer byte de datos (denominado miembro cmsg_data , aunque no está definido en la estructura).


#define UINT WSA_CMSG_SPACE(UINT length);

Devuelve el tamaño total de un objeto de datos de control, dada la cantidad de datos. Se usa para asignar la cantidad correcta de espacio de búfer. Incluye relleno de alineación.


#define UINT WSA_CMSG_LEN(UINT length);

Devuelve el valor de cmsg_len dada la cantidad de datos. Incluye relleno de alineación.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Encabezado	ws2def.h (incluya Winsock2.h)