Windows* Sockets 2 Application Programming Interface An Interface for Transparent Network Programming Under Microsoft Windowstm revision 2 August 7, 1997
Download 1.64 Mb.
|
- Navigate this page:
- 70 accept()
- 71 bind()
69 SOCKET LIBRARY REFERENCEThis chapter presents the data transport routines in alphabetical order, and describes each routine in detail. Note: the getXbyY() and WSAAsyncGetXbyY() functions now appear in section 5 on name resolution. In each routine it is indicated that the header file winsock2.h must be included. Appendix A.2 lists the Berkeley-compatible header files which are supported. These are provided for compatibility purposes only, and each of them will simply include winsock2.h. The Windows header file windows.h is also needed, but winsock2.h will include it if necessary. 70 accept()Description Accept a connection on a socket. #include SOCKET WSAAPI accept ( IN SOCKET s, OUT struct sockaddr FAR* addr, OUT int FAR* addrlen ); s A descriptor identifying a socket which is listening for connections after a listen(). addr An optional pointer to a buffer which receives the address of the connecting entity, as known to the communications layer. The exact format of the addr argument is determined by the address family established when the socket was created. addrlen An optional pointer to an integer which contains the length of the address addr. Remarks This routine extracts the first connection on the queue of pending connections on s, creates a new socket and returns a handle to the new socket. The newly created socket has the same properties as s including asynchronous events registered with WSAAsyncSelect() or with WSAEventSelect(), but not including the listening socket’s group ID, if any. If no pending connections are present on the queue, and the socket is not marked as non-blocking, accept() blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, accept() returns a failure with the error WSAEWOULDBLOCK, as described below. After accept succeeds, and returns a new socket handle, the accepted socket may not be used to accept more connections. The original socket remains open, and listening for new connection requests. The argument addr is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the addr parameter is determined by the address family in which the communication is occurring. The addrlen is a value-result parameter; it should initially contain the amount of space pointed to by addr; on return it will contain the actual length (in bytes) of the address returned. This call is used with connection-oriented socket types such as SOCK_STREAM. If addr and/or addrlen are equal to NULL, then no information about the remote address of the accepted socket is returned. Return Value If no error occurs, accept() returns a value of type SOCKET which is a descriptor for the accepted socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code may be retrieved by calling WSAGetLastError(). The integer referred to by addrlen initially contains the amount of space pointed to by addr. On return it will contain the actual length in bytes of the address returned. Error Codes WSANOTINITIALISED A successful WSAStartup() must occur before using this API. WSAENETDOWN The network subsystem has failed. WSAEFAULT The addrlen argument is too small or addr is not a valid part of the user address space. WSAEINTR A blocking WinSock 1.1 call was canceled via WSACancelBlockingCall(). WSAEINPROGRESS A blocking WinSock 1.1 call is in progress, or the service provider is still processing a callback function. WSAEINVAL listen() was not invoked prior to accept(). WSAEMFILE The queue is non-empty upon entry to accept() and there are no descriptors available. WSAENOBUFS No buffer space is available. WSAENOTSOCK The descriptor is not a socket. WSAEOPNOTSUPP The referenced socket is not a type that supports connection-oriented service. WSAEWOULDBLOCK The socket is marked as non-blocking and no connections are present to be accepted. See Also bind(), connect(), listen(), select(), socket(), WSAAsyncSelect(), WSAAccept() 71 bind()Description Associate a local address with a socket. #include int WSAAPI bind ( IN SOCKET s, IN const struct sockaddr FAR* name, IN int namelen ); s A descriptor identifying an unbound socket. name The address to assign to the socket. The sockaddr structure is defined as follows: struct sockaddr { u_short sa_family; char sa_data[14]; };
namelen The length of the name. Remarks This routine is used on an unconnected connectionless or connection-oriented socket, before subsequent connect()s or listen()s. When a socket is created with socket(), it exists in a name space (address family), but it has no name assigned. bind() 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 which identifies the application. In WinSock 2, the name parameter is not strictly interpreted as a pointer to a "sockaddr" struct. It is cast this way for Windows Sockets compatibility. 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 an error WSAEFAULT will occur. If an application does not care what local address is assigned to it, it may specify the manifest constant value ADDR_ANY for the sa_data field of the name parameter. This allows the underlying service provider to use any appropriate network address, potentially simplifying application programming in the presence of multi-homed hosts (i.e., hosts that have more than one network interface and address). For TCP/IP, if the port is specified as 0, the service provider will assign a unique port to the application with a value between 1024 and 5000. The application may use getsockname() after bind() to learn the address and the port that has been assigned to it, but note that if the Internet address is equal to INADDR_ANY, getsockname() will not necessarily be able to supply the address until the socket is connected, since several addresses may be valid if the host is multi-homed. Binding to a specific port number (i.e., other than port 0) is discouraged for client applications, since there is a danger of conflicting with another socket that is already using that port number. Return Value If no error occurs, bind() returns 0. Otherwise, it returns SOCKET_ERROR, and a specific error code may be retrieved by calling WSAGetLastError(). Error Codes WSANOTINITIALISED A successful WSAStartup() must occur before using this API. WSAENETDOWN The network subsystem has failed. WSAEADDRINUSE Some process on the machine has already bound to the same fully-qualified address (e.g., IP address and port in the af_inet case) and the socket has not been marked to allow address re-use with SO_REUSEADDR. (See the SO_REUSEADDR socket option under setsockopt().) WSAEADDRNOTAVAIL The specified address is not a valid address for this machine. WSAEFAULT The name or the namelen argument is not a valid part of the user address space, the namelen argument is too small, the name argument contains incorrect address format for the associated address family, or the first two bytes of the memory block specified by name does not match the address family associated with the socket descriptor s. WSAEINPROGRESS A blocking WinSock 1.1 call is in progress, or the service provider is still processing a callback function. WSAEINVAL The socket is already bound to an address. WSAENOBUFS Not enough buffers available, too many connections. WSAENOTSOCK The descriptor is not a socket. See Also connect(), listen(), getsockname(), setsockopt(), socket(), WSACancelBlockingCall(). Download 1.64 Mb. Share with your friends:
|