Tenouk C & C++ |< Winsock Functions 2 | Main | Winsock Functions 4 >| Site Index | Download | Linux Socket | Winsock in .NET


 

 

 

 

 

 

 

Winsock 2 References:

Functions, structures etc. used in program examples Part 1

 

 

 

 

 

 

 

Winsock Reference

 

Winsock reference in MSDN is divided into the following sections:

  1. Socket Options.

  2. Winsock Annexes.

  3. Winsock Enumerations.

  4. Winsock Functions.

  5. Winsock Structures.

 

 

Socket Options

 

Use the getsockopt() and setsockopt() functions for more getting and setting socket options. To enumerate protocols and discover supported properties for each installed protocol, use the WSAEnumProtocols() function. The following socket option levels are available:

  1. IPPROTO_IP

  2. IPPROTO_IPV6

  3. IPPROTO_RM

  4. IPPROTO_TCP

  5. IPPROTO_UDP

  6. NSPROTO_IPX

  7. SOL_APPLETALK

  8. SOL_IRLMP

  9. SOL_SOCKET

 

All SO_* socket options apply equally to IPv4 and IPv6 (except SO_BROADCAST, since broadcast is not implemented in IPv6).

 

Winsock Annexes

 

Winsock Annexes provide implementation information for common Winsock protocol suites, and discuss how to use each protocol with Winsock. Each protocol in this annex has conventions, behaviors, or special features that do not lend themselves to generic implementation. This section documents details that developers must consider when implementing or using the described protocols. The Winsock Annexes include the following sections:

  1. Winsock ATM Annex.

  2. Winsock IPX/SPX Annex.

  3. Winsock TCP/IP Annex.

 

Winsock ATM Annex

 

ATM is applicable to both LAN and WAN environments. An ATM network simultaneously transports a wide variety of network traffic - voice, data, image, and video. It provides users with a guaranteed quality of service on a per-virtual channel (VC) basis.

 

Element

Description

Protocol name(s)

ATMPROTO_AAL5, ATMPROTO_AALUSER

Description

ATM AAL5 provides a transport service that is connection-oriented, message-boundary preserved, and QOS guaranteed. ATMPROTO_AALUSER is a user-defined AAL.

Address family

AF_ATM

Header file

ws2atm.h

 

Table 1

 

This section describes the Asynchronous Transfer Mode (ATM)-specific extensions needed to support the native ATM services as exposed and specified in the ATM Forum User Network Interface (UNI) specification version 3.x (3.0 and 3.1). This document supports AAL type 5 (message mode) and user-defined AAL. Future versions of this document will support other types of AAL as well as UNI 4.0.

 

Winsock IPX/SPX Annex

 

This section describes Winsock extensions specific to Internetwork Packet Exchange/Sequenced Packet Exchange (IPX/SPX). It also describes aspects of base Winsock functions that either require special consideration or may exhibit unique behavior.

 

Element

Description

Protocol name(s)

IPX, SPX

Description

Provides transport services over the IPX networking layer: IPX for unreliable datagrams, SPX for reliable, connection-oriented message streams.

Address family

AF_IPX

Header file

wsipx.h

 

Table 2

 

This section discusses how to use Winsock with the IPX family of protocols, enabling traditional IPX applications to be ported to Winsock. IPX networks operate in a fundamentally different manner than IP networks, so such differences must be considered when using IPX/SPX.

 

Winsock TCP/IP Annex

 

This section describes Transmission Control Protocol/Internet Protocol (TCP/IP) functions, data structures, and controls.

 

Element

Description

Protocol name(s)

TCP, UDP

Description

Provides two transport services over the IP networking layer: UDP for unreliable datagrams, TCP for reliable, connection-oriented byte streams.

Address family

AF_INET

Header file

ws2tcpip.h

 

Table 3

 

Two basic types of transport services are offered: unreliable datagrams (UDP), and reliable connection oriented–byte streams (TCP). In addition, a raw socket is optionally supported. Raw sockets allow an application to communicate through protocols other than TCP and UDP such as ICMP. This section covers extensions to Winsock that are specific to TCP/IP protocols. It also describes aspects of base Winsock functions that require special consideration or that may exhibit unique behavior when using TCP/IP.

 

Winsock Enumerations

 

The following list provides concise descriptions of each Winsock enumeration. For additional information on any enumeration, click the enumeration name.

 

Enumeration

Description

eWINDOW_ADVANCE_METHOD

Specifies the window advance mode used for Reliable Multicast.

WSAECOMPARATOR

