path: root/src/input/inputEventHandler.h

/*
 # Copyright (c) 2009 - OpenSLX Project, Computer Center University of Freiburg
 #
 # This program is free software distributed under the GPL version 2.
 # See http://openslx.org/COPYING
 #
 # If you have any feedback please consult http://openslx.org/feedback and
 # send your suggestions, praise, or complaints to feedback@openslx.org
 #
 # General information about OpenSLX can be found at http://openslx.org/
 # --------------------------------------------------------------------------
 # inputEventHandler.h:
 #  - Common definitions for input event handlers
 # --------------------------------------------------------------------------
 */

#ifndef INPUTEVENTHANDLER_H_
#define INPUTEVENTHANDLER_H_

#include <QtGlobal>
#include <QtDebug>
#include <QList>
#include <QString>
#include <QCoreApplication>
#include <src/input/inputEvent.h>
#include "detail/policyChain.h"
#include "detail/systemTraits.h"

/**
 * For handling access control, this specifies who sent the input event.
 * This only really makes sense in the privileged input handler chain.
 */
struct InputEventContext
{
	InputEventContext()
	{
		hasBeenDenied = false;
	}

	virtual pid_t senderPid() const = 0; /**< PID of the sending process */
	virtual uid_t senderUid() const = 0; /**< UID of the sending process */
	virtual gid_t senderGid() const = 0; /**< GID of the sending process */

	/** Support the generation of meaningful log messages. */
	mutable bool hasBeenDenied;
};

namespace input_policy
{

/////////////////////////////////////////////////////////////////////////
// Policy:
//  Modifies the behaviour of an input handler class.
//
//  There are several kinds of policy:
//   - Security Policy (When to allow a certain action)
//   - System Requirements (When to enable a certain handler)
//   - Applicability (When to consider a certain handler)
//
//  Policies are tied together using the detail::PolicyChain class.
/////////////////////////////////////////////////////////////////////////

/**
 * Security Policy.
 * At the moment there are two security policies:
 * -* If the user is on a local seat, allow. If the user is privileged,
 *    allow. Else deny.
 * -* Allow everybody.
 *
 * Additional security policies can be added by following the example
 * set by \ref AllowLocalOrPrivileged
 *
 * \param PolicyImpl The implementation class that security decisions
 *   should be delegated to.
 * \see {AllowLocalOrPrivileged}
 * \see {AllowEverybody}
 */
template<typename PolicyImpl>
BEGIN_POLICY_CLASS(Security)
{
	bool allow(InputEventContext const* context)
	{
		return PolicyImpl::allow(context);
	}
}
END_POLICY_CLASS

/**
 * Check the default security model.
 */
struct AllowLocalOrPrivileged
{
	static bool allow(InputEventContext const*);
};

/**
 * Do not restrict execution.
 */
struct AllowEverybody
{
	static bool allow(InputEventContext const*);
};

/**
 * Shorthand for unrestricted execution.
 */
typedef Security<AllowEverybody> Unprivileged;

/**
 * System Requirements.
 *
 * At the moment, this is trivial, as PVS only runs on Linux. But,
 * as porting efforts are already underway, we include the necessary
 * machinery anyway.
 *
 * \param Trait... a list of system traits that need to be
 *   present in order for the handler that this policy is applied to
 *   to run.
 */
#ifdef DOXYGEN_RUNNING
template<typename Trait...>
#else
template<IMPLICIT_TYPE_LIST_PARAMS(Trait)>
#endif
BEGIN_POLICY_CLASS(Require)
{
	static const bool areSystemRequirementsFulfilled =
			(NextPolicy::areSystemRequirementsFulfilled
				&& !NextPolicy::areSystemRequirementsVacuouslyFulfilled)
			|| detail::Matches<AllOf<IMPLICIT_TYPE_LIST_ARGS(Trait)>, detail::SystemTraits>::value;
	static const bool areSystemRequirementsVacuouslyFulfilled = false;
}
END_POLICY_CLASS

#ifndef DOXYGEN_RUNNING
enum {
	HANDLER_CODE_DONT_CARE = 0xffff,
	HANDLER_VALUE_DONT_CARE = 0xffffffff
};
#endif

/**
 * Event selection.
 *
 * This policy makes the handler it is applied to applicable if the
 * template parameters \c EventType, \c EventCode and \c EventValue
 * match the corresponding fields of the incoming \ref InputEvent.
 *
 * Can be applied multiple times, and will be combined by logical
 * OR.
 *
 * \param EventType Match the \ref InputEvent::type() field.
 * \param EventCode (optional:) Match the \ref InputEvent::code() field.
 * \param EventValue (optional:) Match the \ref InputEvent::value() field.
 */
template<unsigned short EventType,
		unsigned short EventCode = HANDLER_CODE_DONT_CARE,
		unsigned int EventValue = HANDLER_VALUE_DONT_CARE>
BEGIN_POLICY_CLASS(Match)
{
	bool isApplicable(InputEvent const& evt)
	{
		if(evt.type() != EventType)
			return NextPolicy::isApplicable(evt);
		if(EventCode != HANDLER_CODE_DONT_CARE && evt.code() != EventCode)
			return NextPolicy::isApplicable(evt);
		if(EventValue != HANDLER_VALUE_DONT_CARE && evt.value() != EventValue)
			return NextPolicy::isApplicable(evt);
		return true;
	}
};
END_POLICY_CLASS

#ifndef DOXYGEN_RUNNING
namespace detail
{

/////////////////////////////////////////////////////////////////////////
// Base case: If no policies are given:
/////////////////////////////////////////////////////////////////////////
struct InputEventHandlerPolicyBase
{
	// The default security policy applies
	typedef AllowLocalOrPrivileged DefaultSecurityPolicyImpl;

