lwres_gabn.html revision e21a2904f02a03fa06b6db04d348f65fe9c67b2b
25cc5fbba63f84b47e389af749f55abbbde71c8cChristian Maeder - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder - Copyright (C) 2000, 2001 Internet Software Consortium.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - Permission to use, copy, modify, and distribute this software for any
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder - purpose with or without fee is hereby granted, provided that the above
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - copyright notice and this permission notice appear in all copies.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
d8c71aacc9f1c8cd40a8ad8dcdad9be8854b849fChristian Maeder - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - PERFORMANCE OF THIS SOFTWARE.
1aee4aaddde105264c1faf394d88e302c05094ffChristian Maeder<!-- $Id: lwres_gabn.html,v 1.22 2006/12/12 01:45:21 marka Exp $ -->
a53841f6d6e86ac751c12a33dc8aadf53f59d977Klaus Luettich<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
a737caf82de97c1907027c03e4b4509eb492b4b8Christian Maeder<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
96646aed2ae087b942ae23f15bbe729a8f7c43d3Christian Maeder<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
01e383014b555bbcf639c0ca60c5810b3eff83c0Christian Maeder<a name="id2476419"></a><div class="titlepage"></div>
1aee4aaddde105264c1faf394d88e302c05094ffChristian Maeder<p>lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free — lightweight resolver getaddrbyname message handling</p>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
2e2094a642e3775b0d76b890556407941d3a53b6Christian Maederlwres_result_t
2e2094a642e3775b0d76b890556407941d3a53b6Christian Maeder<b class="fsfunc">lwres_gabnrequest_render</b>(</code></td>
8d97ef4f234681b11bb5924bd4d03adef858d2d2Christian Maeder<var class="pdparam">b</var><code>)</code>;</td>
e593b89bfd4952698dc37feced21cefe869d87a2Christian Maeder<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
7cc09dd93962a2155c34d209d1d4cd7d7b838264Christian Maederlwres_result_t
1aee4aaddde105264c1faf394d88e302c05094ffChristian Maeder<b class="fsfunc">lwres_gabnresponse_render</b>(</code></td>
e7757995211bd395dc79d26fe017d99375f7d2a6Christian Maeder<var class="pdparam">b</var><code>)</code>;</td>
c55a0f77be7e88d3620b419ec8961f4379a586e3Klaus Luettich<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
363939beade943a02b31004cea09dec34fa8a6d9Christian Maederlwres_result_t
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder<b class="fsfunc">lwres_gabnrequest_parse</b>(</code></td>
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder<var class="pdparam">structp</var><code>)</code>;</td>
776a1a086df734581431e6edb4343ed4c8d34d55Christian Maeder<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maederlwres_result_t
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder<b class="fsfunc">lwres_gabnresponse_parse</b>(</code></td>
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder<var class="pdparam">structp</var><code>)</code>;</td>
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder<b class="fsfunc">lwres_gabnresponse_free</b>(</code></td>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<var class="pdparam">structp</var><code>)</code>;</td>
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder<b class="fsfunc">lwres_gabnrequest_free</b>(</code></td>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<var class="pdparam">structp</var><code>)</code>;</td>
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder<a name="id2543708"></a><h2>DESCRIPTION</h2>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder These are low-level routines for creating and parsing
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder lightweight resolver name-to-address lookup request and
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder response messages.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder There are four main functions for the getaddrbyname opcode.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder One render function converts a getaddrbyname request structure —
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder <span class="type">lwres_gabnrequest_t</span> —
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder to the lighweight resolver's canonical format.
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder It is complemented by a parse function that converts a packet in this
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder canonical format to a getaddrbyname request structure.
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder Another render function converts the getaddrbyname response structure
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder — <span class="type">lwres_gabnresponse_t</span> —
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder to the canonical format.
89f7631cbfbd1bb99fc152b434bd362a7799d295Christian Maeder This is complemented by a parse function which converts a packet in
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder canonical format to a getaddrbyname response structure.
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder These structures are defined in
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder <code class="filename"><lwres/lwres.h></code>.
f4505a64a089693012a3f5c3b1f12a82cd7a2a5aKlaus Luettich They are shown below.
f4505a64a089693012a3f5c3b1f12a82cd7a2a5aKlaus Luettich#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
36f63902db2b3463faa9f59912ad106e2d5aaa24Klaus Luettichtypedef struct lwres_addr lwres_addr_t;
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maedertypedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
7c5c311d67e187280877c45bd89dcba9038bc0a3Christian Maedertypedef struct {
7c5c311d67e187280877c45bd89dcba9038bc0a3Christian Maeder lwres_uint32_t flags;
7c5c311d67e187280877c45bd89dcba9038bc0a3Christian Maeder lwres_uint32_t addrtypes;
7c5c311d67e187280877c45bd89dcba9038bc0a3Christian Maeder lwres_uint16_t namelen;
7c5c311d67e187280877c45bd89dcba9038bc0a3Christian Maeder} lwres_gabnrequest_t;
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maedertypedef struct {
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder lwres_uint32_t flags;
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder lwres_uint16_t naliases;
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder lwres_uint16_t naddrs;
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder char *realname;
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder char **aliases;
9df11f85fd7f8c4745d64464876e84ec4e263692Christian Maeder lwres_uint16_t realnamelen;
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers lwres_uint16_t *aliaslen;
010c56c4cf12dd7977ca36efe85219b91e265ee3Christian Maeder lwres_addrlist_t addrs;
3b06e23643a9f65390cb8c1caabe83fa7e87a708Till Mossakowski size_t baselen;
5b818f10e11fc79def1fdd5c8a080d64a6438d87Christian Maeder} lwres_gabnresponse_t;
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<p><code class="function">lwres_gabnrequest_render()</code>
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder uses resolver context <em class="parameter"><code>ctx</code></em> to convert
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers getaddrbyname request structure <em class="parameter"><code>req</code></em> to
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder canonical format. The packet header structure
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <em class="parameter"><code>pkt</code></em> is initialised and transferred to
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder buffer <em class="parameter"><code>b</code></em>.
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder The contents of <em class="parameter"><code>*req</code></em> are then appended to
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder the buffer in canonical format.
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder <code class="function">lwres_gabnresponse_render()</code> performs the
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder same task, except it converts a getaddrbyname response structure
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder <span class="type">lwres_gabnresponse_t</span> to the lightweight resolver's
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder canonical format.
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder<p><code class="function">lwres_gabnrequest_parse()</code>
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder uses context <em class="parameter"><code>ctx</code></em> to convert the contents
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder of packet <em class="parameter"><code>pkt</code></em> to a
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder <span class="type">lwres_gabnrequest_t</span> structure. Buffer
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <em class="parameter"><code>b</code></em> provides space to be used for storing
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder this structure. When the function succeeds, the resulting
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <span class="type">lwres_gabnrequest_t</span> is made available through
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <em class="parameter"><code>*structp</code></em>.
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <code class="function">lwres_gabnresponse_parse()</code> offers the same
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder semantics as <code class="function">lwres_gabnrequest_parse()</code>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder except it yields a <span class="type">lwres_gabnresponse_t</span> structure.
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder<p><code class="function">lwres_gabnresponse_free()</code>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder and <code class="function">lwres_gabnrequest_free()</code> release the
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder memory in resolver context <em class="parameter"><code>ctx</code></em> that was
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder allocated to the <span class="type">lwres_gabnresponse_t</span> or
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <span class="type">lwres_gabnrequest_t</span> structures referenced via
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <em class="parameter"><code>structp</code></em>.
e7757995211bd395dc79d26fe017d99375f7d2a6Christian Maeder Any memory associated with ancillary buffers and strings for
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder those structures is also discarded.
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder<a name="id2543853"></a><h2>RETURN VALUES</h2>
3b06e23643a9f65390cb8c1caabe83fa7e87a708Till Mossakowski The getaddrbyname opcode functions
b1f59a4ea7c96f4c03a4d7cfcb9c5e66871cfbbbChristian Maeder <code class="function">lwres_gabnrequest_render()</code>,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="function">lwres_gabnresponse_render()</code>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="function">lwres_gabnrequest_parse()</code>
fb328c4f646dd3dd78a9391c5cb58450a3dd0aa9Klaus Luettich <code class="function">lwres_gabnresponse_parse()</code>
abf2487c3aece95c371ea89ac64319370dcb6483Klaus Luettich <span class="errorcode">LWRES_R_NOMEMORY</span>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder if memory allocation fails.
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder is returned if the available space in the buffer
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder is too small to accommodate the packet header or the
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <span class="type">lwres_gabnrequest_t</span>
18a4d5cb6828f080db9c5f9551785c5151027271Christian Maeder <span class="type">lwres_gabnresponse_t</span>
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder <code class="function">lwres_gabnrequest_parse()</code>
fdb2d618144159395f7bf8ce3327b3c112a17dd3Till Mossakowski <code class="function">lwres_gabnresponse_parse()</code>
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
3b06e23643a9f65390cb8c1caabe83fa7e87a708Till Mossakowski if the buffer is not empty after decoding the received packet.
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder These functions will return
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <span class="errorcode">LWRES_R_FAILURE</span>
38352346eb1a67ba0f4eab8ad6f718528cf0cde0Christian Maeder <em class="structfield"><code>pktflags</code></em>
356fa49fe3e6a8398f92d13e9f920d0f093697ecChristian Maeder in the packet header structure
63e50b4c36074d5fb9de872c4007b688b4bce534Christian Maeder indicate that the packet is not a response to an earlier query.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>