<!-- - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any - purpose with or without fee is hereby granted, provided that the above - copyright notice and this permission notice appear in all copies. - - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. --> <HTML ><HEAD ><TITLE >lwres_resutil</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.73 "></HEAD ><BODY CLASS="REFENTRY" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><H1 ><A NAME="AEN1" >lwres_resutil</A ></H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN8" ></A ><H2 >Name</H2 >lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr -- lightweight resolver utility functions</DIV ><DIV CLASS="REFSYNOPSISDIV" ><A NAME="AEN14" ></A ><H2 >Synopsis</H2 ><DIV CLASS="FUNCSYNOPSIS" ><A NAME="AEN15" ></A ><P ></P ><PRE CLASS="FUNCSYNOPSISINFO" >#include <lwres/lwres.h></PRE ><P ><CODE ><CODE CLASS="FUNCDEF" >lwres_result_t lwres_string_parse</CODE >(lwres_buffer_t *b, char **c, lwres_uint16_t *len);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >lwres_result_t lwres_addr_parse</CODE >(lwres_buffer_t *b, lwres_addr_t *addr);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >lwres_result_t lwres_getaddrsbyname</CODE >(lwres_context_t *ctx, const char *name, lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >lwres_result_t lwres_getnamebyaddr</CODE >(lwres_context_t *ctx, lwres_uint32_t addrtype, lwres_uint16_t addrlen, const unsigned char *addr, lwres_gnbaresponse_t **structp);</CODE ></P ><P ></P ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN43" ></A ><H2 >DESCRIPTION</H2 ><P ><TT CLASS="FUNCTION" >lwres_string_parse()</TT > retrieves a DNS-encoded string starting the current pointer of lightweight resolver buffer <TT CLASS="PARAMETER" ><I >b</I ></TT >: i.e. <TT CLASS="CONSTANT" >b->current</TT >. When the function returns, the address of the first byte of the encoded string is returned via <TT CLASS="PARAMETER" ><I >*c</I ></TT > and the length of that string is given by <TT CLASS="PARAMETER" ><I >*len</I ></TT >. The buffer's current pointer is advanced to point at the character following the string length, the encoded string, and the trailing <SPAN CLASS="TYPE" >NULL</SPAN > character.</P ><P ><TT CLASS="FUNCTION" >lwres_addr_parse()</TT > extracts an address from the buffer <TT CLASS="PARAMETER" ><I >b</I ></TT >. The buffer's current pointer <TT CLASS="CONSTANT" >b->current</TT > is presumed to point at an encoded address: the address preceded by a 32-bit protocol family identifier and a 16-bit length field. The encoded address is copied to <TT CLASS="CONSTANT" >addr->address</TT > and <TT CLASS="CONSTANT" >addr->length</TT > indicates the size in bytes of the address that was copied. <TT CLASS="CONSTANT" >b->current</TT > is advanced to point at the next byte of available data in the buffer following the encoded address.</P ><P ><TT CLASS="FUNCTION" >lwres_getaddrsbyname()</TT > and <TT CLASS="FUNCTION" >lwres_getnamebyaddr()</TT > use the <SPAN CLASS="TYPE" >lwres_gnbaresponse_t</SPAN > structure defined below: <PRE CLASS="PROGRAMLISTING" >typedef struct { lwres_uint32_t flags; lwres_uint16_t naliases; lwres_uint16_t naddrs; char *realname; char **aliases; lwres_uint16_t realnamelen; lwres_uint16_t *aliaslen; lwres_addrlist_t addrs; void *base; size_t baselen; } lwres_gabnresponse_t;</PRE > The contents of this structure are not manipulated directly but they are controlled through the <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >lwres_gabn</SPAN >(3)</SPAN > functions.</P ><P >The lightweight resolver uses <TT CLASS="FUNCTION" >lwres_getaddrsbyname()</TT > to perform foward lookups. Hostname <TT CLASS="PARAMETER" ><I >name</I ></TT > is looked up using the resolver context <TT CLASS="PARAMETER" ><I >ctx</I ></TT > for memory allocation. <TT CLASS="PARAMETER" ><I >addrtypes</I ></TT > is a bitmask indicating which type of addresses are to be looked up. Current values for this bitmask are <SPAN CLASS="TYPE" >LWRES_ADDRTYPE_V4</SPAN > for IPv4 addresses and <SPAN CLASS="TYPE" >LWRES_ADDRTYPE_V6</SPAN > for IPv6 addresses. Results of the lookup are returned in <TT CLASS="PARAMETER" ><I >*structp</I ></TT >.</P ><P ><TT CLASS="FUNCTION" >lwres_getnamebyaddr()</TT > performs reverse lookups. Resolver context <TT CLASS="PARAMETER" ><I >ctx</I ></TT > is used for memory allocation. The address type is indicated by <TT CLASS="PARAMETER" ><I >addrtype</I ></TT >: <SPAN CLASS="TYPE" >LWRES_ADDRTYPE_V4</SPAN > or <SPAN CLASS="TYPE" >LWRES_ADDRTYPE_V6</SPAN >. The address to be looked up is given by <TT CLASS="PARAMETER" ><I >addr</I ></TT > and its length is <TT CLASS="PARAMETER" ><I >addrlen</I ></TT > bytes. The result of the function call is made available through <TT CLASS="PARAMETER" ><I >*structp</I ></TT >.</P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN84" ></A ><H2 >RETURN VALUES</H2 ><P >Successful calls to <TT CLASS="FUNCTION" >lwres_string_parse()</TT > and <TT CLASS="FUNCTION" >lwres_addr_parse()</TT > return <SPAN CLASS="ERRORCODE" >LWRES_R_SUCCESS.</SPAN > Both functions return <SPAN CLASS="ERRORCODE" >LWRES_R_FAILURE</SPAN > if the buffer is corrupt or <SPAN CLASS="ERRORCODE" >LWRES_R_UNEXPECTEDEND</SPAN > if the buffer has less space than expected for the components of the encoded string or address.</P ><P ><TT CLASS="FUNCTION" >lwres_getaddrsbyname()</TT > returns <SPAN CLASS="ERRORCODE" >LWRES_R_SUCCESS</SPAN > on success and it returns <SPAN CLASS="ERRORCODE" >LWRES_R_NOTFOUND</SPAN > if the hostname <TT CLASS="PARAMETER" ><I >name</I ></TT > could not be found.</P ><P ><SPAN CLASS="ERRORCODE" >LWRES_R_SUCCESS</SPAN > is returned by a successful call to <TT CLASS="FUNCTION" >lwres_getnamebyaddr()</TT >.</P ><P >Both <TT CLASS="FUNCTION" >lwres_getaddrsbyname()</TT > and <TT CLASS="FUNCTION" >lwres_getnamebyaddr()</TT > return <SPAN CLASS="ERRORCODE" >LWRES_R_NOMEMORY</SPAN > when memory allocation requests fail and <SPAN CLASS="ERRORCODE" >LWRES_R_UNEXPECTEDEND</SPAN > if the buffers used for sending queries and receiving replies are too small.</P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN105" ></A ><H2 >SEE ALSO</H2 ><P ><SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >lwres_buffer</SPAN >(3)</SPAN >, <SPAN CLASS="CITEREFENTRY" ><SPAN CLASS="REFENTRYTITLE" >lwres_gabn</SPAN >(3)</SPAN >.</P ></DIV ></BODY ></HTML >