contrib/bind-9.5.2/lib/dns/include/dns/tcpmsg.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: tcpmsg.h,v 1.22 2007/06/19 23:47:17 tbox Exp $ */
  19
  20 #ifndef DNS_TCPMSG_H
  21 #define DNS_TCPMSG_H 1
  22
  23 /*! \file dns/tcpmsg.h */
  24
  25 #include <isc/buffer.h>
  26 #include <isc/lang.h>
  27 #include <isc/socket.h>
  28
  29 typedef struct dns_tcpmsg {
  30         /* private (don't touch!) */
  31         unsigned int            magic;
  32         isc_uint16_t            size;
  33         isc_buffer_t            buffer;
  34         unsigned int            maxsize;
  35         isc_mem_t              *mctx;
  36         isc_socket_t           *sock;
  37         isc_task_t             *task;
  38         isc_taskaction_t        action;
  39         void                   *arg;
  40         isc_event_t             event;
  41         /* public (read-only) */
  42         isc_result_t            result;
  43         isc_sockaddr_t          address;
  44 } dns_tcpmsg_t;
  45
  46 ISC_LANG_BEGINDECLS
  47
  48 void
  49 dns_tcpmsg_init(isc_mem_t *mctx, isc_socket_t *sock, dns_tcpmsg_t *tcpmsg);
  50 /*%<
  51  * Associate a tcp message state with a given memory context and
  52  * TCP socket.
  53  *
  54  * Requires:
  55  *
  56  *\li   "mctx" and "sock" be non-NULL and valid types.
  57  *
  58  *\li   "sock" be a read/write TCP socket.
  59  *
  60  *\li   "tcpmsg" be non-NULL and an uninitialized or invalidated structure.
  61  *
  62  * Ensures:
  63  *
  64  *\li   "tcpmsg" is a valid structure.
  65  */
  66
  67 void
  68 dns_tcpmsg_setmaxsize(dns_tcpmsg_t *tcpmsg, unsigned int maxsize);
  69 /*%<
  70  * Set the maximum packet size to "maxsize"
  71  *
  72  * Requires:
  73  *
  74  *\li   "tcpmsg" be valid.
  75  *
  76  *\li   512 <= "maxsize" <= 65536
  77  */
  78
  79 isc_result_t
  80 dns_tcpmsg_readmessage(dns_tcpmsg_t *tcpmsg,
  81                        isc_task_t *task, isc_taskaction_t action, void *arg);
  82 /*%<
  83  * Schedule an event to be delivered when a DNS message is readable, or
  84  * when an error occurs on the socket.
  85  *
  86  * Requires:
  87  *
  88  *\li   "tcpmsg" be valid.
  89  *
  90  *\li   "task", "taskaction", and "arg" be valid.
  91  *
  92  * Returns:
  93  *
  94  *\li   ISC_R_SUCCESS           -- no error
  95  *\li   Anything that the isc_socket_recv() call can return.  XXXMLG
  96  *
  97  * Notes:
  98  *
  99  *\li   The event delivered is a fully generic event.  It will contain no
 100  *      actual data.  The sender will be a pointer to the dns_tcpmsg_t.
 101  *      The result code inside that structure should be checked to see
 102  *      what the final result was.
 103  */
 104
 105 void
 106 dns_tcpmsg_cancelread(dns_tcpmsg_t *tcpmsg);
 107 /*%<
 108  * Cancel a readmessage() call.  The event will still be posted with a
 109  * CANCELED result code.
 110  *
 111  * Requires:
 112  *
 113  *\li   "tcpmsg" be valid.
 114  */
 115
 116 void
 117 dns_tcpmsg_keepbuffer(dns_tcpmsg_t *tcpmsg, isc_buffer_t *buffer);
 118 /*%<
 119  * If a dns buffer is to be kept between calls, this function marks the
 120  * internal state-machine buffer as invalid, and copies all the contents
 121  * of the state into "buffer".
 122  *
 123  * Requires:
 124  *
 125  *\li   "tcpmsg" be valid.
 126  *
 127  *\li   "buffer" be non-NULL.
 128  */
 129
 130 void
 131 dns_tcpmsg_invalidate(dns_tcpmsg_t *tcpmsg);
 132 /*%<
 133  * Clean up all allocated state, and invalidate the structure.
 134  *
 135  * Requires:
 136  *
 137  *\li   "tcpmsg" be valid.
 138  *
 139  * Ensures:
 140  *
 141  *\li   "tcpmsg" is invalidated and disassociated with all memory contexts,
 142  *      sockets, etc.
 143  */
 144
 145 ISC_LANG_ENDDECLS
 146
 147 #endif /* DNS_TCPMSG_H */