	bool allow(InputEventContext const* context)
	{
		return DefaultSecurityPolicyImpl::allow(context);
	}

	// A handler that does not specify requirements works
	// everywhere
	static const bool areSystemRequirementsFulfilled = true;

	// We need this to implement proper logical OR
	static const bool areSystemRequirementsVacuouslyFulfilled = true;

	// Generate an error when no match policy is given.
	bool isApplicable(InputEvent const&)
	{
		return false;
	}

	// If any policy implementation needs an initialization hook:
	// Don't forget to call NextPolicy::initialize() in your
	// implementation!
	void initialize()
	{
	}
};

} // namespace detail
#endif // DOXYGEN_RUNNING

}

/**
 * Base class without template parameters to enable making a list of
 * polymorphic event handlers.
 *
 * The actual handler class needs to provide \ref doHandle and can
 * override \ref allow and \ref isApplicable.
 *
 * \note Do not derive from InputEventHandlerBase to implement
 *   new event handlers! Derive from InputEventHandler instead.
 */
class InputEventHandlerBase
{
public:
	enum HandlerStatus
	{
		HANDLER_MATCHED,		/**< The handler matched the input event and was executed. */
		HANDLER_NOT_ALLOWED,	/**< Execution of the handler was prevented by security policy. */
		HANDLER_NOT_APPLICABLE	/**< The handler did not match the input event. */
	};

	virtual void initialize() = 0;
	HandlerStatus handle(InputEvent const& evt, InputEventContext const* context = 0);

protected:
	/**
	 * Check security preconditions for the execution of this handler.
	 * This is normally handled by the \ref input_policy::Security policy.
	 */
	virtual bool allow(InputEvent const& event, InputEventContext const* context = 0) = 0;

	/**
	 * Check if this handler can handle the incoming input event.
	 * This is normally handled by the \ref input_policy::Match policy.
	 */
	virtual bool isApplicable(InputEvent const& event, InputEventContext const* context = 0) = 0;

	/**
	 * Actually handle the incoming event.
	 * It is assumed that all preconditions have been checked and the handler
	 * has been initialized at the point where this method is called.
	 */
	virtual void doHandle(InputEvent const& event, InputEventContext const* context = 0) = 0;
};

/**
 * Base class for input event handlers.
 */
