DnsValidateName

The DnsValidateName function validates the status of a specified DNS name. Like many DNS functions, the DnsValidateName function type is implemented in multiple forms to facilitate different character encoding. Based on the character encoding involved, use one of the following functions:

DnsValidateName_A (_A for ANSI encoding)

DnsValidateName_W (_W for Unicode encoding)

DnsValidateName_UTF8 (_UTF8 for UTF-8 encoding)

If the DnsValidateName function type is called without its suffix (_A, _W, or _UTF8), a compiler error will occur.

DNS_STATUS DnsValidateName(
  LPCSTR pszName,
  DNS_NAME_FORMAT Format
);

Parameters

pszName

[in] DNS name to be examined.

Format

[in] Format of the name to be examined. The format may have the following values:

DnsNameDomain

DnsNameDomainLabel

DnsNameHostnameFull

DnsNameHostnameLabel

DnsNameWildcard

DnsNameSrvRecord

Remarks

To check the status of the Computer Host (single label), use the DnsValidateName function type with DnsNameHostnameLabel in Format.

Return Values

The DnsValidateName function type provides five possible return values:

• ERROR_SUCCESS
• ERROR_INVALID_NAME
• DNS_ERROR_INVALID_NAME_CHAR
• DNS_ERROR_NUMERIC_NAME
• DNS_ERROR_NON_RFC_NAME

The DnsValidateName function works in a progression when determining whether an error exists with a given DNS name, and returns upon finding its first error. Therefore, a DNS name that has multiple, different errors may be reported as having the first error, and could be corrected and resubmitted, only then to find the second error.

The DnsValidateName function searches for the errors in the following progression.

Returns ERROR_INVALID_NAME if the DNS name:

• Is longer than 255 octets
• Contains a label longer than 63 octets
• Contains a space
• Contains two or more consecutive dots
• Begins with a dot
• Contains a dot if the name is submitted with Format set to DnsNameHostDomainLabel or DnsNameHostnameLabel.

Next, DnsValidateName returns DNS_ERROR_INVALID_NAME_CHAR if the DNS name.

• Contains any of the following invalid characters: { | } ~ [ \ ] ^ ' : ; < = > ? @ ! " # $ % ^ ` ( ) + / ,
• Contains an asterisk (*), unless the asterisk is the first label in the multi-labeled name, submitted with Format set to DnsNameWildcard.

Next, DnsValidateName returns DNS_ERROR_NUMERIC_NAME if the DNS name consists of one or more labels built of only the numeric characters (0-9), unless Format is set to DnsNameDomainLabel or DnsNameDomain, and one of the labels is not fully numeric.

Then, DnsValidateName returns DNS_ERROR_NON_RFC_NAME if the DNS name:

• Contains at least one extended or Unicode character.
• Contains underscore (_), unless the underscore is a first character in a label, in the name, submitted with Format set to DnsNameSrvRecord.

Note that if DnsValidateName returns DNS_ERROR_NON_RFC_NAME, the error should be treated as a warning that not all DNS servers will accept the name. When this error is received, note that Windows 2000 DNS Server does accept the submitted name, if appropriately configured (default configuration accepts the name as submitted when DNS_ERROR_NON_RFC_NAME is returned), but other DNS server software may not.

If DnsValidateName returns any of the following, the error should be treated as an invalid host name:

• DNS_ERROR_NUMERIC_NAMEa
• DNS_ERROR_INVALID_NAME_CHAR
• ERROR_INVALID_NAME

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Windns.h.
  Library: Use Dnsapi.lib.

See Also

DnsNameCompare, DnsQuery