DCHK Client Version 0.5.7 - Documentation DomainCheck

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

Implementation of Lightweight UDP Transfer Protocol for the Internet Registry Information Service. More...

#include <dchk.h>


Detailed Description

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_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.

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

Constructor & Destructor Documentation

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.


Member Function Documentation

int dchk::CIrisLWZ::AcceptDeflated ( int  flag  ) 

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 (  ) 

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 (  ) 

This function destroys the socket to IRISLWZ server.

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

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  ) 

This function sets the SI-flag for IRISLWZ requests.

Parameters:
[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.

Parameters:
[in] p Pointer to an IRISLWZ_PACKET
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 
)

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 (  ) 

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 (  ) 

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 (  ) 

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 (  ) 

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 (  ) 

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  ) 

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.
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.

Returns:
On success, this function returns 1, on error 0.
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.

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 
)

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::CIrisLWZ::QueryVersion (  ) 

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  ) 

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  ) 

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  ) 

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 
)

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  ) 

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 
)

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::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.

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 
)

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::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.

Parameters:
[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
Returns:
On success, this function returns 1, on error 0.
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.

Parameters:
[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.

Parameters:
[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.

Parameters:
[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.

Parameters:
[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.

Parameters:
[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.

Parameters:
[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.

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);

Friends And Related Function Documentation

friend class CDchk [friend]

Field Documentation

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()

See also:
IRISLWZ_HANDLE

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