IP_PKTINFO socket option

The IP_PKTINFO socket option allows an application to enable or disable the return of packet information by the LPFN_WSARECVMSG (WSARecvMsg) function on an IPv4 socket..

To query the status of this socket option, call the getsockopt function. To set this option, call the setsockopt function with the following parameters.

Socket option value

The constant that represents this socket option is 19.

Syntax

int getsockopt(
  (SOCKET) s,      // descriptor identifying a socket 
  (int) IPPROTO_IP,   // level
  (int) IP_PKTINFO, // optname
  (char *) optval, // output buffer,
  (int) optlen,  // size of output buffer
);

int setsockopt(
  (SOCKET) s,      // descriptor identifying a socket 
  (int) IPPROTO_IP,   // level
  (int) IP_PKTINFO, // optname
  (char *) optval, // input buffer,
  (int) optlen,  // size of input buffer
);

Parameters

s [in]

A descriptor identifying the socket.

level [in]

The level at which the option is defined. Use IPPROTO_IP for this operation.

optname [in]

The socket option for which to get or set the value. Use IP_PKTINFO for this operation.

optval [out]

A pointer to the buffer containing the value for the option to set. This parameter should point to buffer equal to or larger than the size of a DWORD value.

This value is treated as a boolean value with 0 used to indicate FALSE (disabled) and a nonzero value to indicate TRUE (enabled).

optlen [in, out]

A pointer to the size, in bytes, of the optval buffer. This size must be equal to or larger than the size of a DWORD value.

Return value

If the operation completes successfully, the getsockopt or setsockopt function returns zero.

If the operation fails, a value of SOCKET_ERROR is returned and a specific error code can be retrieved by calling WSAGetLastError.

Remarks

The getsockopt function called with the IP_PKTINFO socket option allows an application to determine if packet information is to be returned by the LPFN_WSARECVMSG (WSARecvMsg)function for an IPv4 socket.

The setsockopt function called with the IP_PKTINFO socket option allows an application to enable or disable the return of packet information by the LPFN_WSARECVMSG (WSARecvMsg) function. The IP_PKTINFO option for a socket is disabled (set to FALSE) by default.

When this socket option is enabled on an IPv4 socket of type SOCK_DGRAM or SOCK_RAW, the LPFN_WSARECVMSG (WSARecvMsg) function returns packet information in the WSAMSG structure pointed to by the lpMsg parameter. One of the control data objects in the returned WSAMSG structure will contain an in_pktinfo structure used to store received packet address information.

For datagrams received by the LPFN_WSARECVMSG (WSARecvMsg) function over IPv4, the Control member of the WSAMSG structure received will contain a WSABUF structure that contains a WSACMSGHDR structure. The cmsg_level member of this WSACMSGHDR structure would contain IPPROTO_IP, the cmsg_type member of this structure would contain IP_PKTINFO, and the cmsg_data member would contain an in_pktinfo structure used to store received IPv4 packet address information. The IPv4 address in the in_pktinfo structure is the IPv4 address from which the packet was received.

For a dual-stack datagram socket, if an application requires the LPFN_WSARECVMSG (WSARecvMsg) function to return packet information in a WSAMSG structure for datagrams received over IPv4, then IP_PKTINFO socket option must be set to true on the socket. If only the IPV6_PKTINFO option is set to true on the socket, packet information will be provided for datagrams received over IPv6 but may not be provided for datagrams received over IPv4.

If an application tries to set the IP_PKTINFO socket option on a dual-stack datagram socket and IPv4 is disabled on the system, then the setsockopt function will fail and WSAGetLastError will return with an error of WSAEINVAL. This same error is also returned by the setsockopt function as a result of other errors. If an application tries to set an IPPROTO_IP level socket option on a dual-stack socket and it fails with WSAEINVAL, then the application should determine if IPv4 is disabled on the local computer. One method that can be used to detect if IPv4 is enabled or disabled is to call the socket function with the af parameter set to AF_INET to try and create an IPv4 socket. If the socket function fails and WSAGetLastError returns an error of WSAEAFNOSUPPORT, then it means IPv4 is not enabled. In this case, a setsockopt function failure when attempting to set the IP_PKTINFO socket option can be ignored by the application. Otherwise a failure when attempting to set the IP_PKTINFO socket option should be treated as an unexpected error.

Note that the Ws2ipdef.h header file is automatically included in Ws2tcpip.h, and should never be used directly.

Requirements

See also

Dual-Stack Sockets

getsockopt

in_pktinfo

IPPROTO_IP Socket Options

IPV6_PKTINFO

setsockopt

socket

WSAMSG

LPFN_WSARECVMSG (WSARecvMsg)