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
#include <lwres/lwres.h>
lwres_result_t
lwres_context_create( |
lwres_context_t ** | contextp, |
| void * | arg, | |
| lwres_malloc_t | malloc_function, | |
| lwres_free_t |
free_function); |
lwres_result_t
lwres_context_destroy( |
lwres_context_t ** |
contextp); |
void
lwres_context_initserial( |
lwres_context_t * | ctx, |
| lwres_uint32_t |
serial); |
lwres_uint32_t
lwres_context_nextserial( |
lwres_context_t * |
ctx); |
void
lwres_context_freemem( |
lwres_context_t * | ctx, |
| void * | mem, | |
| size_t |
len); |
void
lwres_context_allocmem( |
lwres_context_t * | ctx, |
| size_t |
len); |
void *
lwres_context_sendrecv( |
lwres_context_t * | ctx, |
| void * | sendbase, | |
| int | sendlen, | |
| void * | recvbase, | |
| int | recvlen, | |
| int * |
recvd_len); |
lwres_context_create()
creates a lwres_context_t structure for use in
lightweight resolver operations. It holds a socket and other
data needed for communicating with a resolver daemon. The new
lwres_context_t is returned through
contextp, a pointer to a
lwres_context_t pointer. This
lwres_context_t pointer must initially be NULL, and
is modified to point to the newly created
lwres_context_t.
When the lightweight resolver needs to perform dynamic memory
allocation, it will call
malloc_function
to allocate memory and
free_function
to free it. If
malloc_function
and
free_function
are NULL, memory is allocated using
malloc(3).
and
free(3).
It is not permitted to have a NULL
malloc_function and a non-NULL
free_function or vice versa.
arg is passed as the first parameter to
the memory allocation functions. If
malloc_function and
free_function are NULL,
arg is unused and should be passed as
NULL.
Once memory for the structure has been allocated,
it is initialized using
lwres_conf_init(3)
and returned via *contextp.
lwres_context_destroy()
destroys a lwres_context_t, closing its socket.
contextp is a pointer to a pointer to the
context that is to be destroyed. The pointer will be set to
NULL when the context has been destroyed.
The context holds a serial number that is used to identify
resolver request packets and associate responses with the
corresponding requests. This serial number is controlled using
lwres_context_initserial() and
lwres_context_nextserial().
lwres_context_initserial() sets the serial
number for context *ctx to
serial.
lwres_context_nextserial() increments the
serial number and returns the previous value.
Memory for a lightweight resolver context is allocated and freed
using lwres_context_allocmem() and
lwres_context_freemem(). These use
whatever allocations were defined when the context was created
with lwres_context_create().
lwres_context_allocmem() allocates
len bytes of memory and if successful
returns a pointer to the allocated storage.
lwres_context_freemem() frees
len bytes of space starting at location
mem.
lwres_context_sendrecv()
performs I/O for the context ctx. Data
are read and written from the context's socket. It writes data
from sendbase — typically a
lightweight resolver query packet — and waits for a reply
which is copied to the receive buffer at
recvbase. The number of bytes that were
written to this receive buffer is returned in
*recvd_len.
lwres_context_create()
returns LWRES_R_NOMEMORY if memory for
the struct lwres_context could not be allocated,
LWRES_R_SUCCESS otherwise.
Successful calls to the memory allocator
lwres_context_allocmem()
return a pointer to the start of the allocated space.
It returns NULL if memory could not be allocated.
LWRES_R_SUCCESS
is returned when
lwres_context_sendrecv()
completes successfully.
LWRES_R_IOERROR
is returned if an I/O error occurs and
LWRES_R_TIMEOUT
is returned if
lwres_context_sendrecv()
times out waiting for a response.