contrib/bind-9.3/lib/dns/include/dns/tcpmsg.h

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