Windows sockets functions, structures and macros part 1

Windows Sockets 2: Functions, structures etc. used in program examples starting from the Winsock 2 Modules and that follows, wherever applicable.

To learn about structure you can jump to struct, typedef, enum & union tutorial and macro explained in Preprocessor directives and to learn about function you can jump to C & C++ Functions tutorials.

Index

Structures

WSADATA

WSAPROTOCOL_INFO

fd_set

Linger

SOCKADDR

SOCKADDR_IN

in_addr

SOCKADDR_STORAGE

WSAPROTOCOL_INFO

Macros

LOBYTE()

HIBYTE()

MAKEWORD()

WSADATA

Item	Description
Structure	WSADATA.
Info	A structure contains information about the Windows Sockets implementation.
Definition	typedef struct WSAData { WORD wVersion; WORD wHighVersion; char szDescription[WSADESCRIPTION_LEN+1]; char szSystemStatus[WSASYS_STATUS_LEN+1]; unsigned short iMaxSockets; unsigned short iMaxUdpDg; char FAR* lpVendorInfo; } WSADATA, *LPWSADATA;
Members	wVersion Version of the Windows Sockets specification that the Ws2_32.dll expects the caller to use. wHighVersion Highest version of the Windows Sockets specification that this .dll can support (also encoded as above). Normally this is the same as wVersion. szDescription Null-terminated ASCII string into which the Ws2_32.dll copies a description of the Windows Sockets implementation. The text (up to 256 characters in length) can contain any characters except control and formatting characters: the most likely use that an application can put this to is to display it (possibly truncated) in a status message. szSystemStatus Null-terminated ASCII string into which the WSs2_32.dll copies relevant status or configuration information. The Ws2_32.dll should use this parameter only if the information might be useful to the user or support staff: it should not be considered as an extension of the szDescription parameter. iMaxSockets Retained for backward compatibility, but should be ignored for Windows Sockets version 2 and later, as no single value can be appropriate for all underlying service providers. iMaxUdpDg Ignored for Windows Sockets version 2 and onward. The iMaxUdpDg member is retained for compatibility with Windows Sockets specification 1.1, but should not be used when developing new applications. For the actual maximum message size specific to a particular Windows Sockets service provider and socket type, applications should use getsockopt() to retrieve the value of option SO_MAX_MSG_SIZE after a socket has been created. lpVendorInfo Ignored for Windows Sockets version 2 and onward. It is retained for compatibility with Windows Sockets specification 1.1. Applications needing to access vendor-specific configuration information should use getsockopt to retrieve the value of option PVD_CONFIG. The definition of this value (if utilized) is beyond the scope of this specification.
Header file	<winsock2.h>
Remark	An application should ignore the iMaxsockets, iMaxUdpDg, and lpVendorInfo members in WSADATA if the value in wVersion after a successful call to WSAStartup is at least 2. This is because the architecture of Windows Sockets has been changed in version 2 to support multiple providers, and WSADATA no longer applies to a single vendor's stack. Two new socket options are introduced to supply provider-specific information: SO_MAX_MSG_SIZE (replaces the iMaxUdpDg element) and PVD_CONFIG (allows any other provider-specific configuration to occur).
Table 1

WSAPROTOCOL_INFO

Item	Description
Structure	WSAPROTOCOL_INFO.
Info	Used to store or retrieve complete information for a given protocol.
Definition	typedef struct _WSAPROTOCOL_INFO { DWORD dwServiceFlags1; DWORD dwServiceFlags2; DWORD dwServiceFlags3; DWORD dwServiceFlags4; DWORD dwProviderFlags; GUID ProviderId; DWORD dwCatalogEntryId; WSAPROTOCOLCHAIN ProtocolChain; int iVersion; int iAddressFamily; int iMaxSockAddr; int iMinSockAddr; int iSocketType; int iProtocol; int iProtocolMaxOffset; int iNetworkByteOrder; int iSecurityScheme; DWORD dwMessageSize; DWORD dwProviderReserved; TCHAR szProtocol[WSAPROTOCOL_LEN+1]; } WSAPROTOCOL_INFO, *LPWSAPROTOCOL_INFO;
Members	See below.
Header file	<winsock2.h>
Remark	Declared as Unicode and ANSI structures.
Table 2

