Next: , Previous: Global Functions, Up: Top

7 Callback Functions

The callback is used by mechanisms to retrieve information, such as username and password, from the application. In a server, the callback is used to decide whether a user is permitted to log in or not. You tell the library of your callback function by calling gsasl_callback_set.

Since your callback may need to access to data from other parts of your application, there are hooks to store and retrieve application specific pointers. This avoid the use of global variables in your application, which wouldn't be thread safe. You store a pointer to some information (opaque from the point of view of the library) by calling gsasl_callback_hook_set and can later retrieve this data in your callback by calling gsasl_callback_hook_get.

gsasl_callback_set

— Function: void gsasl_callback_set (Gsasl * ctx, Gsasl_callback_function cb)

ctx: handle received from gsasl_init().

cb: pointer to function implemented by application.

Store the pointer to the application provided callback in the library handle. The callback will be used, via gsasl_callback(), by mechanisms to discover various parameters (such as username and passwords). The callback function will be called with a Gsasl_property value indicating the requested behaviour. For example, for GSASL_ANONYMOUS_TOKEN, the function is expected to invoke gsasl_property_set(CTX, GSASL_ANONYMOUS_TOKEN, "token") where "token" is the anonymous token the application wishes the SASL mechanism to use. See the manual for the meaning of all parameters.

Since: 0.2.0

gsasl_callback

— Function: int gsasl_callback (Gsasl * ctx, Gsasl_session * sctx, Gsasl_property prop)

ctx: handle received from gsasl_init(), may be NULL to derive it from sctx.

sctx: session handle.

prop: enumerated value of Gsasl_property type.

Invoke the application callback. The prop value indicate what the callback is expected to do. For example, for GSASL_ANONYMOUS_TOKEN, the function is expected to invoke gsasl_property_set(SCTX, GSASL_ANONYMOUS_TOKEN, "token") where "token" is the anonymous token the application wishes the SASL mechanism to use. See the manual for the meaning of all parameters.

Note that if no callback has been set by the application, but the obsolete callback interface has been used, this function will translate the old callback interface into the new. This interface should be sufficient to invoke all callbacks, both new and old.

Return value: Returns whatever the application callback return, or GSASL_NO_CALLBACK if no application was known.

Since: 0.2.0

gsasl_callback_hook_set

— Function: void gsasl_callback_hook_set (Gsasl * ctx, void * hook)

ctx: libgsasl handle.

hook: opaque pointer to application specific data.

Store application specific data in the libgsasl handle.

The application data can be later (for instance, inside a callback) be retrieved by calling gsasl_callback_hook_get(). This is normally used by the application to maintain a global state between the main program and callbacks.

Since: 0.2.0

gsasl_callback_hook_get

— Function: void * gsasl_callback_hook_get (Gsasl * ctx)

ctx: libgsasl handle.

Retrieve application specific data from libgsasl handle.

The application data is set using gsasl_callback_hook_set(). This is normally used by the application to maintain a global state between the main program and callbacks.

Return value: Returns the application specific data, or NULL.

Since: 0.2.0

gsasl_session_hook_set

— Function: void gsasl_session_hook_set (Gsasl_session * sctx, void * hook)

sctx: libgsasl session handle.

hook: opaque pointer to application specific data.

Store application specific data in the libgsasl session handle.

The application data can be later (for instance, inside a callback) be retrieved by calling gsasl_session_hook_get(). This is normally used by the application to maintain a per-session state between the main program and callbacks.

Since: 0.2.14

gsasl_session_hook_get

— Function: void * gsasl_session_hook_get (Gsasl_session * sctx)

sctx: libgsasl session handle.

Retrieve application specific data from libgsasl session handle.

The application data is set using gsasl_callback_hook_set(). This is normally used by the application to maintain a per-session state between the main program and callbacks.

Return value: Returns the application specific data, or NULL.

Since: 0.2.14