lwres_gabn.docbook revision d4ef65050feac78554addf6e16a06c6e2e0bd331
803b50652fd6ad81d04d18fc04332c8a94f8fe9aAndreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews - Copyright (C) 2001 Internet Software Consortium.
4a14ce5ba00ab7bc55c99ffdcf59c7a4ab902721Automatic Updater - Permission to use, copy, modify, and distribute this software for any
803b50652fd6ad81d04d18fc04332c8a94f8fe9aAndreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
803b50652fd6ad81d04d18fc04332c8a94f8fe9aAndreas Gustafsson - copyright notice and this permission notice appear in all copies.
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
803b50652fd6ad81d04d18fc04332c8a94f8fe9aAndreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<!-- $Id: lwres_gabn.docbook,v 1.2 2001/04/10 21:51:29 bwelling Exp $ -->
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein</refentryinfo>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein</refnamediv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<refsynopsisdiv>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<funcsynopsis>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<funcprototype>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<function>lwres_gabnrequest_render</function></funcdef>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein</funcprototype>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<funcprototype>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<function>lwres_gabnresponse_render</function></funcdef>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein</funcprototype>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<funcprototype>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<function>lwres_gabnrequest_parse</function></funcdef>
731cc132f22dbc9e0ecd7035dce314a61076d31bAutomatic Updater<paramdef>lwres_gabnrequest_t **structp</paramdef>
731cc132f22dbc9e0ecd7035dce314a61076d31bAutomatic Updater</funcprototype>
731cc132f22dbc9e0ecd7035dce314a61076d31bAutomatic Updater<funcprototype>
351b62535d4c4f89883bfdba025999dd32490266Evan Huntlwres_result_t
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<function>lwres_gabnresponse_parse</function></funcdef>
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater<paramdef>lwres_gabnresponse_t **structp</paramdef>
d060d8669f5558690e7faf4a1c12fe5c02a7c60dAutomatic Updater</funcprototype>
d060d8669f5558690e7faf4a1c12fe5c02a7c60dAutomatic Updater<funcprototype>
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater<function>lwres_gabnresponse_free</function></funcdef>
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater<paramdef>lwres_gabnresponse_t **structp</paramdef>
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater</funcprototype>
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater<funcprototype>
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater<function>lwres_gabnrequest_free</function></funcdef>
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater<paramdef>lwres_gabnrequest_t **structp</paramdef>
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater</funcprototype>
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater</funcsynopsis>
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater</refsynopsisdiv>
d060d8669f5558690e7faf4a1c12fe5c02a7c60dAutomatic UpdaterThese are low-level routines for creating and parsing
d060d8669f5558690e7faf4a1c12fe5c02a7c60dAutomatic Updaterlightweight resolver name-to-address lookup request and
d060d8669f5558690e7faf4a1c12fe5c02a7c60dAutomatic Updaterresponse messages.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThere are four main functions for the getaddrbyname opcode.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinOne render function converts a getaddrbyname request structure —
7329012471d165cd3dc4180ad2a0a43de91e7f01Mark Andrewsto the lighweight resolver's canonical format.
7329012471d165cd3dc4180ad2a0a43de91e7f01Mark AndrewsIt is complemented by a parse function that converts a packet in this
351b62535d4c4f89883bfdba025999dd32490266Evan Huntcanonical format to a getaddrbyname request structure.
351b62535d4c4f89883bfdba025999dd32490266Evan HuntAnother render function converts the getaddrbyname response structure —
351b62535d4c4f89883bfdba025999dd32490266Evan Huntto the canonical format.
351b62535d4c4f89883bfdba025999dd32490266Evan HuntThis is complemented by a parse function which converts a packet in
7329012471d165cd3dc4180ad2a0a43de91e7f01Mark Andrewscanonical format to a getaddrbyname response structure.
351b62535d4c4f89883bfdba025999dd32490266Evan HuntThese structures are defined in
351b62535d4c4f89883bfdba025999dd32490266Evan HuntThey are shown below.
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt<programlisting>
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeintypedef struct lwres_addr lwres_addr_t;
351b62535d4c4f89883bfdba025999dd32490266Evan Hunttypedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
351b62535d4c4f89883bfdba025999dd32490266Evan Hunttypedef struct {
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt lwres_uint32_t flags;
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt lwres_uint32_t addrtypes;
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt lwres_uint16_t namelen;
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt} lwres_gabnrequest_t;
351b62535d4c4f89883bfdba025999dd32490266Evan Hunttypedef struct {
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_uint32_t flags;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_uint16_t naliases;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_uint16_t naddrs;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein char *realname;
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater char **aliases;
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt lwres_uint16_t realnamelen;
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt lwres_uint16_t *aliaslen;
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt lwres_addrlist_t addrs;
90c38ab4e6904126bec2f2f57f60cd834ce759cbAutomatic Updater size_t baselen;
351b62535d4c4f89883bfdba025999dd32490266Evan Hunt} lwres_gabnresponse_t;
3cddb2c552ee6582e8db0849c28747f6b6ca57feAutomatic Updater</programlisting>
ed4475f3f583f6137b4ff7fea775c5363a4fdb29Automatic Updater<function>lwres_gabnrequest_render()</function>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinuses resolver context
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinto convert getaddrbyname request structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinto canonical format.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe packet header structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinis initialised and transferred to
351b62535d4c4f89883bfdba025999dd32490266Evan HuntThe contents of
351b62535d4c4f89883bfdba025999dd32490266Evan Huntare then appended to the buffer in canonical format.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinperforms the same task, except it converts a getaddrbyname response structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinto the lightweight resolver's canonical format.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinto convert the contents of packet
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinprovides space to be used for storing this structure.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinWhen the function succeeds, the resulting
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinis made available through
f02216f5b390ff0a589fa080f29350fd7794bf5cMark Andrewsoffers the same semantics as
f02216f5b390ff0a589fa080f29350fd7794bf5cMark Andrewsexcept it yields a
ea94d370123a5892f6c47a97f21d1b28d44bb168Tinderbox Userrelease the memory in resolver context
ea94d370123a5892f6c47a97f21d1b28d44bb168Tinderbox Userthat was allocated to the
ea94d370123a5892f6c47a97f21d1b28d44bb168Tinderbox Userstructures referenced via
ea94d370123a5892f6c47a97f21d1b28d44bb168Tinderbox UserAny memory associated with ancillary buffers and strings for those
ea94d370123a5892f6c47a97f21d1b28d44bb168Tinderbox Userstructures is also discarded.
b46346eb3026ba4bebc093bc93cfe159131e541eTinderbox UserThe getaddrbyname opcode functions
b46346eb3026ba4bebc093bc93cfe159131e541eTinderbox User<function>lwres_gabnrequest_render()</function>,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinif memory allocation fails.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinis returned if the available space in the buffer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinis too small to accommodate the packet header or the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinif the buffer is not empty after decoding the received packet.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThese functions will return
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinin the packet header structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinindicate that the packet is not a response to an earlier query.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<citerefentry>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<refentrytitle>lwres_packet</refentrytitle><manvolnum>3
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein</citerefentry>