PFN_WSK_ACCEPT callback function (wsk.h)
The WskAccept function accepts an incoming connection on a listening socket.
Syntax
PFN_WSK_ACCEPT PfnWskAccept;
NTSTATUS PfnWskAccept(
[in] PWSK_SOCKET ListenSocket,
ULONG Flags,
[in, optional] PVOID AcceptSocketContext,
[in, optional] const WSK_CLIENT_CONNECTION_DISPATCH *AcceptSocketDispatch,
[out, optional] PSOCKADDR LocalAddress,
[out, optional] PSOCKADDR RemoteAddress,
[in, out] PIRP Irp
)
{...}
Parameters
[in] ListenSocket
A pointer to a WSK_SOCKET structure that specifies the socket object for the listening or stream socket that is being checked for an incoming connection.
Flags
This parameter is reserved for system use. A WSK application must set this parameter to zero.
[in, optional] AcceptSocketContext
A pointer to a caller-supplied context for the socket that is being accepted. The WSK subsystem passes this pointer to the accepted socket's event callback functions. The context information is opaque to the WSK subsystem. The context information must be stored in non-paged memory. If the WSK application will not be enabling any event callback functions on the accepted socket, it should set this pointer to NULL.
[in, optional] AcceptSocketDispatch
A pointer to a constant WSK_CLIENT_CONNECTION_DISPATCH structure. This structure is a dispatch table that contains pointers to the event callback functions for the accepted socket. If the WSK application will not be enabling all of the event callback functions for the accepted socket, it should set the pointers in the dispatch table to NULL for those event callback functions that it does not enable. If the WSK application will not be enabling any event callback functions on the accepted socket, it should set this pointer to NULL.
[out, optional] LocalAddress
A pointer to a caller-allocated buffer that receives the local transport address on which the incoming connection arrived. The buffer must be located in non-paged memory. The buffer must also be large enough to contain the specific SOCKADDR structure type that corresponds to the address family that the WSK application specified when it created the listening socket. This pointer is optional and can be NULL.
[out, optional] RemoteAddress
A pointer to a caller-allocated buffer that receives the remote transport address from which the incoming connection originated. The buffer must be located in non-paged memory. The buffer must also be large enough to contain the specific SOCKADDR structure type that corresponds to the address family that the WSK application specified when it created the listening socket. This pointer is optional and can be NULL.
[in, out] Irp
A pointer to a caller-allocated IRP that the WSK subsystem uses to complete the accept operation asynchronously. For more information about using IRPs with WSK functions, see Using IRPs with Winsock Kernel Functions.
Return value
WskAccept returns one of the following NTSTATUS codes:
| Return code | Description |
|---|---|
|
An incoming connection was successfully accepted. The IRP will be completed with success status. |
|
The IRP has been queued by the WSK subsystem, which is waiting for an incoming connection on the listening socket. |
|
The socket is no longer functional. The IRP will be completed with failure status. The WSK application must call the WskCloseSocket function to close the socket as soon as possible. |
|
An error occurred. The IRP will be completed with failure status. |
Remarks
A WSK application can call the WskAccept function on either a listening socket or stream socket that it previously bound to a local transport address by calling the WskBind function.
The behavior of the WskAccept function depends on whether an incoming connection is waiting to be accepted on the listening socket:
- If an incoming connection has already arrived on the listening socket and is waiting to be accepted, the WskAccept function returns STATUS_SUCCESS. In this situation, the IRP is completed with success status and the IoStatus.Information field of the IRP contains a pointer to the socket object for the accepted socket.
- If an incoming connection is not waiting to be accepted on the listening socket, WskAccept returns STATUS_PENDING and the WSK subsystem queues the IRP until an incoming connection is received. When an incoming connection is received, the WSK subsystem asynchronously completes the IRP with success status. In this situation, the IoStatus.Information field of the IRP contains a pointer to the socket object for the accepted socket.
When the WskAccept function successfully accepts an incoming connection, all of the event callback functions on the accepted socket are disabled by default. For more information about enabling any of the accepted socket's event callback functions, see Enabling and Disabling Event Callback Functions.
If a WSK application specifies a non-NULL pointer in the LocalAddress parameter, in the RemoteAddress parameter, or in both parameters, and if WskAccept returns STATUS_PENDING, the buffers that are pointed to by those parameters must remain valid until the IRP is completed. If the WSK application allocated the buffers with one of the ExAllocateXxx functions, it cannot free the memory with the corresponding ExFreeXxx function until after the IRP is completed. If the WSK application allocated the buffers on the stack, it cannot return from the function that calls the WskAccept function until after the IRP is completed.
The WSK subsystem allocates the memory for the socket object structure ( WSK_SOCKET) for the accepted connection on behalf of the WSK application. The WSK subsystem deallocates this memory when the socket is closed.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows Vista and later versions of the Windows operating systems. |
| Target Platform | Universal |
| Header | wsk.h (include Wsk.h) |
| IRQL | <= DISPATCH_LEVEL |