The WSASocket function creates a socket that is bound to a specific transport-service provider.

Syntax

SOCKET WSASocket(
  __in  int af,
  __in  int type,
  __in  int protocol,
  __in  LPWSAPROTOCOL_INFO lpProtocolInfo,
  __in  GROUP g,
  __in  DWORD dwFlags
);

Parameters

af [in]

The address family specification. Possible values for the address family are defined in the Winsock2.h header file.

On the Windows SDK released for Windows Vista and later, the organization of header files has changed and the possible values for the address family are defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly.

The values currently supported are AF_INET or AF_INET6, which are the Internet address family formats for IPv4 and IPv6. Other options for address family (AF_NETBIOS for use with NetBIOS, for example) are supported if a Windows Sockets service provider for the address family is installed. Note that the values for the AF_ address family and PF_ protocol family constants are identical (for example, AF_INET and PF_INET), so either constant can be used.

The table below lists common values for address family although many other values are possible.

Af	Meaning
AF_UNSPEC 0	The address family is unspecified.
AF_INET 2	The Internet Protocol version 4 (IPv4) address family.
AF_NETBIOS 17	The NetBIOS address family. This address family is only supported if a Windows Sockets provider for NetBIOS is installed.
AF_INET6 23	The Internet Protocol version 6 (IPv6) address family.
AF_IRDA 26	The Infrared Data Association (IrDA) address family. This address family is only supported if the computer has an infrared port and driver installed.
AF_BTH 32	The Bluetooth address family. This address family is only supported if a Bluetooth adapter is installed on Windows Server 2003 or later.

 

type [in]

The type specification for the new socket. Possible values for the socket type are defined in the Winsock2.h header file.

The following table lists the possible values for the type parameter supported for Windows Sockets 2:

Type	Meaning
SOCK_STREAM 1	Provides sequenced, reliable, two-way, connection-based byte streams with an OOB data transmission mechanism. Uses the Transmission Control Protocol (TCP) for the Internet address family (AF_INET or AF_INET6).
SOCK_DGRAM 2	Supports datagrams, which are connectionless, unreliable buffers of a fixed (typically small) maximum length. Uses the User Datagram Protocol (UDP) for the Internet address family (AF_INET or AF_INET6).
SOCK_RAW 3	Provides a raw socket that allows an application to manipulate the next upper-layer protocol header. To manipulate the IPv4 header, the IP_HDRINCL socket option must be set on the socket. To manipulate the IPv6 header, the IPV6_HDRINCL socket option must be set on the socket.
SOCK_RDM 4	Provides a reliable message datagram. An example of this type is the Pragmatic General Multicast (PGM) multicast protocol implementation in Windows, often referred to as reliable multicast programming.
SOCK_SEQPACKET 5	Provides a pseudo-stream packet based on datagrams.

 

In Windows Sockets 2, new socket types were introduced. An application can dynamically discover the attributes of each available transport protocol through the WSAEnumProtocols function. So an application can determine the possible socket type and protocol options for an address family and use this information when specifying this parameter. Socket type definitions in the Winsock2.h and Ws2def.h header files will be periodically updated as new socket types, address families, and protocols are defined.

In Windows Sockets 1.1, the only possible socket types are SOCK_DGRAM and SOCK_STREAM.

protocol [in]

The protocol to be used. The possible options for the protocol parameter are specific to the address family and socket type specified. Possible values for the protocol are defined are defined in the Winsock2.h and Wsrm.h header files.

On the Windows SDK released for Windows Vista and later,, the organization of header files has changed and this parameter can be one of the values from the IPPROTO enumeration type defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly.

If a value of 0 is specified, the caller does not wish to specify a protocol and the service provider will choose the protocol to use.

When the af parameter is AF_INET or AF_INET6 and thetype is SOCK_RAW, the value specified for the protocol is set in the protocol field of the IPv6 or IPv4 packet header.

The table below lists common values for the protocol although many other values are possible.

protocol	Meaning
IPPROTO_TCP 6	The Transmission Control Protocol (TCP). This is a possible value when the af parameter is AF_INET or AF_INET6 and the type parameter is SOCK_STREAM.
IPPROTO_UDP 17	The User Datagram Protocol (UDP). This is a possible value when the af parameter is AF_INET or AF_INET6 and the type parameter is SOCK_DGRAM.
IPPROTO_RM 113	The PGM protocol for reliable multicast. This is a possible value when the af parameter is AF_INET and the type parameter is SOCK_RDM. On the Windows SDK released for Windows Vista and later, this value is also called IPPROTO_PGM.

 

lpProtocolInfo [in]

