contrib/bind-9.5.2/lib/isccc/include/isccc/ccmsg.h

   1 /*
   2  * Portions Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
   3  * Portions Copyright (C) 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 AND NOMINUM DISCLAIMS ALL
  10  * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
  11  * OF MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY
  12  * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16  *
  17  * Portions Copyright (C) 2001  Nominum, Inc.
  18  *
  19  * Permission to use, copy, modify, and/or distribute this software for any
  20  * purpose with or without fee is hereby granted, provided that the above
  21  * copyright notice and this permission notice appear in all copies.
  22  *
  23  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC AND NOMINUM DISCLAIMS ALL
  24  * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
  25  * OF MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY
  26  * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  27  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  28  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  29  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  30  */
  31
  32 /* $Id: ccmsg.h,v 1.11 2007/08/28 07:20:43 tbox Exp $ */
  33
  34 #ifndef ISCCC_CCMSG_H
  35 #define ISCCC_CCMSG_H 1
  36
  37 /*! \file isccc/ccmsg.h */
  38
  39 #include <isc/buffer.h>
  40 #include <isc/lang.h>
  41 #include <isc/socket.h>
  42
  43 /*% ISCCC Message Structure */
  44 typedef struct isccc_ccmsg {
  45         /* private (don't touch!) */
  46         unsigned int            magic;
  47         isc_uint32_t            size;
  48         isc_buffer_t            buffer;
  49         unsigned int            maxsize;
  50         isc_mem_t              *mctx;
  51         isc_socket_t           *sock;
  52         isc_task_t             *task;
  53         isc_taskaction_t        action;
  54         void                   *arg;
  55         isc_event_t             event;
  56         /* public (read-only) */
  57         isc_result_t            result;
  58         isc_sockaddr_t          address;
  59 } isccc_ccmsg_t;
  60
  61 ISC_LANG_BEGINDECLS
  62
  63 void
  64 isccc_ccmsg_init(isc_mem_t *mctx, isc_socket_t *sock, isccc_ccmsg_t *ccmsg);
  65 /*%
  66  * Associate a cc message state with a given memory context and
  67  * TCP socket.
  68  *
  69  * Requires:
  70  *
  71  *\li   "mctx" and "sock" be non-NULL and valid types.
  72  *
  73  *\li   "sock" be a read/write TCP socket.
  74  *
  75  *\li   "ccmsg" be non-NULL and an uninitialized or invalidated structure.
  76  *
  77  * Ensures:
  78  *
  79  *\li   "ccmsg" is a valid structure.
  80  */
  81
  82 void
  83 isccc_ccmsg_setmaxsize(isccc_ccmsg_t *ccmsg, unsigned int maxsize);
  84 /*%
  85  * Set the maximum packet size to "maxsize"
  86  *
  87  * Requires:
  88  *
  89  *\li   "ccmsg" be valid.
  90  *
  91  *\li   512 <= "maxsize" <= 4294967296
  92  */
  93
  94 isc_result_t
  95 isccc_ccmsg_readmessage(isccc_ccmsg_t *ccmsg,
  96                        isc_task_t *task, isc_taskaction_t action, void *arg);
  97 /*%
  98  * Schedule an event to be delivered when a command channel message is
  99  * readable, or when an error occurs on the socket.
 100  *
 101  * Requires:
 102  *
 103  *\li   "ccmsg" be valid.
 104  *
 105  *\li   "task", "taskaction", and "arg" be valid.
 106  *
 107  * Returns:
 108  *
 109  *\li   #ISC_R_SUCCESS          -- no error
 110  *\li   Anything that the isc_socket_recv() call can return.  XXXMLG
 111  *
 112  * Notes:
 113  *
 114  *\li   The event delivered is a fully generic event.  It will contain no
 115  *      actual data.  The sender will be a pointer to the isccc_ccmsg_t.
 116  *      The result code inside that structure should be checked to see
 117  *      what the final result was.
 118  */
 119
 120 void
 121 isccc_ccmsg_cancelread(isccc_ccmsg_t *ccmsg);
 122 /*%
 123  * Cancel a readmessage() call.  The event will still be posted with a
 124  * CANCELED result code.
 125  *
 126  * Requires:
 127  *
 128  *\li   "ccmsg" be valid.
 129  */
 130
 131 void
 132 isccc_ccmsg_invalidate(isccc_ccmsg_t *ccmsg);
 133 /*%
 134  * Clean up all allocated state, and invalidate the structure.
 135  *
 136  * Requires:
 137  *
 138  *\li   "ccmsg" be valid.
 139  *
 140  * Ensures:
 141  *
 142  *\li   "ccmsg" is invalidated and disassociated with all memory contexts,
 143  *      sockets, etc.
 144  */
 145
 146 ISC_LANG_ENDDECLS
 147
 148 #endif /* ISCCC_CCMSG_H */