/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
 33ISC_LANG_BEGINDECLS
 34
 35isc_result_t
 36irs_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
 49isc_result_t
 50irs_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
 64void
 65irs_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
 77isc_mem_t *
 78irs_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
 87isc_appctx_t *
 88irs_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
 97isc_taskmgr_t *
 98irs_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
107isc_timermgr_t *
108irs_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
117isc_task_t *
118irs_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
127dns_client_t *
128irs_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
137irs_resconf_t *
138irs_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
147irs_dnsconf_t *
148irs_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
157ISC_LANG_ENDDECLS
158
159#endif /* IRS_CONTEXT_H */