lwres_context.html revision 841179549b6433e782c164a562eb3422f603533d
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - Copyright (C) 2000, 2001 Internet Software Consortium.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - Permission to use, copy, modify, and distribute this software for any
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - purpose with or without fee is hereby granted, provided that the above
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - copyright notice and this permission notice appear in all copies.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
d1515e527c5d324d2c75e58781f1dd47f18624d8Alexander Eremin - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
95c635efb7c3b86efc493e0447eaec7aecca3f0fGarrett D'Amore - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov<!-- $Id: lwres_context.html,v 1.3 2001/06/08 19:32:19 gson Exp $ -->
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context</TITLE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweNAME="GENERATOR"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCONTENT="Modular DocBook HTML Stylesheet Version 1.61
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="REFENTRY"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweBGCOLOR="#FFFFFF"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweTEXT="#000000"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweLINK="#0000FF"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweVLINK="#840084"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweALINK="#0000FF"
7ffba875a0c7cf118aef7a2c9bfd00c3935e230aGarrett D'Amore>lwres_context</A
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="REFNAMEDIV"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_create, lwres_context_destroy, lwres_context_nextserial, lwres_context_initserial, lwres_context_freemem, lwres_context_allocmem, lwres_context_sendrecv -- lightweight resolver context management</DIV
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="REFSYNOPSISDIV"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>Synopsis</H2
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCSYNOPSIS"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCSYNOPSISINFO"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCDEF"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_result_t
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowelwres_context_create</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, lwres_free_t free_function);</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCDEF"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_result_t
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowelwres_context_destroy</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>(lwres_context_t **contextp);</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCDEF"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowelwres_context_initserial</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>(lwres_context_t *ctx, lwres_uint32_t serial);</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCDEF"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_uint32_t
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowelwres_context_nextserial</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>(lwres_context_t *ctx);</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCDEF"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowelwres_context_freemem</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>(lwres_context_t *ctx, void *mem, size_t len);</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCDEF"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowelwres_context_allocmem</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>(lwres_context_t *ctx, size_t len);</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCDEF"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowelwres_context_sendrecv</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>(lwres_context_t *ctx, void *sendbase, int sendlen, void *recvbase, int recvlen, int *recvd_len);</CODE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="REFSECT1"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>DESCRIPTION</H2
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_create()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_t</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowestructure for use in lightweight resolver operations.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweIt holds a socket and other data needed for communicating
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowewith a resolver daemon.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_t</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweis returned throught
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowea pointer to a
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_t</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowepointer. This
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_t</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowepointer must initially be NULL, and is modified
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweto point to the newly created
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_t</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>When the lightweight resolver needs to perform dynamic memory
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweallocation, it will call
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>malloc_function</I
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweto allocate memory and
ec7588a4ab9972aa7d50fd5f3b5ccdef4079952aRobert MustacchiCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>free_function</I
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweto free it. If
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>malloc_function</I
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>free_function</I
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweare NULL, memory is allocated using
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="CITEREFENTRY"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="REFENTRYTITLE"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweIt is not permitted to have a NULL
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>malloc_function</I
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweand a non-NULL
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>free_function</I
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweor vice versa.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweis passed as the first parameter to the memory
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweallocation functions.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>malloc_function</I
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>free_function</I
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweis unused and should be passed as NULL.</P
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>Once memory for the structure has been allocated,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweit is initialized using
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="CITEREFENTRY"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="REFENTRYTITLE"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_conf_init</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweand returned via
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>*contextp</I
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_destroy()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_t</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweclosing its socket.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweis a pointer to a pointer to the context that is to be destroyed.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweThe pointer will be set to NULL when the context has been destroyed.</P
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>The context holds a serial number that is used to identify resolver
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowerequest packets and associate responses with the corresponding requests.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweThis serial number is controlled using
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_initserial()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_nextserial()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_initserial()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowesets the serial number for context
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_nextserial()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweincrements the serial number and returns the previous value.</P
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>Memory for a lightweight resolver context is allocated and freed using
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_allocmem()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_freemem()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweThese use whatever allocations were defined when the context was
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_create()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_allocmem()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowebytes of memory and if successful returns a pointer to the allocated
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_allocmem()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowemust be greater than 0.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_freemem()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowebytes of space starting at location
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_sendrecv()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweperforms I/O for the context
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweData are read and written from the context's socket.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweIt writes data from
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe— typically a lightweight resolver query packet —
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweand waits for a reply which is copied to the receive buffer at
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweThe number of bytes that were written to this receive buffer is
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="PARAMETER"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>*recvd_len</I
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="REFSECT1"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweNAME="AEN117"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>RETURN VALUES</H2
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_create()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="ERRORCODE"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>LWRES_R_NOMEMORY</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweif memory for the
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>struct lwres_context</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowecould not be allocated,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="ERRORCODE"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>LWRES_R_SUCCESS</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweotherwise.</P
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>Successful calls to the memory allocator
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_allocmem()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowereturn a pointer to the start of the allocated space.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweIt returns NULL if memory could not be allocated.</P
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="ERRORCODE"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>LWRES_R_SUCCESS</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweis returned when
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_sendrecv()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowecompletes successfully.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="ERRORCODE"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>LWRES_R_IOERROR</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweis returned if an I/O error occurs and
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="ERRORCODE"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>LWRES_R_TIMEOUT</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Loweis returned if
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="FUNCTION"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_context_sendrecv()</TT
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowetimes out waiting for a response.</P
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="REFSECT1"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweNAME="AEN132"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>SEE ALSO</H2
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="CITEREFENTRY"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="REFENTRYTITLE"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>lwres_conf_init</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="CITEREFENTRY"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="REFENTRYTITLE"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe>malloc</SPAN
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="CITEREFENTRY"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweCLASS="REFENTRYTITLE"