Members

dwServiceFlags1

Bitmask describing the services provided by the protocol. The following values are possible:

Value	Description
XP1_CONNECTIONLESS	Provides connectionless (datagram) service. If not set, the protocol supports connection-oriented data transfer.
XP1_GUARANTEED_DELIVERY	Guarantees that all data sent will reach the intended destination.
XP1_GUARANTEED_ORDER	Guarantees that data only arrives in the order in which it was sent and that it is not duplicated. This characteristic does not necessarily mean that the data is always delivered, but that any data that is delivered is delivered in the order in which it was sent.
XP1_MESSAGE_ORIENTED	Honors message boundaries—as opposed to a stream-oriented protocol where there is no concept of message boundaries.
XP1_PSEUDO_STREAM	A message-oriented protocol, but message boundaries are ignored for all receipts. This is convenient when an application does not desire message framing to be done by the protocol.
XP1_GRACEFUL_CLOSE	Supports two-phase (graceful) close. If not set, only abortive closes are performed.
XP1_EXPEDITED_DATA	Supports expedited (urgent) data.
XP1_CONNECT_DATA	Supports connect data.
XP1_DISCONNECT_DATA	Supports disconnect data.
XP1_INTERRUPT	Bit is reserved.
XP1_SUPPORT_BROADCAST	Supports a broadcast mechanism.
XP1_SUPPORT_MULTIPOINT	Supports a multipoint or multicast mechanism. Control and data plane attributes are indicated below.
XP1_MULTIPOINT_CONTROL_PLANE	Indicates whether the control plane is rooted (value = 1) or non-rooted (value = 0).
XP1_MULTIPOINT_DATA_PLANE	Indicates whether the data plane is rooted (value = 1) or non-rooted (value = 0).
XP1_QOS_SUPPORTED	Supports quality of service requests.
XP1_UNI_SEND	Protocol is unidirectional in the send direction.
XP1_UNI_RECV	Protocol is unidirectional in the recv direction.
XP1_IFS_HANDLES	Socket descriptors returned by the provider are operating system Installable File System (IFS) handles.
XP1_PARTIAL_MESSAGE	The MSG_PARTIAL flag is supported in WSASend() and WSASendTo(). Note that only one of XP1_UNI_SEND or XP1_UNI_RECV may be set. If a protocol can be unidirectional in either direction, two WSAPROTOCOL_INFO structures should be used. When neither bit is set, the protocol is considered to be bidirectional.
Table 3

dwServiceFlags2

Reserved for additional protocol-attribute definitions.

dwServiceFlags3

Reserved for additional protocol-attribute definitions.

dwServiceFlags4

Reserved for additional protocol-attribute definitions.

dwProviderFlags

Provides information about how this protocol is represented in the protocol catalog. The following flag values are possible:

Value	Description
PFL_MULTIPLE_PROTO_ENTRIES	Indicates that this is one of two or more entries for a single protocol (from a given provider) which is capable of implementing multiple behaviors. An example of this is SPX which, on the receiving side, can behave either as a message-oriented or a stream-oriented protocol.
PFL_RECOMMENDED_PROTO_ENTRY	Indicates that this is the recommended or most frequently used entry for a protocol that is capable of implementing multiple behaviors.
PFL_HIDDEN	Set by a provider to indicate to the ws2_32.dll that this protocol should not be returned in the result buffer generated by WSAEnumProtocols(). Obviously, a Windows Sockets 2 application should never see an entry with this bit set.
PFL_MATCHES_PROTOCOL_ZERO	Indicates that a value of zero in the protocol parameter of socket() or WSASocket() matches this protocol entry.
Table 4

ProviderId

Globally unique identifier assigned to the provider by the service provider vendor. This value is useful for instances where more than one service provider is able to implement a particular protocol. An application may use the dwProviderId value to distinguish between providers that might otherwise be indistinguishable.

dwCatalogEntryId

Unique identifier assigned by the ws2_32.dll for each WSAPROTOCOL_INFO structure.

ProtocolChain

