DCHK Client Version 0.5.7 - Documentation DomainCheck

dchk::CDchk Class Reference
[C++-API]

DCHK Implementation. More...

#include <dchk.h>


Detailed Description

This class implements the Domain Availability Check (DCHK) Registry Type for the Internet Registry Information Service (IRIS) as described in RFC 5144. It is derived from the class CIrisLWZ.

In contrast to the CIrisLWZ base class this class enables compression by default.

CIrisLWZ Options



int AcceptDeflated (int flag)
 Accept compressed answers.
int IgnoreInvalidXML (int flag)
 Tell the library to ignore invalid XML.
int SendDeflated (int flag)
 Send compressed requests.
int SetAuthority (const char *authority)
 Sets the authority for IRISLWZ requests.
int SetAuthorityByDomain (const char *domain)
 Sets authority for IRISLWZ requests by using the TLD of a domain.
int SetAuthorityByDomainList (CDomainList &list)
 Sets authority for IRISLWZ requests by using a domain list.
void SetDebugHandler (void(*DebugHandler)(int, const char *, void *), void *privatedata)
 Sets debug handler.
void SetDebugLevel (int level)
 Sets debug level.
int SetMaximumResponseLength (int bytes)
 Sets the maximum acceptable packet size for answer packets.
int SetTimeout (int seconds, int useconds)
 Set timeout for communication with an IRISLWZ server.
int UseRFC1950 (int flag)
 Use RFC 1950 for compression.

Constructures and Destructures



 CDchk ()
 Constructor of the class.
 ~CDchk ()
 Destructor of the class.

CIrisLWZ Checks



int CheckResponse ()
 Check response if it contains size or other information.
const char * GetPayloadType (IRISLWZ_PACKET *p=NULL)
 Returns the name of the payload type.
bool IsDeflated (IRISLWZ_PACKET *p=NULL)
 Check if packet was deflated.
bool IsDeflateSupported (IRISLWZ_PACKET *p=NULL)
 Check if deflate is supported.
bool IsResponse (IRISLWZ_PACKET *p=NULL)
 Check if packet is a response packet.
bool PayloadIsOther (IRISLWZ_PACKET *p=NULL)
 Check if payload is other information.
bool PayloadIsSizeInfo (IRISLWZ_PACKET *p=NULL)
 Check if payload is size information.
bool PayloadIsVersion (IRISLWZ_PACKET *p=NULL)
 Check if payload is version information.
bool PayloadIsXML (IRISLWZ_PACKET *p=NULL)
 Check if payload is XML.

CIrisLWZ Connection



int Connect ()
 Creates an UDP socket to an IRISLWZ server.
int Disconnect ()
 Destroys socket to IRISLWZ server.
const char * GetHostname ()
 Returns pointer to the hostname of a previous set server.
int GetPort ()
 Returns port of a previous set server.
int SetHost (const char *host, int port=715)
 Set hostname an port of an IRISLWZ server.

Error functions



void CopyError (IRISLWZ_HANDLE *handle)
 Copies an error from an IRISLWZ_HANDLE into this class.
const char * GetAdditionalErrorText () const
 Return additional information about last error.
int GetErrorCode () const
 Return last error code.
const char * GetErrorText () const
 Return text of last error code.
void PrintError () const
 Print last error to STDOUT.
void SetError (int code, const char *fmt=NULL,...)
 Set an error on this class.

CIrisLWZ Testing Options



int FlagOtherInfo (int flag)
 Set OI-Flag.
int FlagSizeInfo (int flag)
 Set SI-Flag.
int TestCleanup ()
 Disable all special test options.
int TestCorruptCompression (int flag)
 Corrupt compressed request packets.
int TestSetAuthorityLength (int length)
 Override value for authority length.
int TestSetHeader (int header)
 Override header byte in LWZ header.
int TestSetTransactionId (int tid)
 Override random transaction id.
int TestSetVersion (int version)
 Override LWZ version.
