lwres_gabn.html revision 2eeb74d1cf5355dd98f6d507a10086e16bb08c4b
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
c78c39caab4cf8b5daefc9c65878f7f5ed3eb7a0Tinderbox User - Copyright (C) 2000, 2001 Internet Software Consortium.
ab496cc3df1648e9ad992a87c35c2c0870fdc69dTinderbox User - Permission to use, copy, modify, and/or distribute this software for any
7c1468ed500356839a4a222517364e6ce18cb1a2Tinderbox User - purpose with or without fee is hereby granted, provided that the above
c57668a2fbbe558c1bd21652813616f2f517c469Tinderbox User - copyright notice and this permission notice appear in all copies.
287a6a8f9040dc43560cd69cddf83bfc0f53b76fTinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox User - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
950d203b64f512b85fcc093ee1e9e3e531a1aea3Tinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupont - PERFORMANCE OF THIS SOFTWARE.
d5637bdbb931ff79fced3d4858d83212ea58ed15Tinderbox User<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
d5637bdbb931ff79fced3d4858d83212ea58ed15Tinderbox User<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" title="lwres_gabn">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<a name="idp60913104"></a><div class="titlepage"></div>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews lwres_gabnrequest_render,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User lwres_gabnresponse_render,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews lwres_gabnrequest_parse,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User lwres_gabnresponse_parse,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews lwres_gabnresponse_free,
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User lwres_gabnrequest_free
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews — lightweight resolver getaddrbyname message handling
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Huntlwres_result_t
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User<b class="fsfunc">lwres_gabnrequest_render</b>(</code></td>
0e573cdd111e060e5f6c18249b5ccacbe8abe278Tinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupont<td>lwres_gabnrequest_t *<var class="pdparam">req</var>, </td>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrewslwres_result_t
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<b class="fsfunc">lwres_gabnresponse_render</b>(</code></td>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt<td>lwres_gabnresponse_t *<var class="pdparam">req</var>, </td>
294e9d4c34462d29a3e766c88f452b46aeb3702fTinderbox User<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt<td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
ee11dfc481f2ef6a032a715454f6290961a722d2Tinderbox Userlwres_result_t
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<b class="fsfunc">lwres_gabnrequest_parse</b>(</code></td>
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
77932ac533c711eca5cd86de4e7eca8d91102b43Tinderbox User<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<td>lwres_gabnrequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox Userlwres_result_t
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<b class="fsfunc">lwres_gabnresponse_parse</b>(</code></td>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
28a5dd720187fddb16055a0f64b63a7b66f29f64Mark Andrews<td>lwres_gabnresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
a450977e98155f6e828fe6f8d52cf24674231831Mark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox User<b class="fsfunc">lwres_gabnresponse_free</b>(</code></td>
fd972434c29fc1169d66594e4cc7697d33036c2bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont<td>lwres_gabnresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews<b class="fsfunc">lwres_gabnrequest_free</b>(</code></td>
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<td>lwres_gabnrequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User These are low-level routines for creating and parsing
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater lightweight resolver name-to-address lookup request and
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews response messages.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User There are four main functions for the getaddrbyname opcode.
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater One render function converts a getaddrbyname request structure —
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <span class="type">lwres_gabnrequest_t</span> —
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews to the lightweight resolver's canonical format.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User It is complemented by a parse function that converts a packet in this
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews canonical format to a getaddrbyname request structure.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User Another render function converts the getaddrbyname response structure
fa0326cc2cf428f67575b6ba3b97b528a31b0010Tinderbox User — <span class="type">lwres_gabnresponse_t</span> —
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User to the canonical format.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews This is complemented by a parse function which converts a packet in
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User canonical format to a getaddrbyname response structure.
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater These structures are defined in
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <code class="filename"><lwres/lwres.h></code>.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews They are shown below.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewstypedef struct lwres_addr lwres_addr_t;
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox Usertypedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewstypedef struct {
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User lwres_uint32_t flags;
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater lwres_uint32_t addrtypes;
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User lwres_uint16_t namelen;
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User} lwres_gabnrequest_t;
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewstypedef struct {
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User lwres_uint32_t flags;
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews lwres_uint16_t naliases;
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User lwres_uint16_t naddrs;
5f7586ddbd3edd11272cdd30ed613d936129328bTinderbox User char *realname;
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User char **aliases;
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews lwres_uint16_t realnamelen;
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User lwres_uint16_t *aliaslen;
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews lwres_addrlist_t addrs;
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews size_t baselen;
70d987def5a58ebeb8243017c0ec2e9b2c326cf4Evan Hunt} lwres_gabnresponse_t;
933799f3641f4f78445d015008bad0038900a82aTinderbox User <p><code class="function">lwres_gabnrequest_render()</code>
f0c5e918974bf778af6cd1e25309ad13e30a79a6Tinderbox User uses resolver context <em class="parameter"><code>ctx</code></em> to convert
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews getaddrbyname request structure <em class="parameter"><code>req</code></em> to
7ca715ad1587a68a531ea1cdea07515d7232567eTinderbox User canonical format. The packet header structure
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User <em class="parameter"><code>pkt</code></em> is initialised and transferred to
8711e5c73ca872d59810760af0332194cbdd619bAutomatic Updater buffer <em class="parameter"><code>b</code></em>.
bac4435d473c9a0281507524f084480c34aa942aTinderbox User The contents of <em class="parameter"><code>*req</code></em> are then appended to
91d187ce035f39073f0732ff2a401a45c3c955fbMark Andrews the buffer in canonical format.
933799f3641f4f78445d015008bad0038900a82aTinderbox User <code class="function">lwres_gabnresponse_render()</code> performs the
8e5fce1f9ceba17dd7e3ff0eb287e1e999c14249Mark Andrews same task, except it converts a getaddrbyname response structure
933799f3641f4f78445d015008bad0038900a82aTinderbox User <span class="type">lwres_gabnresponse_t</span> to the lightweight resolver's
4151211e6649332f7b5a55870cbe37128bcc7b29Tinderbox User canonical format.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <p><code class="function">lwres_gabnrequest_parse()</code>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater uses context <em class="parameter"><code>ctx</code></em> to convert the contents
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater of packet <em class="parameter"><code>pkt</code></em> to a
b02be031b9ff37b042adc8e68e36b8bbc1f672b7Tinderbox User <span class="type">lwres_gabnrequest_t</span> structure. Buffer
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <em class="parameter"><code>b</code></em> provides space to be used for storing
ba8b771c371967dd1254c7fa82ebe4158ee04b24Tinderbox User this structure. When the function succeeds, the resulting
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater <span class="type">lwres_gabnrequest_t</span> is made available through
3ec8f7777ea2b04fc1ebb63077f0916f63b1011aTinderbox User <em class="parameter"><code>*structp</code></em>.
b02be031b9ff37b042adc8e68e36b8bbc1f672b7Tinderbox User <code class="function">lwres_gabnresponse_parse()</code> offers the same
933799f3641f4f78445d015008bad0038900a82aTinderbox User semantics as <code class="function">lwres_gabnrequest_parse()</code>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater except it yields a <span class="type">lwres_gabnresponse_t</span> structure.
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <p><code class="function">lwres_gabnresponse_free()</code>
ecbc7ebb243a1f8a5dc6f28185ffe9e61d3b2102Mark Andrews and <code class="function">lwres_gabnrequest_free()</code> release the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater memory in resolver context <em class="parameter"><code>ctx</code></em> that was
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allocated to the <span class="type">lwres_gabnresponse_t</span> or
bac4435d473c9a0281507524f084480c34aa942aTinderbox User <span class="type">lwres_gabnrequest_t</span> structures referenced via
39ae0eafed076ef769fef5c18b22a8051df5c93aTinderbox User <em class="parameter"><code>structp</code></em>.
c2abd6efeb9affa70aabb63da2acb23e135cf7f2Mark Andrews Any memory associated with ancillary buffers and strings for
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupont those structures is also discarded.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <div class="refsection" title="RETURN VALUES">
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater<a name="idp60985552"></a><h2>RETURN VALUES</h2>
4cda4fd158d6ded5586bacea8c388445d99611eaAutomatic Updater The getaddrbyname opcode functions
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <code class="function">lwres_gabnrequest_render()</code>,
b02be031b9ff37b042adc8e68e36b8bbc1f672b7Tinderbox User <code class="function">lwres_gabnresponse_render()</code>
0e573cdd111e060e5f6c18249b5ccacbe8abe278Tinderbox User <code class="function">lwres_gabnrequest_parse()</code>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="function">lwres_gabnresponse_parse()</code>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span class="errorcode">LWRES_R_NOMEMORY</span>
ba8b771c371967dd1254c7fa82ebe4158ee04b24Tinderbox User if memory allocation fails.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater is returned if the available space in the buffer
933799f3641f4f78445d015008bad0038900a82aTinderbox User is too small to accommodate the packet header or the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="type">lwres_gabnrequest_t</span>
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User <code class="function">lwres_gabnrequest_parse()</code>
ae454ec746d1d4db8d04e107d4d25ff13158c37fMark Andrews <code class="function">lwres_gabnresponse_parse()</code>
a03cb08d0c4f1ca5fbc121d2f02bdffa7eb52286Mark Andrews <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
757ff043760e4743dda1a10e7d58349275934902Tinderbox User if the buffer is not empty after decoding the received packet.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater These functions will return
1bcc3273a80c256f11d9098a00ba2c041939e233Mark Andrews in the packet header structure
1bcc3273a80c256f11d9098a00ba2c041939e233Mark Andrews indicate that the packet is not a response to an earlier query.
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews <span class="refentrytitle">lwres_packet</span>(3)