PFN_WSK_GET_NAME_INFO callback function (wsk.h)

Article
10/21/2021

The WskGetNameInfo function provides protocol-independent translation from a transport address to a host name.

Syntax

PFN_WSK_GET_NAME_INFO PfnWskGetNameInfo;

NTSTATUS PfnWskGetNameInfo(
  [in]            PWSK_CLIENT Client,
  [in]            PSOCKADDR SockAddr,
  [in]            ULONG SockAddrLength,
  [out, optional] PUNICODE_STRING NodeName,
  [out, optional] PUNICODE_STRING ServiceName,
  [in]            ULONG Flags,
  [in, optional]  PEPROCESS OwningProcess,
  [in, optional]  PETHREAD OwningThread,
  [in, out]       PIRP Irp
)
{...}

Parameters

[in] Client

[in] A pointer to a WSK_CLIENT structure that was returned through the WskProviderNpi parameter of the WskCaptureProviderNPI function.

[in] SockAddr

[in] A pointer to a SOCKADDR structure that contains the IP address and port number of the socket.

[in] SockAddrLength

[in] Specifies the length, in bytes, of the buffer pointed to by the SockAddr parameter. The value of SockAddrLength should not exceed the size of the SOCKADDR_STORAGE structure.

[out, optional] NodeName

[out] An optional pointer to a UNICODE_STRING structure that contains a Unicode string that represents a host (node) name. On success, the Unicode host name is written as a Fully Qualified Domain Name (FQDN) by default. The caller must provide a UNICODE_STRING buffer large enough to hold the Unicode host name, which includes the terminating NULL character. If the NodeBuffer parameter is NULL, the caller does not want to receive a host name string. NodeBuffer and ServiceBuffer must not both be NULL.

[out, optional] ServiceName

[out] An optional pointer to a UNICODE_STRING structure that contains a Unicode string that represents a service name associated with the port number. The caller must provide a UNICODE_STRING buffer large enough to hold the Unicode service name, which includes the terminating NULL character. If the NodeBuffer parameter is NULL, the caller does not want to receive a service name string. NodeBuffer and ServiceBuffer must not both be NULL.

[in] Flags

[in] A ULONG value that is used to customize the processing of this function.

The following flags are available:

NI_DGRAM

Indicates that the service is a datagram service. This flag is necessary for the few services that provide different port numbers for UDP and TCP service.

NI_NAMEREQD

Indicates that a host name that cannot be resolved by DNS results in an error.

NI_NOFQDN

Results in a local host having only its Relative Distinguished Name (RDN) returned in the NodeName parameter.

NI_NUMERICHOST

Indicates that the function returns the numeric form of the host name instead of its name, a reverse DNS lookup. The numeric form of the host name is also returned if the host name cannot be resolved by DNS.

NI_NUMERICSERV

Indicates that the function returns the port number of the service instead of its name. Also, if a host name is not found for an IP address (127.0.0.2, for example), the host name is returned as the IP address.

[in, optional] OwningProcess

[in] An optional pointer to the process from which the function retrieves the security context. This security context indicates the user account context in which the function processes the name resolution request.

If this parameter is NULL, the function processes the name resolution request in the context of a predefined local account with minimal privileges.

If this parameter is not NULL and an impersonation token is in effect for the calling thread, this function fails and returns STATUS_INVALID_PARAMETER.

[in, optional] OwningThread

[in] An optional pointer to the thread from which the function retrieves the security context. This parameter can be non-NULL only if OwningProcess is non-NULL. Otherwise, this function fails and returns STATUS_INVALID_PARAMETER.

If this parameter is not NULL and an impersonation token is in effect for the calling thread, this function fails and returns STATUS_INVALID_PARAMETER.

[in, out] Irp

[in/out] A pointer to an I/O request packet (IRP) to use to complete the request asynchronously. Upon completion of the request, Irp -> Iostatus.Information will hold the returned status code.

Return value

WskGetNameInfo returns one of the following NTSTATUS codes:

Return code	Description
STATUS_INVALID_PARAMETER	An invalid parameter was specified.
STATUS_NO_MATCH	The host name cannot be resolved.
STATUS_SUCCESS	The function completed successfully. If the WSK application specified a pointer to an IRP in the Irp parameter, the IRP will be completed with a success status.
STATUS_PENDING	The WSK subsystem could not complete the function immediately. The WSK subsystem will complete the IRP after it has completed the control operation. The status of the control operation will be returned in the IoStatus.Status field of the IRP.
Other status codes	An error occurred. The IRP will be completed with failure status.

Remarks

The process to which the OwningProcess parameter points, or the thread to which the OwningThread process points, indicates the security context for this function. The user account that is indicated by the security context indicates the context for the function's name resolution request.

Requirements

Requirement	Value
Minimum supported client	Available in Windows 7 and later versions of the Windows operating systems.
Target Platform	Universal
Header	wsk.h (include Wsk.h)
IRQL	PASSIVE_LEVEL