The WSPSocket function creates a socket, optionally creates and/or joins a socket group.
SOCKET WSPSocket (
int af,
int type,
int protocol,
LPWSAPROTOCOL_INFOW lpProtocolInfo,
GROUP g,
DWORD dwFlags,
LPINT lpErrno
);
WSPSocket causes a socket descriptor and any related resources to be allocated. By default, the created socket will not have the overlapped attribute. Windows Sockets providers are encouraged to be realized as Windows installable file systems, and supply system file handles as socket descriptors. These providers must call WPUModifyIFSHandle prior to returning from this function. For non-file-system Windows Sockets providers, WPUCreateSocketHandle must be used to acquire a unique socket descriptor from the WS2_32.DLL prior to returning from this function. See section Descriptor Allocation for more information.
The values for af, type and protocol are those supplied by the application in the corresponding API functions socket or WSASocket. A service provider is free to ignore or pay attention to any or all of these values as is appropriate for the particular protocol. However, the provider must be willing to accept the value of zero for af and type, since the WS2_32.DLL considers these to be wild card values. Also the value of manifest constant FROM_PROTOCOL_INFO must be accepted for any of af, type and protocol. This value indicates that the Windows Sockets 2 application needs to use the corresponding values from the indicated WSAPROTOCOL_INFOW structure: (iAddressFamily, iSocketType, iProtocol).
Reserved for future use with socket groups: Parameter g is used to indicate the appropriate actions on socket groups:
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
if g = SG_UNCONSTRAINED_GROUP, create an unconstrained socket group and have the new socket be the first member; or
if g = SG_CONSTRAINED_GROUP, create a constrained socket group and have the new socket be the first member; or
if g = zero, no group operation is performed
Any set of sockets grouped together must be implemented by a single service provider. For unconstrained groups, any set of sockets can be grouped together. A constrained socket group can 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 must be available for the Windows Sockets SPI client to retrieve by calling WSPGetSockOpt with option SO_GROUP_ID. 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 can be used to specify the attributes of the socket by OR-ing any of the following Flags:
| Flag | Meaning |
|---|---|
| WSA_FLAG_OVERLAPPED | This flag causes an overlapped socket to be created. Overlapped sockets can utilize WSPSend, WSPSendTo, WSPRecv, WSPRecvFrom and WSPIoctl for overlapped I/O operations, which allows multiple operations to be initiated and in progress simultaneously. All functions that allow overlapped operation also support non-overlapped usage on an overlapped socket if the values for parameters related to overlapped operation are NULL. |
| WSA_FLAG_MULTIPOINT_C_ROOT | Indicates that the socket created will be a c_root in a multipoint session. Only allowed if a rooted control plane is indicated in the protocol's WSAPROTOCOL_INFOW structure. |
| WSA_FLAG_MULTIPOINT_C_LEAF | Indicates that the socket created will be a c_leaf in a multicast session. Only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the protocol's WSAPROTOCOL_INFOW structure. |
| WSA_FLAG_MULTIPOINT_D_ROOT | Indicates that the socket created will be a d_root in a multipoint session. Only allowed if a rooted data plane is indicated in the protocol's WSAPROTOCOL_INFOW structure. |
| WSA_FLAG_MULTIPOINT_D_LEAF | Indicates that the socket created will be a d_leaf in a multipoint session. Only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the protocol's WSAPROTOCOL_INFOW structure. |
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 SPI: Protocol-Independent Multicast and Multipoint 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 WSPConnect call. Once connected, data can be transferred using WSPSend and WSPRecv calls. When a session has been completed, a WSPCloseSocket 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 WSPSendTo and WSPRecvFrom. If such a socket is WSPConnected to a specific peer, datagrams can be sent to that peer using WSPSend and can be received from (only) this peer using WSPRecv.
Support for sockets with type SOCK RAW is not required but service providers are encouraged to support raw sockets whenever it makes sense to do so.
A layered service provider supplies an implementation of this function, but it is also a client of this function if and when it calls WSPSocket of the next layer in the protocol chain. Some special considerations apply to this function's lpProtocolInfo parameter as it is propagated down through the layers of the protocol chain.
If the next layer in the protocol chain is another layer then when the next layer's WSPSocket is called, this layer must pass to the next layer a lpProtocolInfo that references the same unmodified WSAPROTOCOL_INFOW structure with the same unmodified chain information. However, if the next layer is the base protocol (that is, the last element in the chain), this layer performs a substitution when calling the base provider's WSPSocket. In this case, the base provider's WSAPROTOCOL_INFOW structure should be referenced by the lpProtocolInfo parameter.
One vital benefit of this policy is that base service providers do not have to be aware of protocol chains.
This same propagation policy applies when propagating a WSAPROTOCOL_INFOW structure through a layered sequence of other functions such as WSPAddressToString, WSPDuplicateSocket, WSPStartup, or WSPStringToAddress.
If no error occurs, WSPSocket returns a descriptor referencing the new socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code is available in lpErrno.
| WSAENETDOWN | The network subsystem has failed. |
| WSAEAFNOSUPPORT | The specified address family is not supported. |
| WSAEINPROGRESS | A blocking Windows Sockets call is in progress, or the service provider is still processing a callback function. |
| WSAEMFILE | No more socket descriptors are available. |
| WSAENOBUFS | No buffer space is available. The socket cannot be created. |
| WSAEPROTONOSUPPORT | The specified protocol is not supported. |
| WSAEPROTOTYPE | The specified protocol is the wrong type for this socket. |
| WSAESOCKTNOSUPPORT | The specified socket type is not supported in this address family. |
| WSAEINVAL | The parameter g specified is not valid. |
Windows NT: Yes
Windows: Yes
Windows CE: Unsupported.
Header: Declared in ws2spi.h.
WSPAccept, WSPBind, WSPConnect, WSPGetSockName, WSPGetSockOpt, WSPSetSockOpt, WSPListen, WSPRecv, WSPRecvFrom, WSPSend, WSPSendTo, WSPShutdown, WSPIoctl, WPUCreateSocketHandle