Struttura WSAMSG (ws2def.h)

Articolo
03/13/2024

La struttura WSAMSG viene usata con le funzioni LPFN_WSARECVMSG WSARecvMsg (WSARecvMsg) e WSASendMsg per archiviare informazioni di controllo e indirizzo su socket connessi e non connessi, nonché una matrice di buffer usati per archiviare i dati dei messaggi.

Sintassi

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;

Members

name

Tipo: LPSOCKADDR

Puntatore a una struttura SOCKET_ADDRESS che archivia informazioni sull'indirizzo remoto. Usato solo con socket non connessi.

namelen

Tipo: INT

Lunghezza, in byte, della struttura SOCKET_ADDRESS a cui punta nel membro pAddr . Usato solo con socket non connessi.

lpBuffers

Tipo: LPWSABUF

Matrice di strutture WSABUF usate per ricevere i dati del messaggio. La funzionalità del membro lpBuffers per contenere più buffer consente l'uso di I/O a dispersione/raccolta.

dwBufferCount

Tipo: DWORD

Numero di buffer a cui punta il membro lpBuffers .

Control

Tipo: WSABUF

Struttura di tipo WSABUF usata per specificare i dati di controllo facoltativi. Vedere la sezione Osservazioni.

dwFlags

Tipo: DWORD

Uno o più flag di controllo, specificati come OR logico dei valori. I valori possibili per i membri dwFlags nell'input sono definiti nel file di intestazione Winsock2.h. I valori possibili per i membri dwFlags nell'output sono definiti nel file di intestazione Ws2def.h che viene incluso automaticamente dal file di intestazione Winsock2.h.

Flag sull'input	Significato
MSG_PEEK	Anteprima rapida ai dati in ingresso. I dati vengono copiati nel buffer, ma non vengono rimossi dalla coda di input. Questo flag è valido solo per socket non sovrapposti.

Flag restituito	Significato
MSG_BCAST	Il datagram è stato ricevuto come trasmissione a livello di collegamento o con un indirizzo IP di destinazione che è un indirizzo broadcast.
MSG_MCAST	Il datagram è stato ricevuto con un indirizzo IP di destinazione che è un indirizzo multicast.
MSG_TRUNC	Il datagram è stato troncato. Sono stati presenti più dati rispetto alla stanza allocata dal processo.
MSG_CTRUNC	I dati di controllo (ausiliario) sono stati troncati. Sono stati presenti più dati di controllo rispetto alla stanza allocata per il processo.

Commenti

In Microsoft Windows Software Development Kit (Windows SDK) (SDK), la versione di questa struttura da usare in Windows Vista viene definita con il tipo di dati per i membri dwBufferCount e dwFlags come ULONG. Quando si compila un'applicazione se la piattaforma di destinazione è Windows Vista e versioni successive (NTDDI_VERSION = NTDDI_LONGHORN, _WIN32_WINNT >= 0x0600 >o WINVER >= 0x0600), il tipo di dati per i membri dwBufferCount e dwFlags è un ULONG.

Windows Server 2003 e Windows XP: Quando si compila un'applicazione, il tipo di dati per i membri dwBufferCount e dwFlags è una DWORD.

Nella Windows SDK rilasciata per Windows Vista e versioni successive, la struttura WSAMSG viene definita nel file di intestazione Ws2def.h. Si noti che il file di intestazione Ws2def.h viene incluso automaticamente in Winsock2.h e non deve mai essere usato direttamente

Se i dati del datagram o del controllo vengono troncati durante la trasmissione, la funzione usata in associazione alla struttura WSAMSG restituisce SOCKET_ERROR e una chiamata alla funzione WSAGetLastError restituisce WSAEMSGSIZE. L'applicazione deve determinare cosa è stato troncato controllando MSG_TRUNC e/o MSG_CTRUNC flag.

Uso del membro del controllo

La tabella seguente riepiloga i vari usi dei dati di controllo disponibili per l'uso nel membro Control per IPv4 e IPv6.

