lwres_gabn

LWRES_GABN(3)							LWRES_GABN(3)



NAME
       lwres_gabnrequest_render,   lwres_gabnresponse_render,	lwres_gabnre-
       quest_parse,    lwres_gabnresponse_parse,     lwres_gabnresponse_free,
       lwres_gabnrequest_free  -  lightweight  resolver getaddrbyname message
       handling

SYNOPSIS
       #include <lwres/lwres.h>

       lwres_result_t lwres_gabnrequest_render(lwres_context_t *ctx,
       lwres_gabnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);

       lwres_result_t lwres_gabnresponse_render(lwres_context_t *ctx,
       lwres_gabnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);

       lwres_result_t lwres_gabnrequest_parse(lwres_context_t *ctx,
       lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnrequest_t
       **structp);

       lwres_result_t lwres_gabnresponse_parse(lwres_context_t *ctx,
       lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnresponse_t
       **structp);

       void lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnre-
       sponse_t **structp);

       void lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t
       **structp);


DESCRIPTION
       These are low-level routines  for  creating  and	 parsing  lightweight
       resolver name-to-address lookup request and response messages.

       There  are four main functions for the getaddrbyname opcode.  One ren-
       der function converts a getaddrbyname request structure —  lwres_gabn-
       request_t — to the lighweight resolver’s canonical format.  It is com-
       plemented by a parse function that converts a packet in this canonical
       format  to a getaddrbyname request structure.  Another render function
       converts the getaddrbyname response structure — lwres_gabnresponse_t —
       to  the	canonical  format.   This is complemented by a parse function
       which converts  a  packet  in  canonical	 format	 to  a	getaddrbyname
       response structure.

       These  structures  are  defined	in  <lwres/lwres.h>.   They are shown
       below.

       #define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U

       typedef struct lwres_addr lwres_addr_t;
       typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;

       typedef struct {
	       lwres_uint32_t  flags;
	       lwres_uint32_t  addrtypes;
	       lwres_uint16_t  namelen;
	       char	      *name;
       } lwres_gabnrequest_t;

       typedef struct {
	       lwres_uint32_t	       flags;
	       lwres_uint16_t	       naliases;
	       lwres_uint16_t	       naddrs;
	       char		      *realname;
	       char		     **aliases;
	       lwres_uint16_t	       realnamelen;
	       lwres_uint16_t	      *aliaslen;
	       lwres_addrlist_t	       addrs;
	       void		      *base;
	       size_t		       baselen;
       } lwres_gabnresponse_t;


       lwres_gabnrequest_render() uses resolver context ctx to convert getad-
       drbyname request structure req to canonical format.  The packet header
       structure pkt is initialised and transferred to buffer  b.   The	 con-
       tents  of  *req	are  then appended to the buffer in canonical format.
       lwres_gabnresponse_render() performs the same task, except it converts
       a   getaddrbyname   response  structure	lwres_gabnresponse_t  to  the
       lightweight resolver’s canonical format.

       lwres_gabnrequest_parse() uses context ctx to convert the contents  of
       packet  pkt  to	a  lwres_gabnrequest_t	structure.  Buffer b provides
       space to be used for storing this structure.  When the  function	 suc-
       ceeds,  the  resulting  lwres_gabnrequest_t  is made available through
       *structp.  lwres_gabnresponse_parse() offers  the  same	semantics  as
       lwres_gabnrequest_parse()  except  it  yields  a	 lwres_gabnresponse_t
       structure.

       lwres_gabnresponse_free()  and  lwres_gabnrequest_free()	 release  the
       memory in resolver context ctx that was allocated to the lwres_gabnre-
       sponse_t or lwres_gabnrequest_t	structures  referenced	via  structp.
       Any  memory  associated	with  ancillary buffers and strings for those
       structures is also discarded.

RETURN VALUES
       The   getaddrbyname   opcode   functions	  lwres_gabnrequest_render(),
       lwres_gabnresponse_render()  lwres_gabnrequest_parse() and lwres_gabn-
       response_parse() all return LWRES_R_SUCCESS on success.	 They  return
       LWRES_R_NOMEMORY if memory allocation fails.  LWRES_R_UNEXPECTEDEND is
       returned if the available space in the buffer b is too small to accom-
       modate  the packet header or the lwres_gabnrequest_t and lwres_gabnre-
       sponse_t	 structures.   lwres_gabnrequest_parse()  and	lwres_gabnre-
       sponse_parse()  will return LWRES_R_UNEXPECTEDEND if the buffer is not
       empty after decoding the received packet.  These functions will return
       LWRES_R_FAILURE	 if   pktflags	 in   the   packet  header  structure
       lwres_lwpacket_t indicate that the packet is not a response to an ear-
       lier query.

SEE ALSO
       lwres_packet(3)



BIND9				 Jun 30, 2000			LWRES_GABN(3)