Used for version-comparison semantics.

 

Table 4

 

Winsock Functions

 

The following list provides concise descriptions of each Winsock function.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Function

Description

accept()

Permits an incoming connection attempt on a socket.

AcceptEx()

Accepts a new connection, returns the local and remote address, and receives the first block of data sent by the client application.

bind()

Associates a local address with a socket.

closesocket()

Closes an existing socket.

connect()

Establishes a connection to a specified socket.

ConnectEx()

Establishes a connection to a specified socket, and optionally sends data once the connection is established. Only supported on connection-oriented sockets.

DisconnectEx()

Closes a connection on a socket, and allows the socket handle to be reused.

EnumProtocols()

Retrieves information about a specified set of network protocols that are active on a local host.

freeaddrinfo()

Frees address information that the getaddrinfo() function dynamically allocates in its addrinfo structures.

gai_strerror()

Assists in printing error messages based on the EAI_* errors returned by the getaddrinfo() function.

GetAcceptExSockaddrs()

Parses the data obtained from a call to the AcceptEx() function.

GetAddressByName()

Queries a namespace, or a set of default namespaces, to retrieve network address information for a specified network service. This process is known as service name resolution. A network service can also use the function to obtain local address information that it can use with the bind function.

getaddrinfo()

Provides protocol-independent translation from host name to address.

gethostbyaddr()

Retrieves the host information corresponding to a network address.

gethostbyname()

Retrieves host information corresponding to a host name from a host database. Deprecated: use getaddrinfo instead.

gethostname()

Retrieves the standard host name for the local computer.

GetNameByType()

Retrieves the name of a network service for the specified service type.

getnameinfo()

Provides name resolution from an address to the host name.

getpeername()

Retrieves the name of the peer to which a socket is connected.

getprotobyname()

Retrieves the protocol information corresponding to a protocol name.

getprotobynumber()

Retrieves protocol information corresponding to a protocol number.

getservbyname()

Retrieves service information corresponding to a service name and protocol.

getservbyport()

Retrieves service information corresponding to a port and protocol.

GetService()

Retrieves information about a network service in the context of a set of default namespaces or a specified namespace.

getsockname()

Retrieves the local name for a socket.

getsockopt()

Retrieves a socket option.

GetTypeByName()

Retrieves a service type GUID for a network service specified by name.

htonl()

Converts a u_long from host to TCP/IP network byte order (which is big-endian).

htons()

Converts a u_short from host to TCP/IP network byte order (which is big-endian).

inet_addr()

Converts a string containing an (Ipv4) Internet Protocol dotted address into a proper address for the in_addr structure.

inet_ntoa()

Converts an (IPv4) Internet network address into a string in Internet standard dotted format.

ioctlsocket()

Controls the I/O mode of a socket.

listen()

Places a socket a state where it is listening for an incoming connection.

ntohl()

Converts a u_long from TCP/IP network order to host byte order (which is little-endian on Intel processors).

ntohs()

Converts a u_short from TCP/IP network byte order to host byte order (which is little-endian on Intel processors).

recv()

Receives data from a connected or bound socket.

recvfrom()

Receives a datagram and stores the source address.

select()

Determines the status of one or more sockets, waiting if necessary, to perform synchronous I/O.

send()

Sends data on a connected socket.

sendto()

Sends data to a specific destination.

SetService()

Registers or removes from the registry a network service within one or more namespaces. Can also add or remove a network service type within one or more namespaces.

setsockopt()

Sets a socket option.

shutdown()

Disables sends or receives on a socket.

socket()

Creates a socket that is bound to a specific service provider.

TransmitFile()

Transmits file data over a connected socket handle.

TransmitPackets()

Transmits in-memory data or file data over a connected socket.

WSAAccept()

Conditionally accepts a connection based on the return value of a condition function, provides quality of service flow specifications, and allows the transfer of connection data.

WSAAddressToString()

Converts all components of a sockaddr structure into a human-readable string representation of the address.

WSAAsyncGetHostByAddr()

Asynchronously retrieves host information that corresponds to an address.

WSAAsyncGetHostByName()

Asynchronously retrieves host information that corresponds to a host name.

WSAAsyncGetProtoByName()

Asynchronously retrieves protocol information that corresponds to a protocol name.

WSAAsyncGetProtoByNumber()

Asynchronously retrieves protocol information that corresponds to a protocol number.

WSAAsyncGetServByName()

Asynchronously retrieves service information that corresponds to a service name and port.

WSAAsyncGetServByPort()

Asynchronously retrieves service information that corresponds to a port and protocol.

