DCHK Client Version 0.5.7 - Documentation DomainCheck

C-API DCHK
[C-API Functions]

API for doing DCHK queries. More...


Detailed Description

The following functions implement the Domain Availability Check (DCHK) Registry Type for the Internet Registry Information Service (IRIS) as described in RFC 5144. It sits on top of the IrisLWZ C-API.

Please see API Usage for more information on using the API.

Functions

int dchk_AddDomain (DCHK_DOMAINLIST *list, const char *domain)
 Add a domain to a domain list.
int dchk_AddnDomain (DCHK_DOMAINLIST *list, const char *domain, int n)
 Add a portion of a string as domain to a domain list.
int dchk_EscapeSpecialChars (const char *string, char *buffer, int buffersize)
 Escape some special characters, which are not allowed in XML.
void dchk_FreeDomainList (DCHK_DOMAINLIST *list)
 Frees a domain list.
DCHK_DOMAINLISTdchk_NewDomainList ()
 Create a new domain list.
int dchk_PrintResults (DCHK_DOMAINLIST *list)
 Print the contents of a DCHK_DOMAINLIST to STDOUT.
int dchk_QueryDomain (IRISLWZ_HANDLE *handle, const char *domain, char **status, char **dbupdate)
 Checks status of a single domain.
int dchk_QueryDomainList (IRISLWZ_HANDLE *handle, DCHK_DOMAINLIST *list, int maxdomainsperquery)
 Checks status of domains in domain list.
int dchk_SetHostByDNS (IRISLWZ_HANDLE *handle, const char *tld)
 Set hostname of DCHK server by using DNS.
int dchk_XML_ParseDomain (IRISLWZ_HANDLE *handle, void *node, DCHK_RECORD *r)
 Parse a domain node.
int dchk_XML_ParseOther (IRISLWZ_HANDLE *handle)
 Parse other information.
int dchk_XML_ParseResult (IRISLWZ_HANDLE *handle, DCHK_DOMAINLIST *domainset)
 Parse DCHK response.
int dchk_XML_ParseSize (IRISLWZ_HANDLE *handle)
 Parse size information.

Function Documentation

int dchk_AddDomain ( DCHK_DOMAINLIST list,
const char *  domain 
)

This function adds a domain name to the list

Parameters:
[in] list pointer to a DCHK_DCHK_DOMAINLIST object, which was created with dchk_NewDomainList
[in] domain pointer to a domain name, which must not be longer than 512 bytes
Returns:
On success, the function returns 1, otherwise 0. An error could only occur, when one of the parameters was NULL, not enough memory is available or the domain name is longer that 512 bytes.
Example:
See dchk_NewDomainList
See also:
Use dchk_NewDomainList to create the list and dchk_FreeDomainList to free the list.
int dchk_AddnDomain ( DCHK_DOMAINLIST list,
const char *  domain,
int  n 
)

This function adds a domain name to the list

Parameters:
[in] list pointer to a DCHK_DCHK_DOMAINLIST object, which was created with dchk_NewDomainList
[in] domain pointer to a domain name, which must not be longer than 512 bytes
[in] n Size of the domain string. Only the first
bytes of the domain string will be copied into the list. If domain is shorter than
, the complete string is copied.
Returns:
On success, the function returns 1, otherwise 0. An error could only occur, when one of the parameters was NULL, not enough memory is available or the domain name is longer that 512 bytes.
Example:
See dchk_NewDomainList
See also:
Use dchk_NewDomainList to create the list and dchk_FreeDomainList to free the list.
int dchk_EscapeSpecialChars ( const char *  string,
char *  buffer,
int  buffersize 
)

This function translates some some special characters, which are not allowed within XML:

  • '&' (ampersand) becomes '&'
  • '"' (double quote) becomes '"'
  • ''' (single quote) becomes '''
  • '<' (less than) becomes '<'
  • '>' (greater than) becomes '>'
