WskGetNameInfo function

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

Syntax


NTSTATUS APIENTRY WskGetNameInfo(
  _In_      PWSK_CLIENT     Client,
  _In_      PSOCKADDR       SockAddr,
  _In_      ULONG           SockAddrLength,
  _Out_opt_ PUNICODE_STRING NodeName,
  _Out_opt_ PUNICODE_STRING ServiceName,
  _In_      ULONG           Flags,
  _In_opt_  PEPROCESS       OwningProcess,
  _In_opt_  PETHREAD        OwningThread,
  _Inout_   PIRP            Irp
);

Parameters

Client [in]

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

SockAddr [in]

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

SockAddrLength [in]

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

NodeName [out, optional]

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

ServiceName [out, optional]

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

Flags [in]

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

OwningProcess [in, optional]

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

OwningThread [in, optional]

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

Irp [in, out]

[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 codeDescription
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

Target platform

Universal

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)

IRQL

PASSIVE_LEVEL

See also

SOCKADDR
SOCKADDR_STORAGE
UNICODE_STRING
WSK_CLIENT
WskCaptureProviderNPI
WskGetAddressInfo

 

 

Send comments about this topic to Microsoft

Show: