WSPBind (Windows Embedded CE 6.0)

1/6/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 sockaddr structure is defined.

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

  Except for the sa_family member, sockaddr contents are expressed in network byte order. In Winsock, the name parameter is not strictly interpreted as a pointer to a sockaddr structure. 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_short is 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.

Remarks

This function is used on an unconnected connectionless or connection-oriented socket, before subsequent calls to WSPConnect or 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. WSPBind establishes 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 name parameter is not strictly interpreted as a pointer to a sockaddr structure. 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_family in the sockaddr declaration) 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_ANY for the sa_data member of the name parameter. 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 WSPGetSockName after WSPBind to learn the address and the port that has been assigned to it. However, note that if the Internet address is equal to INADDR_ANY, WSPGetSockOpt will not necessarily be able to supply the address until the socket is connected, because several addresses can be valid if the host is multihomed.

Requirements

See Also

Reference

Winsock SPI Functions
sockaddr
WSPConnect
WSPListen
WSPGetSockName
WSPSetSockOpt
WSPSocket