int TestTruncatePacket (int bytes)
 Truncate the request packet.

CIrisLWZ Tools



int GetCompressedSize (const char *buffer, int size)
 Calculate the zlib compressed size of a buffer.
int Validate (const char *xml, char **beautified)
 Do an XML validation against a text.

CIrisLWZ Queries



IRISLWZ_HANDLEGetHandle ()
 Get Pointer to IRISLWZ_HANDLE.
IRISLWZ_PACKETGetRequestPacket ()
 Get Pointer of Request Packet.
IRISLWZ_PACKETGetResponsePacket ()
 Get Pointer of Response Packet.
int Query (const char *payload)
 Send a request to an IRISLWZ server.
int Query2 (const char *payload, int bytes)
 Send a request to an IRISLWZ server.
int QueryVersion ()
 Send a version request to the server.

CDchk Queries



int PrintResults (CDomainList &list)
 Print the contents of a DCHK_DOMAINLIST to STDOUT.
int QueryDomain (const char *domain, char **status, char **dbupdate)
 Checks status of a single domain.
int QueryDomainList (CDomainList &list)
 Checks status of domains in domain list.

CDchk Options



int SetHostByDNS (const char *tld)
 Set hostname of DCHK server by using DNS.
void SetMaxDomainsPerQuery (int count)
 Sets the maximum number of domains per query.

Private Attributes

int maxdomainsperquery

Constructor & Destructor Documentation

dchk::CDchk::CDchk (  ) 

The constructor initializes the internal structures and sets some defaults.

dchk::CDchk::~CDchk (  ) 

The destructor of this class does actually nothing


Member Function Documentation

int dchk::CIrisLWZ::AcceptDeflated ( int  flag  )  [inherited]

Tell the client if it should accept zlib compressed answers or not

Parameters:
[in] flag set to 1, if we accept compressed answers, set to 0 if not
Returns:
Always returns 1.
int dchk::CIrisLWZ::Connect (  )  [inherited]

This function creates an UDP socket to an IRISLWZ server. As UDP is a connection less protocol, there is no connection made to the server, but the hostname gets resolved and the TCP stack checks, if the destination host is reachable.

Returns:
On success, this function returns 1, on error 0.
void dchk::CError::CopyError ( IRISLWZ_HANDLE handle  )  [inherited]

This function is used internally to copy an error from an IRISLWZ_HANDLE object into this class.

Parameters:
[in] handle Pointer to a IRISLWZ_HANDLE object
int dchk::CIrisLWZ::Disconnect (  )  [inherited]

This function destroys the socket to IRISLWZ server.

Returns:
On success, this function returns 1, on error 0.
int dchk::CIrisLWZ::FlagOtherInfo ( int  flag  )  [inherited]

This function sets the OI-flag for IRISLWZ requests.

Parameters:
[in] flag Should be "1" to set the flag or "0" to unset it.
int dchk::CIrisLWZ::FlagSizeInfo ( int  flag  )  [inherited]

This function sets the SI-flag for IRISLWZ requests.

Parameters:
[in] flag Should be "1" to set the flag or "0" to unset it.
const char * dchk::CError::GetAdditionalErrorText (  )  const [inherited]

Return additional information about last error.

Returns:
Pointer to the additional error text, or NULL if there is no text.
int dchk::CIrisLWZ::GetCompressedSize ( const char *  buffer,
int  size 
) [inherited]

This function compresses the given buffer with zlib and returns the required amount of Bytes. It is used internally by some functions, but can be used externally, too.

Parameters:
[in] buffer Pointer to the beginning of data, which should be compressed
[in] size Amount of bytes in the buffer
Returns:
On success, this function returns the amount of bytes needed to compress the data, otherwise it will return 0.
int dchk::CError::GetErrorCode (  )  const [inherited]

Return last error code

