DCHK Client Version 0.5.7 - Documentation |
![]() |
DCHK Implementation. More...
#include <dchk.h>
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_HANDLE * | GetHandle () |
Get Pointer to IRISLWZ_HANDLE. | |
IRISLWZ_PACKET * | GetRequestPacket () |
Get Pointer of Request Packet. | |
IRISLWZ_PACKET * | GetResponsePacket () |
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 |
dchk::CDchk::CDchk | ( | ) |
The constructor initializes the internal structures and sets some defaults.
dchk::CDchk::~CDchk | ( | ) |
The destructor of this class does actually nothing
int dchk::CIrisLWZ::AcceptDeflated | ( | int | flag | ) | [inherited] |
Tell the client if it should accept zlib compressed answers or not
[in] | flag | set to 1, if we accept compressed answers, set to 0 if not |
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.
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.
[in] | handle | Pointer to a IRISLWZ_HANDLE object |
int dchk::CIrisLWZ::Disconnect | ( | ) | [inherited] |
This function destroys the socket to IRISLWZ server.
int dchk::CIrisLWZ::FlagOtherInfo | ( | int | flag | ) | [inherited] |
This function sets the OI-flag for IRISLWZ requests.
[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.
[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.
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.
[in] | buffer | Pointer to the beginning of data, which should be compressed |
[in] | size | Amount of bytes in the buffer |
int dchk::CError::GetErrorCode | ( | ) | const [inherited] |
Return last error code
const char * dchk::CError::GetErrorText | ( | ) | const [inherited] |
Return text of last error code
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.
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.
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.
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.
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.
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.
[in] | flag | set to 1, if we want to ignore invalid XML, set to 0 if not |
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".
[in] | list | Referencer to a CDomainList object |
list
is NULL, otherwise it returns 1.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.
[in] | payload | Request, which should be send to IRIS server |
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.
[in] | payload | Request, which should be send to IRIS server |
[in] | bytes | Size of the payload |
handle
. The request structure is filled, too. In case of an error, 0 will be returned.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
.
[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 |
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.
[in,out] | list | Reference to a CDomainList object |
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
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
[in] | flag | set to 1, if we want to send compressed requests, set to 0 if not |
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.
[in] | authority | Pointer to an authority string. The string must not be longer than 255 octets. |
int dchk::CIrisLWZ::SetAuthorityByDomain | ( | const char * | domain | ) | [inherited] |
This function uses the TLD of the given domain
to set the authority for further requests.
[in] | domain | pointer to a domain name |
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); }
[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 |
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).
[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
[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.
[in] | host | name or IP address of the server which should be used |
[in] | port | port of the server (default=715) |
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".
[in] | tld | pointer to a string with the desired TLD. |
void dchk::CDchk::SetMaxDomainsPerQuery | ( | int | count | ) |
This function sets the maximum number of domains, which can be bundled into one request.
[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.
[in] | bytes | number of bytes |
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.
[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 |
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.
[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.
[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.
[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.
[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.
[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.
[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.
[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 . |
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);
int dchk::CDchk::maxdomainsperquery [private] |