lwres.html revision 5bb39eeafa9c0a30b51f0473c45d7a29fa75dbc5
65b0f0cd3c38007138720b7eaa43c963a9ee1244vboxsync - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
ea7d33962ceb90ea90e67e427d60b5788f34268avboxsync - Copyright (C) 2000, 2001 Internet Software Consortium.
65b0f0cd3c38007138720b7eaa43c963a9ee1244vboxsync - Permission to use, copy, modify, and distribute this software for any
65b0f0cd3c38007138720b7eaa43c963a9ee1244vboxsync - purpose with or without fee is hereby granted, provided that the above
c58f1213e628a545081c70e26c6b67a841cff880vboxsync - copyright notice and this permission notice appear in all copies.
65b0f0cd3c38007138720b7eaa43c963a9ee1244vboxsync - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
65b0f0cd3c38007138720b7eaa43c963a9ee1244vboxsync - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
65b0f0cd3c38007138720b7eaa43c963a9ee1244vboxsync - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync - PERFORMANCE OF THIS SOFTWARE.
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync<!-- $Id: lwres.html,v 1.16 2005/09/15 23:02:36 marka Exp $ -->
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
65b0f0cd3c38007138720b7eaa43c963a9ee1244vboxsync<a name="id2456972"></a><div class="titlepage"></div>
cf57145d4697dceca3f0542b370c20f7a2c5c6e8vboxsync<p>lwres — introduction to the lightweight resolver library</p>
65b0f0cd3c38007138720b7eaa43c963a9ee1244vboxsync<div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre></div>
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync The BIND 9 lightweight resolver library is a simple, name service
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync independent stub resolver library. It provides hostname-to-address
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync and address-to-hostname lookup services to applications by
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync transmitting lookup requests to a resolver daemon
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync <span><strong class="command">lwresd</strong></span>
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync running on the local host. The resover daemon performs the
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync lookup using the DNS or possibly other name service protocols,
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync and returns the results to the application through the library.
560a1042a968cf73161ac78555eddc8d16e8bebdvboxsync The library and resolver daemon communicate using a simple
560a1042a968cf73161ac78555eddc8d16e8bebdvboxsync UDP-based protocol.
e52b0dfe3d9ead70e24f2ce4ed3faa6c79c00618vboxsync The lwresd library implements multiple name service APIs.
e52b0dfe3d9ead70e24f2ce4ed3faa6c79c00618vboxsync The standard
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync functions are all supported. To allow the lwres library to coexist
c320aee99660824809e157bbad368db3542a9e90vboxsync with system libraries that define functions of the same name,
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync the library defines these functions with names prefixed by
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync To define the standard names, applications must include the
ab455939477d81b7bb500586f88029d3a3c0b34cvboxsync header file
ab455939477d81b7bb500586f88029d3a3c0b34cvboxsync <code class="filename"><lwres/netdb.h></code>
ea7d33962ceb90ea90e67e427d60b5788f34268avboxsync which contains macro definitions mapping the standard function names
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync prefixed ones. Operating system vendors who integrate the lwres
f9f72da3edbd8434dc722c26ee038e2808d691favboxsync library into their base distributions should rename the functions
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync in the library proper so that the renaming macros are not needed.
55870b5b46ea9754616dcc3663a110ce71927a0evboxsync The library also provides a native API consisting of the functions
55870b5b46ea9754616dcc3663a110ce71927a0evboxsync <code class="function">lwres_getaddrsbyname()</code>
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync <code class="function">lwres_getnamebyaddr()</code>.
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync These may be called by applications that require more detailed
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync control over the lookup process than the standard functions
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync In addition to these name service independent address lookup
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync functions, the library implements a new, experimental API
f2af1be3e27a2fefe95332260d360f4b26cffbcfvboxsync for looking up arbitrary DNS resource records, using the
75d8fea43f2d7474d00172dcf906f7ab598a8c8fvboxsync <code class="function">lwres_getaddrsbyname()</code>
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync Finally, there is a low-level API for converting lookup
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync requests and responses to and from raw lwres protocol packets.
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync This API can be used by clients requiring nonblocking operation,
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync and is also used when implementing the server side of the lwres
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync protocol, for example in the
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync <span><strong class="command">lwresd</strong></span>
eaae6c3ce81916ccc4e74af4b55972ba956cf5c8vboxsync resolver daemon. The use of this low-level API in clients
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync and servers is outlined in the following sections.
f1c8438d14b7420eb2b916ef5981ac09faa4f6c4vboxsync<a name="id2514737"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2>
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync When a client program wishes to make an lwres request using the
b6dc9545438e63d05fff621e85ddb7dc39cf14e7vboxsync native low-level API, it typically performs the following
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync sequence of actions.
20593760b116c90f3e439552763eef632a3bbb17vboxsync (1) Allocate or use an existing <span class="type">lwres_packet_t</span>,
46f5824f3e233b92bad1626932d5ce9522886f54vboxsync (2) Set <em class="structfield"><code>pkt.recvlength</code></em> to the maximum length
46f5824f3e233b92bad1626932d5ce9522886f54vboxsync we will accept.
46f5824f3e233b92bad1626932d5ce9522886f54vboxsync This is done so the receiver of our packets knows how large our receive
46f5824f3e233b92bad1626932d5ce9522886f54vboxsync buffer is. The "default" is a constant in
881b5ff6bc55e1fb0f4ef42f9782ccec79c0a138vboxsync <code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>.
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync (3) Set <em class="structfield"><code>pkt.serial</code></em>
17ef1920962b3df57bf6d2704ced1586396d96f0vboxsync to a unique serial number. This value is echoed
17ef1920962b3df57bf6d2704ced1586396d96f0vboxsync back to the application by the remote server.
17ef1920962b3df57bf6d2704ced1586396d96f0vboxsync (4) Set <em class="structfield"><code>pkt.pktflags</code></em>. Usually this is set to
17ef1920962b3df57bf6d2704ced1586396d96f0vboxsync (5) Set <em class="structfield"><code>pkt.result</code></em> to 0.
17ef1920962b3df57bf6d2704ced1586396d96f0vboxsync (6) Call <code class="function">lwres_*request_render()</code>,
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync or marshall in the data using the primitives
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync such as <code class="function">lwres_packet_render()</code>
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync and storing the packet data.
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync (7) Transmit the resulting buffer.
63e576f3c901db19ac9a11f2353025b66a6798eevboxsync (8) Call <code class="function">lwres_*response_parse()</code>
63e576f3c901db19ac9a11f2353025b66a6798eevboxsync to parse any packets received.
881b5ff6bc55e1fb0f4ef42f9782ccec79c0a138vboxsync (9) Verify that the opcode and serial match a request, and process the
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync packet specific information contained in the body.
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync<a name="id2514885"></a><h2>SERVER-SIDE LOW-LEVEL API CALL FLOW</h2>
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync When implementing the server side of the lightweight resolver
0b4890533cbae4f30a0241d0780d4ff9daa304f4vboxsync protocol using the lwres library, a sequence of actions like the
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync following is typically involved in processing each request packet.
7e33622becf3d7cf9a2401ac0c53d315877f6e34vboxsync Note that the same <span class="type">lwres_packet_t</span> is used
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync in both the <code class="function">_parse()</code> and <code class="function">_render()</code> calls,
7e33622becf3d7cf9a2401ac0c53d315877f6e34vboxsync with only a few modifications made
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync to the packet header's contents between uses. This method is
a1e9b93d4f2b32d7a2aac1fb6ee958e1d147197cvboxsync recommended
a1e9b93d4f2b32d7a2aac1fb6ee958e1d147197cvboxsync as it keeps the serial, opcode, and other fields correct.
881b5ff6bc55e1fb0f4ef42f9782ccec79c0a138vboxsync (1) When a packet is received, call <code class="function">lwres_*request_parse()</code> to
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync unmarshall it. This returns a <span class="type">lwres_packet_t</span> (also called <code class="varname">pkt</code>, below)
20593760b116c90f3e439552763eef632a3bbb17vboxsync as well as a data specific type, such as <span class="type">lwres_gabnrequest_t</span>.
c0cb47bd8aa02fca08ff72a37ba5c65894241cbfvboxsync (2) Process the request in the data specific type.
8c3ab623787ffed571ef7a1fa8c1a98e22d28021vboxsync (3) Set the <em class="structfield"><code>pkt.result</code></em>,
96d5bb6dc5895c648c1f60b3d4faef7b93404756vboxsync <em class="structfield"><code>pkt.recvlength</code></em> as above. All other fields
8c48cf39dfb84c1f26e0e7fbd1c407e25a34eef1vboxsync be left untouched since they were filled in by the <code class="function">*_parse()</code> call
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync above. If using <code class="function">lwres_*response_render()</code>,
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync <em class="structfield"><code>pkt.pktflags</code></em> will be set up
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync (4) Call the data specific rendering function, such as
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync <code class="function">lwres_gabnresponse_render()</code>.
881b5ff6bc55e1fb0f4ef42f9782ccec79c0a138vboxsync (5) Send the resulting packet to the client.
d1ae44110ca869b6cb4a708dc6d676e10f4167bavboxsync<p><span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>,
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>,
20024c6bd4100e9925d1ff0516af5753814fc43dvboxsync <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>,
ac6ede0b256f7583f8673aef5347770437c003davboxsync <span class="citerefentry"><span class="refentrytitle">lwres_noop</span>(3)</span>,
ac6ede0b256f7583f8673aef5347770437c003davboxsync <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>,
ac6ede0b256f7583f8673aef5347770437c003davboxsync <span class="citerefentry"><span class="refentrytitle">lwres_gnba</span>(3)</span>,
ac6ede0b256f7583f8673aef5347770437c003davboxsync <span class="citerefentry"><span class="refentrytitle">lwres_context</span>(3)</span>,
ac6ede0b256f7583f8673aef5347770437c003davboxsync <span class="citerefentry"><span class="refentrytitle">lwres_config</span>(3)</span>,
ac6ede0b256f7583f8673aef5347770437c003davboxsync <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>,
ac6ede0b256f7583f8673aef5347770437c003davboxsync <span class="citerefentry"><span class="refentrytitle">lwresd</span>(8)</span>.