#ifdef DOXYGEN_RUNNING
template<typename Policy...>
#else
template<POLICY_PARAMS>
#endif
class InputEventHandler : public InputEventHandlerBase
{
#ifndef DOXYGEN_RUNNING
protected:
	// instantiate our policy:
	typedef USE_POLICY(input_policy::detail::InputEventHandlerPolicyBase) policy_type;
	policy_type policy;
#endif

public:
	void initialize()
	{
		policy.initialize();
	}

	/** Export this so the handler chain can decide whether to include this handler */
	static const bool areSystemRequirementsFulfilled = policy_type::areSystemRequirementsFulfilled;

protected:

	bool allow(InputEvent const&, InputEventContext const* context = 0)
	{
		return policy.allow(context);
	}

	bool isApplicable(InputEvent const& event, InputEventContext const* = 0)
	{
		return policy.isApplicable(event);
	}
};

/**
 * Chain \ref InputEventHandler instances together.
 * The chain is also responsible for the creation of instances.
 *
 * \see privilegedInputEventHandlerChain.cpp
 * \see unprivilegedInputEventHandlerChain.cpp
 */
class InputEventHandlerChain
{
private:
	QList<InputEventHandlerBase*> handlers;

#ifndef DOXYGEN_RUNNING // Implementation detail
	/////////////////////////////////////////////////////////////////////////
	// We need to statically dispatch on a static member of HandlerType.
	// Unfortunately, we cannot specialize member functions of a template.
	// So, we need to make this a class with a static non-template member.
	/////////////////////////////////////////////////////////////////////////
	template<bool Compatible, typename HandlerType>
	struct ConditionallyAppend
	{
		/////////////////////////////////////////////////////////////////////////
		// This method will never be instantiated for handlers that are
		// not Compatible, thus generating no reference to HandlerType
		// and permitting compilation to proceed without
		// tedious nested preprocessor conditionals.
		/////////////////////////////////////////////////////////////////////////
		static void doIt(InputEventHandlerChain* chain)
		{
			chain->handlers.append(new HandlerType);
		}
	};

	template<typename HandlerType>
	struct ConditionallyAppend<false, HandlerType>
	{
		static void doIt(InputEventHandlerChain*)
		{
		}
	};
#endif // DOXYGEN_RUNNING

public:
	/**
	 * Add an event handler to the chain.
	 *
	 * \param fake_parameter The parameter is only for
	 *   compilers which cannot handle template member functions
	 *   correctly.
	 * \return A reference to the receiver, for invocation chaining.
	 *
	 * \note Do not pass a value to this function. The function
	 *   handles creation of an instance itself.
	 */
	template<typename HandlerType>
	InputEventHandlerChain& add(HandlerType const* fake_parameter = 0)
	{
		ConditionallyAppend<HandlerType::areSystemRequirementsFulfilled, HandlerType>::doIt(this);
		return *this;
	}

	/**
	 * Call \ref InputEventHandlerBase::initialize() on all
	 * handlers in the chain.
	 */
	void initialize()
	{
		QListIterator<InputEventHandlerBase*> i(handlers);
		while(i.hasNext())
		{
			i.next()->initialize();
		}
	}

	/**
	 * Handle an input event. All handlers in the chain are tried
	 * in the order they were added, until one handler's
	 * implementation of InputEventHandlerBase::handle() returns
	 * InputEventHandlerBase::HANDLER_MATCHED.
	 */
	void handle(InputEvent const& event, InputEventContext const* context = 0)
	{
		QListIterator<InputEventHandlerBase*> i(handlers);
		while(i.hasNext())
		{
			switch(i.next()->handle(event, context))
			{
			case InputEventHandlerBase::HANDLER_MATCHED:
				return;
			case InputEventHandlerBase::HANDLER_NOT_ALLOWED:
				context->hasBeenDenied = true;
			case InputEventHandlerBase::HANDLER_NOT_APPLICABLE:
				continue;
			}
		}
	}
};

#endif /* INPUTEVENTHANDLER_H_ */