1/* callback.c --- Callback handling.
2 * Copyright (C) 2002-2012 Simon Josefsson
3 *
4 * This file is part of GNU SASL Library.
5 *
6 * GNU SASL Library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public License
8 * as published by the Free Software Foundation; either version 2.1 of
9 * the License, or (at your option) any later version.
10 *
11 * GNU SASL Library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License License along with GNU SASL Library; if not, write to the
18 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 *
21 */
22
23#include "internal.h"
24
25/**
26 * gsasl_callback_set:
27 * @ctx: handle received from gsasl_init().
28 * @cb: pointer to function implemented by application.
29 *
30 * Store the pointer to the application provided callback in the
31 * library handle. The callback will be used, via gsasl_callback(),
32 * by mechanisms to discover various parameters (such as username and
33 * passwords). The callback function will be called with a
34 * Gsasl_property value indicating the requested behaviour. For
35 * example, for %GSASL_ANONYMOUS_TOKEN, the function is expected to
36 * invoke gsasl_property_set(@CTX, %GSASL_ANONYMOUS_TOKEN, "token")
37 * where "token" is the anonymous token the application wishes the
38 * SASL mechanism to use. See the manual for the meaning of all
39 * parameters.
40 *
41 * Since: 0.2.0
42 **/
43void
44gsasl_callback_set (Gsasl * ctx, Gsasl_callback_function cb)
45{
46 ctx->cb = cb;
47}
48
49/**
50 * gsasl_callback:
51 * @ctx: handle received from gsasl_init(), may be NULL to derive it
52 * from @sctx.
53 * @sctx: session handle.
54 * @prop: enumerated value of Gsasl_property type.
55 *
56 * Invoke the application callback. The @prop value indicate what the
57 * callback is expected to do. For example, for
58 * %GSASL_ANONYMOUS_TOKEN, the function is expected to invoke
59 * gsasl_property_set(@SCTX, %GSASL_ANONYMOUS_TOKEN, "token") where
60 * "token" is the anonymous token the application wishes the SASL
61 * mechanism to use. See the manual for the meaning of all
62 * parameters.
63 *
64 * Note that if no callback has been set by the application, but the
65 * obsolete callback interface has been used, this function will
66 * translate the old callback interface into the new. This interface
67 * should be sufficient to invoke all callbacks, both new and old.
68 *
69 * Return value: Returns whatever the application callback returns, or
70 * %GSASL_NO_CALLBACK if no application was known.
71 *
72 * Since: 0.2.0
73 **/
74int
75gsasl_callback (Gsasl * ctx, Gsasl_session * sctx, Gsasl_property prop)
76{
77 if (ctx == NULL && sctx == NULL)
78 return GSASL_NO_CALLBACK;
79
80 if (ctx == NULL)
81 ctx = sctx->ctx;
82
83 if (ctx->cb)
84 return ctx->cb (ctx, sctx, prop);
85
86#ifndef GSASL_NO_OBSOLETE
87 return _gsasl_obsolete_callback (ctx, sctx, prop);
88#endif
89
90 return GSASL_NO_CALLBACK;
91}
92
93/**
94 * gsasl_callback_hook_set:
95 * @ctx: libgsasl handle.
96 * @hook: opaque pointer to application specific data.
97 *
98 * Store application specific data in the libgsasl handle.
99 *
100 * The application data can be later (for instance, inside a callback)
101 * be retrieved by calling gsasl_callback_hook_get(). This is
102 * normally used by the application to maintain a global state between
103 * the main program and callbacks.
104 *
105 * Since: 0.2.0
106 **/
107void
108gsasl_callback_hook_set (Gsasl * ctx, void *hook)
109{
110 ctx->application_hook = hook;
111}
112
113/**
114 * gsasl_callback_hook_get:
115 * @ctx: libgsasl handle.
116 *
117 * Retrieve application specific data from libgsasl handle.
118 *
119 * The application data is set using gsasl_callback_hook_set(). This
120 * is normally used by the application to maintain a global state
121 * between the main program and callbacks.
122 *
123 * Return value: Returns the application specific data, or NULL.
124 *
125 * Since: 0.2.0
126 **/
127void *
128gsasl_callback_hook_get (Gsasl * ctx)
129{
130 return ctx->application_hook;
131}
132
133/**
134 * gsasl_session_hook_set:
135 * @sctx: libgsasl session handle.
136 * @hook: opaque pointer to application specific data.
137 *
138 * Store application specific data in the libgsasl session handle.
139 *
140 * The application data can be later (for instance, inside a callback)
141 * be retrieved by calling gsasl_session_hook_get(). This is normally
142 * used by the application to maintain a per-session state between the
143 * main program and callbacks.
144 *
145 * Since: 0.2.14
146 **/
147void
148gsasl_session_hook_set (Gsasl_session * sctx, void *hook)
149{
150 sctx->application_hook = hook;
151}
152
153/**
154 * gsasl_session_hook_get:
155 * @sctx: libgsasl session handle.
156 *
157 * Retrieve application specific data from libgsasl session handle.
158 *
159 * The application data is set using gsasl_callback_hook_set(). This
160 * is normally used by the application to maintain a per-session state
161 * between the main program and callbacks.
162 *
163 * Return value: Returns the application specific data, or NULL.
164 *
165 * Since: 0.2.14
166 **/
167void *
168gsasl_session_hook_get (Gsasl_session * sctx)
169{
170 return sctx->application_hook;
171}
172