lwres_gabn.docbook revision 938440694b33cd752e9e4b71a526368b4811c177
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User [<!ENTITY mdash "—">]>
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User - Copyright (C) 2000, 2001 Internet Software Consortium.
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User - Permission to use, copy, modify, and/or distribute this software for any
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User - purpose with or without fee is hereby granted, provided that the above
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User - copyright notice and this permission notice appear in all copies.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
f9ce6280cec79deb16ff6d9807aa493ff23e10d9Tinderbox User - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User - PERFORMANCE OF THIS SOFTWARE.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <refentryinfo>
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User </refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </copyright>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User <refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User </refnamediv>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User <refsynopsisdiv>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <funcsynopsis>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User<funcprototype>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userlwres_result_t
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User<function>lwres_gabnrequest_render</function></funcdef>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User <paramdef>lwres_gabnrequest_t *<parameter>req</parameter></paramdef>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User </funcprototype>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User<funcprototype>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userlwres_result_t
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<function>lwres_gabnresponse_render</function></funcdef>
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <paramdef>lwres_gabnresponse_t *<parameter>req</parameter></paramdef>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
801d3c8888d6026eb1fd31c23e51e4f54dbc317eTinderbox User <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
801d3c8888d6026eb1fd31c23e51e4f54dbc317eTinderbox User </funcprototype>
adabefa84c3dcf048566cc23fd457c577f208eeaTinderbox User<funcprototype>
adabefa84c3dcf048566cc23fd457c577f208eeaTinderbox Userlwres_result_t
adabefa84c3dcf048566cc23fd457c577f208eeaTinderbox User<function>lwres_gabnrequest_parse</function></funcdef>
adabefa84c3dcf048566cc23fd457c577f208eeaTinderbox User <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
801d3c8888d6026eb1fd31c23e51e4f54dbc317eTinderbox User <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
801d3c8888d6026eb1fd31c23e51e4f54dbc317eTinderbox User <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User </funcprototype>
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User<funcprototype>
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox Userlwres_result_t
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User<function>lwres_gabnresponse_parse</function></funcdef>
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User </funcprototype>
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User<funcprototype>
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox User<function>lwres_gabnresponse_free</function></funcdef>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox User <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User </funcprototype>
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User<funcprototype>
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User<function>lwres_gabnrequest_free</function></funcdef>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User </funcprototype>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User</funcsynopsis>
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User </refsynopsisdiv>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User These are low-level routines for creating and parsing
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lightweight resolver name-to-address lookup request and
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User response messages.
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User There are four main functions for the getaddrbyname opcode.
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User One render function converts a getaddrbyname request structure —
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User to the lighweight resolver's canonical format.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User It is complemented by a parse function that converts a packet in this
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User canonical format to a getaddrbyname request structure.
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User Another render function converts the getaddrbyname response structure
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User — <type>lwres_gabnresponse_t</type> —
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User to the canonical format.
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User This is complemented by a parse function which converts a packet in
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User canonical format to a getaddrbyname response structure.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User These structures are defined in
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User They are shown below.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</programlisting>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Usertypedef struct lwres_addr lwres_addr_t;
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox Usertypedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User</programlisting>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Usertypedef struct {
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_uint32_t flags;
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_uint32_t addrtypes;
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_uint16_t namelen;
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User} lwres_gabnrequest_t;
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User</programlisting>
f33abec8a62ab6f2b867d7189dfffa72592c027bTinderbox Usertypedef struct {
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_uint32_t flags;
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User lwres_uint16_t naliases;
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User lwres_uint16_t naddrs;
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User char *realname;
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User char **aliases;
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User lwres_uint16_t realnamelen;
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User lwres_uint16_t *aliaslen;
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User lwres_addrlist_t addrs;
fb2e132c5c1246d709ade9a2b3dad5ad72d35c5cTinderbox User size_t baselen;
fb2e132c5c1246d709ade9a2b3dad5ad72d35c5cTinderbox User} lwres_gabnresponse_t;
fb2e132c5c1246d709ade9a2b3dad5ad72d35c5cTinderbox User</programlisting>
fb2e132c5c1246d709ade9a2b3dad5ad72d35c5cTinderbox User <para><function>lwres_gabnrequest_render()</function>
fb2e132c5c1246d709ade9a2b3dad5ad72d35c5cTinderbox User uses resolver context <parameter>ctx</parameter> to convert
fb2e132c5c1246d709ade9a2b3dad5ad72d35c5cTinderbox User getaddrbyname request structure <parameter>req</parameter> to
fb2e132c5c1246d709ade9a2b3dad5ad72d35c5cTinderbox User canonical format. The packet header structure
fb2e132c5c1246d709ade9a2b3dad5ad72d35c5cTinderbox User <parameter>pkt</parameter> is initialised and transferred to
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User The contents of <parameter>*req</parameter> are then appended to
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User the buffer in canonical format.
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User <function>lwres_gabnresponse_render()</function> performs the
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User same task, except it converts a getaddrbyname response structure
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User <type>lwres_gabnresponse_t</type> to the lightweight resolver's
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User canonical format.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <para><function>lwres_gabnrequest_parse()</function>
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User uses context <parameter>ctx</parameter> to convert the contents
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User <type>lwres_gabnrequest_t</type> structure. Buffer
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User <parameter>b</parameter> provides space to be used for storing
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User this structure. When the function succeeds, the resulting
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <type>lwres_gabnrequest_t</type> is made available through
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User <function>lwres_gabnresponse_parse()</function> offers the same
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User semantics as <function>lwres_gabnrequest_parse()</function>
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User except it yields a <type>lwres_gabnresponse_t</type> structure.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <para><function>lwres_gabnresponse_free()</function>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User and <function>lwres_gabnrequest_free()</function> release the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User memory in resolver context <parameter>ctx</parameter> that was
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User allocated to the <type>lwres_gabnresponse_t</type> or
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User <type>lwres_gabnrequest_t</type> structures referenced via
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User Any memory associated with ancillary buffers and strings for
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User those structures is also discarded.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt The getaddrbyname opcode functions
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User <function>lwres_gabnrequest_render()</function>,
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User <function>lwres_gabnresponse_render()</function>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <function>lwres_gabnrequest_parse()</function>
0da02c26a6631c25f075a8e4ac6de9e58f49a0c2Tinderbox User <function>lwres_gabnresponse_parse()</function>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt if memory allocation fails.
ffe29868b4bbc64953fc5d0de51f988c20158967Tinderbox User is returned if the available space in the buffer
ffe29868b4bbc64953fc5d0de51f988c20158967Tinderbox User is too small to accommodate the packet header or the
ffe29868b4bbc64953fc5d0de51f988c20158967Tinderbox User <function>lwres_gabnrequest_parse()</function>
ffe29868b4bbc64953fc5d0de51f988c20158967Tinderbox User <function>lwres_gabnresponse_parse()</function>
ffe29868b4bbc64953fc5d0de51f988c20158967Tinderbox User if the buffer is not empty after decoding the received packet.
ffe29868b4bbc64953fc5d0de51f988c20158967Tinderbox User These functions will return
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt in the packet header structure
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt indicate that the packet is not a response to an earlier query.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - Local variables:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - mode: sgml