WSPAccept function
WSPAccept conditionally accepts a connection, based on the return value of a condition function.
Syntax
SOCKET WSPAccept(
_In_ SOCKET s,
_Out_ struct sockaddr FAR *addr,
_Inout_ LPINT addrlen,
_In_ LPCONDITIONPROC lpfnCondition,
_In_ DWORD dwCallbackData,
_Out_ lpErrno
);
Parameters
s [in]
Descriptor identifying a socket that is listening for connections as a result of a call to the SAN service provider's WSPListen function.addr [out]
Pointer to a buffer into which the SAN service provider copies the IP address of the remote connecting entity.addrlen [in, out]
Pointer to a variable that receives the size, in bytes, of the buffer at Addr.lpfnCondition [in]
Pointer to a condition function supplied by the Windows Sockets switch. The SAN service provider calls this condition function to accept or reject a connection. The condition function is defined as ConditionFunc.dwCallbackData [in]
Callback data to be passed back to the Windows Socket switch as the value of the condition function's dwCallbackData parameter. The SAN service provider does not interpret this parameter.lpErrno [out]
Pointer to a variable that receives the error code.
Return value
Returns a value of type SOCKET that is a descriptor for the accepted socket, if successful; otherwise, returns INVALID_SOCKET and, at lpErrno, one of the following error codes:
| Return code | Description |
|---|---|
| WSAECONNREFUSED | Connection request was forcefully rejected as indicated by CF_REJECT. |
| WSAENETDOWN | Network subsystem failure. |
| WSAEFAULT | Value of addrlen parameter is too small, or the condition function to which lpfnCondition points is not part of the user address space. |
| WSAEINVAL | Indicates one of the following: the WSPListen function was not called prior to calling WSPAccept, parameter g specified in the condition function is not a valid value, the return value of the condition function is not valid, or any case where the specified socket is in an invalid state. |
| WSAEMFILE | Queue is nonempty upon entry to WSPAccept; no socket descriptors available. |
| WSAENOBUFS | No buffer space available. |
| WSAENOTSOCK | Descriptor does not describe a socket. |
| WSAEOPNOTSUPP | Referenced socket is not a type that supports connection-oriented service. |
| WSAEWOULDBLOCK | No connections are present to be accepted. |
| WSAEACCES | Connection request withdrawn or timed out. |
Remarks
ConditionFunc
int CALLBACK
ConditionFunc(
IN LPWSABUF lpCallerId,
IN LPWSABUF lpCallerData,
IN/OUT LPQOS lpSQOS,
IN/OUT LPQOS lpGQOS,
IN/OUT LPWSABUF lpCalleeId,
IN/OUT LPWSABUF lpCalleeData,
OUT GROUP FAR *g,
IN DWORD dwCallbackData
);
The parameters of this function are defined as:
lpCallerId
Pointer to a WSABUF structure that contains the address of the remote connecting entity.lpCallerData
Pointer to a WSABUF structure that contains any user data that was included with the incoming connection request.lpSQOS
Pointer to a QoS structure that contains flow specifications for socket S supplied to the WSPAccept function. For more information about QoS, see the Microsoft Windows SDK documentation.lpGQOS
Reserved.lpCalleeId
Pointer to a WSABUF structure that contains the local IP address that the provider uses to accept the incoming connection. This local IP address must be one of the addresses that the provider can return in response to an SIO_ADDRESS_LIST_QUERY made through a call to WSPIoctl.lpCalleeData
Pointer to a WSABUF structure that can contain user data that the SAN service provider must pass back to the remote connecting entity.g
Reserved.dwCallbackData
Context information related to the connection/acceptance request.
In response to a SAN service provider's signaling a network event object, the Windows Sockets switch calls the SAN service provider's WSPEnumNetworkEvents function to receive event codes. The event code for an incoming connection request that previously arrived on the listening local socket is FD_ACCEPT. Upon receiving the FD_ACCEPT event code, the switch calls the SAN service provider's WSPAccept function to accept or reject an incoming connection request. After the switch calls WSPAccept, the SAN service provider resets the event object so the SAN service provider can again signal an event.
WSPAccept extracts the first connection request on the listening socket's queue of pending connection requests. To accept or reject the connection request, the SAN service provider must call the condition function that the switch passes to WSPAccept. The condition function must be executed in the same thread as WSPAccept.
If the switch's condition function returns CF_REJECT to reject the connection request, or if some other problem prevents the connection from being fully established, the SAN service provider should return the appropriate error code.
If the switch calls WSPAccept when no pending connections are present on the listening socket's queue, WSPAccept returns the error code WSAEWOULDBLOCK.
If the switch's condition function returns CF_ACCEPT to accept the connection request, WSPAccept creates a new socket. This socket has the same properties as the original local socket. As described in Accepting Connection Requests, a SAN service provider must call the WPUCreateSocketHandle function to allocate a descriptor for the new socket. The switch intercepts this upcall (calls prefixed with WPU) and returns a socket descriptor. The SAN service provider must store this descriptor in its internal data structure for the new socket. Finally, the SAN service provider returns its own descriptor for the socket to complete the WSPAccept call. The switch must supply the SAN service provider's internal descriptor for the new socket when calling the SAN service provider's functions, while the SAN service provider must supply the switch's socket descriptor in upcalls to the switch. For more information about WPUCreateSocketHandle, see the Windows SDK documentation.
The SAN service provider uses the return value of the switch's condition function to indicate to the remote connecting entity whether it accepts or refuses the connection request. After the switch calls the SAN service provider's WSPAccept function to accept or reject the deferred connection request, the switch's condition function can return either the CF_ACCEPT or CF_REJECT value. If the switch's condition function returns CF_REJECT, the SAN service provider should terminate the already established connection.
If the connection request is accepted, the switch cannot use the new accepted socket to accept more connections. Also if the connection request is accepted, the SAN service provider passes the IP address of the remote connecting entity to the switch. The original socket remains open and in listening mode.
The SAN service provider must supply the address of the remote connecting entity and any user data that was sent along with the incoming connection request at the lpCallerId and lpCallerData parameters of the condition function. If no caller identifier or caller data is available, the SAN service provider sets the corresponding parameter to NULL.
If the SAN service provider supports quality of service (QoS), it specifies flow parameters for socket S. The SAN service specifies flow parameters for both transmission and reception, and specifies any additional provider-specific parameters at the lpSQOS parameter of the condition function. A SAN service provider specifies a NULL value for lpSQOS to indicate that no QoS negotiation is possible. A non-NULLlpSQOS pointer indicates that a QoS negotiation will occur or that the SAN service provider is prepared to accept the QoS request without negotiation.
The switch uses the lpCalleeData parameter of the condition function to supply user data back to the remote connecting entity. The SAN service provider must allocate a WSABUF structure to provide storage for this data.
If the SAN service provider does not support passing user data back to the remote connecting entity, it sets the len member of this WSABUF structure to zero.
If the SAN service provider supports passing user data back to the remote connecting entity, it allocates a buffer to which the buf member of WSABUF points and sets the len member of WSABUF to the maximum number of bytes of data that the condition function can copy into the buffer. After the condition function copies the data, it updates the len member of WSABUF to indicate the actual number of bytes copied.
If the condition function does not pass any user data back to the connecting entity, it sets the len member of WSABUF to zero.
The SAN service provider passes the value that the switch passed as the dwCallbackData parameter in the original WSPAccept call to the dwCallbackData parameter for the condition function. This value is interpreted only by the Windows Sockets switch. The switch can pass context information from the WSPAccept call to the condition function to provide the condition function with any additional information required to determine whether to accept the connection. A typical usage of this functionality is to pass a (suitably cast) pointer to a data structure containing references to application-defined objects with which this socket is associated.
Requirements
Target platform |
Desktop |
Version |
Requires Windows Sockets version 2.0. |
Header |
Ws2spi.h (include Ws2spi.h) |
See also