Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function associates a local address (that is, name) with a socket.

Syntax 

int WSPBind(
  SOCKET 
s,
  const struct sockaddr FAR* 
name,
  int 
namelen,
  LPINT 
lpErrno 
);

Parameters

s

[in] Descriptor identifying an unbound socket.

name

[in] Address to assign to the socket. The following code sample shows how the sockaddrstructure is defined.

Copy Code 
sockaddr {
	_short	 sa_family;
	char	 sa_data[14];
};

Except for the sa_familymember, sockaddrcontents are expressed in network byte order. In Winsock, the nameparameter is not strictly interpreted as a pointer to a sockaddrstructure. It is cast this way for Windows Sockets compatibility. The actual structure is interpreted differently in the context of different address families. The only requirements are that the first u_shortis the address family and the total size of the memory buffer in bytes is namelen.

namelen

[in] Length of the name.

lpErrno

[out] Pointer to the error code.

Return Value

If no error occurs, this function returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code is available in lpErrno.

The following table shows the possible error codes.

Error value Description

WSAENETDOWN

Network subsystem has failed.

WSAEADDRINUSE

Some process on the machine has already bound to the same fully qualified address (for example, IP address and port in the af_inetcase) and the socket has not been marked to allow address reuse with SO_REUSEADDR. (See the SO_REUSEADDR socket option under WSPSetSockOpt.)

WSAEADDRNOTAVAIL

Specified address is not a valid address for this machine.

WSAEFAULT

Nameor the namelenparameter is not a valid part of the user address space, the namelenparameter is too small, the nameparameter contains incorrect address format for the associated address family, or the first two bytes of the memory block specified by namedo not match the address family associated with the socket descriptor s.

WSAEINPROGRESS

Function is invoked when a callback is in progress.

WSAEINVAL

Socket is already bound to an address.

WSAENOBUFS

Not enough buffers available, too many connections.

WSAENOTSOCK

Descriptor is not a socket.

Remarks

This function is used on an unconnected connectionless or connection-oriented socket, before subsequent calls to WSPConnector WSPListen. When a socket is created with WSPSocket, it exists in a name space (address family), but it has no name or local address assigned. WSPBindestablishes the local association of the socket by assigning a local name to an unnamed socket.

As an example, in the Internet address family, a name consists of three parts: the address family, a host address, and a port number that identifies the Windows Sockets SPI client. In Winsock, the nameparameter is not strictly interpreted as a pointer to a sockaddrstructure. Service providers are free to regard it as a pointer to a block of memory of size namelen. The first two bytes in this block (corresponding to sa_familyin the sockaddrdeclaration) must contain the address family that was used to create the socket. Otherwise, the error WSAEFAULT will be indicated.

If a Winsock SPI client does not care what local address is assigned to it, it will specify the manifest constant value ADDR_ANYfor the sa_datamember of the nameparameter. This instructs the service provider to use any appropriate network address. For TCP/IP, if the port is specified as zero, the service provider will assign a unique port to the Windows Sockets SPI client with a value between 49152 and 65535. The SPI client can use WSPGetSockNameafter WSPBindto learn the address and the port that has been assigned to it. However, note that if the Internet address is equal to INADDR_ANY, WSPGetSockOptwill notnecessarily be able to supply the address until the socket is connected, because several addresses can be valid if the host is multihomed.

Requirements

Header ws2spi.h
Library Ws2.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also