lwres_gabn.docbook revision c651f15b30f1dae5cc2f00878fb5da5b3a35a468
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - Copyright (C) 2000, 2001 Internet Software Consortium.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - Permission to use, copy, modify, and distribute this software for any
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - purpose with or without fee is hereby granted, provided that the above
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - copyright notice and this permission notice appear in all copies.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - PERFORMANCE OF THIS SOFTWARE.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<!-- $Id: lwres_gabn.docbook,v 1.5 2005/04/07 03:50:01 marka Exp $ -->
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentryinfo>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein</refentryinfo>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein</refnamediv>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<refsynopsisdiv>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<funcsynopsis>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<funcprototype>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userlwres_result_t
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User<function>lwres_gabnrequest_render</function></funcdef>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</funcprototype>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<funcprototype>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntlwres_result_t
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<function>lwres_gabnresponse_render</function></funcdef>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein</funcprototype>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<funcprototype>
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userlwres_result_t
f9ce6280cec79deb16ff6d9807aa493ff23e10d9Tinderbox User<function>lwres_gabnrequest_parse</function></funcdef>
46472a450e043434d78fa18edc73bca8c47f3981Tinderbox User<paramdef>lwres_gabnrequest_t **structp</paramdef>
46472a450e043434d78fa18edc73bca8c47f3981Tinderbox User</funcprototype>
e285c11870c6263cd79b418e104c7eb3e2d96952Tinderbox User<funcprototype>
46472a450e043434d78fa18edc73bca8c47f3981Tinderbox Userlwres_result_t
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<function>lwres_gabnresponse_parse</function></funcdef>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<paramdef>lwres_gabnresponse_t **structp</paramdef>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</funcprototype>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<funcprototype>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<function>lwres_gabnresponse_free</function></funcdef>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<paramdef>lwres_gabnresponse_t **structp</paramdef>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</funcprototype>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<funcprototype>
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User<function>lwres_gabnrequest_free</function></funcdef>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User<paramdef>lwres_gabnrequest_t **structp</paramdef>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User</funcprototype>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User</funcsynopsis>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User</refsynopsisdiv>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserThese are low-level routines for creating and parsing
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userlightweight resolver name-to-address lookup request and
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userresponse messages.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserThere are four main functions for the getaddrbyname opcode.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserOne render function converts a getaddrbyname request structure —
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userto the lighweight resolver's canonical format.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserIt is complemented by a parse function that converts a packet in this
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Usercanonical format to a getaddrbyname request structure.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserAnother render function converts the getaddrbyname response structure —
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userto the canonical format.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserThis is complemented by a parse function which converts a packet in
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Usercanonical format to a getaddrbyname response structure.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserThese structures are defined in
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThey are shown below.
6b7cba2b10d6cb5363d94b434b0d22ecfb33a6f3Tinderbox User<programlisting>
e2f974003e61b59321a99f01a6f43576d9b76231Tinderbox User#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
e2f974003e61b59321a99f01a6f43576d9b76231Tinderbox Usertypedef struct lwres_addr lwres_addr_t;
e2f974003e61b59321a99f01a6f43576d9b76231Tinderbox Usertypedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
6b7cba2b10d6cb5363d94b434b0d22ecfb33a6f3Tinderbox Usertypedef struct {
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User lwres_uint32_t flags;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User lwres_uint32_t addrtypes;
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt lwres_uint16_t namelen;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User} lwres_gabnrequest_t;
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Usertypedef struct {
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User lwres_uint32_t flags;
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User lwres_uint16_t naliases;
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User lwres_uint16_t naddrs;
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User char *realname;
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User char **aliases;
1ffe3f29e3cd0d8355500e9fd34de918ad9b4a01Tinderbox User lwres_uint16_t realnamelen;
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User lwres_uint16_t *aliaslen;
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User lwres_addrlist_t addrs;
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User size_t baselen;
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User} lwres_gabnresponse_t;
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User</programlisting>
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User<function>lwres_gabnrequest_render()</function>
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Useruses resolver context
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userto convert getaddrbyname request structure
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userto canonical format.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserThe packet header structure
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Useris initialised and transferred to
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserThe contents of
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userare then appended to the buffer in canonical format.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User<function>lwres_gabnresponse_render()</function>
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userperforms the same task, except it converts a getaddrbyname response structure
3ba1f79ade054aa6a0dc5032502bcdcf357cd7bdTinderbox Userto the lightweight resolver's canonical format.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<function>lwres_gabnrequest_parse()</function>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntto convert the contents of packet
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntprovides space to be used for storing this structure.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntWhen the function succeeds, the resulting
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntis made available through
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntoffers the same semantics as
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntexcept it yields a
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntrelease the memory in resolver context
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userthat was allocated to the
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userstructures referenced via
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntAny memory associated with ancillary buffers and strings for those
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntstructures is also discarded.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThe getaddrbyname opcode functions
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntif memory allocation fails.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntis returned if the available space in the buffer
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntis too small to accommodate the packet header or the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntif the buffer is not empty after decoding the received packet.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThese functions will return
76cf91b5df7a1bc450afcb9ce7585c61bb87de68Tinderbox Userin the packet header structure
76cf91b5df7a1bc450afcb9ce7585c61bb87de68Tinderbox Userindicate that the packet is not a response to an earlier query.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User<citerefentry>
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User<refentrytitle>lwres_packet</refentrytitle><manvolnum>3
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>