Inter-Corporate Computer & Network Services, inc. Solutions Services Support Products Login Company Contact Inter-Corporate
Inter-Corporate Computer & Network Services, inc.

ICELIB0.NLM   →   ICE_QueryDNS()

ICE_QueryDNS

Description:
Sends a query to the specified DNS server and returns a pointer to an array of uncompressed records if successful.  This function uses BSD sockets for UDP communications with the specified DNS server, and can support DNS servers listening on non-standard ports if required.

This DNS resolver function supports 41 different types of DNS RRs (Resource Records) based on various internet RFCs, and includes support for those DNS RRs most commonly used (1/A, 2/NS, 5/CNAME, 6/SOA, 12/PTR, and 15/MX).  A clear understanding of DNS is required in order to use this function effectively.
 

Syntax for C:
int ICE_QueryDNS (
  unsigned int dnsServer <or char *dnsServer>,
  unsigned int udpPort,
  char *rrText,
  unsigned int rrType <or char *rrType>,
  unsigned int rrClass <or char *rrClass>,
  unsigned int nsTimeout,
  unsigned int nsRetries,
  void *retryThread,
  int retryValue,
  int flags,
  int *returnCode
);
 
Syntax for Assembly:
Call ICE_QueryDNS C, {offset} dnsServer, [udpPort], offset rrText, {offset} rrType, {offset} rrClass, [nsTimeout], [nsRetries], offset retryThread, [retryValue], [flags], offset returnCode
 
Parameters:
dnsServer
(IN) 32-bit IP address (internet bit-order), or pointer to ASCIIZ string containing the IP address if internet standard dotted notation Flag 1 is set
 
udpPort
(IN) UDP port to use (usually 53), 32-bit value ranging 1 through 65535
 
rrText
(IN) Pointer to ASCIIZ string of DNS name to query (see also Flag 2)
 
rrType
(IN) 32-bit record type value, or pointer to ASCIIZ string containing the Resource Record type if Flag 4 is set
 
rrClass
(IN) 32-bit record class value, or pointer to ASCIIZ string containing the Resource Record class if Flag 8 is set (usually 1 or "IN")
 
nsTimeout
(IN) Number of seconds to wait before assuming specified DNS server is down or UDP packet was lost (0 = no timeout / OS default)
 
