WSPBind function
WSPBind associates the local IP address, or name, of a network interface with a socket. This network interface is serviced by the SAN service provider.
Syntax
int WSPBind(
_In_ SOCKET s,
_In_ const struct sockaddr FAR *name,
_In_ int namelen,
_In_ LPINT lpErrno
);
Parameters
s [in]
Descriptor that identifies an unbound socket.name [in]
Pointer to a sockaddr structure that contains the address to assign to the socket. The SAN service provider does not strictly interpret the name parameter as a pointer to a sockaddr structure. The name parameter is cast this way for Windows Sockets compatibility. The SAN service provider interprets the actual structure as a sockaddr_in structure, which is used with the TCP/IP protocol. For more information about sockaddr and sockaddr_in, see the Microsoft Windows SDK documentation.namelen [in]
Size, in bytes, of the buffer at name.lpErrno [in]
Pointer to a variable that receives the error code.
Return value
Returns zero if successful; otherwise, returns SOCKET_ERROR and, at lpErrno, one of the following error codes:
| Return code | Description |
|---|---|
| WSAENETDOWN | Network subsystem failed. |
| WSAEADDRNOTAVAIL | Specified address is not a valid address for the computer. |
| WSAEFAULT | The name or namelen parameter is not a valid part of the user address space, the namelen parameter is too small, the name parameter contains an incorrect address format for the associated address family, or the first two bytes of the memory block specified by name do not match the address family associated with the socket descriptor S. |
| WSAEINVAL | Socket is already bound to an address. |
| WSAENOBUFS | Not enough buffers available, too many connections. |
| WSAENOTSOCK | Descriptor is not a socket. |
Note that a SAN service provider does not support the following error codes for WSPBind:
| Return code | Description |
|---|---|
| WSAEINPROGRESS | The Windows Sockets switch never issues cancel blocking calls to a SAN service provider. |
| WSAEADDRINUSE | The Windows Sockets switch, in conjunction with the TCP/IP provider, handles address reuse. |
Remarks
The Windows Sockets switch calls a SAN service provider's WSPBind function to assign a name to an unnamed socket, thereby establishing a local association for the socket. The switch previously called the WSPSocket function to create the unnamed socket. The switch calls the WSPBind function before calling the WSPConnect or WSPListen functions.
The SAN service provider must interpret the information to which name points as a sockaddr_in structure, which is used with the TCP/IP protocol. The sin_family member of sockaddr_in must contain one of the WSK address families that was used to create the socket. Otherwise, the SAN service provider returns the WSAEFAULT error code.
In most cases, the switch passes a name that is associated with one of the network interface cards (NICs) serviced by the SAN service provider. This name is fully qualified; that is, the sin_port and sin_addr members of its sockaddr_in structure are both set to nonzero values. The switch obtains the IP address of one of the SAN service provider's NICs from the TCP/IP provider.
If the switch requires a socket to listen for connection requests on all NICs serviced by the SAN service provider, the switch passes the wildcard IP address. The wildcard IP address has the sin_addr member of its sockaddr_in structure set to zero. If the wildcard IP address is specified using the Internet standard ".'' (dotted) notation, it is 0.0.0.0.
Note Beginning with Windows Vista, the wildcard IP address 0.0.0.0 is not available.
Also beginning with Windows Vista, if the IPAutoconfigurationEnabled registry key is set to a value of 0, automatic IP address assignment is disabled, and no IP address is assigned. In this case, the ipconfig command line tool will not display an IP address. If the key is set to a nonzero value, an IP address is automatically assigned. This key can be located at the following paths in the registry:
HKEY_LOCAL_MACHINE\SYSTEM\Current Control Set\Services\Tcpip\Parameters\IPAutoconfigurationEnabled
HKEY_LOCAL_MACHINE\SYSTEM\Current Control Set\Services\Tcpip\Parameters\Interfaces\GUID\IPAutoconfigurationEnabled
The switch can call WSPBind to bind more than one socket to the same local name; that is, to the same port. The switch can use sockets that are bound to the same port to initiate multiple connections from that port. Each of these connections are independent from the other. Note that if more than one socket is listening on the same port, only one should receive connection requests.
Requirements
Target platform |
Desktop |
Version |
Requires Windows Sockets version 2.0. |
Header |
Ws2spi.h (include Ws2spi.h) |
See also