lwres_context.docbook revision dafcb997e390efa4423883dafd100c975c4095d6
c313914d0e66b20969215e519bbf2ab4ecf39512Tinderbox User<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
c80e152862cc3e3207dc837fde7116bd4c0e4b9dTinderbox User - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
8d1b3ceb4d491ce32572f1702f37ed585eede993Evan Hunt - Copyright (C) 2001, 2003 Internet Software Consortium.
d77cb075aae5595e460e3299bfc1e8ea5d42b560Evan Hunt - Permission to use, copy, modify, and distribute this software for any
d77cb075aae5595e460e3299bfc1e8ea5d42b560Evan Hunt - purpose with or without fee is hereby granted, provided that the above
30ca20f720ad0887772a79e7abb25b4fa0e4b5b0Mark Andrews - copyright notice and this permission notice appear in all copies.
30ca20f720ad0887772a79e7abb25b4fa0e4b5b0Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
30ca20f720ad0887772a79e7abb25b4fa0e4b5b0Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
30ca20f720ad0887772a79e7abb25b4fa0e4b5b0Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
701a93f5a592e4652343e049aa495d409c3ee133Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
7ec97ae74e42ec21b354fd2d1366313b41d947d6Evan Hunt - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
701a93f5a592e4652343e049aa495d409c3ee133Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
701a93f5a592e4652343e049aa495d409c3ee133Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
8f1ed05dc0aae7ae6c3da6ec6d405df61257a61eMark Andrews<!-- $Id: lwres_context.docbook,v 1.5 2004/03/05 05:12:56 marka Exp $ -->
8f1ed05dc0aae7ae6c3da6ec6d405df61257a61eMark Andrews<refentryinfo>
73cf0ba4e82c6baef638ecc4e31321223f841d28Mark Andrews</refentryinfo>
31c7ab4fb3f7710af87dc9c3d64c5daf9a3dea35Mark Andrews<refpurpose>lightweight resolver context management</refpurpose>
ad309e8dfa0601d6053aaa12770a98a6940f89deEvan Hunt</refnamediv>
ad309e8dfa0601d6053aaa12770a98a6940f89deEvan Hunt<refsynopsisdiv>
635e4351b04fd61ca6d853bdac6268c090b55129Mark Andrews<funcsynopsis>
635e4351b04fd61ca6d853bdac6268c090b55129Mark Andrews<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
fc04365d2f83f197c8a54545dd9cd4ce6a209940Mark Andrews<funcprototype>
7cbac360bf98c0a52b2d6866ad887616c32d4d3aMark Andrewslwres_result_t
7cbac360bf98c0a52b2d6866ad887616c32d4d3aMark Andrews<function>lwres_context_create</function></funcdef>
1cf118a656f5fd210787908b845362077fc507f8Evan Hunt<paramdef>lwres_malloc_t malloc_function</paramdef>
1cf118a656f5fd210787908b845362077fc507f8Evan Hunt</funcprototype>
1cf118a656f5fd210787908b845362077fc507f8Evan Hunt<funcprototype>
1cf118a656f5fd210787908b845362077fc507f8Evan Huntlwres_result_t
1cf118a656f5fd210787908b845362077fc507f8Evan Hunt<function>lwres_context_destroy</function></funcdef>
6fb3db01acad7f5c1f4e23789fb0f2ce56cc07deMukund Sivaraman<paramdef>lwres_context_t **contextp</paramdef>
6fb3db01acad7f5c1f4e23789fb0f2ce56cc07deMukund Sivaraman</funcprototype>
6fb3db01acad7f5c1f4e23789fb0f2ce56cc07deMukund Sivaraman<funcprototype>
fd82c70695888c134287b8018296028c252d100eMukund Sivaraman<function>lwres_context_initserial</function></funcdef>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews</funcprototype>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<funcprototype>
2cf0fe3b8092f64f8f68ae3693fe2e73e90ad1a4Mark Andrewslwres_uint32_t
2cf0fe3b8092f64f8f68ae3693fe2e73e90ad1a4Mark Andrews<function>lwres_context_nextserial</function></funcdef>
4221d9cd1d02311fbf9b5f08a038f5af78b10b4aEvan Hunt</funcprototype>
4221d9cd1d02311fbf9b5f08a038f5af78b10b4aEvan Hunt<funcprototype>
4221d9cd1d02311fbf9b5f08a038f5af78b10b4aEvan Hunt<function>lwres_context_freemem</function></funcdef>
f9c410d93711fbf312a0162f1e2d3f2a5ede69afFrancis Dupont</funcprototype>
e526027287b849f0b6ab6e069156697cbafa22c1Michał Kępień<funcprototype>
e526027287b849f0b6ab6e069156697cbafa22c1Michał Kępień<function>lwres_context_allocmem</function></funcdef>
929329d2d66a7e1083c70a9c918381935bf12799Mukund Sivaraman</funcprototype>
7e1a62eea2e4ba9d6c3fc718e679b965fa514f69Mark Andrews<funcprototype>
afefd754734f896bf3e0590177fff83e7cdfdf35Mark Andrews<function>lwres_context_sendrecv</function></funcdef>
7ff28f5befbee76048a23e504dcd3f9a44ce6209Evan Hunt</funcprototype>
7ff28f5befbee76048a23e504dcd3f9a44ce6209Evan Hunt</funcsynopsis>
7ff28f5befbee76048a23e504dcd3f9a44ce6209Evan Hunt</refsynopsisdiv>
cad79077bd5b2616bc4a7a6b3cbc0953bef8917fMark Andrewsstructure for use in lightweight resolver operations.
cad79077bd5b2616bc4a7a6b3cbc0953bef8917fMark AndrewsIt holds a socket and other data needed for communicating
cad79077bd5b2616bc4a7a6b3cbc0953bef8917fMark Andrewswith a resolver daemon.
adfe58e8e5cd1890585e92b67f1fd01989a1fa7dMark Andrewsis returned through
c3237dec879f82855403ff7e3ba87b298172efd5Mark Andrewsa pointer to a
c3237dec879f82855403ff7e3ba87b298172efd5Mark Andrewspointer. This
cb616c6d5c2ece1fac37fa6e0bca2b53d4043098Mark Andrewspointer must initially be NULL, and is modified
cb616c6d5c2ece1fac37fa6e0bca2b53d4043098Mark Andrewsto point to the newly created
534057c9f91a3eb6e0541f3526459c716239b337Mark AndrewsWhen the lightweight resolver needs to perform dynamic memory
534057c9f91a3eb6e0541f3526459c716239b337Mark Andrewsallocation, it will call
0f14b041328c062b1fa391887376388dfc8b2fe5Mark Andrewsto allocate memory and
f7f4730e563a2749629fe7fef4cd9513cd2bfab7Mark Andrewsto free it. If
2d82ed9456e72dc4373bea19d63411afe1c48962Mark Andrewsare NULL, memory is allocated using
a5a1cbece45e6ca68aafe3b9b995eac6b0f45dd2Mark Andrews<citerefentry>
0d6328ce5f6b799f8e7c6cbbb3b965cf29bfb7baMark Andrews<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
0d6328ce5f6b799f8e7c6cbbb3b965cf29bfb7baMark Andrews</citerefentry>.
e01ef6f01c7e8f80122cd80a2e011425a0135489Mark AndrewsIt is not permitted to have a NULL
677f507de7c546c187c1505c48bc7b440545485cMark Andrewsand a non-NULL
124cc0660c7eff8021c2422fb47441e9ca08b3f9Tinderbox Useror vice versa.
677f507de7c546c187c1505c48bc7b440545485cMark Andrewsis passed as the first parameter to the memory
677f507de7c546c187c1505c48bc7b440545485cMark Andrewsallocation functions.
677f507de7c546c187c1505c48bc7b440545485cMark Andrewsis unused and should be passed as NULL.
bf459d24a117ae2c54c37016430b41cd6d73491cMark AndrewsOnce memory for the structure has been allocated,
f53e0bda467d96dfeeba1b4da30c37b37766bb75Evan Huntit is initialized using
f53e0bda467d96dfeeba1b4da30c37b37766bb75Evan Hunt<citerefentry>
f53e0bda467d96dfeeba1b4da30c37b37766bb75Evan Hunt<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
f53e0bda467d96dfeeba1b4da30c37b37766bb75Evan Hunt</citerefentry>
81e3e3084980afcd61416f572c6e72d38a3808abMichał Kępieńand returned via
64d7fa3ec4785b390665860aa6bdae304b3c1d24Mark Andrewsclosing its socket.
75505befa93c993aa5d2df24a2b64eac0c34cbffMark Andrewsis a pointer to a pointer to the context that is to be destroyed.
75505befa93c993aa5d2df24a2b64eac0c34cbffMark AndrewsThe pointer will be set to NULL when the context has been destroyed.
a38f07c73790170842e4523b4a474d01ca0dede1Michał KępieńThe context holds a serial number that is used to identify resolver
39d5523a8afc73cbdb4fa426de2ce071267a5d6fMark Andrewsrequest packets and associate responses with the corresponding requests.
39d5523a8afc73cbdb4fa426de2ce071267a5d6fMark AndrewsThis serial number is controlled using
1f4a3c7088594d1b64cd734eb69e1fd023fde8bfMichał Kępień<function>lwres_context_nextserial()</function>.
1f4a3c7088594d1b64cd734eb69e1fd023fde8bfMichał Kępień<function>lwres_context_initserial()</function>
1f4a3c7088594d1b64cd734eb69e1fd023fde8bfMichał Kępieńsets the serial number for context
35aae5884f410180706a89a9715bf9a85eeeb4b7Michał Kępień<function>lwres_context_nextserial()</function>
35aae5884f410180706a89a9715bf9a85eeeb4b7Michał Kępieńincrements the serial number and returns the previous value.
57b1d64d9ae12d56973716e96f9743a00d47af4aMichał KępieńMemory for a lightweight resolver context is allocated and freed using
09c3efda414314d7edcfb2aed9463fb935fc95a6Mark AndrewsThese use whatever allocations were defined when the context was
86d2f9abc8493321aacb0d540485de4d562fb734Mark Andrewsbytes of memory and if successful returns a pointer to the allocated
86d2f9abc8493321aacb0d540485de4d562fb734Mark Andrewsbytes of space starting at location
3ed16e796dba90c96933c8a8a3f5b9404d8d3e61Mark Andrewsperforms I/O for the context
14d8a144779b54b103d2da741a2242bf5f9052f7Mark AndrewsData are read and written from the context's socket.
70e041bea19b6ad9522b89c2299ad315a2deaafdMark AndrewsIt writes data from
70e041bea19b6ad9522b89c2299ad315a2deaafdMark Andrews— typically a lightweight resolver query packet —
67247b4a8304bac790648a351a95b8b0f4c512a6Mark Andrewsand waits for a reply which is copied to the receive buffer at
eeb919b6f572e033d97cf001e4cd44aaff54e5dcMichał KępieńThe number of bytes that were written to this receive buffer is
f8362536c647625e602c8450a778a2b7ba90c9f4Mark Andrewsif memory for the
24231e53a5c3079431f84dcddfee1e761fec7329Mark Andrewscould not be allocated,
4b669b69bae7dedda2faa09a7ade247499c1d49cMichał KępieńSuccessful calls to the memory allocator
eb11b39981689e4a20fbe95e533577eacab992b4Mukund Sivaramanreturn a pointer to the start of the allocated space.
eb11b39981689e4a20fbe95e533577eacab992b4Mukund SivaramanIt returns NULL if memory could not be allocated.
e7c0f978425f45731b08be1363f20626b0344f23Evan Huntis returned when
01967d183990e44752fe61f193dab9c04c3afd9cEvan Huntcompletes successfully.
01967d183990e44752fe61f193dab9c04c3afd9cEvan Huntis returned if an I/O error occurs and
575e9d9e4b6beaae688f107814a320b91243a4b2Mark Andrewsis returned if
575e9d9e4b6beaae688f107814a320b91243a4b2Mark Andrewstimes out waiting for a response.
5e1ca7a326741a8f74e6f2b907c7e1fbf428bf80Michał Kępień<citerefentry>
5e1ca7a326741a8f74e6f2b907c7e1fbf428bf80Michał Kępień<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
5e1ca7a326741a8f74e6f2b907c7e1fbf428bf80Michał Kępień</citerefentry>,
ba93bc80a7bce5ba07b2f98e68f0f57402f2459cMark Andrews<citerefentry>
8ed107eab48687887d45a1ceb18b712bc7209dbaTinderbox User<refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
ba93bc80a7bce5ba07b2f98e68f0f57402f2459cMark Andrews</citerefentry>,
5f103158280fb2e814db305f917aa42040221623Mark Andrews<citerefentry>
e5715e1fe12e5ad17522bd41c31e637c869d27b7Evan Hunt</citerefentry>.