DCHK Client Version 0.5.7 - Documentation |
![]() |
Implementation of Lightweight UDP Transfer Protocol for the Internet Registry Information Service. More...
#include <dchk.h>
This class implements a Lightweight UDP Transfer Protocol for the Internet Registry Information Service. (see RFC 4993: http://tools.ietf.org/html/rfc4993)
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. | |
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. | |
Constructures and Destructures | |
| |
CIrisLWZ () | |
Constructor of the class. | |
~CIrisLWZ () | |
Destructor of the class. | |
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. | |
Private Member Functions | |
void | FreePacket (IRISLWZ_PACKET *p) |
Frees the memory used by an IRISLWZ_PACKET. | |
int | PrepareQuery () |
Prepare IRISLWZ Header for next query. | |
int | Talk (IRISLWZ_PACKET *request, IRISLWZ_PACKET *response) |
Talk with an IRISLWZ server. | |
Private Attributes | |
IRISLWZ_HANDLE | handle |
Basic data structure for underlying C-API. | |
Friends | |
class | CDchk |
dchk::CIrisLWZ::CIrisLWZ | ( | ) |
The constructor initializes the internal structures and sets some defaults.
dchk::CIrisLWZ::~CIrisLWZ | ( | ) |
The destructor frees all memory used by this class.
int dchk::CIrisLWZ::AcceptDeflated | ( | int | flag | ) |
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 | ( | ) |
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 | ( | ) |
This function destroys the socket to IRISLWZ server.
int dchk::CIrisLWZ::FlagOtherInfo | ( | int | flag | ) |
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 | ) |
This function sets the SI-flag for IRISLWZ requests.
[in] | flag | Should be "1" to set the flag or "0" to unset it. |
void dchk::CIrisLWZ::FreePacket | ( | IRISLWZ_PACKET * | p | ) | [private] |
This function frees the memory allocated within an IRISLWZ_PACKET object. The object itself is not freed.
[in] | p | Pointer to an IRISLWZ_PACKET |
const char * dchk::CError::GetAdditionalErrorText | ( | ) | const [inherited] |
Return additional information about last error.
int dchk::CIrisLWZ::GetCompressedSize | ( | const char * | buffer, | |
int | size | |||
) |
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 | ( | ) |
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 | ( | ) |
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 | ( | ) |
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 | ( | ) |
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 | ( | ) |
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 | ) |
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 |
int dchk::CIrisLWZ::PrepareQuery | ( | ) | [private] |
This function initializes the IRISLWZ header in the request structure of the IRISLWZ_HANDLE. It uses the data and flags of the IRISLWZ_HANDLE object and sets the values and bits in the IRISLWZ_HEADER. The packet and header pointer must have been already allocated with enough space to hold the 6 byte header and the authority name.
void dchk::CError::PrintError | ( | ) | const [inherited] |
This function prints the last error occurred in this class to STDOUT (Screen).
int dchk::CIrisLWZ::Query | ( | const char * | payload | ) |
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 | |||
) |
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::CIrisLWZ::QueryVersion | ( | ) |
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 | ) |
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 | ) |
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 | ) |
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 | |||
) |
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 | ) |
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 | |||
) |
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::CIrisLWZ::SetMaximumResponseLength | ( | int | bytes | ) |
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 | |||
) |
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::Talk | ( | IRISLWZ_PACKET * | request, | |
IRISLWZ_PACKET * | response | |||
) | [private] |
This function is used for communication with an IRISLWZ-server. The server must be connected previously with irislwz_Connect.
[in] | request | pointer to an IRISLWZ_PACKET object, which holds the request |
[out] | response | pointer to an IRISLWZ_PACKET object, in which the answer is stored |
int dchk::CIrisLWZ::TestCleanup | ( | ) |
By calling this function all special test options get disabled.
int dchk::CIrisLWZ::TestCorruptCompression | ( | int | flag | ) |
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 | ) |
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 | ) |
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 | ) |
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 | ) |
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 | ) |
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 | |||
) |
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);
friend class CDchk [friend] |
dchk::CIrisLWZ::handle [private] |
Basic data type for all DCHK C-API functions. It is automatically initialized by the constructor of this class an deinitialized by it's destructor. You can get a pointer on this structure by calling CIrisLWZ::GetHandle()