Returns:
last error code
Remarks:
Please keep in mind that a non zero value does not necessarily mean that the previous function was not successful. If a function returns a value, you should always check if it is valid or indicates an error. Most functions return 0 or NULL when an error occurred, and only if this is the case, you will get the correct error.
const char * dchk::CError::GetErrorText (  )  const [inherited]

Return text of last error code

Returns:
Pointer to the error text.
IRISLWZ_HANDLE * dchk::CIrisLWZ::GetHandle (  )  [inherited]

This function returns a pointer to the IRISLWZ_HANDLE. You can use it to directly call the low level C-API Functions [C-API] functions or read informations from it.

Returns:
Pointer to the IRISLWZ_HANDLE used by this class.
const char * dchk::CIrisLWZ::GetHostname (  )  [inherited]

This function returns a pointer to the previous set hostname. This could have been done by explicit calling the CIrisLWZ::SetHost function or automatically by calling CDchk::SetHostByDNS.

Returns:
Returns a pointer to the hostname or NULL, if the hostname was not set yet.
int dchk::CIrisLWZ::GetPort (  )  [inherited]

This function returns the port of a previous set IRISLWZ server. This could have been done by explicit calling the CIrisLWZ::SetHost function or automatically by calling CDchk::SetHostByDNS.

Returns:
Returns port of server or 0 if no server was set, yet.
IRISLWZ_PACKET * dchk::CIrisLWZ::GetRequestPacket (  )  [inherited]

This function returns a IRISLWZ_PACKET pointer to the request packet. It's contents are only valid, if a request was send before.

Returns:
Pointer to an IRISLWZ_PACKET
IRISLWZ_PACKET * dchk::CIrisLWZ::GetResponsePacket (  )  [inherited]

This function returns a IRISLWZ_PACKET pointer to the response packet. It's contents are only valid, if a request was send before.

Returns:
Pointer to an IRISLWZ_PACKET
int dchk::CIrisLWZ::IgnoreInvalidXML ( int  flag  )  [inherited]

Normally the client would stop and raise a validation error if the request payload contains invalid XML. With this function you can disable this check, so it is possible to test how the server reacts to an invalid XML request.

Parameters:
[in] flag set to 1, if we want to ignore invalid XML, set to 0 if not
Returns:
Always returns 1.
void dchk::CError::PrintError (  )  const [inherited]

This function prints the last error occurred in this class to STDOUT (Screen).

int dchk::CDchk::PrintResults ( CDomainList 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 Referencer to a CDomainList object
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::CIrisLWZ::Query ( const char *  payload  )  [inherited]

This function is used to send a request to an IRISLWZ server and wait for response.

Parameters:
[in] payload Request, which should be send to IRIS server
Returns:
On success, this function returns 1 and the response is saved in the response structure of handle. The request structure is filled, too. In case of an error, 0 will be returned.
int dchk::CIrisLWZ::Query2 ( const char *  payload,
int  bytes 
) [inherited]

This function is used to send a request to an IRISLWZ server and wait for response. In addition to CIrisLWZ::Query, this function needs a second parameter indicating the size of the payload.

Parameters:
[in] payload Request, which should be send to IRIS server
[in] bytes Size of the payload
Returns:
On success, this function returns 1 and the response is saved in the response structure of handle. The request structure is filled, too. In case of an error, 0 will be returned.
Since:
Version 0.5.4
int dchk::CDchk::QueryDomain ( 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] 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::CDchk::QueryDomainList ( CDomainList list  ) 

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,out] list Reference to a CDomainList object
Returns:
On success, the function returns 1 and the domain list is updated. If an error occurred, it returns 0.
int dchk::CIrisLWZ::QueryVersion (  )  [inherited]

This function sends a version request to the server

Returns:
On success, this function returns 1, on error 0.

To query the version, the Version-Bit is set in the IRISLWZ_HEADER. The server itself answers with a version information in the payload, which looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<versions xmlns="urn:ietf:params:xml:ns:iris-transport">
  <transferProtocol protocolId="iris.lwz">
    <application protocolId="urn:ietf:params:xml:ns:iris1">
      <dataModel protocolId="urn:ietf:params:xml:ns:dchk1"/>
    </application>
  </transferProtocol>