WSAPROTOCOLCHAIN structure associated with the protocol. If the length of the chain is 0, this WSAPROTOCOL_INFO entry represents a layered protocol which has Windows Sockets 2 SPI as both its top and bottom edges. If the length of the chain equals 1, this entry represents a base protocol whose Catalog Entry identifier is in the dwCatalogEntryId member of the WSAPROTOCOL_INFO structure. If the length of the chain is larger than 1, this entry represents a protocol chain which consists of one or more layered protocols on top of a base protocol. The corresponding Catalog Entry identifiers are in the ProtocolChain.ChainEntries array starting with the layered protocol at the top (the zero element in the ProtocolChain.ChainEntries array) and ending with the base protocol. Refer to the Windows Sockets 2 Service Provider Interface specification for more information on protocol chains.

iVersion

Protocol version identifier.

iAddressFamily

Value to pass as the address family parameter to the socket()/WSASocket() function in order to open a socket for this protocol. This value also uniquely defines the structure of protocol addresses sockaddrs used by the protocol.

iMaxSockAddr

Maximum address length, in bytes.

iMinSockAddr

Minimum address length, in bytes.

iSocketType

Value to pass as the socket type parameter to the socket() function in order to open a socket for this protocol.

iProtocol

Value to pass as the protocol parameter to the socket function in order to open a socket for this protocol.

iProtocolMaxOffset

Maximum value that may be added to iProtocol when supplying a value for the protocol parameter to socket and WSASocket(). Not all protocols allow a range of values. When this is the case iProtocolMaxOffset is zero.

iNetworkByteOrder

Currently these values are manifest constants (BIGENDIAN and LITTLEENDIAN) that indicate either big-endian or little-endian with the values 0 and 1 respectively.

iSecurityScheme

Indicates the type of security scheme employed (if any). A value of SECURITY_PROTOCOL_NONE is used for protocols that do not incorporate security provisions.

dwMessageSize

Maximum message size supported by the protocol. This is the maximum size, in bytes, that can be sent from any of the host's local interfaces. For protocols that do not support message framing, the actual maximum that can be sent to a given address may be less. There is no standard provision to determine the maximum inbound message size. The following special values are defined:

Value	Description
0	The protocol is stream-oriented and hence the concept of message size is not relevant.
0x1	The maximum outbound (send()) message size is dependent on the underlying network MTU (maximum sized transmission unit) and hence cannot be known until after a socket is bound. Applications should use getsockopt() to retrieve the value of SO_MAX_MSG_SIZE after the socket has been bound to a local address.
0xFFFFFFFF	The protocol is message-oriented, but there is no maximum limit to the size of messages that may be transmitted.
Table 5

dwProviderReserved

Reserved for use by service providers.

szProtocol

Array of characters that contains a human-readable name identifying the protocol, for example "SPX2". The maximum number of characters allowed is WSAPROTOCOL_LEN, which is defined to be 255.

fd_set

Item	Description
Structure	fd_set.
Info	used by various Windows Sockets functions and service providers, such as the select() function, to place sockets into a "set" for various purposes, such as testing a given socket for readability using the readfds parameter of the select function.
Definition	typedef struct fd_set { u_int fd_count; SOCKET fd_array[FD_SETSIZE]; } fd_set;
Members	fd_count Number of sockets in the set. fd_array Array of sockets that are in the set.
Header file	<winsock2.h>
Remark	-
Table 6

Linger

Item	Description
Structure	Linger.
Info	Maintains information about a specific socket that specifies how that socket should behave when data is queued to be sent and the closesocket() function is called on the socket.
Definition	typedef struct linger { u_short l_onoff; u_short l_linger; } linger;
Members	l_onoff Specifies whether a socket should remain open for a specified amount of time after a closesocket function call to enable queued data to be sent. l_linger Enabling SO_LINGER also disables SO_DONTLINGER, and vice versa. Note that if SO_DONTLINGER is DISABLED (that is, SO_LINGER is ENABLED) then no time-out value is specified. In this case, the time-out used is implementation dependent. If a previous time-out has been established for a socket (by enabling SO_LINGER), this time-out value should be reinstated by the service provider.
Header file	<winsock2.h>
Remark	To enable SO_LINGER, the application should set l_onoff to a nonzero value, set l_linger to zero or the desired time-out (in seconds), and call the setsockopt() function. To specify SO_DONTLINGER (that is, disable SO_LINGER) l_onoff should be set to zero and setsockopt should be called. Note that enabling SO_LINGER with a nonzero time-out on a non-blocking socket is not recommended.
Table 7

