WSASocketA

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

Syntax

SOCKET WSASocketA(
         int af,
         int type,
         int protocol,
         LPWSAPROTOCOL_INFOA lpProtocolInfo,
         GROUP g,
         DWORD dwFlags
)  

Parameters

af
Type: int 

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

On the Microsoft Windows Software Development Kit (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.

type
Type: int 

[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:

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
Type: int 

[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 Microsoft Windows Software Development Kit (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 the type 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.

lpProtocolInfo
Type: LPWSAPROTOCOL_INFOA 

[in, optional] 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
Type: GROUP 

[in]

An existing socket group ID or an appropriate action to take when creating a new socket and a new socket group.

If g is an existing socket group ID, join the new socket to this socket group, provided all the requirements set by this group are met.

If g is not an existing socket group ID, then the following values are possible.

Note

  The SG_UNCONSTRAINED_GROUP and SG_CONSTRAINED_GROUP constants are not currently defined in a public header file.

dwFlags
Type: DWORD 

[in]

A set of flags used to specify additional socket attributes.

A combination of these flags may be set, although some combinations are not allowed.

Important

  For multipoint sockets, only one of WSA_FLAG_MULTIPOINT_C_ROOT or WSA_FLAG_MULTIPOINT_C_LEAF flags can be specified, and only one of WSA_FLAG_MULTIPOINT_D_ROOT or WSA_FLAG_MULTIPOINT_D_LEAF flags can be specified. Refer to Multipoint and Multicast Semantics for additional information.

Return value

Type: SOCKET 

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.

Return codes

Remarks

The WSASocket function causes a socket descriptor and any related resources to be allocated and associated with a transport-service provider. Most sockets should be created with the WSA_FLAG_OVERLAPPED attribute set in the dwFlags parameter. A socket created with this attribute supports the use of overlapped I/O operations which provide higher performance. By default, a socket created with the WSASocket function will not have this overlapped attribute set. In contrast, the socket function creates a socket that supports overlapped I/O operations as the default behavior.

If the lpProtocolInfo parameter is NULL, Winsock will utilize the first available transport-service provider that supports the requested combination of address family, socket type and protocol specified in the af, type, and protocol parameters.

If the lpProtocolInfo parameter 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.

Applications are encouraged to use AF_INET6 for the af parameter and create a dual-mode socket that can be used with both IPv4 and IPv6.

If a socket is created using the WSASocket function, then the dwFlags parameter must have the WSA_FLAG_OVERLAPPED attribute set for the SO_RCVTIMEO or SO_SNDTIMEO socket options to function properly. Otherwise the timeout never takes effect on the socket.

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 a specified socket is established with a connect or WSAConnect function call. Once connected, data can be transferred using send/WSASend and recv/WSARecv calls. When a session has been completed, the closesocket function should be called to release the resources associated with the socket. For connection-oriented sockets, the shutdown function should be called to stop data transfer on the socket before calling the closesocket function.

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.

The WSASocket function can be used to create a socket to be used by a service so that if another socket tries to bind to the same port used by the service, and audit record is generared. To enable this option, an application would need to do the following:

• Call the AdjustTokenPrivileges function to enable the SE_SECURITY_NAME privilege in the access token for the process. This privilege is required to set the ACCESS_SYSTEM_SECURITY access rights on the security descriptor for an object.
• Call the WSASocket function to create a socket with dwFlag with the WSA_FLAG_ACCESS_SYSTEM_SECURITY option set. The WSASocket function will fail if the AdjustTokenPrivileges function is not called first to enable the SE_SECURITY_NAME privilege needed for this operation.
• Call the SetSecurityInfo function to set a security descriptor with a System Access Control List (SACL) on the socket. The socket handle returned by the WSASocket function is passed in the handle parameter. If the function succeeds, this will set the ACCESS_SYSTEM_SECURITY access right on the security descriptor for the socket.
• Call the bind function to bind the socket to a specific port. If the bind function succeeds, then an audit entry is generated if another socket tries to bind to the same port.
• Call the AdjustTokenPrivileges function to remove the SE_SECURITY_NAME privilege in the access token for the process, since this is no longer needed.

For more information on ACCESS_SYSTEM_SECURITY, see SACL Access Right and Audit Generation in the Authorization documentation.

Socket Groups

WinSock 2 introduced the notion of a socket group as a means for an application, or cooperating set of applications, to indicate to an underlying service provider that a particular set of sockets are related and that the group thus formed has certain attributes. Group attributes include relative priorities of the individual sockets within the group and a group quality of service specification. Applications that need to exchange multimedia streams over the network are an example where being able to establish a specific relationship among a set of sockets could be beneficial. It is up to the transport on how to treat socket groups.

The WSASocket and WSAAccept functions can be used to explicitly create and join a socket group when creating a new socket. The socket group ID for a socket can be retrieved by using the getsockopt function with level parameter set to SOL_SOCKET and the optname parameter set to SO_GROUP_ID. A socket group and its associated socket group ID remain valid until the last socket belonging to this socket group is closed. Socket group IDs are unique across all processes for a given service provider. A socket group of zero indicates that the socket is not member of a socket group.

The relative group priority of a socket group can be accessed by using the getsockopt function with the level parameter set to SOL_SOCKET and the optname parameter set to SO_GROUP_PRIORITY. The relative group priority of a socket group can be set by using setsockopt with the level parameter set to SOL_SOCKET and the optname parameter set to SO_GROUP_PRIORITY.

The Winsock provider included with Windows allows the creation of socket groups and it enforces the SG_CONSTRAINED_GROUP. All sockets in a constrained socket group must be created with the same value for the type and protocol parameters. A constrained socket group may consist only of connection-oriented sockets, and requires that connections on all grouped sockets be to the same address on the same host. This is the only restriction applied to a socket group by the Winsock provider included with Windows. The socket group priority is not currently used by the Winsock provider or the TCP/IP stack included with Windows.

Example Code

Example

The following example demonstrates the use of the WSASocket function.

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.

Windows Phone 8: This API is supported.

Requirements

Header: Declared in winsock2.h.

Library: Use ws2_32.lib.