DCHK Client Version 0.5.7 - Documentation
|
|
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_DOMAINLIST * | dchk_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
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.
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
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.
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:
- See also:
- Use dchk_FreeDomainList to free the list and dchk_AddDomain to add domains.
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:
-
- 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.
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.
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.
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.
This function is internally used to parse an "other information" answer.
- Parameters:
-
- 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:
-
When a request is received with a payload type indicating size information (i.e., the PT field is 'si').
-
When a request is received with a payload type indicating other information (i.e., the PT field is 'oi').
-
When a request is sent with a transaction ID of 0xFFFF (which is reserved for server use).
-
When a request is received with an incomplete or truncated payload descriptor.
-
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.
This function is internally used. It parses the response of a DCHK query and stores various information in the DCHK_DOMAINLIST.
- Parameters:
-
- Returns:
- On success, the function returns 1, otherwise 0.
This function is internally used to parse a size information answer.
- Parameters:
-
- 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>