WSAAccept

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function conditionally accepts a connection based on the return value of a condition function and allows the transfer of connection data.

Syntax

SOCKET WSAAccept(
  SOCKET s,
  struct sockaddr FAR* addr,
  LPINT addrlen,
  LPCONDITIONPROC lpfnCondition,
  DWORD dwCallbackData
);

Parameters

• s
  [in] Descriptor identifying a socket that is listening for connections after a call to the listen function.

• addr
  [out] Optional pointer to a buffer that receives 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 established when the socket was created.

• addrlen
  [in, out] Optional pointer to an integer that contains the length of the address addr.

• lpfnCondition
  [in] Procedure instance address of the optional, application-supplied condition function that will make an accept/reject decision based on the caller information passed in as parameters.

• dwCallbackData
  [in] Callback data passed back to the application as the value of the dwCallbackData parameter of the condition function. This parameter is not interpreted by Windows Sockets.

Return Value

If no error occurs, this function returns a value of type SOCKET that is a descriptor for the accepted socket. If an error occurs, 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. The following table shows a list of possible error codes.

Remarks

This 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. The newly created socket has the same properties as socket s, including asynchronous events registered with WSAEventSelect. If the condition function returns CF_REJECT, WSAAccept rejects the connection request. The condition function runs in the same thread as this function 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 default mode (blocking) will block until a connection is present when an application calls WSAAccept and no connections are pending on the queue.

A socket in nonblocking mode fails with the error WSAEWOULDBLOCK when an application calls WSAAccept and no connections are pending on the queue. After WSAAccept succeeds and returns a new socket handle, the new 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 completed 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 parameter 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 completed regardless of whether the condition function is specified or what it returns.

The prototype of the callback 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_PTR dwCallbackData
);

The ConditionFunc function 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. **

The lpCallerId parameter points to a WSABUF structure that contains the address of the connecting entity, where its len parameter is the length of the buffer in bytes and its buf parameter is a pointer to the buffer. The lpCallerData parameter 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 identifier information at connection-request time. The buf portion of the WSABUF structure pointed to by lpCallerId points to a sockaddr structure. The sockaddr structure is interpreted according to its address family (typically by casting the sockaddr to some type specific to the address family).

The lpCalleeId parameter is a value parameter that contains the local address of the connected entity. The buf portion of the WSABUF structure pointed to by lpCalleeId points to a sockaddr structure. The sockaddr structure is interpreted according to its address family (typically by casting the sockaddr to some type specific to the address family).

The lpCalleeData parameter 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.

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 Winsock 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. 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.

Requirements

See Also

Reference

accept (Windows Sockets)
bind (Windows Sockets)
connect (Windows Sockets)
getsockopt (Windows Sockets)
listen
select
sockaddr
socket (Windows Sockets)
WSAConnect
WSAEventSelect
WSAGetLastError
WSAStartup