WSPSocket function
WSPSocket function creates a socket.
Syntax
SOCKET WSPSocket(
_In_ int af,
_In_ int type,
_In_ int protocol,
_In_ LPWSAPROTOCOL_INFOW lpProtocolInfo,
_In_ GROUP g,
_In_ DWORD dwFlags,
_Out_ LPINT lpErrno
);
Parameters
af [in]
Address family specification for the new socket. The Windows Sockets switch sets af to one of the WSK address families.type [in]
Type specification for the new socket. The Windows Sockets switch sets type to SOCK_STREAM.protocol [in]
Protocol to be used with the new socket that is specific to the address family in af. The Windows Sockets switch sets protocol to IPPROTO_TCP.lpProtocolInfo [in]
Pointer to a WSAPROTOCOL_INFOW structure that specifies the characteristics of the socket to be created.g [in]
Reserved.dwFlags [in]
Set of flags that specify supplementary information about the socket.lpErrno [out]
Pointer to a variable that receives the error code.
Return value
Returns a value of type SOCKET that is a descriptor for the new socket, if successful; otherwise, returns INVALID_SOCKET and, at lpErrno, one of the following error codes:
| Return code | Description |
|---|---|
| WSAENETDOWN | Network subsystem failed. |
| WSAEAFNOSUPPORT | The specified address family is not supported. |
| WSAEMFILE | No more socket descriptors available. |
| WSAENOBUFS | No buffer space is available; socket cannot be created. |
| WSAEPROTONOSUPPORT | Specified protocol is not supported. |
| WSAEPROTOTYPE | Specified protocol is the wrong type for this socket. |
| WSAESOCKTNOSUPPORT | Specified socket type is not supported in the address family in af. |
| WSAEINVAL | The g parameter is not valid. |
Remarks
The Windows Sockets switch calls a SAN service provider's WSPSocket function to allocate a socket descriptor and any related resources for that socket descriptor. In this call, the switch always passes the WSA_FLAG_OVERLAPPED flag to specify that the created socket can use asynchronous (overlapped) data transfer.
In the WSPSocket call, the switch also specifies values for address family, socket type, and protocol type that an application supplies in corresponding Socket or WSASocket function calls. In the current version of Windows Sockets Direct, the switch only creates sockets with the following values for address family, socket type, and protocol type:
one of the WSK address families for the standard Internet address family.
SOCK_STREAM for a socket type specification that provides sequenced, reliable, two-way, connection-based byte streams and uses TCP for the Internet address family.
IPPROTO_TCP for the TCP/IP protocol.
In the WSPSocket call, the switch also passes a pointer to a WSAPROTOCOL_INFOW structure that specifies TCP/IP protocol information and characteristics of the socket.
A SAN service provider creates socket descriptors that are not installable file system (IFS) objects; that is, it is a provider of non-IFS socket descriptors. On the other hand, the TCP/IP provider is a provider of IFS socket descriptors. Applications that are Windows Sockets SPI clients can call only standard Win32 I/O functions, such as ReadFile and WriteFile, using IFS socket descriptors. For more information about ReadFile and WriteFile, see the Microsoft Windows SDK documentation.
A SAN service provider must call the WPUCreateSocketHandle function to acquire a unique socket descriptor from the switch prior to returning from WSPSocket. The SAN service provider must store the switch's descriptor in the SAN service provider's internal data structure for the new socket. The SAN service provider returns its own descriptor for the socket to complete the WSPSocket call. The switch must supply the SAN service provider's internal descriptor for the new socket when calling the SAN service provider's functions, while the SAN service provider must supply the switch's socket descriptor in upcalls to the switch. For more information about WPUCreateSocketHandle, see the Windows SDK documentation.
The switch specifies only the WSA_FLAG_OVERLAPPED flag in the dwFlags parameter in a WSPSocket call. This flag causes a SAN service provider to create an overlapped socket. The switch can call the SAN service provider's WSPRecv, WSPRdmaRead, WSPSend, WSPRdmaWrite, and WSPIoctl functions using an overlapped socket to start multiple overlapped operations on that socket that run simultaneously. All these functions that allow overlapped operation also support nonoverlapped usage on an overlapped socket if the values for parameters related to overlapped operation are set to NULL. Functions that perform operations in a nonoverlapped manner block further processing. That is, those functions do not return until their associated operations complete.
SAN sockets, which are SOCK_STREAM socket types, provide full-duplex connections (that is, two-way communication that takes place in both directions simultaneously can occur on SAN sockets). Before receiving or sending any data on a SAN socket, the switch can call the SAN service provider's WSPConnect function to connect such a SAN socket to a peer. After connection is established, the switch can call the SAN service provider's WSPSend, WSPRdmaWrite, WSPRecv and WSPRdmaRead functions to transfer data. After a data transfer session completes, the switch must call the SAN service provider's WSPCloseSocket function to close the socket.
SAN transports that are used to transfer data reliably ensure that data is not lost or duplicated. If data (for which the remote peer has buffer space) cannot be successfully transmitted within a reasonable length of time, the connection is considered broken and subsequent calls fail with the error code set to WSAETIMEDOUT.
The switch, running in a controlling process, calls the SAN service provider's WSPDuplicateSocket function to obtain a special WSAPROTOCOL_INFOW structure. The switch, running in another process, in turn, calls the SAN service provider's WSPSocket function and passes this WSAPROTOCOL_INFOW structure to create a socket descriptor for a shared underlying socket. Applications running in two or more processes can use this shared socket, but not simultaneously. In this WSPSocket call, the SAN service provider ignores socket group and flags parameters. In addition, the dwProviderReserved member of the WSAPROTOCOL_INFOW structure that specifies protocol information should be set to the same value that WSPDuplicateSocket returned. For more information, see Duplicating Socket Handles for a SAN.
Requirements
Target platform |
Desktop |
Version |
Requires Windows Sockets version 2.0. |
Header |
Ws2spi.h (include Ws2spi.h) |
See also