/contrib/bind9/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 */
 28typedef struct lwres_lwpacket lwres_lwpacket_t;
 29
 30/*% lwres_lwpacket structure */
 31struct 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
148LWRES_LANG_BEGINDECLS
149
150/* XXXMLG document */
151lwres_result_t
152lwres_lwpacket_renderheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt);
153
154lwres_result_t
155lwres_lwpacket_parseheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt);
156
157LWRES_LANG_ENDDECLS
158
159#endif /* LWRES_LWPACKET_H */