The SASL mechanism factory. Clients can use the factory to prioritize a list of SASL mechanisms. When the time comes to choose an appropriate mechanism, the client can submit a list of choices. The factory will return the highest priority registered mechanism that also appears in the list of choices. More...

#include "sasl_mech.h"

Typedefs
typedef struct _jw_sasl_factory	jw_sasl_factory

typedef jw_sasl_mech *	jw_sasl_factory_iter

Functions
JABBERWERX_API bool	jw_sasl_factory_create (jw_htable config, jw_sasl_factory factory, jw_err err)

JABBERWERX_API void	jw_sasl_factory_destroy (jw_sasl_factory *factory)

JABBERWERX_API void	jw_sasl_factory_htable_cleaner (bool replace, bool destroy_key, void key, void data)

JABBERWERX_API bool	jw_sasl_factory_add_mech (jw_sasl_factory factory, jw_sasl_mech mech, jw_err *err)

JABBERWERX_API bool	jw_sasl_factory_get_best_mech_in_dom (jw_sasl_factory factory, jw_dom_node choices, jw_htable config, jw_sasl_mech_instance instance, jw_err err)

JABBERWERX_API bool	jw_sasl_factory_get_best_mech_in_set (jw_sasl_factory factory, jw_htable choices, jw_htable config, jw_sasl_mech_instance instance, jw_err err)

JABBERWERX_API bool	jw_sasl_factory_iter_begin (jw_sasl_factory factory, jw_sasl_factory_iter iter, jw_err *err)

JABBERWERX_API bool	jw_sasl_factory_iter_next (jw_sasl_factory_iter iter, jw_sasl_mech mech, jw_err err)

Detailed Description

The SASL mechanism factory. Clients can use the factory to prioritize a list of SASL mechanisms. When the time comes to choose an appropriate mechanism, the client can submit a list of choices. The factory will return the highest priority registered mechanism that also appears in the list of choices.

Copyrights

Typedef Documentation

typedef struct _jw_sasl_factory jw_sasl_factory

A SASL mechanism factory instance

typedef jw_sasl_mech* jw_sasl_factory_iter

Datatype used for iterating through the SASL mechanisms registered with a particular SASL factory.

Function Documentation

JABBERWERX_API bool jw_sasl_factory_add_mech	(	jw_sasl_factory *	factory,
		jw_sasl_mech *	mech,
		jw_err *	err
	)

Register a SASL mechanism with the factory. The mechanism becomes the new preferred mechanism for the factory. The factory takes ownership of the mechanism and will destroy it when the factory is destroyed. This means that a jw_sasl_mech MUST NOT be added to more than one factory. If a mechanism needs to be added to more than one factory, duplicate the mechanism with jw_sasl_mech_create() or jw_sasl_mech_copy().

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the operation failed due to insufficient memory
JW_ERR_INVALID_ARG if a mechanism with the same name is already registered

Invariant: NULL != factory; NULL != mech

Parameters

[in]	factory	the SASL mechanism factory
[in]	mech	the mechanism to register
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if the mechanism was successfully registered

JABBERWERX_API bool jw_sasl_factory_create	(	jw_htable *	config,
		jw_sasl_factory **	factory,
		jw_err *	err
	)

Create a SASL mechanism factory.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the factory could not be allocated

Invariant: NULL != factory

Parameters

[in]	config	A collection of configuration options. No options are currently defined for jw_sasl_factory_create. For the time being, this parameter can be NULL.
[out]	factory	the newly-created factory
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if the factory was created successfully

JABBERWERX_API void jw_sasl_factory_destroy ( jw_sasl_factory * factory )

Destroy a SASL mechanism factory.

NOTE: This function does not destroy the config passed to create(), but it does destroy the mechanisms passed to add_mech().

Invariant: NULL != factory

Parameters

[in] factory The factory to clean up