Parameters:
[in] string Pointer to a 0-terminated unescaped string
[in,out] buffer Pointer to a result buffer, which must be big enough to receive the escaped string In worst case, this could be 6 times the original string length
[in] buffersize Size of the result buffer
Returns:
On success the function returns 1 and the converted string can be found in buffer. If an error occurs, it returns 0. This could happen, if the buffer is not big enough.
Since:
This function was added in version 0.5.4
void dchk_FreeDomainList ( DCHK_DOMAINLIST list  ) 

This function frees a previously created domain list and all it's contents.

Parameters:
[in] list pointer to a DCHK_DCHK_DOMAINLIST object
Example:
See dchk_NewDomainList
See also:
Use dchk_NewDomainList to create the list and dchk_AddDomain to add domains.
DCHK_DOMAINLIST* dchk_NewDomainList (  ) 

This function creates a new domain list, which is used to check status of multiple domains in bundled requests.

Returns:
On success a pointer to a new DCHK_DOMAINLIST is returned, otherwise NULL. The function could only fail when the process is out of memory.
Example:
    // Create the domain list
    DCHK_DOMAINLIST *list=dchk_NewDomainList();
    // Assume all program parameters are domain names
    int i;
    for (i=1;i<=argc;i++) dchk_AddDomain(list,argv[i]);
    // Do something with the list
    ...
    // Free the domain list
    dchk_FreeDomainList(list);
See also:
Use dchk_FreeDomainList to free the list and dchk_AddDomain to add domains.
int dchk_PrintResults ( DCHK_DOMAINLIST list  ) 

This function prints the contents of a DCHK_DOMAINLIST to STDOUT. If the status of a domain in the list was already checked, it's status and timestamp of last database update is printed, otherwise it prints "unchecked".

Parameters:
[in] list Pointer to a DCHK_DOMAINLIST
Returns:
The function returns 0, if the parameter list is NULL, otherwise it returns 1.
Example:
This is an example output of the function:
denic.de: active [2008-06-10T10:55:00+02:00]
opsblau.de: active [2008-06-10T10:55:00+02:00]
example.de: active [2008-06-10T10:55:00+02:00]
fdefdw3e.de: free
urgs#123.de: invalid
int dchk_QueryDomain ( IRISLWZ_HANDLE handle,
const char *  domain,
char **  status,
char **  dbupdate 
)

This function takes a single domain name and checks it's status against the DCHK server. The result is returned in status and dbupdate.

Parameters:
[in] handle pointer to an IRISLWZ_HANDLE object
[in] domain pointer to the domain name
[out] status pointer to a status variable, where the status of the domain is stored
[out] dbupdate pointer to the last update date of the DCHK database
Returns:
On success, the function returns 1 and status and dbupdate get updated as long as their pointers are not NULL. Please note that you have to free the memory used by status and dbupdate manually! If an error occurred, it returns 0 and the value of status and dbupdate is unchanged.
int dchk_QueryDomainList ( IRISLWZ_HANDLE handle,
DCHK_DOMAINLIST list,
int  maxdomainsperquery 
)

This function takes a list of domains and checks them against the DCHK server. Multiple domains are bundled to one request. If dchk_SetMaxDomainsPerQuery was called, then it will bundle up to the number of domains configured, otherwise it will bundle as many domains as fit into the request payload. For each bundled request it will call DoQuery to do the actual DCHK call. The result for each domain is stored back in the list.

Parameters:
[in] handle pointer to an IRISLWZ_HANDLE object
[in,out] list pointer to DCHK_DOMAINLIST, which was created with dchk_NewDomainList and filled with dchk_AddDomain
[in] maxdomainsperquery maximum number of domains which can be bundled to one request A value of "0" means unlimited.
Returns:
On success, the function returns 1 and the domain list is updated. If an error occurred, it returns 0.
int dchk_SetHostByDNS ( IRISLWZ_HANDLE handle,
const char *  tld 
)

If you don't know the hostname of the DCHK server you can use this function to make a DNS lookup for the specified TLD. The function will query the nameserver for the given TLD and check if there is a NAPTR- and a SRV record for "DCHK1:iris.lwz".

