Developer

API Reference

ISockPort_Bind()

Brew Release
Brew MP 1.0.2
See Also
None.
Description
This function associates a local address and port with the socket. The bind function is used on an unconnected socket.
When a socket is created, it exists in a name space (address family), but it has no name assigned to it. There are three distinct name spaces available: AEE_AF_LOCAL, AEE_AF_INET and AEE_AF_INET6.
- AEE_AF_LOCAL

~ Binding of local domain sockets will never result in a return value of IPORT_WAIT, as there is no network connection to be established.
Currently AEE_AF_LOCAL is not supported.
- AEE_AF_INET/AEE_AF_INET6

~ Passing the IPv4 or IPv6 ANY (zero) address explicitly requests that the socket be assigned to any local address. Passing the IPv4 or IPv6 BREW LOOPBACK address will allow local connections that do not leave the host. Passing a multicast group address can be used for receiving multicast traffic destined to that group, if the selected network is a multicast network, such as MediaFLO or CDMA BCMCS. On other networks, multicast is not supported yet.
Note that the ability to bind to a specific local IP address is not presently supported, and the above mentioned options are the only valid values for the address. In the case of ANY, the local IP address is assigned automatically by the sockets library.
The IPv4 ANY address is defined by AEE_INADDR_ANY. The IPv6 ANY address can be generated with AEE_IN6ADDR_SET_ANY()
Passing zero for the port explicitly requests that the socket be assigned any available port.
Also note the possibility of an IPORT_WAIT result. This will normally occur only in cases where a network connection (e.g. a PPP link) must be established. In that event, Bind() will return IPORT_WAIT, and can be called again to obtain the final result (error or success). For notification of when to call Bind() again, the ISockPort_Writeable() call can be used. (Note that just as with Write(), a Writeable() callback does not guarantee that a subsequent call to Bind() call will complete, so the caller must be prepared to receive IPORT_WAIT again.)
The user is not required to call Bind() until a non-WOULDBLOCK result is returned. The user can proceed to attempt to send and/or receive data, in which case the bind operation (and any network startup) will proceed in the background, and any failure in startup phases will be reflected in a subsequent error result.
Parameters
  • po
    []:
    pointer to the ISockPort interface
  • pAddr
    []:
    an opaque pointer to the address to bind to (see AEESockAddrStorage)
Interface
Prototype
   int ISockPort_Bind(ISockPort* po, const void* pAddr)
Return
AEE_SUCCESS : socket has been successfully bound to the local address
IPORT_WAIT : (AEE_AF_INET and AEE_AF_INET6 only) The operation cannot be completed at present. This can occur when a network connection is being established (see ISockPort_Writeable()).
AEE_NET_EBADF : socket is not open AEE_NET_EAFNOSUPPORT: not an inet address AEE_NET_EMFILE : Not enough resources to complete this operation (too many sockets in use) AEE_NET_ENETDOWN : network is unavailable (handset has lost network coverage) AEE_NET_EOPNOTSUPP : specific local IP address was requested (not supported) AEE_NET_EADDRINUSE : the local address is already in use AEE_NET_EINVAL : socket is already bound to a local address AEE_NET_EFAULT : invalid address parameter has been specified
Other error codes are also possible.
Side Effect
None.
Comment
Note that the IPORT_WAIT return value is used instead of an error return value and an AEE_NET_EWOULDBLOCK error code.
Binding to a specific local IP address is not currently supported.
  • Follow