WSAAsyncSelect()

Requests Windows message-based notification of network events for a socket.

WSACancelAsyncRequest()

Cancels an incomplete asynchronous operation.

WSACleanup()

Terminates use of the Ws2_32.DLL.

WSACloseEvent()

Closes an open event object handle.

WSAConnect()

Establishes a connection to another socket application, exchanges connect data, and specifies needed quality of service based on the specified FLOWSPEC structure.

WSACreateEvent()

Creates a new event object.

WSADuplicateSocket()

Returns a structure that can be used to create a new socket descriptor for a shared socket.

WSAEnumNameSpaceProviders()

Retrieves information about available namespaces.

WSAEnumNetworkEvents()

Discovers occurrences of network events for the indicated socket, clear internal network event records, and reset event objects (optional).

WSAEnumProtocols()

Retrieves information about available transport protocols.

WSAEventSelect()

Specifies an event object to be associated with the specified set of FD_XXX network events.

__WSAFDIsSet()

Specifies whether a socket is included in a set of socket descriptors.

WSAGetLastError()

Returns the error status for the last operation that failed.

WSAGetOverlappedResult()

Retrieves the results of an overlapped operation on the specified socket.

WSAGetQOSByName()

Initializes a QOS structure based on a named template, or it supplies a buffer to retrieve an enumeration of the available template names.

WSAGetServiceClassInfo()

Retrieves the class information (schema) pertaining to a specified service class from a specified namespace provider.

WSAGetServiceClassNameByClassId()

Retrieves the name of the service associated with the specified type.

WSAHtonl()

Converts a u_long from host byte order to network byte order.

WSAHtons()

Converts a u_short from host byte order to network byte order.

WSAInstallServiceClass()

Registers a service class schema within a namespace.

WSAIoctl()

Controls the mode of a socket.

WSAJoinLeaf()

Joins a leaf node into a multipoint session, exchanges connect data, and specifies needed quality of service based on the specified structures.

WSALookupServiceBegin()

Initiates a client query that is constrained by the information contained within a WSAQUERYSET structure.

WSALookupServiceEnd()

Frees the handle used by previous calls to WSALookupServiceBegin() and WSALookupServiceNext().

WSALookupServiceNext()

Retrieve the requested service information.

WSANSPIoctl()

Developers to make I/O control calls to a registered namespace.

WSANtohl()

Converts a u_long from network byte order to host byte order.

WSANtohs()

Converts a u_short from network byte order to host byte order.

WSAProviderConfigChange()

Notifies the application when the provider configuration is changed.

WSARecv()

Receives data from a connected socket.

WSARecvDisconnect()

Terminates reception on a socket, and retrieves the disconnect data if the socket is connection oriented.

WSARecvEx()

Receives data from a connected socket.

WSARecvFrom()

Receives a datagram and stores the source address.

WSARecvMsg()

Receives data and optional control information from connected and unconnected sockets.

WSARemoveServiceClass()

Permanently removes the service class schema from the registry.

WSAResetEvent()

Resets the state of the specified event object to non-signaled.

WSASend()

Sends data on a connected socket.

WSASendDisconnect()

Initiates termination of the connection for the socket and sends disconnect data.

WSASendTo()

Sends data to a specific destination, using overlapped I/O where applicable.

WSASetEvent()

Sets the state of the specified event object to signaled.

WSASetLastError()

Sets the error code.

WSASetService()

Registers or removes from the registry a service instance within one or more namespaces.

WSASocket()

Creates a socket that is bound to a specific transport-service provider.

WSAStartup()

Initiates use of WS2_32.DLL by a process.

WSAStringToAddress()

Converts a numeric string to a sockaddr structure.

WSAWaitForMultipleEvents()

Returns either when one or all of the specified event objects are in the signaled state, or when the time-out interval expires.

 

Table 5

 

 

 

 

 

 

 

 

 

 

   

 

 

 

 

 

 

 

 

 

 

Winsock Structures

 

The following list provides concise descriptions of each Winsock structure.

 

Structure

Description

addrinfo

Used by the getaddrinfo() function to hold host address information.

AFPROTOCOLS

Supplies a list of protocols to which application programmers can constrain queries. Used for query purposes only.

BLOB

Contains information about a block of data. Derived from Binary Large Object.

CSADDR_INFO

Contains Winsock address information for a network service or namespace provider.

fd_set

Used by various Winsock functions and service providers, such as select(), to place sockets into a "set" for various purposes, such as testing a given socket for readability.

hostent

