lwres_resutil.docbook revision ddccd5811feff696ba460dabfb666ce61040f545
4d237bbe075b1d2c19428cd954d721d65b31f67cwrowe<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
bf52162f2d05c1fb1a107c7ef108de73f739b3edpquerna - Copyright (C) 2000, 2001 Internet Software Consortium.
0938450cadc9a083d112a86bc7dd7ae34f791364trawick - Permission to use, copy, modify, and distribute this software for any
0938450cadc9a083d112a86bc7dd7ae34f791364trawick - purpose with or without fee is hereby granted, provided that the above
0938450cadc9a083d112a86bc7dd7ae34f791364trawick - copyright notice and this permission notice appear in all copies.
8bed7ee6d97933b958e97e222f37154d83e384e5jorton - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
8bed7ee6d97933b958e97e222f37154d83e384e5jorton - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
8bed7ee6d97933b958e97e222f37154d83e384e5jorton - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
8bed7ee6d97933b958e97e222f37154d83e384e5jorton - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
d33ddda47790d3295f4218f87e3a296cf51a9becmjc - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
c7d46b58052fe666c74a47bd26b6cb1e351492adrpluem - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
4e08c8c1a91e2887b41d8cacd3aa532355d0237drpluem - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
7a25b029b69f169bd22718165dff3b271114f92eniq - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
43d051c8401a1f3b4f7853cd897d3565ab814ea7poirier<!-- $Id: lwres_resutil.docbook,v 1.1 2001/03/31 00:08:23 gson Exp $ -->
2f34374f6e04b9094a1d13a5ed823f331ba841a3rpluem <refentryinfo>
2f34374f6e04b9094a1d13a5ed823f331ba841a3rpluem</refentryinfo>
0df8f79d2324b131c36955d7e474a735a762f9eeniq<refnamediv>
e991c6fc032c59eb6cb751d9d382e933a53a2866niq<refpurpose>lightweight resolver utility functions</refpurpose>
e991c6fc032c59eb6cb751d9d382e933a53a2866niq</refnamediv>
e991c6fc032c59eb6cb751d9d382e933a53a2866niq<refsynopsisdiv>
e991c6fc032c59eb6cb751d9d382e933a53a2866niq<funcsynopsis>
9a00e2d46c44c111d6952e553a2f1a61b7594eb3rpluem<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
9a00e2d46c44c111d6952e553a2f1a61b7594eb3rpluem<funcprototype>
33d9be77cc6f5fc8734e9c1f526b82d359955152rpluemlwres_result_t
da128c59ec571c4dff70f41ecba9c8a9974c6cd6niq</funcprototype>
45932a847f237b4d8f0667b138bd3f8a15fb53ffniq<funcprototype>
45932a847f237b4d8f0667b138bd3f8a15fb53ffniqlwres_result_t
186e9d990f453d16826ab87a87df7b87e6e05921rpluem</funcprototype>
6861702c2d883e5c0744d5f7528d2060671ad24dtakashi<funcprototype>
6861702c2d883e5c0744d5f7528d2060671ad24dtakashilwres_result_t
292cb7b720095e7bb434d79ae53b02d332aeb99acovener</funcprototype>
292cb7b720095e7bb434d79ae53b02d332aeb99acovener<funcprototype>
292cb7b720095e7bb434d79ae53b02d332aeb99acovenerlwres_result_t
4e08c8c1a91e2887b41d8cacd3aa532355d0237drpluem</funcprototype>
d0cd62f11bcd8fa9bf758c5125f55cea5d9038dfrpluem</funcsynopsis>
d0cd62f11bcd8fa9bf758c5125f55cea5d9038dfrpluem</refsynopsisdiv>
27c7a7cad9e83eeebad0a4d5a321144394adc3f9trawickretrieves a DNS-encoded string starting the current pointer of
27c7a7cad9e83eeebad0a4d5a321144394adc3f9trawicklightweight resolver buffer
8f2700898323915da289644dc1f3ee11a5e5b4earpluemWhen the function returns, the address of the first byte of the
8f2700898323915da289644dc1f3ee11a5e5b4earpluemencoded string is returned via
e7983ce746b0df56a1b74b42da6d82f5ecb99349covenerand the length of that string is given by
e7983ce746b0df56a1b74b42da6d82f5ecb99349covenerThe buffer's current pointer is advanced to point at the character
bbcfb8ab8e22f90fdf346e9993bd58ba2203b182trawickfollowing the string length, the encoded string, and the trailing
d1745d6933c22c807cf2388332426defd1b19f03covenerhas an assertion check that
2db5d76ac4c75aadecf38e20569bccbfd2360ba7rpluemextracts an address from the buffer
1c03114a0f0315ed19a05f654021da9f66005897rjungIt checks that
89691c9bd17f5f53fa0aa8d3fe2e1faee5a5d984rpluemis not null.
89691c9bd17f5f53fa0aa8d3fe2e1faee5a5d984rpluemThe buffer's current pointer
89691c9bd17f5f53fa0aa8d3fe2e1faee5a5d984rpluemis presumed to point at an encoded address: the address preceded by a
3e9c0665b06e44cf776528c6954ed3ca34a77c7fsctemme32-bit protocol family identifier and a 16-bit length field.
51a475d92e7d68ee6d7b57aa7fd6e73b2712ce31sctemmeThe encoded address is copied to
6707208ba4e9a5841ca1ab830830fd286ea5b7c5trawickindicates the size in bytes of the address that was copied.
873c287c391b0bbc4719b68bb84946515811e1batrawickis advanced to point at the next byte of available data in the buffer
832853bb93c1831daf24e4727c5ca0e1b1786e83larsfollowing the encoded address.
1782dcd420de504978945e6b812523eeae6d56a2larsstructure defined below:
d2696ac6757b3d8bdaa27634a141ac8c8a045e08fielding<programlisting>
1782dcd420de504978945e6b812523eeae6d56a2larstypedef struct {
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluem lwres_uint32_t flags;
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluem lwres_uint16_t naliases;
59dc8d935dbf862712683bbc9e267bd08ced0b14fielding lwres_uint16_t naddrs;
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluem char *realname;
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluem char **aliases;
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluem lwres_uint16_t realnamelen;
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluem lwres_uint16_t *aliaslen;
cf8d02ea0c91653917b044529f3133c5a1bb9200fielding lwres_addrlist_t addrs;
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluem void *base;
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluem size_t baselen;
17ac330ebaa71b24cb77580411a231ee45996e03pquerna} lwres_gabnresponse_t;
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluem</programlisting>
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemThe contents of this structure are not manipulated directly but
9f38f3ec3e8087985d108a24ae796962fef83644takashithey are controlled through the
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluem<citerefentry>
d4ee4552489641d35d1195bbbd6021351c4b79aarjung</manvolnum>
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluem</citerefentry>
abb99af8aa7da2cb4c324133a4e10bd7a50f875erpluemThe lightweight resolver uses
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemto perform foward lookups.
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemis looked up using the resolver context
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemfor memory allocation.
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemis a bitmask indicating which type of addresses are to be looked up.
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemCurrent values for this bitmask are
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemfor IPv4 addresses and
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemfor IPv6 addresses.
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemResults of the lookup are returned in
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemchecks that its pointer arguments are not
df46ff21c57d00f6addccaaf9b1484f2b56b8577pquernais non-zero.
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemperforms reverse lookups.
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemResolver context
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemis used for memory allocation.
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemThe address type is indicated by
6824182b3b8e045db97a228d3127bdfcbdfeb0bcniqThe address to be looked up is given by
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemand its length is
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemThe result of the function call is made available through
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemuses assertion checking to ensure its pointer arguments are not
abc69b39766c0de3eaf99e9016ea3f35e23c116drpluemis not zero.
1464434c2c104e0ba224644c42552330f5158537coveneralso checks that
8d574b3ac4185e4f71c8b9aae76e7122a78201c4rpluemis non-zero.
509111f5f58a9effd4c832f6a0cbd6ad9d549188jortonSuccessful calls to
66b8ec445dced7a2036bcd3b87b6fc3f08a1ab24jortonBoth functions return
66b8ec445dced7a2036bcd3b87b6fc3f08a1ab24jortonif the buffer is corrupt or
0e2a2eae9b72ac099aa25d7419e55af13b004be9minfrinif the buffer has less space than expected for the components of the
0e2a2eae9b72ac099aa25d7419e55af13b004be9minfrinencoded string or address.
6f33babce8f8bc723f0b2c755aef049cd509504fpquernaon success and it returns
0a12339f39799193ac6866fce812a1deb8f4a1abpquernaif the hostname
3fb118bc4e1a634f71c1fa509819ceac36c79dcbpquernacould not be found.
fb59af4ce3fcdd314b848359faeddf1e51bb24c5jimis returned by a successful call to
a91a59d0b0ceed7cd5621fe8757eda5ff6a043a8pquernawhen memory allocation requests fail and
a91a59d0b0ceed7cd5621fe8757eda5ff6a043a8pquernaif the buffers used for sending queries and receiving replies are too
3ec1e3a35106ec4c8bcf8fae6a20cb623aed0b62pquerna<citerefentry>
3ec1e3a35106ec4c8bcf8fae6a20cb623aed0b62pquerna<refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
3ec1e3a35106ec4c8bcf8fae6a20cb623aed0b62pquerna</citerefentry>,
97f7daaffd9b6c1031302d7e551d5279fa0d0d72pquerna<citerefentry>
97f7daaffd9b6c1031302d7e551d5279fa0d0d72pquerna<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
847db8b2f0188cd9c840acbe4fea77a32748b2edpquerna</citerefentry>.