JABBERWERX_API bool jw_sasl_factory_get_best_mech_in_dom	(	jw_sasl_factory *	factory,
		jw_dom_node *	choices,
		jw_htable *	config,
		jw_sasl_mech_instance **	instance,
		jw_err *	err
	)

Parses a mechanism(s) dom and returns an instance of the most preferred mechanism that is both listed in the dom and that can be instantiated given the specified config.

The choices dom can be either in the form of a <mechanism/> element or a <mechanisms/> element that contains multiple <mechanism/> elements. The namespace of the elements is ignored.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the operation failed due to insufficient memory
JW_ERR_INVALID_ARG if the given dom does not contain mechanism data

Invariant: NULL != factory; NULL != choices; NULL != instance

Parameters

[in]	factory	the SASL mechanism factory
[in]	choices	the dom that lists the available mechanisms
[in]	config	A collection of configuration options that are passed through to the mechanism's instance constructor. This function does not require the parameter to be non-NULL, but the mechanism's instance constructor might.
[out]	instance	The highest-priority mechanism that is listed in choices and that successfully instantiates, or NULL if no valid mechanism is found. If this variable is not NULL when the function returns, the caller is expected to destroy the instance when done with it.
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if the mechanisms were successfully extracted from choices

JABBERWERX_API bool jw_sasl_factory_get_best_mech_in_set	(	jw_sasl_factory *	factory,
		jw_htable *	choices,
		jw_htable *	config,
		jw_sasl_mech_instance **	instance,
		jw_err *	err
	)

Returns the most preferred mechanism that exists in the specified set.

NOTE: The choices parameter must have a case-insensitive string-based hash function and a case-insensitive string comparator.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the operation failed due to insufficient memory

If an error occurs while instantiating a mechanism, the error is ignored and not returned from this function if it is anything other than NO_MEMORY.

Invariant: NULL != factory; NULL != choices; NULL != mech

Parameters

[in]	factory	the SASL mechanism factory
[in]	choices	the set of mechanism names to choose from
[in]	config	A collection of configuration options that are passed through to the mechanism's instance constructor. This function does not require the parameter to be non-NULL, but the mechanism's instance constructor might.
[out]	instance	The highest-priority mechanism that is listed in choices and that successfully instantiates, or NULL if no valid mechanism is found. If this variable is not NULL when the function returns, the caller is expected to destroy the instance when done with it.
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if there was sufficient memory for this operation

JABBERWERX_API void jw_sasl_factory_htable_cleaner	(	bool	replace,
		bool	destroy_key,
		void *	key,
		void *	data
	)

Calls jw_sasl_factory_destroy on data associated with a jw_htable node. This can be used to clean up a sasl factory when the keys are static values.

Parameters

[in]	replace	ignored
[in]	destroy_key	ignored
[in]	key	ignored
[in]	data	the sasl factory that will be destroyed

JABBERWERX_API bool jw_sasl_factory_iter_begin	(	jw_sasl_factory *	factory,
		jw_sasl_factory_iter *	iter,
		jw_err *	err
	)

Initializes an iterator to point to the highest-priority mechanism registered in the factory. If any mechanisms are added to the factory after this iterator is initialized, they will not be visited by this iterator.

This function can generate the following errors (set when returning false):

no errors are defined for this function

Invariant: NULL != factory; NULL != iter

Parameters

[in]	factory	the SASL mechanism factory
[out]	iter
[out]	err	the error information (provide NULL to ignore)

Return values

bool	this function always returns true

JABBERWERX_API bool jw_sasl_factory_iter_next	(	jw_sasl_factory_iter *	iter,
		jw_sasl_mech **	mech,
		jw_err *	err
	)

Get the next-highest-priority mechanism registered in the factory.

This function can generate the following errors (set when returning false):

no errors are defined for this function

Invariant: NULL != iter; NULL != mech

Parameters

[in]	iter	the iterator. This parameter is both read and modified.
[out]	mech	the next item in the collection, or NULL if no more exist
[out]	err	the error information (provide NULL to ignore)

Return values

bool	this function always returns true

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation