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 */
160