contrib/bind-9.5.2/lib/lwres/include/lwres/lwpacket.h

   1 /*
   2  * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: lwpacket.h,v 1.24 2007/06/19 23:47:23 tbox Exp $ */
  19
  20 #ifndef LWRES_LWPACKET_H
  21 #define LWRES_LWPACKET_H 1
  22
  23 #include <lwres/lang.h>
  24 #include <lwres/lwbuffer.h>
  25 #include <lwres/result.h>
  26
  27 /*% lwres_lwpacket_t */
  28 typedef struct lwres_lwpacket lwres_lwpacket_t;
  29
  30 /*% lwres_lwpacket structure */
  31 struct lwres_lwpacket {
  32         /*! The overall packet length, including the
  33          *  entire packet header.
  34          *  This field is filled in by the
  35          *  \link lwres_gabn.c lwres_gabn_*()\endlink
  36          *  and \link lwres_gnba.c lwres_gnba_*()\endlink calls.
  37          */
  38         lwres_uint32_t          length;
  39         /*! Specifies the header format.  Currently,
  40          *  there is only one format, #LWRES_LWPACKETVERSION_0.
  41          *  This field is filled in by the
  42          *  \link lwres_gabn.c lwres_gabn_*()\endlink
  43          *  and \link lwres_gnba.c lwres_gnba_*()\endlink calls.
  44          */
  45         lwres_uint16_t          version;
  46         /*! Specifies library-defined flags for this packet, such as
  47          *  whether the packet is a request or a reply.  None of
  48          *  these are definable by the caller, but library-defined values
  49          *  can be set by the caller.  For example, one bit in this field
  50          *  indicates if the packet is a request or a response.
  51          *  This field is filled in by
  52          *  the application wits the exception of the
  53          *  #LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library
  54          *  in the
  55          *  \link lwres_gabn.c lwres_gabn_*()\endlink
  56          *  and \link lwres_gnba.c lwres_gnba_*()\endlink calls.
  57          */
  58         lwres_uint16_t          pktflags;
  59         /*! Set by the requestor and is returned in all replies.
  60          *  If two packets from the same source have the same serial
  61          *  number and are from the same source, they are assumed to
  62          *  be duplicates and the latter ones may be dropped.
  63          *  (The library does not do this by default on replies, but
  64          * does so on requests.)
  65          */
  66         lwres_uint32_t          serial;
  67         /*! Opcodes between 0x04000000 and 0xffffffff
  68          *  are application defined.  Opcodes between
  69          *  0x00000000 and 0x03ffffff are
  70          * reserved for library use.
  71          *  This field is filled in by the
  72          *  \link lwres_gabn.c lwres_gabn_*()\endlink
  73          *  and \link lwres_gnba.c lwres_gnba_*()\endlink calls.
  74          */
  75         lwres_uint32_t          opcode;
  76         /*! Only valid for results.
  77          *  Results between 0x04000000 and 0xffffffff are application
  78          *  defined.
  79          * Results between 0x00000000 and 0x03ffffff are reserved for
  80          * library use.
  81          * (This is the same reserved range defined in <isc/resultclass.h>,
  82          * so it
  83          * would be trivial to map ISC_R_* result codes into packet result
  84          * codes when appropriate.)
  85          *  This field is filled in by the
  86          *  \link lwres_gabn.c lwres_gabn_*()\endlink
  87          *  and \link lwres_gnba.c lwres_gnba_*()\endlink calls.
  88          */
  89         lwres_uint32_t          result;
  90         /*! Set to the maximum buffer size that the receiver can
  91          *  handle on requests, and the size of the buffer needed to
  92          *  satisfy a request
  93          *  when the buffer is too large for replies.
  94          *  This field is supplied by the application.
  95          */
  96         lwres_uint32_t          recvlength;
  97         /*! The packet level auth type used.
  98          *  Authtypes between 0x1000 and 0xffff are application defined.
  99          *  Authtypes
 100          *  between 0x0000 and 0x0fff are reserved for library use.
 101          *  This is currently
 102          *  unused and MUST be set to zero.
 103          */
 104         lwres_uint16_t          authtype;
 105         /*! The length of the authentication data.
 106          *  See the specific
 107          * authtypes for more information on what is contained
 108          * in this field.  This is currently unused, and
 109          * MUST be set to zero.
 110          */
 111         lwres_uint16_t          authlength;
 112 };
 113
 114 #define LWRES_LWPACKET_LENGTH           (4 * 5 + 2 * 4) /*%< Overall length. */
 115
 116 #define LWRES_LWPACKETFLAG_RESPONSE     0x0001U /*%< If set, pkt is a response. */
 117
 118
 119 #define LWRES_LWPACKETVERSION_0         0       /*%< Header format. */
 120
 121 /*! \file lwres/lwpacket.h
 122  *
 123  *
 124  * The remainder of the packet consists of two regions, one described by
 125  * "authlen" and one of "length - authlen - sizeof(lwres_lwpacket_t)".
 126  *
 127  * That is:
 128  *
 129  * \code
 130  *      pkt header
 131  *      authlen bytes of auth information
 132  *      data bytes
 133  * \endcode
 134  *
 135  * Currently defined opcodes:
 136  *
 137  *\li   #LWRES_OPCODE_NOOP.  Success is always returned, with the packet contents echoed.
 138  *
 139  *\li   #LWRES_OPCODE_GETADDRSBYNAME.  Return all known addresses for a given name.
 140  *              This may return NIS or /etc/hosts info as well as DNS
 141  *              information.  Flags will be provided to indicate ip4/ip6
 142  *              addresses are desired.
 143  *
 144  *\li   #LWRES_OPCODE_GETNAMEBYADDR.    Return the hostname for the given address.  Once
 145  *              again, it will return data from multiple sources.
 146  */
 147
 148 LWRES_LANG_BEGINDECLS
 149
 150 /* XXXMLG document */
 151 lwres_result_t
 152 lwres_lwpacket_renderheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt);
 153
 154 lwres_result_t
 155 lwres_lwpacket_parseheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt);
 156
 157 LWRES_LANG_ENDDECLS
 158
 159 #endif /* LWRES_LWPACKET_H */