merged tasking branch into trunk

src/charon/sa/tasks/task.h

@@ -0,0 +1,151 @@
+/**
+ * @file task.h
+ * 
+ * @brief Interface task_t.
+ * 
+ */
+
+/*
+ * Copyright (C) 2006 Martin Willi
+ * Hochschule fuer Technik Rapperswil
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the
+ * Free Software Foundation; either version 2 of the License, or (at your
+ * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * for more details.
+ */
+
+#ifndef TASK_H_
+#define TASK_H_
+
+typedef enum task_type_t task_type_t;
+typedef struct task_t task_t;
+
+#include <library.h>
+#include <sa/ike_sa.h>
+#include <encoding/message.h>
+
+/**
+ * @brief Different kinds of tasks.
+ * 
+ * @ingroup tasks
+ */
+enum task_type_t {
+	/** establish an unauthenticated IKE_SA */
+	IKE_INIT,
+	/** detect NAT situation */
+	IKE_NATD,
+	/** authenticate the initiated IKE_SA */
+	IKE_AUTHENTICATE,
+	/** exchange certificates and requests */
+	IKE_CERT,
+	/** Configuration payloads, virtual IP and such */
+	IKE_CONFIG,
+	/** DPD detection */
+	IKE_DEADPEER,
+	/** rekey an IKE_SA */
+	IKE_REKEY,
+	/** delete an IKE_SA */
+	IKE_DELETE,
+	/** liveness check */
+	IKE_DPD,
+	/** establish a CHILD_SA within an IKE_SA */
+	CHILD_CREATE,
+	/** delete an established CHILD_SA */
+	CHILD_DELETE,
+	/** rekey an CHILD_SA */
+	CHILD_REKEY,
+};
+
+/**
+ * enum names for task_type_t.
+ */
+extern enum_name_t *task_type_names;
+
+/**
+ * @brief Interface for a task, an operation handled within exchanges.
+ *
+ * A task is an elemantary operation. It may be handled by a single or by
+ * multiple exchanges. An exchange may even complete multiple tasks.
+ * A task has a build() and an process() operation. The build() operation 
+ * creates payloads and adds it to the message. The process() operation
+ * inspects a message and handles its payloads. An initiator of an exchange
+ * first calls build() to build the request, and processes the response message
+ * with the process() method.
+ * A responder does the opposite; it calls process() first to handle an incoming
+ * request and secondly calls build() to build an appropriate response.
+ * Both methods return either SUCCESS, NEED_MORE or FAILED. A SUCCESS indicates
+ * that the task completed, even when the task completed unsuccesfully. The
+ * manager then removes the task from the list. A NEED_MORE is returned when
+ * the task needs further build()/process() calls to complete, the manager
+ * leaves the taks in the queue. A returned FAILED indicates a critical failure.
+ * The manager closes the IKE_SA whenever a task returns FAILED.
+ *
+ * @b Constructors:
+ *  - None, use implementations specific constructors
+ * 
+ * @ingroup tasks
+ */
+struct task_t {
+
+	/**
+	 * @brief Build a request or response message for this task.
+	 * 
+	 * @param this 			calling object
+	 * @param message		message to add payloads to
+	 * @return
+	 * 						- FAILED if a critical error occured
+	 *						- NEED_MORE if another call to build/process needed
+	 *						- SUCCESS if task completed
+	 */
+	status_t (*build) (task_t *this, message_t *message);
+
+	/**
+	 * @brief Process a request or response message for this task.
+	 * 
+	 * @param this 			calling object
+	 * @param message		message to read payloads from
+	 * @return
+	 * 						- FAILED if a critical error occured
+	 *						- NEED_MORE if another call to build/process needed
+	 *						- SUCCESS if task completed
+	 */
+	status_t (*process) (task_t *this, message_t *message);
+
+	/**
+	 * @brief Get the type of the task implementation.
+	 * 
+	 * @param this 			calling object
+	 */
+	task_type_t (*get_type) (task_t *this);
+	
+	/**
+	 * @brief Migrate a task to a new IKE_SA.
+	 *
+	 * After migrating a task, it goes back to a state where it can be
+	 * used again to initate an exchange. This is useful when a task
+	 * has to get migrated to a new IKE_SA.
+	 * A special usage is when a INVALID_KE_PAYLOAD is received. A call
+	 * to reset resets the task, but uses another DH group for the next
+	 * try.
+	 * The ike_sa is the new IKE_SA this task belongs to and operates on.
+	 *
+	 * @param this 			calling object
+	 * @param ike_sa		new IKE_SA this task works for
+	 */
+	void (*migrate) (task_t *this, ike_sa_t *ike_sa);
+	
+	/**
+	 * @brief Destroys a task_t object.
+	 *
+	 * @param this 			calling object
+	 */
+	void (*destroy) (task_t *this);
+};
+
+#endif /* TASK_H_ */