lwres_resutil.html revision 841179549b6433e782c164a562eb3422f603533d
10139N/A<!--
10139N/A - Copyright (C) 2000, 2001 Internet Software Consortium.
10139N/A -
10139N/A - Permission to use, copy, modify, and distribute this software for any
10139N/A - purpose with or without fee is hereby granted, provided that the above
10139N/A - copyright notice and this permission notice appear in all copies.
10139N/A -
10139N/A - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
10139N/A - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
10139N/A - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
10139N/A - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
10139N/A - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
11922N/A - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
10139N/A - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
10139N/A - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
10139N/A-->
10139N/A
11819N/A<!-- $Id: lwres_resutil.html,v 1.5 2001/06/08 19:33:02 gson Exp $ -->
10139N/A
10139N/A<HTML
10139N/A><HEAD
10139N/A><TITLE
10139N/A>lwres_resutil</TITLE
10139N/A><META
10139N/ANAME="GENERATOR"
10139N/ACONTENT="Modular DocBook HTML Stylesheet Version 1.61
10139N/A"></HEAD
10139N/A><BODY
10139N/ACLASS="REFENTRY"
10139N/ABGCOLOR="#FFFFFF"
10139N/ATEXT="#000000"
10139N/ALINK="#0000FF"
10139N/AVLINK="#840084"
10139N/AALINK="#0000FF"
10139N/A><H1
10139N/A><A
10139N/ANAME="AEN1"
10139N/A>lwres_resutil</A
10139N/A></H1
10139N/A><DIV
10139N/ACLASS="REFNAMEDIV"
10139N/A><A
10139N/ANAME="AEN8"
10139N/A></A
10139N/A><H2
10139N/A>Name</H2
10139N/A>lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr&nbsp;--&nbsp;lightweight resolver utility functions</DIV
10139N/A><DIV
10139N/ACLASS="REFSYNOPSISDIV"
10139N/A><A
10139N/ANAME="AEN14"
10139N/A></A
10139N/A><H2
10139N/A>Synopsis</H2
10139N/A><DIV
10139N/ACLASS="FUNCSYNOPSIS"
10778N/A><A
10778N/ANAME="AEN15"
10139N/A></A
10139N/A><P
10139N/A></P
10139N/A><PRE
10139N/ACLASS="FUNCSYNOPSISINFO"
10139N/A>#include &lt;lwres/lwres.h&gt;</PRE
10139N/A><P
10139N/A><CODE
10139N/A><CODE
11370N/ACLASS="FUNCDEF"
11142N/A>lwres_result_t
10139N/Alwres_string_parse</CODE
10139N/A>(lwres_buffer_t *b, char **c, lwres_uint16_t *len);</CODE
10139N/A></P
10139N/A><P
10139N/A><CODE
10139N/A><CODE
10139N/ACLASS="FUNCDEF"
10139N/A>lwres_result_t
10139N/Alwres_addr_parse</CODE
10139N/A>(lwres_buffer_t *b, lwres_addr_t *addr);</CODE
10139N/A></P
10139N/A><P
10424N/A><CODE
10139N/A><CODE
10139N/ACLASS="FUNCDEF"
10139N/A>lwres_result_t
10139N/Alwres_getaddrsbyname</CODE
10139N/A>(lwres_context_t *ctx, const char *name, lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);</CODE
10139N/A></P
10139N/A><P
10139N/A><CODE
10139N/A><CODE
10139N/ACLASS="FUNCDEF"
10139N/A>lwres_result_t
10139N/Alwres_getnamebyaddr</CODE
10139N/A>(lwres_context_t *ctx, lwres_uint32_t addrtype, lwres_uint16_t addrlen, const unsigned char *addr, lwres_gnbaresponse_t **structp);</CODE
10139N/A></P
10139N/A><P
10139N/A></P
10139N/A></DIV
10139N/A></DIV
10139N/A><DIV
10139N/ACLASS="REFSECT1"
10139N/A><A
10139N/ANAME="AEN43"
10139N/A></A
10139N/A><H2
10139N/A>DESCRIPTION</H2
10139N/A><P
10139N/A><TT
10139N/ACLASS="FUNCTION"
10139N/A>lwres_string_parse()</TT
10139N/A>
10139N/Aretrieves a DNS-encoded string starting the current pointer of
10139N/Alightweight resolver buffer
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>b</I
10139N/A></TT
10139N/A>:
10139N/A
10139N/Ai.e.
10139N/A<TT
10139N/ACLASS="CONSTANT"
10139N/A>b-&gt;current</TT
10139N/A>.
10139N/A
10139N/AWhen the function returns, the address of the first byte of the
10139N/Aencoded string is returned via
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>*c</I
10139N/A></TT
10139N/A>
10139N/Aand the length of that string is given by
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>*len</I
10139N/A></TT
11922N/A>.
11922N/A
11819N/AThe buffer's current pointer is advanced to point at the character
11819N/Afollowing the string length, the encoded string, and the trailing
11416N/A<SPAN
11416N/ACLASS="TYPE"
11370N/A>NULL</SPAN
11370N/A>
11370N/Acharacter.
11256N/A<TT
11256N/ACLASS="FUNCTION"
11172N/A>lwres_string_parse()</TT
11175N/A>
11136N/Ahas an assertion check that
11136N/A<TT
11123N/ACLASS="PARAMETER"
11123N/A><I
11083N/A>b</I
11083N/A></TT
11083N/A>
11066N/Ais not
11071N/A<SPAN
11071N/ACLASS="TYPE"
11066N/A>NULL</SPAN
10972N/A>.&#13;</P
10972N/A><P
10972N/A><TT
10820N/ACLASS="FUNCTION"
10820N/A>lwres_addr_parse()</TT
10778N/A>
10778N/Aextracts an address from the buffer
10778N/A<TT
10778N/ACLASS="PARAMETER"
10774N/A><I
10774N/A>b</I
10748N/A></TT
10748N/A>.
10666N/A
10666N/AIt checks that
10650N/A<TT
10650N/ACLASS="PARAMETER"
10596N/A><I
10596N/A>addr</I
10580N/A></TT
10580N/A>
10473N/Ais not null.
10473N/AThe buffer's current pointer
10424N/A<TT
10424N/ACLASS="CONSTANT"
10424N/A>b-&gt;current</TT
10346N/A>
10346N/Ais presumed to point at an encoded address: the address preceded by a
10285N/A32-bit protocol family identifier and a 16-bit length field.
10285N/AThe encoded address is copied to
10179N/A<TT
10187N/ACLASS="CONSTANT"
10139N/A>addr-&gt;address</TT
10139N/A>
10139N/Aand
10139N/A<TT
10139N/ACLASS="CONSTANT"
10139N/A>addr-&gt;length</TT
10139N/A>
10139N/Aindicates the size in bytes of the address that was copied.
10139N/A<TT
10139N/ACLASS="CONSTANT"
10139N/A>b-&gt;current</TT
10139N/A>
10139N/Ais advanced to point at the next byte of available data in the buffer
10139N/Afollowing the encoded address.</P
10139N/A><P
10139N/A><TT
10139N/ACLASS="FUNCTION"
10139N/A>lwres_getaddrsbyname()</TT
10139N/A>
10139N/Aand
10139N/A<TT
10139N/ACLASS="FUNCTION"
10139N/A>lwres_getnamebyaddr()</TT
10139N/A>
10139N/Ause the
10139N/A<SPAN
10139N/ACLASS="TYPE"
10139N/A>lwres_gnbaresponse_t</SPAN
10139N/A>
10139N/Astructure defined below:
10139N/A<PRE
10139N/ACLASS="PROGRAMLISTING"
10139N/A>typedef struct {
10139N/A lwres_uint32_t flags;
10139N/A lwres_uint16_t naliases;
10139N/A lwres_uint16_t naddrs;
10139N/A char *realname;
10139N/A char **aliases;
10139N/A lwres_uint16_t realnamelen;
10139N/A lwres_uint16_t *aliaslen;
10139N/A lwres_addrlist_t addrs;
10139N/A void *base;
10139N/A size_t baselen;
10139N/A} lwres_gabnresponse_t;</PRE
10139N/A>
10139N/AThe contents of this structure are not manipulated directly but
10139N/Athey are controlled through the
10139N/A<SPAN
10139N/ACLASS="CITEREFENTRY"
10139N/A><SPAN
10139N/ACLASS="REFENTRYTITLE"
10139N/A>lwres_gabn</SPAN
10139N/A>(3)</SPAN
10139N/A>
10139N/Afunctions.</P
10139N/A><P
10139N/A>The lightweight resolver uses
10139N/A<TT
10139N/ACLASS="FUNCTION"
10139N/A>lwres_getaddrsbyname()</TT
10139N/A>
10139N/Ato perform foward lookups.
10139N/AHostname
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>name</I
10139N/A></TT
10139N/A>
10139N/Ais looked up using the resolver context
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>ctx</I
10139N/A></TT
10139N/A>
10139N/Afor memory allocation.
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>addrtypes</I
10139N/A></TT
10139N/A>
10139N/Ais a bitmask indicating which type of addresses are to be looked up.
10139N/ACurrent values for this bitmask are
10139N/A<SPAN
10139N/ACLASS="TYPE"
10139N/A>LWRES_ADDRTYPE_V4</SPAN
10139N/A>
10139N/Afor IPv4 addresses and
10139N/A<SPAN
10139N/ACLASS="TYPE"
10139N/A>LWRES_ADDRTYPE_V6</SPAN
10139N/A>
10139N/Afor IPv6 addresses.
10139N/AResults of the lookup are returned in
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>*structp</I
10139N/A></TT
10139N/A>.
10139N/A
10139N/A<TT
10139N/ACLASS="FUNCTION"
10139N/A>lwres_getaddrsbyname()</TT
10139N/A>
10139N/Achecks that its pointer arguments are not
10139N/A<SPAN
10139N/ACLASS="TYPE"
10139N/A>NULL</SPAN
10139N/A>
10139N/Aand that
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>addrtypes</I
10139N/A></TT
10139N/A>
10139N/Ais non-zero.</P
10139N/A><P
10139N/A><TT
10139N/ACLASS="FUNCTION"
10139N/A>lwres_getnamebyaddr()</TT
10139N/A>
10139N/Aperforms reverse lookups.
10139N/AResolver context
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>ctx</I
10139N/A></TT
10139N/A>
10139N/Ais used for memory allocation.
10139N/AThe address type is indicated by
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>addrtype</I
10139N/A></TT
10139N/A>:
10139N/A
10139N/A<SPAN
10139N/ACLASS="TYPE"
10139N/A>LWRES_ADDRTYPE_V4</SPAN
10139N/A>
10139N/Aor
10139N/A<SPAN
10139N/ACLASS="TYPE"
10139N/A>LWRES_ADDRTYPE_V6</SPAN
10139N/A>.
10139N/A
10139N/AThe address to be looked up is given by
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>addr</I
10139N/A></TT
10139N/A>
10139N/Aand its length is
10139N/A<TT
10139N/ACLASS="PARAMETER"
10139N/A><I
10139N/A>addrlen</I
10139N/A></TT
10139N/A>
10139N/Abytes.
10139N/AThe result of the function call is made available through
<TT
CLASS="PARAMETER"
><I
>*structp</I
></TT
>.
Like
<TT
CLASS="FUNCTION"
>lwres_getaddrsbyname()</TT
>,
<TT
CLASS="FUNCTION"
>lwres_getnamebyaddr()</TT
>
uses assertion checking to ensure its pointer arguments are not
<SPAN
CLASS="TYPE"
>NULL</SPAN
>
and
<TT
CLASS="PARAMETER"
><I
>addrtype</I
></TT
>
is not zero.
<TT
CLASS="FUNCTION"
>lwres_getaddrsbyname()</TT
>
also checks that
<TT
CLASS="PARAMETER"
><I
>addrlen</I
></TT
>
is non-zero.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN97"
></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
>.&#13;</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="AEN118"
></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
>