Protocollo	cmsg_level	cmsg_type	Descrizione
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	Riceve l'interfaccia di arrivo IPv4 originale in cui è stato ricevuto il pacchetto per i socket di datagram. Questi dati di controllo vengono usati dai firewall quando viene usato un tunnel Teredo, 6to4 o ISATAP per l'attraversamento NAT IPv4. Il membro cmsg_data[] nella struttura WSAMSG è un ULONG che contiene la IF_INDEX definita nel file di intestazione Ifdef.h. Per altre informazioni, vedere opzioni socket IPPROTO_IP per l'opzione socket IP_ORIGINAL_ARRIVAL_IF. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Il IP_ORIGINAL_ARRIVAL_IF cmsg_type non è supportato.
IPv4	IPPROTO_IP	IP_PKTINFO	Specifica/riceve le informazioni sui pacchetti per un socket IPv4. Per altre informazioni, vedere l'opzione IP_PKTINFO socket.
IPv4	IPPROTO_IP	IP_ECN	Specifica/riceve il punto di codice ECN nel campo intestazione IPv4 Type of Service (TOS). Per altre informazioni, vedere WSASetRecvIPEcn.
IPv6	IPPROTO_IPV6	IPV6_DSTOPTS	Specifica/riceve le opzioni di destinazione.
IPv6	IPPROTO_IPV6	IPV6_HOPLIMIT	Specifica/riceve il limite di hop. Per altre informazioni, vedere opzioni socket IPPROTO_IPV6 per l'opzione socket IPV6_HOPLIMIT.
IPv6	IPPROTO_IPV6	IPV6_HOPOPTS	Specifica/riceve opzioni hop-by-hop.
IPv6	IPPROTO_IPV6	IPV6_NEXTHOP	Specifica l'indirizzo hop successivo.
IPv6	IPPROTO_IPV6	IPV6_PKTINFO	Specifica/riceve le informazioni sui pacchetti per un socket IPv6. Per altre informazioni, vedere l'opzione socket IPV6_PKTINFO .
IPv6	IPPROTO_IPV6	IPV6_RTHDR	Specifica/riceve l'intestazione di routing.
IPv6	IPPROTO_IPV6	IPV6_ECN	Specifica/riceve il punto di codice ECN nel campo intestazione IPv6 della classe di traffico. Per altre informazioni, vedere WSASetRecvIPEcn.

I dati di controllo sono costituiti da uno o più oggetti dati di controllo, ognuno che inizia con una struttura WSACMSGHDR , definita come segue.

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

Nota Il trasporto, non l'applicazione, compila le informazioni di intestazione nella struttura WSACMSGHDR . L'applicazione imposta semplicemente le opzioni socket necessarie e fornisce le dimensioni del buffer adeguate.

I membri della struttura WSACMSGHDR sono i seguenti:

Termine	Descrizione
cmsg_len	Numero di byte di dati a partire dall'inizio di WSACMSGHDR alla fine dei dati (esclusi i byte di spaziatura interna che possono seguire i dati).
cmsg_level	Protocollo che ha originato le informazioni sul controllo.
cmsg_type	Tipo specifico del protocollo delle informazioni sul controllo.

Per spostarsi tra gli oggetti dati vengono utilizzate le macro seguenti:


#define LPCMSGHDR *WSA_CMSG_FIRSTHDR(LPWSAMSG msg);

Restituisce un puntatore al primo oggetto dati del controllo. Restituisce un puntatore NULL se non sono presenti dati di controllo nella struttura WSAMSG , ad esempio quando il membro Control è un puntatore NULL .


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

Restituisce un puntatore all'oggetto dati del controllo successivo o NULL se non sono presenti più oggetti dati. Se il parametro pcmsg è NULL, viene restituito un puntatore al primo oggetto dati del controllo.


#define UCHAR *WSA_CMSG_DATA(LPWSACMSGHDR pcmsg);

Restituisce un puntatore al primo byte di dati (detto membro cmsg_data , anche se non è definito nella struttura).


#define UINT WSA_CMSG_SPACE(UINT length);

Restituisce la dimensione totale di un oggetto dati del controllo, in base alla quantità di dati. Usato per allocare la quantità corretta di spazio buffer. Include la spaziatura interna dell'allineamento.


#define UINT WSA_CMSG_LEN(UINT length);

Restituisce il valore in cmsg_len in base alla quantità di dati. Include la spaziatura interna dell'allineamento.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Intestazione	ws2def.h (include Winsock2.h)