lwres_gabn.html revision 010a51c427bfb6ab658fc0056955a1a5b69810be
010a51c427bfb6ab658fc0056955a1a5b69810beTinderbox User - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews - Copyright (C) 2000, 2001 Internet Software Consortium.
4a14ce5ba00ab7bc55c99ffdcf59c7a4ab902721Automatic Updater - Permission to use, copy, modify, and/or distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" title="lwres_gabn">
010a51c427bfb6ab658fc0056955a1a5b69810beTinderbox User<a name="idp60762064"></a><div class="titlepage"></div>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User lwres_gabnrequest_render,
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User lwres_gabnresponse_render,
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User lwres_gabnrequest_parse,
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User lwres_gabnresponse_parse,
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User lwres_gabnresponse_free,
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User lwres_gabnrequest_free
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User — lightweight resolver getaddrbyname message handling
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <div class="refsynopsisdiv" title="Synopsis">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_gabnrequest_render</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_gabnrequest_t *<var class="pdparam">req</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_gabnresponse_render</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_gabnresponse_t *<var class="pdparam">req</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_gabnrequest_parse</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_gabnrequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_gabnresponse_parse</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_gabnresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_gabnresponse_free</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_gabnresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_gabnrequest_free</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_gabnrequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
010a51c427bfb6ab658fc0056955a1a5b69810beTinderbox User<a name="idp60831056"></a><h2>DESCRIPTION</h2>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein These are low-level routines for creating and parsing
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lightweight resolver name-to-address lookup request and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein response messages.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein There are four main functions for the getaddrbyname opcode.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein One render function converts a getaddrbyname request structure —
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="type">lwres_gabnrequest_t</span> —
a24330c4805a224191ab687d0291963062fe3355Tinderbox User to the lightweight resolver's canonical format.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein It is complemented by a parse function that converts a packet in this
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein canonical format to a getaddrbyname request structure.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Another render function converts the getaddrbyname response structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein — <span class="type">lwres_gabnresponse_t</span> —
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein to the canonical format.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This is complemented by a parse function which converts a packet in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein canonical format to a getaddrbyname response structure.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein These structures are defined in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="filename"><lwres/lwres.h></code>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein They are shown below.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct lwres_addr lwres_addr_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t flags;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t addrtypes;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t namelen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_gabnrequest_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t flags;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t naliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t naddrs;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char *realname;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char **aliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t realnamelen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t *aliaslen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_addrlist_t addrs;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson size_t baselen;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein} lwres_gabnresponse_t;
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <p><code class="function">lwres_gabnrequest_render()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein uses resolver context <em class="parameter"><code>ctx</code></em> to convert
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein getaddrbyname request structure <em class="parameter"><code>req</code></em> to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein canonical format. The packet header structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>pkt</code></em> is initialised and transferred to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein buffer <em class="parameter"><code>b</code></em>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The contents of <em class="parameter"><code>*req</code></em> are then appended to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the buffer in canonical format.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_gabnresponse_render()</code> performs the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein same task, except it converts a getaddrbyname response structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="type">lwres_gabnresponse_t</span> to the lightweight resolver's
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein canonical format.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <p><code class="function">lwres_gabnrequest_parse()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein uses context <em class="parameter"><code>ctx</code></em> to convert the contents
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein of packet <em class="parameter"><code>pkt</code></em> to a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="type">lwres_gabnrequest_t</span> structure. Buffer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>b</code></em> provides space to be used for storing
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein this structure. When the function succeeds, the resulting
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="type">lwres_gabnrequest_t</span> is made available through
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>*structp</code></em>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_gabnresponse_parse()</code> offers the same
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein semantics as <code class="function">lwres_gabnrequest_parse()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein except it yields a <span class="type">lwres_gabnresponse_t</span> structure.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <p><code class="function">lwres_gabnresponse_free()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein and <code class="function">lwres_gabnrequest_free()</code> release the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein memory in resolver context <em class="parameter"><code>ctx</code></em> that was
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein allocated to the <span class="type">lwres_gabnresponse_t</span> or
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="type">lwres_gabnrequest_t</span> structures referenced via
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>structp</code></em>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Any memory associated with ancillary buffers and strings for
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein those structures is also discarded.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <div class="refsection" title="RETURN VALUES">
010a51c427bfb6ab658fc0056955a1a5b69810beTinderbox User<a name="idp60851408"></a><h2>RETURN VALUES</h2>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The getaddrbyname opcode functions
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_gabnrequest_render()</code>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_gabnresponse_render()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_gabnrequest_parse()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_gabnresponse_parse()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein if memory allocation fails.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is returned if the available space in the buffer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is too small to accommodate the packet header or the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_gabnrequest_parse()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_gabnresponse_parse()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein if the buffer is not empty after decoding the received packet.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein These functions will return
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein in the packet header structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein indicate that the packet is not a response to an earlier query.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <span class="refentrytitle">lwres_packet</span>(3)