contrib/bind9/lib/irs/include/irs/context.h

   1 /*
   2  * Copyright (C) 2009  Internet Systems Consortium, Inc. ("ISC")
   3  *
   4  * Permission to use, copy, modify, and/or distribute this software for any
   5  * purpose with or without fee is hereby granted, provided that the above
   6  * copyright notice and this permission notice appear in all copies.
   7  *
   8  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
   9  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  10  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  11  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  12  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  13  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  14  * PERFORMANCE OF THIS SOFTWARE.
  15  */
  16
  17 /* $Id: context.h,v 1.3 2009/09/02 23:48:02 tbox Exp $ */
  18
  19 #ifndef IRS_CONTEXT_H
  20 #define IRS_CONTEXT_H 1
  21
  22 /*! \file
  23  *
  24  * \brief
  25  * The IRS context module provides an abstract interface to the DNS library
  26  * with an application.  An IRS context object initializes and holds various
  27  * resources used in the DNS library.
  28  */
  29
  30 #include <dns/types.h>
  31 #include <irs/types.h>
  32
  33 ISC_LANG_BEGINDECLS
  34
  35 isc_result_t
  36 irs_context_create(irs_context_t **contextp);
  37 /*%<
  38  * Create an IRS context.  It internally initializes the ISC and DNS libraries
  39  * (if not yet), creates a DNS client object and initializes the client using
  40  * the configuration files parsed via the 'resconf' and 'dnsconf' IRS modules.
  41  * Some of the internally initialized objects can be used by the application
  42  * via irs_context_getxxx() functions (see below).
  43  *
  44  * Requires:
  45  *
  46  *\li   contextp != NULL && *contextp == NULL.
  47  */
  48
  49 isc_result_t
  50 irs_context_get(irs_context_t **contextp);
  51 /*%<
  52  * Return an IRS context for the calling thread.  If no IRS context is
  53  * associated to the thread, this function creates a new one by calling
  54  * irs_context_create(), and associates it with the thread as a thread specific
  55  * data value.  This function is provided for standard libraries that are
  56  * expected to be thread-safe but do not accept an appropriate IRS context
  57  * as a library parameter, e.g., getaddrinfo().
  58  *
  59  * Requires:
  60  *
  61  *\li   contextp != NULL && *contextp == NULL.
  62  */
  63
  64 void
  65 irs_context_destroy(irs_context_t **contextp);
  66 /*%<
  67  * Destroy an IRS context.
  68  *
  69  * Requires:
  70  *
  71  *\li   '*contextp' is a valid IRS context.
  72  *
  73  * Ensures:
  74  *\li   '*contextp' == NULL.
  75  */
  76
  77 isc_mem_t *
  78 irs_context_getmctx(irs_context_t *context);
  79 /*%<
  80  * Return the memory context held in the context.
  81  *
  82  * Requires:
  83  *
  84  *\li   'context' is a valid IRS context.
  85  */
  86
  87 isc_appctx_t *
  88 irs_context_getappctx(irs_context_t *context);
  89 /*%<
  90  * Return the application context held in the context.
  91  *
  92  * Requires:
  93  *
  94  *\li   'context' is a valid IRS context.
  95  */
  96
  97 isc_taskmgr_t *
  98 irs_context_gettaskmgr(irs_context_t *context);
  99 /*%<
 100  * Return the task manager held in the context.
 101  *
 102  * Requires:
 103  *
 104  *\li   'context' is a valid IRS context.
 105  */
 106
 107 isc_timermgr_t *
 108 irs_context_gettimermgr(irs_context_t *context);
 109 /*%<
 110  * Return the timer manager held in the context.
 111  *
 112  * Requires:
 113  *
 114  *\li   'context' is a valid IRS context.
 115  */
 116
 117 isc_task_t *
 118 irs_context_gettask(irs_context_t *context);
 119 /*%<
 120  * Return the task object held in the context.
 121  *
 122  * Requires:
 123  *
 124  *\li   'context' is a valid IRS context.
 125  */
 126
 127 dns_client_t *
 128 irs_context_getdnsclient(irs_context_t *context);
 129 /*%<
 130  * Return the DNS client object held in the context.
 131  *
 132  * Requires:
 133  *
 134  *\li   'context' is a valid IRS context.
 135  */
 136
 137 irs_resconf_t *
 138 irs_context_getresconf(irs_context_t *context);
 139 /*%<
 140  * Return the resolver configuration object held in the context.
 141  *
 142  * Requires:
 143  *
 144  *\li   'context' is a valid IRS context.
 145  */
 146
 147 irs_dnsconf_t *
 148 irs_context_getdnsconf(irs_context_t *context);
 149 /*%<
 150  * Return the advanced DNS configuration object held in the context.
 151  *
 152  * Requires:
 153  *
 154  *\li   'context' is a valid IRS context.
 155  */
 156
 157 ISC_LANG_ENDDECLS
 158
 159 #endif /* IRS_CONTEXT_H */