PFN_WSK_GET_REMOTE_ADDRESS callback function (wsk.h)

Article
10/21/2021

The WskGetRemoteAddress function retrieves the remote transport address of a connection-oriented or stream socket.

Syntax

PFN_WSK_GET_REMOTE_ADDRESS PfnWskGetRemoteAddress;

NTSTATUS PfnWskGetRemoteAddress(
  [in]      PWSK_SOCKET Socket,
  [out]     PSOCKADDR RemoteAddress,
  [in, out] PIRP Irp
)
{...}

Parameters

[in] Socket

A pointer to a WSK_SOCKET structure that specifies the socket object for the socket that is being queried.

[out] RemoteAddress

A pointer to a caller-allocated buffer that receives the remote transport address for the socket. 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 socket.

For a connection-oriented socket that the WSK application accepted on a listening socket, the address family is the same as the address family that the WSK application specified when it created the listening socket.

[in, out] Irp

A pointer to a caller-allocated IRP that the WSK subsystem uses to complete the retrieve operation asynchronously. For more information about using IRPs with WSK functions, see Using IRPs with Winsock Kernel Functions.

Return value

WskGetRemoteAddress returns one of the following NTSTATUS codes:

Return code	Description
STATUS_SUCCESS	The remote transport address for the socket was successfully retrieved. The IRP will be completed with success status.
STATUS_PENDING	The WSK subsystem could not retrieve the remote transport address for the socket immediately. The WSK subsystem will complete the IRP after it has retrieved the remote transport address for the socket. The status of the retrieve operation will be returned in the IoStatus.Status field of the IRP.
STATUS_INVALID_DEVICE_STATE	The socket is not connected to a remote transport address. The IRP will be completed with failure status.
STATUS_FILE_FORCED_CLOSED	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.
Other status codes	An error occurred. The IRP will be completed with failure status.

Remarks

A WSK application can call the WskGetRemoteAddress function only on a connection-oriented or stream socket that has been connected to a remote transport address. A stream socket is connected to a remote transport address by calling the WskConnect function. A connection-oriented socket is connected to a remote transport address in one of the following ways:

The WSK application calls the WskConnect function.
The WSK application creates, binds, and connects the socket by calling the WskSocketConnect function.
The WSK subsystem connects the socket when the WSK application accepts an incoming connection request on a listening socket.

If the WskGetRemoteAddress function returns STATUS_PENDING, the buffer that is pointed to by the RemoteAddress parameter must remain valid until the IRP is completed. If the WSK application allocated the buffer 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 buffer on the stack, it cannot return from the function that calls the WskGetRemoteAddress function until after the IRP is completed.

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