nsRetries
(IN) Number of times to resend the query to specified DNS server after timeout expires (0 = don't retry)
 
retryThread
(IN) Pointer to function to call whenever a retry occurs, or NULL to disable this feature. BeginThread() is called with an argument that is a pointer to newly allocated memory with the following structure (this thread must free() this memory):
  1. retryValue (32 bits), see next parameter (below)
  2. Retry count (32 bits), first value is 1, then 2, ...
  3. dnsServer (32 bits), same as "dnsServer" parameter
  4. rrText (32 bits), same as "rrText" parameter
Be aware that your NLM could terminate before this thread does, and applications that require this thread to be "blocking" can use flag 32.
 
retryValue
(IN) Any 32-bit value, defined by the software developer, which will be included in the structure passed to the function defined in "retryThread" (above).
 
flags
(IN) Some rules to be enforced during the query.  All undocumented bit flags are considered reserved for future use, and should remain cleared (0) to ensure upward compatibility with newer versions of ICELIB0.NLM.  Currently supported flags are as follows:

1 = dnsServer is a pointer to an ASCIIZ string (e.g., "127.0.0.1"), instead of a 32-bit (internet order) IP address

2 = rrText is already formatted for DNS communications, instead of a standard ASCIIZ string such as "inter-corporate.com" (see Note 4)

4 = rrType is a pointer to an ASCIIZ string (e.g., "a" or "mx"), instead of a 32-bit type number (see Note 2)

8 = rrClass is a pointer to an ASCIIZ string (e.g., "IN"), instead of a 32-bit class number (see Note 3)

16 = Return raw data (no splicing and no conversion, see Note 5)

32 = If set, calls the function directly instead of starting a thread, thus making it a blocking function (see Note 9 for some important notes about using this flag)

64 = Reserved for future use, set to zero (0) for upward compatibility

128 = Enable recursion (instructs the DNS server to contact the root servers when the answer is not cached locally)

256..2048 = Query type, 4 bits, 0=Query, 1=InverseQuery, 2=Status, all others reserved according to RFC1035

4096..16384 = Z, 3 bits, must be zero for Query types 0 and 1
 

returnCode
(OUT) Pointer to 32-bit value which will contain one of the following return codes if the query fails:

0 = Successful query
-1 = Unable to allocate memory (malloc() failed)
-2 = Invalid DNS server (dnsServer)
-3 = Invalid UDP port (udpPort)
-4 = Invalid query string (rrText)
-5 = Invalid resource record type (rrType)
-6 = Invalid resource record class (rrClass)
-7 = Socket open or I/O failure
-8 = DNS server returned no response (due to socket read error)
-9 = DNS server returned empty response (no answer)
-10 = DNS server timed out (may be down or UDP packets were lost)
 

Returns:
Buffer pointer created by malloc() containing array, or 0 if no buffer was created -- see "Array" notes for details about the format of information returned, which depends on the rrType specified for the query.
 
Remarks:
DNS is a specialized internet protocol which includes hostname compression and variable record sizes. This function reliably converts responses from DNS servers to an easy-to-handle array format, thus allowing developers to perform DNS queries without needing to know the inner-workings of DNS. A basic understanding of DNS administrative concepts is highly recommended though.

Note 1
Only an IP address may be specified for the "dnsServer" parameter, because hostname resolution requires the use of a DNS server.
 
Note 2
Supported DNS RR Types are:  1/A, 2/NS, 3/MD, 4/MF, 5/CNAME, 6/SOA, 7/MB, 8/MG, 9/MR, 10/NULL, 11/WKS, 12/PTR, 13/HINFO, 14/MINFO, 15/MX, 16/TXT, 17/RP, 18/AFSDB, 19/X25, 20/ISDN, 21/RT, 22/NSAP, 23/NSAP-PTR, 24/SIG, 25/KEY, 26/PX, 27/GPOS, 28/AAAA, 29/LOC/ICBM, 30/NXT, 31/EID, 32/NIMLOC, 33/SRV, 34/ATMA, 35/NAPTR, 36/KX, 37/CERT, 38/A6, 39/DNAME, 40/SINK, and 41/OPT -- All other values may return an error.  See "Array" (below) for record structures.
 
Note 3
Supported DNS RR Classes are:  1/IN;  Unsupported DNS RR Classes are: 2/CS, 3/CH, and 4/HS -- All other values may return an error.
 
Note 4
DNS communications format for domain names is a comprimise between a standard ASCIIZ string and an array. The first byte of each element in the string represents the length of bytes to follow, and no dots (periods) are present. For example, www.inter-corporate.com[0] is represented as [3]www[15]inter-corporate[3]com[0] instead.  The entire string is null-terminated.
 
Note 5
The internet utilizes binary values that are constructed with a bit order opposite of what Intel's processors use natively, and this function automatically converts these values in recognized rrTypes when converting them into array format.  However, if Flag 16 is set, no conversion is performed because it is assumed that the NLM needs the raw data as it was received from the DNS server.
 
Note 6
All values in the returned structure are either 32-bit pointers, or 32-bit values.  Values that are naturally 8, 16, or 24 bits are always extended to 32 bits in order to simplify structure handling.  Included here is a list of all data types used within the structures and how they should be interpreted by the developer:
  • 32<8> bits:  8-bit value extended to 32 bits
  • 32<16> bits:  16-bit value extended to 32 bits
  • 32<24> bits:  24-bit value extended to 32 bits
  • 32 bits:  32-bit value
  • ASCIIZ eMail address:  32-bit pointer to a null-terminated eMail address (see Note 8 for details)
  • ASCIIZ hostname:  32-bit pointer to null-terminated hostname
  • ASCIIZ string:  32-bit pointer to null-terminated string
Note 7
Every structure returned in the Array begins with a 32-bit value identifying the DNS record type, followed by a 32-bit pointer to the hostname also known as the "Owner."  Currently, only one record type may be queried for at one time, although it is possible this could change in the future, so to ensure compatibility with all future versions of this function the developer must verify that the first value matches the expected record type before using its data.
 
Note 8
Some DNS records, such as SOA or RP, use a hostname to store eMail addresses.  Since the "@" symbol is invalid in hostname data types in DNS because its ASCII value interferes with DNS hostname compression, the first entity in the hostname is considered to be the username portion (before the "@" symbol).  For nearly all purposes, this scheme works very well, but in the event that a username includes a period (e.g., "firstname.lastname@..."), the period is included in the first entity of the hostname (in the DNS configuration file this is usually expressed as "\.").  When an ASCIIZ eMail address is generated by this function, the "@" symbol is kept in the proper place, and extra dots in the first entity are maintained in order to preserve the intended eMail address.

For example, an eMail address of "firstname@example.com" would be represented in DNS as "firstname.example.com" while an eMail address of "firstname.lastname@example.com" would be represented in DNS as "firstname.lastname\.example.com" (when present, the "\." is converted to an "@" symbol).
 

Note 9
Do NOT use ExitThread() to terminate your retryThread function when flag 32 is set, or the thread that originally called ICE_QueryDNS() will be terminated and some resources will not be freed!  It is assumed that various registers and flags may be altered, so they are preserved by ICE_QueryDNS() before calling retryThread to ensure a stable environment upon return.
 

Remember to use NetWare's free() function when you no longer need the string.
 

Resource files:
icelib0.imp
 
Structures:
Array
An array of pointers is returned, with the final pointer being NULL to identify the end of the array.  The structure of the data within each element depends on the rrType specified for the query.  Details of the data structures is as follows (see Note 6 for important notes about data formats, and see Note 7 for information about the first two values within each structure):
 
A: 32-bit IPv4 address
  1. 1 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. IP address (32 bits)

NS: Authoritative name server
  1. 2 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Name server (ASCIIZ hostname)

MD: Mail destination - Obsolete, use MX
  1. 3 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. eMail agent (ASCIIZ hostname)

MF: Mail forwarder - Obsolete, use MX
  1. 4 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. eMail agent (ASCIIZ hostname)

CNAME: Canonical name for an alias
  1. 5 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Canonical name of owner (ASCIIZ hostname)

SOA: Start Of zone Authority
  1. 6 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Primary name server (ASCIIZ hostname)
  4. Responsible person (ASCIIZ eMail address)
  5. Serial number (32 bits)
  6. Refresh (32 bits)
  7. Retry interval (32 bits)
  8. Expiry (32 bits)
  9. Minimum TTL (32 bits)

MB: Mailbox domain name - Experimental
  1. 7 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Host of specified mailbox (ASCIIZ hostname)

MG: Mail group member - Experimental
  1. 8 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Mail group member (ASCIIZ eMail address)

MR: Mail rename domain name - Experimental
  1. 9 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Proper rename of specified mailbox (ASCIIZ eMail address)

NULL: Null - Experimental
  1. 10 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Size of binary data (32<16> bits)
  4. Binary data

WKS: Well Known Service
  1. 11 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. IP address (32 bits)
  4. Protocol (32<8> bits)
  5. Size in bytes of bit map (32<16> bits, ranging from 0 to 8192)
  6. Bit map

PTR: Domain name pointer
  1. 12 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Location (ASCIIZ hostname)

HINFO: Host information
  1. 13 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. CPU (ASCIIZ string)
  4. OS (ASCIIZ string)

MINFO: Mailbox or Mailing list information
  1. 14 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Responsible person (ASCIIZ eMail address)
  4. Errors (ASCIIZ eMail address)

MX: Mail exchange
  1. 15 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Preference (32<16> bits)
  4. Exchange (ASCIIZ hostname)

TXT: Text strings
  1. 16 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Text data (ASCIIZ string)

RP: Responsible person
  1. 17 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Responsible person (ASCIIZ eMail address)
  4. Location of related TXT records (ASCIIZ hostname)
    (ICELIB v1.07d required -- see history for ICELIB0.NLM)

AFSDB: AFS Data Base location
  1. 18 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Sub type (32<16> bits)
  4. Location of server (ASCIIZ hostname)

X25: X.25 PSDN address
  1. 19 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. PSDN address (ASCIIZ string)

ISDN: ISDN address
  1. 20 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. ISDN number, beginning with 4-digit DNIC (ASCIIZ string)
  4. Subaddress, optional (ASCIIZ string)

RT: Route through
  1. 21 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Preference (32<16> bits)
  4. Intermediate host (ASCIIZ hostname)

NSAP: Network service access point
  1. 22 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Count (ASCIIZ string)
  4. Address (ASCIIZ string)

NSAP-PTR: Network service access point, opposite of NSAP
  1. 23 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Owner (ASCIIZ hostname)

SIG: Security signature
  1. 24 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Type covered (32<16> bits)
  4. Algorithm (32<8> bits)
  5. Labels (32<8> bits)
  6. Original TTL (32 bits)
  7. Signature expiration (32 bits)
  8. Signature inception (32 bits)
  9. Key tag (32<16> bits)
  10. Signer (ASCIIZ hostname)
  11. Size of Signature (32<16> bits)
  12. Signature

KEY: Security key
  1. 25 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Flags (32<16> bits)
  4. Protocol (32<8> bits)
  5. Algorithm (32<8> bits)
  6. Size of Public Key (32<16> bits)
  7. Public Key

PX: X.400 mail mapping information
  1. 26 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Preference (32<16> bits)
  4. MAP822 (ASCIIZ hostname)
  5. MAPX400 (ASCIIZ hostname)

GPOS: Geographical position
  1. 27 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Longitude (ASCIIZ string)
  4. Latitude (ASCIIZ string)
  5. Altitude (ASCIIZ string)

AAAA: 128-bit IPv6 address
  1. 28 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. IPv6 address (pointer to 128-bit/16-byte value)

LOC; ICBM: Location information
  1. 29 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Version (32<8> bits)
  4. Size diameter, in centimeters (32<8> bits)
  5. Horizontal precision, in centimeters (32<8> bits)
  6. Vertical precision, in centimeters (32<8> bits)
  7. Latitude (32 bits)
  8. Longitute (32 bits)
  9. Altitude (32 bits)

NXT: Next domain
  1. 30 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Hostname (ASCIIZ hostname)
  4. Size of bitmap to follow (32<16> bits)
  5. Bitmap of RR types

EID: Endpoint identifier
  1. 31 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Format unknown, no data will be returned

NIMLOC: Nimrod locator
  1. 32 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Format unknown, no data will be returned

SRV: Server selection
  1. 33 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Priority (32<16> bits)
  4. Weight (32<16> bits)
  5. Port (32<16> bits)
  6. Target (ASCIIZ hostname)

ATMA: ATM address
  1. 34 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Format unknown, no data will be returned

NAPTR: Naming authority pointer
  1. 35 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Order (32<16> bits)
  4. Preference (32<16> bits)
  5. Flags (ASCIIZ string)
  6. Service (ASCIIZ string)
  7. Regexp (ASCIIZ string)
  8. Replacement (ASCIIZ hostname)

KX: Key exchanger
  1. 36 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Preference (32<16> bits)
  4. Exchanger (ASCIIZ hostname)

CERT: Certificate
  1. 37 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Type (32<16> bits)
  4. Key tag (32<16> bits)
  5. Algorithm (32<8> bits)
  6. Size of Certificate (32<16> bits)
  7. Certificate

A6: A6
  1. 38 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Format unknown, no data will be returned

DNAME: Non-terminate DNS name redirection
  1. 39 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. DName (ASCIIZ hostname)

SINK: Kitchen sink
  1. 40 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Coding (32<8> bits)
  4. Subcoding (32<8> bits)
  5. Size of Data (32<16> bits)
  6. Data

OPT: Option extension mechanisms for DNS
  1. 41 (32 bits)
  2. Owner (ASCIIZ hostname)
  3. Option code (32<16> bits)
  4. Option length (32<16> bits)
  5. Size of Option data (32<16> bits)
  6. Option data
Solutions Services Support Products Home Login Company Contact
Copyright © 1992-2024 Inter-Corporate Computer & Network Services, Inc.  All rights reserved.  All trademarks are the property of their respective owners.  The information provided on this internet site does not constitute a contract with any person or entity unless otherwise specified.  Although reasonable efforts are made to present accurate information, we do not guarantee it.  Information may change without prior notice.