<!-- - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 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 ISC DISCLAIMS ALL WARRANTIES WITH - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY - AND FITNESS. IN NO EVENT SHALL ISC 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. --> <!-- $Id: lwres_resutil.html,v 1.8.2.1.4.2 2004/08/22 23:39:05 marka Exp $ --> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML ><HEAD ><TITLE >lwres_resutil</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD ><BODY CLASS="REFENTRY" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><H1 ><A NAME="AEN1" ></A >lwres_resutil</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" ><P ></P ><A NAME="AEN15" ></A ><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 ><CODE CLASS="FUNCTION" >lwres_string_parse()</CODE > retrieves a DNS-encoded string starting the current pointer of lightweight resolver buffer <VAR CLASS="PARAMETER" >b</VAR >: i.e. <CODE CLASS="CONSTANT" >b->current</CODE >. When the function returns, the address of the first byte of the encoded string is returned via <VAR CLASS="PARAMETER" >*c</VAR > and the length of that string is given by <VAR CLASS="PARAMETER" >*len</VAR >. 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 ><CODE CLASS="FUNCTION" >lwres_addr_parse()</CODE > extracts an address from the buffer <VAR CLASS="PARAMETER" >b</VAR >. The buffer's current pointer <CODE CLASS="CONSTANT" >b->current</CODE > 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 <CODE CLASS="CONSTANT" >addr->address</CODE > and <CODE CLASS="CONSTANT" >addr->length</CODE > indicates the size in bytes of the address that was copied. <CODE CLASS="CONSTANT" >b->current</CODE > is advanced to point at the next byte of available data in the buffer following the encoded address.</P ><P ><CODE CLASS="FUNCTION" >lwres_getaddrsbyname()</CODE > and <CODE CLASS="FUNCTION" >lwres_getnamebyaddr()</CODE > 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 <CODE CLASS="FUNCTION" >lwres_getaddrsbyname()</CODE > to perform foward lookups. Hostname <VAR CLASS="PARAMETER" >name</VAR > is looked up using the resolver context <VAR CLASS="PARAMETER" >ctx</VAR > for memory allocation. <VAR CLASS="PARAMETER" >addrtypes</VAR > 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 <VAR CLASS="PARAMETER" >*structp</VAR >.</P ><P ><CODE CLASS="FUNCTION" >lwres_getnamebyaddr()</CODE > performs reverse lookups. Resolver context <VAR CLASS="PARAMETER" >ctx</VAR > is used for memory allocation. The address type is indicated by <VAR CLASS="PARAMETER" >addrtype</VAR >: <SPAN CLASS="TYPE" >LWRES_ADDRTYPE_V4</SPAN > or <SPAN CLASS="TYPE" >LWRES_ADDRTYPE_V6</SPAN >. The address to be looked up is given by <VAR CLASS="PARAMETER" >addr</VAR > and its length is <VAR CLASS="PARAMETER" >addrlen</VAR > bytes. The result of the function call is made available through <VAR CLASS="PARAMETER" >*structp</VAR >.</P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN84" ></A ><H2 >RETURN VALUES</H2 ><P >Successful calls to <CODE CLASS="FUNCTION" >lwres_string_parse()</CODE > and <CODE CLASS="FUNCTION" >lwres_addr_parse()</CODE > 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 ><CODE CLASS="FUNCTION" >lwres_getaddrsbyname()</CODE > returns <SPAN CLASS="ERRORCODE" >LWRES_R_SUCCESS</SPAN > on success and it returns <SPAN CLASS="ERRORCODE" >LWRES_R_NOTFOUND</SPAN > if the hostname <VAR CLASS="PARAMETER" >name</VAR > could not be found.</P ><P ><SPAN CLASS="ERRORCODE" >LWRES_R_SUCCESS</SPAN > is returned by a successful call to <CODE CLASS="FUNCTION" >lwres_getnamebyaddr()</CODE >.</P ><P >Both <CODE CLASS="FUNCTION" >lwres_getaddrsbyname()</CODE > and <CODE CLASS="FUNCTION" >lwres_getnamebyaddr()</CODE > 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 >