lwres_gabn.docbook revision 1753d3c4d74241a847794f7e7cfd94cc79be6600
4d237bbe075b1d2c19428cd954d721d65b31f67cwrowe<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
bf52162f2d05c1fb1a107c7ef108de73f739b3edpquerna "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
bf52162f2d05c1fb1a107c7ef108de73f739b3edpquerna [<!ENTITY mdash "—">]>
86bb763be5d87c295c8844d30078da2ddb964f73rpluem - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
86bb763be5d87c295c8844d30078da2ddb964f73rpluem - Copyright (C) 2000, 2001 Internet Software Consortium.
ba217dc41cebc0976010ee177f8fedac782d1f6fminfrin - Permission to use, copy, modify, and/or distribute this software for any
86bb763be5d87c295c8844d30078da2ddb964f73rpluem - purpose with or without fee is hereby granted, provided that the above
86bb763be5d87c295c8844d30078da2ddb964f73rpluem - copyright notice and this permission notice appear in all copies.
a50db00c3663c2a0d3531965c64d995516b06288niq - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
a50db00c3663c2a0d3531965c64d995516b06288niq - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
a50db00c3663c2a0d3531965c64d995516b06288niq - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
ea6ff3396df1d6d43ee0ecfa3e26ada981d8e9a3sctemme - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
ea6ff3396df1d6d43ee0ecfa3e26ada981d8e9a3sctemme - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
8a0c75e992cc657a98317e78374b800d16963cfatrawick - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
ba217dc41cebc0976010ee177f8fedac782d1f6fminfrin - PERFORMANCE OF THIS SOFTWARE.
3f985866b9b5b49fb57735b5eb135591163f30dfsf <refentryinfo>
7f51e5c395d431b8c20226f77de28efe13272bfasf </refentryinfo>
17d64c884a44f5ca72f6901afd3e50991bfc1c63sf </refmeta>
a6e4caaa97e433cc2ef78d957bc32756d9c49f79sf <copyright>
304903af1cf77cbdfa07e8a6482f35f3d9d7b0f3sf <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
a6e4caaa97e433cc2ef78d957bc32756d9c49f79sf </copyright>
a96ba81cada826f2a9ab1e24218a77bfadfc31d8sf <copyright>
4f133508c93204c06e1acba9774ff184e5812606niq </copyright>
4f133508c93204c06e1acba9774ff184e5812606niq </docinfo>
87587593f1a53030e840acc0dec6cc881022ea40covener <refnamediv>
52071e4b9f49c3a1c2c767c7ea80ec92cf9032c9covener <refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
89b8bbc89404e7071e573c4f0a17f528996e855djorton </refnamediv>
89b8bbc89404e7071e573c4f0a17f528996e855djorton <refsynopsisdiv>
89b8bbc89404e7071e573c4f0a17f528996e855djorton <funcsynopsis>
e1d4c4e8366f46dc5dc1e6e24b4c7ac448dfa061sf<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
e1d4c4e8366f46dc5dc1e6e24b4c7ac448dfa061sf<funcprototype>
6bc4f334a04802bab835893d0c42af8bfb9c3c41sflwres_result_t
53593dbd8fece82cb66a23f0b7024d8d713d66f1sf <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
79e3f2f950745953fff4a6a8dfe1f7cce31ce287sf <paramdef>lwres_gabnrequest_t *<parameter>req</parameter></paramdef>
79e3f2f950745953fff4a6a8dfe1f7cce31ce287sf <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
ab2b977442827214b1d884decf3e3f1579fd45e1rpluem <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
ab2b977442827214b1d884decf3e3f1579fd45e1rpluem </funcprototype>
ab2b977442827214b1d884decf3e3f1579fd45e1rpluem<funcprototype>
195edf54eccd8c5a436c7dd17f5f604e7074d5d1sflwres_result_t
3709b26f3370ae89c5324a3c03fab56a93b09ecdsf <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
3709b26f3370ae89c5324a3c03fab56a93b09ecdsf <paramdef>lwres_gabnresponse_t *<parameter>req</parameter></paramdef>
3709b26f3370ae89c5324a3c03fab56a93b09ecdsf <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
03577bc320125eaa2b27ee7af78b894ee6dfe121takashi <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
03577bc320125eaa2b27ee7af78b894ee6dfe121takashi </funcprototype>
03577bc320125eaa2b27ee7af78b894ee6dfe121takashi<funcprototype>
f5119c5d7cfe8c6d53cb29d43f8746684068ed82minfrinlwres_result_t
f5119c5d7cfe8c6d53cb29d43f8746684068ed82minfrin<function>lwres_gabnrequest_parse</function></funcdef>
f5119c5d7cfe8c6d53cb29d43f8746684068ed82minfrin <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
f74d35a61a835e15412b99b8aebe4958fe4e94a5takashi <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
94713632faf403489b3f8b4e0ed65e1011ac4991takashi <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
f74d35a61a835e15412b99b8aebe4958fe4e94a5takashi <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
20216b769716c4346cce373f2028d7dbebf03886poirier </funcprototype>
20216b769716c4346cce373f2028d7dbebf03886poirier<funcprototype>
7317a32e0c621c9a28f6f10e83e6c5dc63e3f3bdsflwres_result_t
7317a32e0c621c9a28f6f10e83e6c5dc63e3f3bdsf <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
ecc6e723b804fb4b8f858910eff3f88242ec56fasf <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
ecc6e723b804fb4b8f858910eff3f88242ec56fasf <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
ecc6e723b804fb4b8f858910eff3f88242ec56fasf <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
ecc6e723b804fb4b8f858910eff3f88242ec56fasf </funcprototype>
ecc6e723b804fb4b8f858910eff3f88242ec56fasf<funcprototype>
727d68c6009030f56a350b4603384ce4fb844341minfrin<function>lwres_gabnresponse_free</function></funcdef>
727d68c6009030f56a350b4603384ce4fb844341minfrin <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
ed6dfb7d7057dc4f42348f12d7bff9fe98fc73cfminfrin <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
ed6dfb7d7057dc4f42348f12d7bff9fe98fc73cfminfrin </funcprototype>
ed6dfb7d7057dc4f42348f12d7bff9fe98fc73cfminfrin<funcprototype>
23247a8f748077bc788a5fbaf91d5fad34d0b7d1sf <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
23247a8f748077bc788a5fbaf91d5fad34d0b7d1sf <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
23247a8f748077bc788a5fbaf91d5fad34d0b7d1sf </funcprototype>
23247a8f748077bc788a5fbaf91d5fad34d0b7d1sf</funcsynopsis>
58015652ffe00f004c6404a0631474f23dadc7dasf </refsynopsisdiv>
58015652ffe00f004c6404a0631474f23dadc7dasf <refsect1>
2af38cc44e48753913565b38a7a9f325f898a293minfrin These are low-level routines for creating and parsing
745417156908df54538ca284b382ce8d27b30066minfrin lightweight resolver name-to-address lookup request and
2af38cc44e48753913565b38a7a9f325f898a293minfrin response messages.
fc2f0972572614b50523bc5ddb3f866ca4acd2f0sf There are four main functions for the getaddrbyname opcode.
251430bcaff1fa6a77953bfe56475eb6cc7abc78sf One render function converts a getaddrbyname request structure —
251430bcaff1fa6a77953bfe56475eb6cc7abc78sf to the lighweight resolver's canonical format.
7b467aa53854c95318a1c709709c1619a4f47118minfrin It is complemented by a parse function that converts a packet in this
7b467aa53854c95318a1c709709c1619a4f47118minfrin canonical format to a getaddrbyname request structure.
7b467aa53854c95318a1c709709c1619a4f47118minfrin Another render function converts the getaddrbyname response structure
7ba7402d405dc9e3c1083e34049ed933472ca910poirier to the canonical format.
7ba7402d405dc9e3c1083e34049ed933472ca910poirier This is complemented by a parse function which converts a packet in
7ba7402d405dc9e3c1083e34049ed933472ca910poirier canonical format to a getaddrbyname response structure.
4286d2e267e788d856092bf2ccf461e7ca99570frpluem These structures are defined in
4286d2e267e788d856092bf2ccf461e7ca99570frpluem They are shown below.
5357892a1e367372dc2d4a315156e3e44dc5d56dpoirier#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
5357892a1e367372dc2d4a315156e3e44dc5d56dpoirier</programlisting>
b42af5f6edf4fe4b820288c37920a7a6fd65f1f1poiriertypedef struct lwres_addr lwres_addr_t;
49cea03e96dc4707bce15d6318eb013cb8668d96minfrintypedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
49cea03e96dc4707bce15d6318eb013cb8668d96minfrin</programlisting>
847b3922f7dcde6830f4aad49d29c84b4569c260minfrintypedef struct {
63eaa8ed62d63de0a44346b8af48e08e562db01eminfrin lwres_uint32_t flags;
63eaa8ed62d63de0a44346b8af48e08e562db01eminfrin lwres_uint32_t addrtypes;
847b3922f7dcde6830f4aad49d29c84b4569c260minfrin lwres_uint16_t namelen;
1af2b28846e2647963db788b081676884fb7df8crpluem char *name;
1af2b28846e2647963db788b081676884fb7df8crpluem} lwres_gabnrequest_t;
1af2b28846e2647963db788b081676884fb7df8crpluem</programlisting>
845258fbf5102b8b09fe9b7f4cb4ea4c089344c3poiriertypedef struct {
5d36cddfe00d5c6ad18845fcc04e6f7662050fafminfrin lwres_uint32_t flags;
5d36cddfe00d5c6ad18845fcc04e6f7662050fafminfrin lwres_uint16_t naliases;
5d36cddfe00d5c6ad18845fcc04e6f7662050fafminfrin lwres_uint16_t naddrs;
20aa41f86a5b451529d26d9b901eea69989e5c0aminfrin char *realname;
20aa41f86a5b451529d26d9b901eea69989e5c0aminfrin char **aliases;
20aa41f86a5b451529d26d9b901eea69989e5c0aminfrin lwres_uint16_t realnamelen;
8c92aeeb75b1b393f61a3e01c495484737a0ff8cminfrin lwres_uint16_t *aliaslen;
8c92aeeb75b1b393f61a3e01c495484737a0ff8cminfrin lwres_addrlist_t addrs;
8c92aeeb75b1b393f61a3e01c495484737a0ff8cminfrin void *base;
1018201f5223624476334c6e23aead02db7c4040minfrin size_t baselen;
1018201f5223624476334c6e23aead02db7c4040minfrin} lwres_gabnresponse_t;
e5db2522dbe503cbf5399094b6239c88c246a8c5poirier</programlisting>
e5db2522dbe503cbf5399094b6239c88c246a8c5poirier <para><function>lwres_gabnrequest_render()</function>
ad7e5e9fb8f63a5155bb392114162997505ff772minfrin uses resolver context <parameter>ctx</parameter> to convert
ad7e5e9fb8f63a5155bb392114162997505ff772minfrin getaddrbyname request structure <parameter>req</parameter> to
ad7e5e9fb8f63a5155bb392114162997505ff772minfrin canonical format. The packet header structure
ad7e5e9fb8f63a5155bb392114162997505ff772minfrin <parameter>pkt</parameter> is initialised and transferred to
59cb8d601b8c44476e59310f68b9c373d8fc62a6minfrin The contents of <parameter>*req</parameter> are then appended to
59cb8d601b8c44476e59310f68b9c373d8fc62a6minfrin the buffer in canonical format.
59cb8d601b8c44476e59310f68b9c373d8fc62a6minfrin <function>lwres_gabnresponse_render()</function> performs the
59cb8d601b8c44476e59310f68b9c373d8fc62a6minfrin same task, except it converts a getaddrbyname response structure
ec8b1faa56744b338f6d6421144b56c2bb3faae6poirier <type>lwres_gabnresponse_t</type> to the lightweight resolver's
ec8b1faa56744b338f6d6421144b56c2bb3faae6poirier canonical format.
87e0bf269cc3386ee8e6ab561ff00770151f4f53niq uses context <parameter>ctx</parameter> to convert the contents
3c67b7956d44501360506a9f13a5011be73b30ecminfrin <parameter>b</parameter> provides space to be used for storing
3c67b7956d44501360506a9f13a5011be73b30ecminfrin this structure. When the function succeeds, the resulting
3c67b7956d44501360506a9f13a5011be73b30ecminfrin <type>lwres_gabnrequest_t</type> is made available through
97d20d37d21b8d427a920e211858172f0a82427epoirier <function>lwres_gabnresponse_parse()</function> offers the same
8e04e8ec7d682bff5e6dccdd70c082971a88cb8bniq semantics as <function>lwres_gabnrequest_parse()</function>
8e04e8ec7d682bff5e6dccdd70c082971a88cb8bniq except it yields a <type>lwres_gabnresponse_t</type> structure.
53c999a82fcca729dabc8a512b3fb996d61fd814niq and <function>lwres_gabnrequest_free()</function> release the
53c999a82fcca729dabc8a512b3fb996d61fd814niq memory in resolver context <parameter>ctx</parameter> that was
25d0f8adcab13255494a3572edff1a25f6fbeea3rpluem allocated to the <type>lwres_gabnresponse_t</type> or
25d0f8adcab13255494a3572edff1a25f6fbeea3rpluem <type>lwres_gabnrequest_t</type> structures referenced via
dd9ae259e1578c4388739c880ede97c55cec543frpluem Any memory associated with ancillary buffers and strings for
dd9ae259e1578c4388739c880ede97c55cec543frpluem those structures is also discarded.
0938450cadc9a083d112a86bc7dd7ae34f791364trawick </refsect1>
8bed7ee6d97933b958e97e222f37154d83e384e5jorton The getaddrbyname opcode functions
43d051c8401a1f3b4f7853cd897d3565ab814ea7poirier on success.
43d051c8401a1f3b4f7853cd897d3565ab814ea7poirier They return
2f34374f6e04b9094a1d13a5ed823f331ba841a3rpluem if memory allocation fails.
2f34374f6e04b9094a1d13a5ed823f331ba841a3rpluem is returned if the available space in the buffer
7a25b029b69f169bd22718165dff3b271114f92eniq is too small to accommodate the packet header or the
3e6a46d2fecf446daf0e280a49fa5565f5f635eajorton structures.
0df8f79d2324b131c36955d7e474a735a762f9eeniq will return
30e3e760b737f13ce800fa02c5930ade7659ba66niq if the buffer is not empty after decoding the received packet.
30e3e760b737f13ce800fa02c5930ade7659ba66niq These functions will return
e991c6fc032c59eb6cb751d9d382e933a53a2866niq in the packet header structure
9a00e2d46c44c111d6952e553a2f1a61b7594eb3rpluem indicate that the packet is not a response to an earlier query.
9a00e2d46c44c111d6952e553a2f1a61b7594eb3rpluem </refsect1>
da128c59ec571c4dff70f41ecba9c8a9974c6cd6niq <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
172e83c0f024fe6396dd1f3ca3492fd83c304db5jim </citerefentry>
45932a847f237b4d8f0667b138bd3f8a15fb53ffniq </refsect1>
45932a847f237b4d8f0667b138bd3f8a15fb53ffniq - Local variables:
186e9d990f453d16826ab87a87df7b87e6e05921rpluem - mode: sgml