contrib/bind9/lib/isccc/include/isccc/ccmsg.h

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