A pointer to a WSAPROTOCOL_INFO structure that defines the characteristics of the socket to be created. If this parameter is not NULL, the socket will be bound to the provider associated with the indicated WSAPROTOCOL_INFO structure.

g [in]

Reserved.

dwFlags [in]

A flag that specifies the socket attribute.

Return Value

If no error occurs, WSASocket returns a descriptor referencing the new socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Note  This error code description is Microsoft-specific.

Remarks

The WSASocket function causes a socket descriptor and any related resources to be allocated and associated with a transport-service provider. By default, the socket will not have an overlapped attribute.

If lpProtocolInfo is NULL, the WS2_32.DLL uses the first three parameters (af, type, protocol) to determine which service provider is used by selecting the first transport provider able to support the stipulated address family, socket type, and protocol values.

If the lpProtocolInfo is not NULL, the socket will be bound to the provider associated with the indicated WSAPROTOCOL_INFO structure. In this instance, the application can supply the manifest constant FROM_PROTOCOL_INFO as the value for any of af, type, or protocol parameters. This indicates that the corresponding values from the indicated WSAPROTOCOL_INFO structure (iAddressFamily, iSocketType, iProtocol) are to be assumed. In any case, the values specified for af, type, and protocol are passed unmodified to the transport-service provider.

When selecting a protocol and its supporting service provider based on af, type, and protocol, this procedure will only choose a base protocol or a protocol chain, not a protocol layer by itself. Unchained protocol layers are not considered to have partial matches on type or af, either. That is, they do not lead to an error code of WSAEAFNOSUPPORT or WSAEPROTONOSUPPORT, if no suitable protocol is found.

Note  The manifest constant AF_UNSPEC continues to be defined in the header file but its use is strongly discouraged, as this can cause ambiguity in interpreting the value of the protocol parameter.

The dwFlags parameter can be used to specify the attributes of the socket by using the bitwise OR operator with any of the following flags.

Important  For multipoint sockets, exactly one of WSA_FLAG_MULTIPOINT_C_ROOT or WSA_FLAG_MULTIPOINT_C_LEAF must be specified, and exactly one of WSA_FLAG_MULTIPOINT_D_ROOT or WSA_FLAG_MULTIPOINT_D_LEAF must be specified. Refer to Multipoint and Multicast Semantics for additional information.

Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections, and must be in a connected state before any data can be sent or received on them. A connection to another socket is created with a connect/WSAConnect call. Once connected, data can be transferred using send/WSASend and recv/WSARecv calls. When a session has been completed, a closesocket must be performed.

The communications protocols used to implement a reliable, connection-oriented socket ensure that data is not lost or duplicated. If data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, the connection is considered broken and subsequent calls will fail with the error code set to WSAETIMEDOUT.

Connectionless, message-oriented sockets allow sending and receiving of datagrams to and from arbitrary peers using sendto/WSASendTo and recvfrom/WSARecvFrom. If such a socket is connected to a specific peer, datagrams can be sent to that peer using send/WSASend and can be received from (only) this peer using recv/WSARecv.

Support for sockets with type SOCK_RAW is not required, but service providers are encouraged to support raw sockets whenever possible.

Example Code

The following example demonstrates the use of the WSASocket function.

#include <windows.h>
#include <winsock2.h>
#include <stdio.h>

int main() {
  WSADATA wsaData;
  SOCKET RecvSocket;

  int iResult;

  //-----------------------------------------------
  // Initialize Winsock
  iResult = WSAStartup(MAKEWORD(2,2), &wsaData);
  if (iResult != 0) {
      printf("WSAStartup failed: %d\n", iResult);
      return 1;
  }


  //-----------------------------------------------
  // Create a socket 
  RecvSocket = WSASocket(AF_INET, 
    SOCK_DGRAM, 
    IPPROTO_UDP, 
    NULL, 
    0, 
    WSA_FLAG_OVERLAPPED);

  if (RecvSocket == INVALID_SOCKET) {
      printf("WSASocket call failed with error: %ld\n", WSAGetLastError());
      WSACleanup();
      return 1;
  }

}

Shared Sockets

When a special WSAPROTOCOL_INFO structure (obtained through the WSADuplicateSocket function and used to create additional descriptors for a shared socket) is passed as an input parameter to WSASocket, the g and dwFlags parameters are ignored. Such a WSAPROTOCOL_INFO structure may only be used once, otherwise the error code WSAEINVAL will result.

Requirements

See Also

Winsock Reference

Winsock Functions

accept

bind

connect

getsockname

getsockopt

ioctlsocket

listen

recv

recvfrom

select

send

sendto

setsockopt

shutdown

Send comments about this topic to Microsoft

Build date: 11/12/2009