lwres.docbook revision 4b01d45a49f1c2cc4bddc9a1b4c78232867de134
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - Copyright (C) 2000, 2001 Internet Software Consortium.
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Permission to use, copy, modify, and distribute this software for any
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - 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 INTERNET SOFTWARE CONSORTIUM
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<!-- $Id: lwres.docbook,v 1.1 2001/03/29 02:43:28 gson Exp $ -->
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refentryinfo>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein</refentryinfo>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<refpurpose>introduction to the lightweight resolver library</refpurpose>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refsynopsisdiv>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<funcsynopsis>
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</funcsynopsis>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</refsynopsisdiv>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThe BIND 9 lightweight resolver library is a simple, name service
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntindependent stub resolver library. It provides hostname-to-address
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntand address-to-hostname lookup services to applications by
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunttransmitting lookup requests to a resolver daemon
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntrunning on the local host. The resover daemon performs the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntlookup using the DNS or possibly other name service protocols,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinand returns the results to the application through the library.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserThe library and resolver daemon communicate using a simple
f9ce6280cec79deb16ff6d9807aa493ff23e10d9Tinderbox UserUDP-based protocol.
46472a450e043434d78fa18edc73bca8c47f3981Tinderbox UserThe lwresd library implements multiple name service APIs.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntfunctions are all supported. To allow the lwres library to coexist
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userwith system libraries that define functions of the same name,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntthe library defines these functions with names prefixed by
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntTo define the standard names, applications must include the
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userwhich contains macro definitions mapping the standard function names
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userprefixed ones. Operating system vendors who integrate the lwres
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userlibrary into their base distributions should rename the functions
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userin the library proper so that the renaming macros are not needed.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserThe library also provides a native API consisting of the functions
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserThese may be called by applications that require more detailed
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Usercontrol over the lookup process than the standard functions
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserIn addition to these name service independent address lookup
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userfunctions, the library implements a new, experimental API
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userfor looking up arbitrary DNS resource records, using the
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserFinally, there is a low-level API for converting lookup
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userrequests and responses to and from raw lwres protocol packets.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserThis API can be used by clients requiring nonblocking operation,
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userand is also used when implementing the server side of the lwres
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userprotocol, for example in the
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userresolver daemon. The use of this low-level API in clients
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntand servers is outlined in the following sections.
e2f974003e61b59321a99f01a6f43576d9b76231Tinderbox User<title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title>
576bce9d7331498ca5453f8743f94ed8e2e59d9fTinderbox UserWhen a client program wishes to make an lwres request using the
6b7cba2b10d6cb5363d94b434b0d22ecfb33a6f3Tinderbox Usernative low-level API, it typically performs the following
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Usersequence of actions.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt(1) Allocate or use an existing <type>lwres_packet_t</type>,
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User(2) Set <structfield>pkt.recvlength</structfield> to the maximum length we will accept.
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserThis is done so the receiver of our packets knows how large our receive
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userbuffer is. The "default" is a constant in
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User<filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userto a unique serial number. This value is echoed
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userback to the application by the remote server.
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User(4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to 0.
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User(5) Set <structfield>pkt.result</structfield> to 0.
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User(6) Call <function>lwres_*request_render()</function>,
1ffe3f29e3cd0d8355500e9fd34de918ad9b4a01Tinderbox Useror marshall in the data using the primitives
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Usersuch as <function>lwres_packet_render()</function>
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userand storing the packet data.
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User(7) Transmit the resulting buffer.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User(8) Call <function>lwres_*response_parse()</function>
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userto parse any packets received.
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User(9) Verify that the opcode and serial match a request, and process the
3ba1f79ade054aa6a0dc5032502bcdcf357cd7bdTinderbox Userpacket specific information contained in the body.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntWhen implementing the server side of the lightweight resolver
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntprotocol using the lwres library, a sequence of actions like the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntfollowing is typically involved in processing each request packet.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntNote that the same <type>lwres_packet_t</type> is used
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntin both the <function>_parse()</function> and <function>_render()</function> calls,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntwith only a few modifications made
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntto the packet header's contents between uses. This method is recommended
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntas it keeps the serial, opcode, and other fields correct.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User(1) When a packet is received, call <function>lwres_*request_parse()</function> to
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntunmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntas well as a data specific type, such as <type>lwres_gabnrequest_t</type>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt(2) Process the request in the data specific type.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<structfield>pkt.recvlength</structfield> as above. All other fields can
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntbe left untouched since they were filled in by the <function>*_parse()</function> call
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntabove. If using <function>lwres_*response_render()</function>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<structfield>pkt.pktflags</structfield> will be set up
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntproperly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt(4) Call the data specific rendering function, such as
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<function>lwres_gabnresponse_render()</function>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt(5) Send the resulting packet to the client.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</citerefentry>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</citerefentry>,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</citerefentry>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
76cf91b5df7a1bc450afcb9ce7585c61bb87de68Tinderbox User<refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User</citerefentry>,
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User<citerefentry>
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User</citerefentry>,
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User<citerefentry>
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User<refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User</citerefentry>.