WSASocket  8Z9QXO 

The Windows Sockets WSASocket function creates a socket which is bound to a specific transport service provider, and optionally creates and/or joins a socket group.

SOCKET WSASocket (

Parameters

af

[in] An address family specification.

type

[in] A type specification for the new socket.

protocol

[in] A particular protocol to be used with the socket which is specific to the indicated address family.

lpProtocolInfo

[in] A pointer to a WSAPROTOCOL_INFO structure that defines the characteristics of the socket to be created.

g

[in] The identifier of the socket group.

dwFlags

[in] The socket attribute specification.

Remarks

This 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 Windows Sockets 2 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 may supply the manifest constant FROM_PROTOCOL_INFO as the value for any of af, type or protocol. This indicates that the corresponding values from the indicated WSAPROTOCOL_INFO structure (iAddressFamily, iSocketType, iProtocol) are to be assumed. In any case, the values supplied for af, type and protocol are supplied unmodified to the transport service provider through the corresponding parameters to the WSPSocket function in the SPI.

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

Parameter g is used to indicate the appropriate actions on socket groups:

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

  2.  if g = SG_UNCONSTRAINED_GROUP, create an unconstrained socket group and have the new socket be the first member; or

  3.  if g = SG_CONSTRAINED_GROUP, create a constrained socket group and have the new socket be the first member; or

  4.  if g = zero, no group operation is performed

For unconstrained groups, any set of sockets may be grouped together as long as they are supported by a single service provider. 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. For newly created socket groups, the new group ID can be retrieved by using getsockopt with option SO_GROUP_ID, if this operation completes successfully. A socket group and its associated 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.

The dwFlags parameter may be used to specify the attributes of the socket by or-ing 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 SemanticsWZD6W2 for additional information.

Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections, and must be in a connected state before any data may be sent or received on them. A connection to another socket is created with a connect/WSAConnect call. Once connected, data may 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 may be sent to that peer using send/WSASend and may be received from (only) this peer using recv/WSARecv.

Support for sockets with type RAW is not required, but service providers are encourages to support raw sockets whenever it makes sense to do so.

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.

Return Values

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 may be retrieved by calling WSAGetLastError.

Error Codes

See Also