Stores information about a given host, such as host name, IP address, and so forth.

in_addr

Represents a host by its Internet address.

in_pktinfo

Stores received packet address information, and is used by Windows to return information about received packets.

in6_addr

Represents an IPv6 host by its Internet address.

in6_pktinfo

Stores received IPv6 packet address information, and is used by Windows to return information about received packets.

ip_mreq

Provides multicast group information, and is used with the IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP socket options.

ip_mreq_source

Provides multicast group information for IGMPv3.

ip_msfilter

Provides multicast filtering parameters for IGMPv3.

ipv6_mreq

Provides multicast group information for IPv6 addresses.

linger

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.

NS_SERVICE_INFO

Contains information about a network service or a network service type in the context of a specified namespace, or a set of default namespaces.

PROTOCOL_INFO

Contains information about a protocol.

protoent

Contains the name and protocol numbers that correspond to a given protocol name.

RM_FEC_INFO

Specifies settings for using forward error correction (FEC) with Reliable Multicast.

RM_RECEIVER_STATS

Provides statistical information for a Reliable Multicast receiver session.

RM_SEND_WINDOW

Specifies the Reliable Multicast send window.

RM_SENDER_STATS

Provides statistical information for a Reliable Multicast sender session.

servent

Stores or returns the name and service number for a given service name.

SERVICE_ADDRESS

Contains address information for a service.

 

Contains an array of SERVICE_ADDRESSES data structures.

SERVICE_INFO

Contains information about a network service or a network service type.

SERVICE_TYPE_INFO_ABS

Contains information about a network service type.

SERVICE_TYPE_VALUE_ABS

Contains information about a network-service type value. The information may be specific to a namespace.

sockaddr

Contains socket address information. The sockaddr structure varies depending on the protocol selected. Limited to IPv4; use SOCKADDR_STORAGE instead.

SOCKADDR_IRDA

Used with IrDA socket operations, defined by address family AF_IRDA.

SOCKADDR_STORAGE

Stores socket address information, and is sufficiently large to store IPv4 or IPv6 address information, promoting protocol-family and protocol-version independence. Use this structure in place of the sockaddr structure.

SOCKET_ADDRESS

Stores protocol-specific address information.

timeval

Used to specify time values. Associated with the Berkeley Software Distribution (BSD) file time.h.

TRANSMIT_FILE_BUFFERS

Specifies data to be transmitted before and after file data during a TransmitFile() transfer operation.

TRANSMIT_PACKETS_ELEMENT

Specifies a single data element to be transmitted by the TransmitPackets() function.

WSABUF

Enables the creation or manipulation of a data buffer.

WSACOMPLETION

Specifies completion notification settings for I/O control calls made to a registered namespace.

WSADATA

Contains information about the Windows Sockets implementation.

WSAMSG

Stores address and optional control information about connected and unconnected sockets. Used with the WSARecvMsg() function.

WSANAMESPACE_INFO

Contains all registration information for a namespace provider.

WSANETWORKEVENTS

Stores a socket's internal information about network events.

WSANSCLASSINFO

Provides individual parameter information for a specific Winsock namespace.

WSAOVERLAPPED

Provides a communication medium between the initiation of an overlapped I/O operation and its subsequent completion.

WSAPROTOCOL_INFO

Stores or retrieves complete information for a given protocol.

WSAPROTOCOL_INFOW

Store or retrieves complete information for a given protocol. The protocol name is represented as an array of Unicode characters.

WSAPROTOCOLCHAIN

Contains a counted list of Catalog Entry identifiers that comprise a protocol chain.

WSAQUERYSET

Provides relevant information about a given service.

WSASERVICECLASSINFO

Contains information about a specified service class.

WSAVERSION

Provides version comparison in Winsock.

 

Table 6

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Further reading and digging:

 

  1. Linux and TCP/IP.

  2. Linux Sockets: Story and program examples.

  3. Structure, enum, union and typedef story can be found struct, enum, union & typedef tutorial.

  4. For Multibytes, Unicode characters and Localization please refer to Multibyte, Unicode and wide characters (Story) and Win32 Windows & Users tutorial (Implementation).

  5. A complete info on Windows socket reference from MSDN which include managed and unmanaged API doc.

  6. Windows data type information is Win32 - Windows data types.

  7. Check the best selling C / C++ and Windows books at Amazon.com.

 

 

 

 

 

 

 


 

Tenouk C & C++ |< Winsock Functions 2 | Main | Winsock Functions 4 >| Site Index | Download | Linux Socket | Winsock in .NET