getnameinfo

  • Article

This function provides name resolution from an address to the host name.

int getnameinfo(
  const struct sockaddr FAR* sa,
  socklen_t salen,
  char FAR* host,
  DWORD hostlen,
  char FAR* serv,
  DWORD servlen,
  int flags
);

Parameters

  • sa
    [in] Pointer to a socket address structure containing the address and port number of the socket. For IPv4, the sa parameter points to a sockaddr_in structure; for IPv6, the sa parameter points to a sockaddr_in6 structure.
  • salen
    [in] Length of the structure pointed to in the sa parameter.
  • host
    [out] Pointer to the host name. The host name is returned as a Fully Qualified Domain Name (FQDN) by default.
  • hostlen
    [in] Length of the buffer pointed to by the host parameter. The caller must provide a buffer large enough to hold the host name, including terminating NULL characters. A value of zero indicates the caller does not want to receive the string provided in host.
  • serv
    [out] Pointer to the service name associated with the port number.
  • servlen
    [in] Length of the buffer pointed to by the serv parameter. The caller must provide a buffer large enough to hold the service name, including terminating NULL characters. A value of zero indicates the caller does not want to receive the string provided in serv.
  • flags
    [in] Flags used to customize processing of this function.

Return Values

If no error occurs, this function returns zero. Any nonzero return value indicates failure. Use the WSAGetLastError function to retrieve error information.

Remarks

To simplify determining buffer requirements for the host and serv parameters, the following values for maximum host name length and maximum service name are defined in the Ws2tcpip.h header file:

#define NI_MAXHOST  1025
#define NI_MAXSERV    32

The flags parameter can be used to customize processing of this function. The following table shows the available flags.

Flag Description
NI_NOFQDN Setting the NI_NOFQDN flag results in local hosts having only their Relative Distinguished Name (RDN) returned in the host parameter.
NI_NUMERICHOST Setting this flag returns the numeric form of the host name instead of its name. The numeric form of the host name is also returned if the host name cannot be resolved by DNS.
NI_NAMEREQD Setting this flag is set results in an error when host names cannot be resolved by Domain Name System (DNS).
NI_NUMERICSERV Setting this flag returns the port number of the service instead of its name.
NI_DGRAM Setting this flag 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.

Requirements

OS Versions: Windows CE .NET 4.1 and later.
Header: Ws2tcpip.h.
Link Library: Ws2.lib.

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.