Parameters:
[in] handle pointer to an IRISLWZ_HANDLE object
[in] tld pointer to a string with the desired TLD.
Returns:
If the function can find a suitable DCHK server, the server is automatically configured by calling irislwz_SetHost and the function returns 1 (success). You can use the functions irislwz_GetHostname and irislwz_GetPort to get the results. If no DCHK server can be found or if an error occured, the function will return 0.
Remarks:
This function will only succeed if the registry for the specified TLD has a NAPTR record for "DCHK1:iris.lwz" and a SRV record in it's zonefile.
int dchk_XML_ParseDomain ( IRISLWZ_HANDLE handle,
void *  node,
DCHK_RECORD r 
)

This function is internally called to parse a domain node of an answer section. It searches for status, domainName and lastDatabaseUpdateDateTime and stores the result in the DCHK_RECORD r.

Parameters:
[in] handle pointer to an IRISLWZ_HANDLE object
[in] node pointer to the XML node which should be inspected
[in,out] r pointer to a DCHK_RECORD object, in which the result should be stored.
Returns:
On success the function returns 1, in case of an error it returns 0.
int dchk_XML_ParseOther ( IRISLWZ_HANDLE handle  ) 

This function is internally used to parse an "other information" answer.

Parameters:
[in] handle pointer to an IRISLWZ_HANDLE object
Returns:
Returns 1, if other information could be parsed and sets an appropriate error code (see below), otherwise 0.

The payload of a size information looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<other xmlns="urn:ietf:params:xml:ns:iris-transport" type="payload-error">
  <description language="en">Decoding or parsing of payload failed</description>
</other>

RFC 4993 describes the following types:

  • 'descriptor-error' - indicates there was an error decoding the descriptor. Servers SHOULD send a descriptor error in the following cases:
    1. When a request is received with a payload type indicating size information (i.e., the PT field is 'si').
    2. When a request is received with a payload type indicating other information (i.e., the PT field is 'oi').
    3. When a request is sent with a transaction ID of 0xFFFF (which is reserved for server use).
    4. When a request is received with an incomplete or truncated payload descriptor.
    5. When reserved bits in the payload descriptor are set to values other than zero.
    If this type occurs, this function will raise error 74048.
  • 'payload-error' - indicates there was an error interpreting the payload. Servers MUST send a payload error if they receive XML (i.e., the PT field is set to 'xml') and the XML cannot be parsed. If this type occurs, this function will raise error 74049.
  • 'system-error' - indicates that the receiver cannot process the request due to a condition not related to this protocol. Servers SHOULD send a system-error when they are capable of responding to requests but not capable of processing requests. If this type occurs, this function will raise error 74050.
  • 'authority-error' - indicates that the intended authority specified in the corresponding request is not served by the receiver. Servers SHOULD send an authority error when they receive a request directed to an authority other than those they serve. If this type occurs, this function will raise error 74051.
  • 'no-inflation-support-error' - indicates that the receiver does not support payloads that have been compressed with DEFLATE [1]. Servers MUST send this error when they receive a request that has been compressed with DEFLATE but they do not support inflation. If this type occurs, this function will raise error 74051.
int dchk_XML_ParseResult ( IRISLWZ_HANDLE handle,
DCHK_DOMAINLIST domainset 
)

This function is internally used. It parses the response of a DCHK query and stores various information in the DCHK_DOMAINLIST.

Parameters:
[in] handle pointer to an IRISLWZ_HANDLE object
[in,out] domainset pointer to a DCHK_DOMAINLIST
Returns:
On success, the function returns 1, otherwise 0.
int dchk_XML_ParseSize ( IRISLWZ_HANDLE handle  ) 

This function is internally used to parse a size information answer.

Parameters:
[in] handle pointer to an IRISLWZ_HANDLE object
Returns:
If size information is found in the XML, it's value (octets) is returned, otherwise 0.

The payload of a size information looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<size xmlns="urn:ietf:params:xml:ns:iris-transport">
  <response>
    <octets>371</octets>
  </response>
</size>
Generated on Wed Aug 4 21:23:46 2010 for DCHK Client Documentation by  doxygen 1.6.3