SOCKADDR – Winsock version 1.x.

Item	Description
Structure	SOCKADDR – Winsock version 1.x.
Info	Used to store an Internet Protocol (IP) address for a machine participating in a Windows Sockets communication.
Definition	struct sockaddr { unsigned short sa_family; char sa_data[14];};
Members	sa_family Socket address family. sa_data Maximum size of all the different socket address structures.
Header file	<winsock.h>
Remark	The Microsoft TCP/IP Sockets Developer's Kit only supports the Internet address domains. To actually fill in values for each part of an address, you use the SOCKADDR_IN data structure, which is specifically for this address format. The SOCKADDR and the SOCKADDR_IN data structures are the same size. You simply cast to switch between the two structure types.
Table 8

SOCKADDR_IN - Winsock version 1.x

Item	Description
Structure	SOCKADDR_IN - Winsock version 1.x.
Info	Used by Windows Sockets to specify a local or remote endpoint address to which to connect a socket.
Definition	struct sockaddr_in{ short sin_family; unsigned short sin_port; struct in_addr sin_addr; char sin_zero[8];};
Members	sin_family Address family (must be AF_INET). sin_port IP port. sin_addr IP address. sin_zero Padding to make structure the same size as SOCKADDR.
Header file	<winsock.h>
Remark	This is the form of the SOCKADDR structure specific to the Internet address family and can be cast to SOCKADDR. The IP address component of this structure is of type IN_ADDR that defined in <winsock.h>.
Table 9

in_addr

Item	Description
Structure	in_addr.
Info	Represents a host by its Internet address.
Definition	typedef struct in_addr { union { struct { u_char s_b1,s_b2,s_b3,s_b4; } S_un_b; struct { u_short s_w1,s_w2; } S_un_w; u_long S_addr; } S_un; } in_addr;
Members	S_un - S_un_b Address of the host formatted as four u_chars. S_un_w Address of the host formatted as two u_shorts. S_addr Address of the host formatted as a u_long.
Header file	<winsock2.h>
Remark
Table 10

SOCKADDR_STORAGE

Item	Description
Structure	SOCKADDR_STORAGE.
Info	The SOCKADDR_STORAGE structure stores socket address information. Since the SOCKADDR_STORAGE structure is sufficiently large to store IPv4 or IPv6 address information, or others, its use promotes protocol-family and protocol-version independence, and simplifies cross-platform development. Use the SOCKADDR_STORAGE structure in place of the sockaddr structure.
Definition	typedef struct sockaddr_storage { short ss_family; char __ss_pad1[_SS_PAD1SIZE]; __int64 __ss_align; char __ss_pad2[_SS_PAD2SIZE]; } SOCKADDR_STORAGE, *PSOCKADDR_STORAGE;
Members	ss_family Address family of the socket, such as AF_INET. __ss_pad1 Reserved. Defined as a 48-bit pad that ensures SOCKADDR_STORAGE achieves 64-bit alignment. __ss_align Reserved. Used by the compiler to align the structure. __ss_pad2 Reserved. Used by the compiler to align the structure.
Header file	<winsock2.h.>. Windows XP and Windows Server 2003.
Remark	Application developers use only the ss_family member of the SOCKADDR_STORAGE. The remaining three members ensure the SOCKADDR_STORAGE is padded appropriately to achieve 64-bit alignment. Such alignment enables protocol-specific socket address data structures to access fields within a SOCKADDR_STORAGE structure without alignment problems. With its padding, the SOCKADDR_STORAGE structure is 128 bytes in length. The member field of the SOCKADDR_STORAGE structure is isomorphic with the sockaddr structure to enable simplified transition from sockaddr to SOCKADDR_STORAGE. For more information about platform-independent SOCKADDR_STORAGE implementation recommendations, refer to RFC 2553, available at www.ietf.org.
Table 11

WSAPROTOCOL_INFO

Item