</versions>
int dchk::CIrisLWZ::SendDeflated ( int  flag  )  [inherited]

Tell the client if it should send zlib compressed requests or not

Parameters:
[in] flag set to 1, if we want to send compressed requests, set to 0 if not
Returns:
Always returns 1.
int dchk::CIrisLWZ::SetAuthority ( const char *  authority  )  [inherited]

With this function you can define the authority which is used in IRISLWZ request packets. The default is not to use an authority.

Parameters:
[in] authority Pointer to an authority string. The string must not be longer than 255 octets.
Returns:
Returns 1 on success or 0 when an error occurred.
int dchk::CIrisLWZ::SetAuthorityByDomain ( const char *  domain  )  [inherited]

This function uses the TLD of the given domain to set the authority for further requests.

Parameters:
[in] domain pointer to a domain name
Returns:
Returns 1 on success or 0 when an error occurred.
Note:
If the TLD is set to "arpa", a special handling takes place. At the moment the library only checks if the domain ends with "9.4.e164.arpa" (german ENUM domains). If this is the case "9.4.e164.arpa" is used as authority name. Other arpa zones are not implemented.
void dchk::CIrisLWZ::SetDebugHandler ( void(*)(int, const char *, void *)  DebugHandler,
void *  privatedata 
) [inherited]

If you set a debug level higher than 0, you will get debug output on STDOUT. If you want the output somewhere else, you can specify a debug handler or callback function. The function must have the following syntax:

 void debughandler(int level, const char *text, void *privatedata)
 {
    // Do something, e.g. printf("%s\n",text);
 }
Parameters:
[in] DebugHandler Pointer to the function that will receive the debug output
[in] privatedata Pointer to some optional data, which is passed to the callback function
See also:
irislwz_SetDebugLevel
void dchk::CIrisLWZ::SetDebugLevel ( int  level  )  [inherited]

This functions sets the debug level for debug output. By default the library does not output any debug (level=0). The higher the level, the more output you will get. You can specify a debug handler if you want the output anywhere else than STDOUT (see irislwz_SetDebugHandler).

Parameters:
[in] level debug level. 0=no debug
void dchk::CError::SetError ( int  code,
const char *  fmt = NULL,
  ... 
) [inherited]

This function is used internally to store an error in this class

Parameters:
[in] code Error code
[in] fmt Format string for an additional error text. The syntax of this string is identical to sprintf/printf.
[in] ... Optional additional parameters for the format string
int dchk::CIrisLWZ::SetHost ( const char *  host,
int  port = 715 
) [inherited]

With this function you can specify hostname or IP address and port of IRISLWZ server manually. If you don't know the hostname, you can use the function CDchk::SetHostByDNS and let the DCHK library find out the server name by using DNS.

