lwres_context.docbook revision ac299c4f5ca236370b9df2a91b18b149b1d344a7
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder - Copyright (C) 2001 Internet Software Consortium.
4b0a4c7dea0f67a233dcc42ce9bb18d36de109aeChristian Maeder - Permission to use, copy, modify, and distribute this software for any
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder - purpose with or without fee is hereby granted, provided that the above
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder - copyright notice and this permission notice appear in all copies.
83cc27e4ca7cf1a4bb5f4a8df17d3e6d44e6f1eaChristian Maeder - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
46d766efdf8beaaadf3f34d99c305738064e9216Christian Maeder - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder<!-- $Id: lwres_context.docbook,v 1.3 2001/06/18 22:56:16 gson Exp $ -->
23f8d286586ff38a9e73052b2c7c04c62c5c638fChristian Maeder<refentryinfo>
9379646a4fecb772e793a8875bb92723e854268cChristian Maeder</refentryinfo>
b190f5c7cf3ddda73724efe5ce82b9585ed76be1Christian Maeder<refentrytitle>lwres_context</refentrytitle>
1db126da06f707b90b5be9d66a73c36ee2cd22eeChristian Maeder<refpurpose>lightweight resolver context management</refpurpose>
1db126da06f707b90b5be9d66a73c36ee2cd22eeChristian Maeder<refsynopsisdiv>
1db126da06f707b90b5be9d66a73c36ee2cd22eeChristian Maeder<funcsynopsis>
1db126da06f707b90b5be9d66a73c36ee2cd22eeChristian Maeder<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
1db126da06f707b90b5be9d66a73c36ee2cd22eeChristian Maeder<funcprototype>
ca010363454de207082dfaa4b753531ce2a34551Christian Maederlwres_result_t
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<function>lwres_context_create</function></funcdef>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<paramdef>lwres_context_t **contextp</paramdef>
d601fb0d7be0f4e8de9f01b5293df7d80673d76aChristian Maeder<paramdef>lwres_malloc_t malloc_function</paramdef>
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<paramdef>lwres_free_t free_function</paramdef>
b190f5c7cf3ddda73724efe5ce82b9585ed76be1Christian Maeder</funcprototype>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<funcprototype>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maederlwres_result_t
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<function>lwres_context_destroy</function></funcdef>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<paramdef>lwres_context_t **contextp</paramdef>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder</funcprototype>
aae44eae4cd27141bea70af8d54844c3849a0711Christian Maeder<funcprototype>
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder<function>lwres_context_initserial</function></funcdef>
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder</funcprototype>
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder<funcprototype>
ca010363454de207082dfaa4b753531ce2a34551Christian Maederlwres_uint32_t
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder<function>lwres_context_nextserial</function></funcdef>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder</funcprototype>
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder<funcprototype>
88d16ba9fcfb786c4e953f99982e3056ad2045ecChristian Maeder<function>lwres_context_freemem</function></funcdef>
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder</funcprototype>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<funcprototype>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<function>lwres_context_allocmem</function></funcdef>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder</funcprototype>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<funcprototype>
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder<function>lwres_context_sendrecv</function></funcdef>
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder</funcprototype>
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder</funcsynopsis>
ca010363454de207082dfaa4b753531ce2a34551Christian Maeder</refsynopsisdiv>
aae44eae4cd27141bea70af8d54844c3849a0711Christian Maederstructure for use in lightweight resolver operations.
aae44eae4cd27141bea70af8d54844c3849a0711Christian MaederIt holds a socket and other data needed for communicating
aae44eae4cd27141bea70af8d54844c3849a0711Christian Maederwith a resolver daemon.
aae44eae4cd27141bea70af8d54844c3849a0711Christian Maederis returned throught
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maedera pointer to a
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maederpointer must initially be NULL, and is modified
46d766efdf8beaaadf3f34d99c305738064e9216Christian Maederto point to the newly created
aae44eae4cd27141bea70af8d54844c3849a0711Christian MaederWhen the lightweight resolver needs to perform dynamic memory
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maederallocation, it will call
aae44eae4cd27141bea70af8d54844c3849a0711Christian Maederto allocate memory and
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maederto free it. If
b190f5c7cf3ddda73724efe5ce82b9585ed76be1Christian Maederare NULL, memory is allocated using
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<citerefentry>
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
1db126da06f707b90b5be9d66a73c36ee2cd22eeChristian Maeder</citerefentry>.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian MaederIt is not permitted to have a NULL
ca010363454de207082dfaa4b753531ce2a34551Christian Maederand a non-NULL
a0a2ff520a916e334d58f96e59f009aae61e98a7Christian Maederor vice versa.
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maederis passed as the first parameter to the memory
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maederallocation functions.
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maederis unused and should be passed as NULL.
08f8731b34de5dc1ced274594978ad8879c831bdChristian MaederOnce memory for the structure has been allocated,
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maederit is initialized using
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<citerefentry>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder</citerefentry>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maederand returned via
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<function>lwres_context_destroy()</function>
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maederclosing its socket.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maederis a pointer to a pointer to the context that is to be destroyed.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian MaederThe pointer will be set to NULL when the context has been destroyed.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian MaederThe context holds a serial number that is used to identify resolver
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maederrequest packets and associate responses with the corresponding requests.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian MaederThis serial number is controlled using
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<function>lwres_context_initserial()</function>
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<function>lwres_context_nextserial()</function>.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<function>lwres_context_initserial()</function>
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maedersets the serial number for context
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<function>lwres_context_nextserial()</function>
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maederincrements the serial number and returns the previous value.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian MaederMemory for a lightweight resolver context is allocated and freed using
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<function>lwres_context_allocmem()</function>
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<function>lwres_context_freemem()</function>.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian MaederThese use whatever allocations were defined when the context was
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<function>lwres_context_create()</function>.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<function>lwres_context_allocmem()</function>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maederbytes of memory and if successful returns a pointer to the allocated
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maeder<function>lwres_context_freemem()</function>
08f8731b34de5dc1ced274594978ad8879c831bdChristian Maederbytes of space starting at location
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<function>lwres_context_sendrecv()</function>
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maederperforms I/O for the context
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian MaederData are read and written from the context's socket.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian MaederIt writes data from
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder— typically a lightweight resolver query packet —
b190f5c7cf3ddda73724efe5ce82b9585ed76be1Christian Maederand waits for a reply which is copied to the receive buffer at
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian MaederThe number of bytes that were written to this receive buffer is
8853be843bc3eed2ca6722efeee5174335e28b0eChristian Maederif memory for the
8853be843bc3eed2ca6722efeee5174335e28b0eChristian Maedercould not be allocated,
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian MaederSuccessful calls to the memory allocator
aae44eae4cd27141bea70af8d54844c3849a0711Christian Maeder<function>lwres_context_allocmem()</function>
aae44eae4cd27141bea70af8d54844c3849a0711Christian Maederreturn a pointer to the start of the allocated space.
aae44eae4cd27141bea70af8d54844c3849a0711Christian MaederIt returns NULL if memory could not be allocated.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maederis returned when
cf58a323fcb5c4185c3aa378713bbee3bba18c0aChristian Maeder<function>lwres_context_sendrecv()</function>
cf58a323fcb5c4185c3aa378713bbee3bba18c0aChristian Maedercompletes successfully.
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maederis returned if an I/O error occurs and
14b47f7dabb39996a31c7286810a5897587aed3aChristian Maederis returned if
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maeder<function>lwres_context_sendrecv()</function>
8b39fe4e459a2c534b55bab3bd68f929ba9a8b74Christian Maedertimes out waiting for a response.
46d766efdf8beaaadf3f34d99c305738064e9216Christian Maeder<citerefentry>
46d766efdf8beaaadf3f34d99c305738064e9216Christian Maeder<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
46d766efdf8beaaadf3f34d99c305738064e9216Christian Maeder</citerefentry>,
46d766efdf8beaaadf3f34d99c305738064e9216Christian Maeder<citerefentry>
46d766efdf8beaaadf3f34d99c305738064e9216Christian Maeder<refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
46d766efdf8beaaadf3f34d99c305738064e9216Christian Maeder</citerefentry>,
46d766efdf8beaaadf3f34d99c305738064e9216Christian Maeder<citerefentry>
46d766efdf8beaaadf3f34d99c305738064e9216Christian Maeder<refentrytitle>free</refentrytitle><manvolnum>3
46d766efdf8beaaadf3f34d99c305738064e9216Christian Maeder</citerefentry>.