lwres_gnba.html revision 5a4557e8de2951a2796676b5ec4b6a90caa5be14
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
c78c39caab4cf8b5daefc9c65878f7f5ed3eb7a0Tinderbox User - Copyright (C) 2000, 2001 Internet Software Consortium.
ab496cc3df1648e9ad992a87c35c2c0870fdc69dTinderbox User - Permission to use, copy, modify, and 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
e676a596869d8a80a644c99a848afb53d1c5975eMark Andrews - PERFORMANCE OF THIS SOFTWARE.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<!-- $Id: lwres_gnba.html,v 1.17 2005/07/19 06:12:23 marka Exp $ -->
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
e676a596869d8a80a644c99a848afb53d1c5975eMark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<a name="id2456972"></a><div class="titlepage"></div>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<p>lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free — lightweight resolver getnamebyaddress message handling</p>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewslwres_result_t
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<b class="fsfunc">lwres_gnbarequest_render</b>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<var class="pdparam">b</var><code>)</code>;</td>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
16f6050f29b6b0422cee858e609f65e474e70ef2Tinderbox Userlwres_result_t
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<var class="pdparam">b</var><code>)</code>;</td>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox Userlwres_result_t
0e573cdd111e060e5f6c18249b5ccacbe8abe278Tinderbox User<b class="fsfunc">lwres_gnbarequest_parse</b>(</code></td>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<var class="pdparam">structp</var><code>)</code>;</td>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewslwres_result_t
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<b class="fsfunc">lwres_gnbaresponse_parse</b>(</code></td>
a03cb08d0c4f1ca5fbc121d2f02bdffa7eb52286Mark Andrews<var class="pdparam">structp</var><code>)</code>;</td>
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<var class="pdparam">structp</var><code>)</code>;</td>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<b class="fsfunc">lwres_gnbarequest_free</b>(</code></td>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<var class="pdparam">structp</var><code>)</code>;</td>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson These are low-level routines for creating and parsing
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User lightweight resolver address-to-name lookup request and
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews response messages.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User There are four main functions for the getnamebyaddr opcode.
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater One render function converts a getnamebyaddr request structure —
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <span class="type">lwres_gnbarequest_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 getnamebyaddr request structure.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User Another render function converts the getnamebyaddr response structure
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <span class="type">lwres_gnbaresponse_t</span>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews to the canonical format.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User This is complemented by a parse function which converts a packet in
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews canonical format to a getnamebyaddr response structure.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User These structures are defined in
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User They are shown below.
5f7586ddbd3edd11272cdd30ed613d936129328bTinderbox User#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox Usertypedef struct {
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews lwres_uint32_t flags;
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews lwres_addr_t addr;
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews} lwres_gnbarequest_t;
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox Usertypedef struct {
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews lwres_uint32_t flags;
7ca715ad1587a68a531ea1cdea07515d7232567eTinderbox User lwres_uint16_t naliases;
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User char *realname;
8711e5c73ca872d59810760af0332194cbdd619bAutomatic Updater char **aliases;
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater lwres_uint16_t realnamelen;
bac4435d473c9a0281507524f084480c34aa942aTinderbox User lwres_uint16_t *aliaslen;
933799f3641f4f78445d015008bad0038900a82aTinderbox User size_t baselen;
8e5fce1f9ceba17dd7e3ff0eb287e1e999c14249Mark Andrews} lwres_gnbaresponse_t;
bc0a53583d92309bebcf93c408e2f3247ebd3d3cAutomatic Updater<p><code class="function">lwres_gnbarequest_render()</code>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater uses resolver context <code class="varname">ctx</code> to convert
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater getnamebyaddr request structure <code class="varname">req</code> to
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater canonical format. The packet header structure
b02be031b9ff37b042adc8e68e36b8bbc1f672b7Tinderbox User <code class="varname">pkt</code> is initialised and transferred to buffer
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="varname">b</code>. The contents of <code class="varname">*req</code>
ba8b771c371967dd1254c7fa82ebe4158ee04b24Tinderbox User are then appended to the buffer in canonical format.
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater <code class="function">lwres_gnbaresponse_render()</code> performs the
3ec8f7777ea2b04fc1ebb63077f0916f63b1011aTinderbox User same task, except it converts a getnamebyaddr response structure
d7d105151a78d35afb4233d2a6dbd47b7ec0d9a5Tinderbox User <span class="type">lwres_gnbaresponse_t</span> to the lightweight resolver's
b02be031b9ff37b042adc8e68e36b8bbc1f672b7Tinderbox User canonical format.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<p><code class="function">lwres_gnbarequest_parse()</code>
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater uses context <code class="varname">ctx</code> to convert the contents of
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater packet <code class="varname">pkt</code> to a
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <span class="type">lwres_gnbarequest_t</span> structure. Buffer
7f94d9a8162c9a96b56e66176702b66e79d8e1a2Automatic Updater <code class="varname">b</code> provides space to be used for storing this
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater structure. When the function succeeds, the resulting
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="type">lwres_gnbarequest_t</span> is made available through
39ae0eafed076ef769fef5c18b22a8051df5c93aTinderbox User <code class="function">lwres_gnbaresponse_parse()</code> offers the same
91d187ce035f39073f0732ff2a401a45c3c955fbMark Andrews semantics as <code class="function">lwres_gnbarequest_parse()</code>
c2abd6efeb9affa70aabb63da2acb23e135cf7f2Mark Andrews except it yields a <span class="type">lwres_gnbaresponse_t</span> structure.
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User<p><code class="function">lwres_gnbaresponse_free()</code>
96ea71632887c58a9d00f47eb318bf76b35903c3Mark Andrews and <code class="function">lwres_gnbarequest_free()</code> release the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater memory in resolver context <code class="varname">ctx</code> that was
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater allocated to the <span class="type">lwres_gnbaresponse_t</span> or
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User <span class="type">lwres_gnbarequest_t</span> structures referenced via
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User <code class="varname">structp</code>. Any memory associated with
4cda4fd158d6ded5586bacea8c388445d99611eaAutomatic Updater ancillary buffers and strings for those structures is also
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id2515045"></a><h2>RETURN VALUES</h2>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews The getnamebyaddr opcode functions
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <code class="function">lwres_gnbarequest_render()</code>,
bac4435d473c9a0281507524f084480c34aa942aTinderbox User <code class="function">lwres_gnbaresponse_render()</code>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <code class="function">lwres_gnbarequest_parse()</code>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <code class="function">lwres_gnbaresponse_parse()</code>
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User <span class="errorcode">LWRES_R_SUCCESS</span>
e64202536ea72d8f371dd0df9fc763f8d70bf886Tinderbox User <span class="errorcode">LWRES_R_NOMEMORY</span>
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews if memory allocation fails.
da59e63e7af147a8bcef985b98b04443e04c3a0eTinderbox User <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User is returned if the available space in the buffer
ae454ec746d1d4db8d04e107d4d25ff13158c37fMark Andrews is too small to accommodate the packet header or the
757ff043760e4743dda1a10e7d58349275934902Tinderbox User <span class="type">lwres_gnbaresponse_t</span>
ae454ec746d1d4db8d04e107d4d25ff13158c37fMark Andrews <code class="function">lwres_gnbarequest_parse()</code>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <code class="function">lwres_gnbaresponse_parse()</code>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
1bcc3273a80c256f11d9098a00ba2c041939e233Mark Andrews if the buffer is not empty after decoding the received packet.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews These functions will return
ba8b771c371967dd1254c7fa82ebe4158ee04b24Tinderbox User <span class="errorcode">LWRES_R_FAILURE</span>
f520803b46dc189fdaf84adc87ef327d3587b435Mark Andrews <em class="structfield"><code>pktflags</code></em>
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User in the packet header structure
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews indicate that the packet is not a response to an earlier query.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>.