Parameters:
[in] host name or IP address of the server which should be used
[in] port port of the server (default=715)
Returns:
Returns 1 on success or 0 when an error occurred.
int dchk::CDchk::SetHostByDNS ( 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 name server for the given TLD and check if there is a NAPTR- and a SRV record for "DCHK1:iris.lwz".

Parameters:
[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 CDchk::SetHost and the function returns 1 (success). You can use the functions CDchk::GetHostname and CDchk::GetPort to get the results. If no DCHK server can be found or if an error occurred, 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.
void dchk::CDchk::SetMaxDomainsPerQuery ( int  count  ) 

This function sets the maximum number of domains, which can be bundled into one request.

Parameters:
[in] count Number of domains. A value of "0" means unlimited.
int dchk::CIrisLWZ::SetMaximumResponseLength ( int  bytes  )  [inherited]

By default the client accepts a maximum packet size of 1500 octets (Bytes), which is the recommend size by the Lightweight UDP Transfer Protocol RFC, when the path MTU is unknown. With this function you can set any other size.

Parameters:
[in] bytes number of bytes
Returns:
Always returns 1 (success).
Remarks:
Please keep in mind, that even if you specify a bigger packet size, the DCHK server will not exceed 4000 octets. If the answer does not fit into the answer packet, the server will send a "size information".
int dchk::CIrisLWZ::SetTimeout ( int  seconds,
int  useconds 
) [inherited]

With this function you can set a timeout for the communication with a server. After sending a request packet to the server the client has to wait for the response. As UDP is an unreliable protocol the client can not detect if the request packet reached it's destination. It is also possible, that the answer packet got lost. By default the library has a timeout of 5 seconds.

With this function you can define a shorter timeout.

Parameters:
[in] seconds Number of seconds. If you pass 0 seconds, the library uses no timeout. If no response arrives, the library blocks until the operating system issues a timeout, which could be several minutes.
[in] useconds Number of microseconds
Returns:
Always returns 1
int dchk::CIrisLWZ::TestCleanup (  )  [inherited]

By calling this function all special test options get disabled.

int dchk::CIrisLWZ::TestCorruptCompression ( int  flag  )  [inherited]

When calling this function, a compressed request packet will be corrupted by changing some values of the compressed stream with random values. It is meant for testing purposes only.

Parameters:
[in] flag 1=enable or 0=disable
int dchk::CIrisLWZ::TestSetAuthorityLength ( int  bytes  )  [inherited]

With this function you can override the value for authority length in the LWZ header, to corrupt the request. It is meant for testing purposes only.

Parameters:
[in] bytes A value between 0 and 255
int dchk::CIrisLWZ::TestSetHeader ( int  header  )  [inherited]

With this function you can completely override the header-byte in the LWZ header. It is meant for testing purposes only.

Parameters:
[in] header A value between 0 and 255
int dchk::CIrisLWZ::TestSetTransactionId ( int  tid  )  [inherited]

With this function you can override the default random transaction id in the LWZ header. It is meant for testing purposes only.

Parameters:
[in] tid A value between 0 and 65535
int dchk::CIrisLWZ::TestSetVersion ( int  version  )  [inherited]

With this function you can override the version bits in the LWZ header. It is meant for testing purposes only.

Parameters:
[in] version Should be a value between 0 and 3.
int dchk::CIrisLWZ::TestTruncatePacket ( int  bytes  )  [inherited]

With this function you can truncate the request packet at any position, to corrupt the request. It is meant for testing purposes only.

Parameters:
[in] bytes A value between 0 and 65535
int dchk::CIrisLWZ::Validate ( const char *  xml,
char **  beautified 
) [inherited]

This function takes the given xml test an tries to validate it with the XML library (xmlReadMemory). If the XML is valid, a beautified version, which can be better read by humans, can be stored optionally.

Parameters:
[in] xml pointer to the text which should be validated
[out] beautified optional pointer to which a beautified version of the xml is written. The Memory for this is allocated by the library, but must be freed by the client using free.
Returns:
If the XML is valid, the function returns 1, otherwise 0.
Example:
const char *xml="<iris1:request xmlns:iris1=\"urn:ietf:params:xml:ns:iris1\">"
        "<iris1:searchSet><iris1:lookupEntity registryType=\"dchk1\" "
        "entityClass=\"domain-name\" entityName=\"denic.de\"/>"
        "</iris1:searchSet></iris1:request>";
char *beautified=NULL;
CIrisLWZ iris;
if (iris.Validate(xml,&beautified)) {
    printf ("Original XML code:\n");
    printf ("%s\n",xml);
    printf ("Beautified version:\n");
    printf ("%s\n",beautified);
}
if (beautified) free(beautified);

Field Documentation


The documentation for this class was generated from the following files:
Generated on Wed Aug 4 21:23:46 2010 for DCHK Client Documentation by  doxygen 1.6.3