The Windows Sockets WSAAccept function conditionally accepts a connection based on the return value of a condition function, optionally creates or joins a socket group, provides QOS flowspecs, and allows transfer of connection data.
SOCKET WSAAccept (
SOCKET s,
struct sockaddr FAR * addr,
LPINT addrlen,
LPCONDITIONPROC lpfnCondition,
DWORD dwCallbackData
);
The WSAAccept function extracts the first connection on the queue of pending connections on socket s, and checks it against the condition function, provided the condition function is specified (that is, not NULL). If the condition function returns CF_ACCEPT, WSAAccept creates a new socket and performs any socket grouping as indicated by the result parameter g in the condition function. The newly created socket has the same properties as socket s including asynchronous events registered with WSAAsyncSelect or with WSAEventSelect, but not including the listening socket's group ID, if any. If the condition function returns CF_REJECT, WSAAccept rejects the connection request. The condition function runs in the same thread as this function does, and should return as soon as possible. If the decision cannot be made immediately, the condition function should return CF_DEFER to indicate that no decision has been made, and no action about this connection request should be taken by the service provider. When the application is ready to take action on the connection request, it will invoke WSAAccept again and return either CF_ACCEPT or CF_REJECT as a return value from the condition function.
A socket in the default mode (blocking) will block until a connection is present when an application calls WSAAccept and no connections are pendng on the queue.
A socket in the nonblocking mode (blocking) fails with the error WSAEWOULDBLOCK when an application calls WSAAccept and no connections are pendng on the queue. After WSAAccept succeeds and returns a new socket handle, the accepted socket cannot be used to accept any more connections. The original socket remains open and listens for new connection requests.
The addr parameter 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. Otherwise, these two parameters will be filled in regardless of whether the condition function is specified or what it returns.
A prototype of the condition function is as follows:
int CALLBACK ConditionFunc(
IN LPWSABUF lpCallerId,
IN LPWSABUF lpCallerData,
IN OUT LPQOS lpSQOS,
IN OUT LPQOS lpGQOS,
IN LPWSABUF lpCalleeId,
OUT LPWSABUF lpCalleeData,
OUT GROUP FAR * g,
IN DWORD dwCallbackData
);
The ConditionFunc is a placeholder for the application-supplied callback function. The actual condition function must reside in a DLL or application module. It is exported in the module definition file. Use MakeProcInstance to get a procedure-instance address for the callback function.
The lpCallerId parameter is a value parameter that contains the address of the connecting entity. The lpCallerData is a value parameter that contains any user data. The information in these parameters is sent along with the connection request. If no caller identification or caller data is available, the corresponding parameters will be NULL. Many network protocols do not support connect-time caller data. Most conventional network protocols can be expected to support caller ID information at connection-request time. The buf portion of the WSABUF pointed to by lpCallerId points to a SOCKADDR. The SOCKADDR is interpreted according to its address family (typically by casting the SOCKADDR to some type specific to the address family).
The lpSQOS parameter references the FLOWSPEC structures for socket s specified by the caller, one for each direction, followed by any additional provider-specific parameters. The sending or receiving flow specification values will be ignored as appropriate for any unidirectional sockets. A NULL value for indicates that there is no caller supplied QOS and that no negotiation is possible. A non-NULL lpSQOS pointer indicates that a QOS negotiation is to occur or that the provider is prepared to accept the QOS request without negotiation.
The lpGQOS parameter (reserved for future use with socket groups) references the FLOWSPEC structures for the socket group the caller is to create, one for each direction, followed by any additional provider-specific parameters. A NULL value for lpGQOS indicates no caller-supplied group quality of service. quality of service information can be returned if negotiation is to occur.
The lpCalleeId is a value parameter that contains the local address of the connected entity. The buf portion of the WSABUF pointed to by lpCalleeId points to a SOCKADDR. The SOCKADDR is interpreted according to its address family (typically by casting the SOCKADDR to some type specific to the address family).
The lpCalleeData is a result parameter used by the condition function to supply user data back to the connecting entity. The lpCalleeData->len initially contains the length of the buffer allocated by the service provider and pointed to by lpCalleeData->buf. A value of zero means passing user data back to the caller is not supported. The condition function should copy up to lpCalleeData->len bytes of data into lpCalleeData->buf, and then update lpCalleeData->len to indicate the actual number of bytes transferred. If no user data is to be passed back to the caller, the condition function should set lpCalleeData->len to zero. The format of all address and user data is specific to the address family to which the socket belongs.
Reserved for future use with socket groups: The result parameter g is assigned within the condition function to indicate the following actions:
For unconstrained groups, any set of sockets can be grouped together as long as they are supported by a single service provider. A constrained socket group can consist only of connection-oriented sockets, and requires that connections on all grouped sockets be to the same address on the same host. For newly created socket groups, the new group ID can be retrieved by using getsockopt with option SO_GROUP_ID, if this operation completes successfully. A socket group and its associated ID remain valid until the last socket belonging to this socket group is closed. Socket group IDs are unique across all processes for a given service provider.
The dwCallbackData parameter value passed to the condition function is the value passed as the dwCallbackData parameter in the original WSAAccept call. This value is interpreted only by the Windows Socket version 2 client. This allows a client to pass some context information from the WSAAccept call site through to the condition function. This also provides the condition function with any additional information required to determine whether to accept the connection or not. A typical usage is to pass a (suitably cast) pointer to a data structure containing references to application-defined objects with which this socket is associated.
If no error occurs, WSAAccept returns a value of type SOCKET that is a descriptor for the accepted socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code can 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.
| WSANOTINITIALISED | A successful WSAStartup must occur before using this function. |
| WSAECONNREFUSED | The connection request was forcefully rejected as indicated in the return value of the condition function (CF_REJECT). |
| WSAENETDOWN | The network subsystem has failed. |
| WSAEFAULT | The addrlen parameter is too small or the addr or lpfnCondition are not part of the user address space. |
| WSAEINTR | A blocking Windows Sockets 1.1 call was canceled through WSACancelBlockingCall. |
| WSAEINPROGRESS | A blocking Windows Sockets 1.1 call is in progress. |
| WSAEINVAL | listen was not invoked prior to WSAAccept, parameter g specified in the condition function is not a valid value, the source address of the incoming connection request is not consistent with that of the constrained group the parameter g is referring to, the return value of the condition function is not a valid one, or any case where the specified socket is in an invalid state. |
| WSAEMFILE | The queue is nonempty upon entry to WSAAccept and there are no socket 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. |
| WSATRY_AGAIN | The acceptance of the connection request was deferred as indicated in the return value of the condition function (CF_DEFER). |
| WSAEWOULDBLOCK | The socket is marked as nonblocking and no connections are present to be accepted. |
| WSAEACCES | The connection request that was offered has timed out or been withdrawn. |
Windows NT: Yes
Windows: Yes
Windows CE: Unsupported.
Header: Declared in winsock2.h.
Import Library: Link with ws2_32.lib.
accept, bind, connect, getsockopt, listen, select, socket, WSAAsyncSelect, WSAConnect