1 files changed, 362 insertions, 0 deletions
diff --git a/libseaudit/include/seaudit/model.h b/libseaudit/include/seaudit/model.h
new file mode 100644
index 0000000..e5daacf
--- /dev/null
+++ b/libseaudit/include/seaudit/model.h
@@ -0,0 +1,362 @@
+/**
+ *  @file
+ *
+ *  Public interface to a seaudit_model.  This represents a subset of
+ *  log messages from one or more seaudit_log, where the subset is
+ *  defined by a finite set of seaudit_filter and sorted by some
+ *  criterion or criteria.
+ *
+ *  @author Jeremy A. Mowery jmowery@tresys.com
+ *  @author Jason Tang jtang@tresys.com
+ *
+ *  Copyright (C) 2004-2007 Tresys Technology, LLC
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library 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
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
+#ifndef SEAUDIT_MODEL_H
+#define SEAUDIT_MODEL_H
+
+#ifdef  __cplusplus
+extern "C"
+{
+#endif
+
+#include "filter.h"
+#include "log.h"
+#include "message.h"
+#include "sort.h"
+
+#include <stdlib.h>
+
+	typedef struct seaudit_model seaudit_model_t;
+
+/**
+ * Create a seaudit_model based upon the messages from some particular
+ * seaudit_log.  The model will be initialized with the default filter
+ * (i.e., accept all of the messages from the log).
+ *
+ * @param name Name for the model; the string will be duplicated.  If
+ * NULL then the model will be assigned a non-unique default name.
+ * @param log Initial log for this model to watch.  If NULL then do
+ * not watch any log files.
+ *
+ * @return An initialized model, or NULL upon error.  The caller must
+ * call seaudit_model_destroy() afterwards.
+ */
+	extern seaudit_model_t *seaudit_model_create(const char *name, seaudit_log_t * log);
+
+/**
+ * Create a new seaudit_model object, initialized with the data from
+ * an existing model.  This will do a deep copy of the original model.
+ * The new model will be watch the same logs that the original model
+ * was watching.
+ *
+ * @param model Model to clone.
+ *
+ * @return A cloned model, or NULL upon error.  The caller must call
+ * seaudit_model_destroy() afterwards.
+ */
+	extern seaudit_model_t *seaudit_model_create_from_model(const seaudit_model_t * model);
+
+/**
+ * Create and return a model initialized from the contents of a XML
+ * configuration file.  This will also load filters into the model.
+ * The model will not be associated with any logs; for that call
+ * seaudit_model_append_log().
+ *
+ * @param filename File containing model data.
+ *
+ * @return An initialized model, or NULL upon error.  The caller must
+ * call seaudit_model_destroy() afterwards.
+ *
+ * @see seaudit_model_save_to_file()
+ */
+	extern seaudit_model_t *seaudit_model_create_from_file(const char *filename);
+
+/**
+ * Destroy the referenced seadit_model object.
+ *
+ * @param model Model to destroy.  The pointer will be set to NULL
+ * afterwards.  (If pointer is already NULL then do nothing.)
+ */
+	extern void seaudit_model_destroy(seaudit_model_t ** model);
+
+/**
+ * Save to disk, in XML format, the given model's values.  This
+ * includes the filters contained within the model as well.  Note that
+ * this does not save the messages within the model nor the associated
+ * logs.
+ *
+ * @param model Model to save.
+ * @param filename Name of the file to write.  If the file already
+ * exists it will be overwritten.
+ *
+ * @return 0 on success, < 0 on error.
+ *
+ * @see seaudit_model_create_from_file()
+ */
+	extern int seaudit_model_save_to_file(const seaudit_model_t * model, const char *filename);
+
+/**
+ * Get the name of this model.
+ *
+ * @param model Model whose name to get.
+ *
+ * @return Name of the model, or NULL upon error.  Do not modify this
+ * string.
+ */
+	extern const char *seaudit_model_get_name(const seaudit_model_t * model);
+
+/**
+ * Set the name of this model, overwriting any previous name.
+ *
+ * @param model Model whose name to set.
+ * @param name New name for the model; the string will be duplicated.
+ * If NULL then the model will be assigned a non-unique default name.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int seaudit_model_set_name(seaudit_model_t * model, const char *name);
+
+/**
+ * Have the given model start watching the given log file, in addition
+ * to any other log files the model was watching.
+ *
+ * @param model Model to modify.
+ * @param log Additional log file to watch.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int seaudit_model_append_log(seaudit_model_t * model, seaudit_log_t * log);
+
+/**
+ * Append a filter to a model.  The next time the model's messages are
+ * retrieved only those messages that match this filter will be
+ * returned.  Multiple filters may be applied to a model.  Upon
+ * success, the model takes ownership of the filter.
+ *
+ * @param model Model to modify.
+ * @param filter Additional filter to be applied.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int seaudit_model_append_filter(seaudit_model_t * model, seaudit_filter_t * filter);
+
+/**
+ * Get the list of filters for a model.  Whenever a filter is modified
+ * the model will be recomputed.  Note: to remove a filter from the
+ * model use seaudit_model_remove_filter().
+ *
+ * @param model Model containing filters.
+ *
+ * @return Vector of seaudit_filter objects, or NULL upon error.  Note
+ * that the vector my be empty.  Do not destroy or otherwise modify
+ * this vector.  (It is safe to manipulate the elements within the
+ * vector.)
+ */
+	extern const apol_vector_t *seaudit_model_get_filters(const seaudit_model_t * model);
+
+/**
+ * Remove a filter from a model.  The given parameter must match one
+ * of the filters stored within the model; call
+ * seaudit_model_get_filters() to get a list of the model's filters.
+ *
+ * @param model Model to modify.
+ * @param filter Filter to remove.  Upon success the pointer becomes
+ * invalid.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int seaudit_model_remove_filter(seaudit_model_t * model, seaudit_filter_t * filter);
+
+/**
+ * Set a model to accept a message if all filters are met (default
+ * behavior) or if any filter is met.  Note that is independent from
+ * the setting given to seaudit_model_set_filter_visible().
+ *
+ * @param model Model to modify.
+ * @param match Matching behavior if model has multiple filters.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int seaudit_model_set_filter_match(seaudit_model_t * model, seaudit_filter_match_e match);
+
+/**
+ * Get the current filter match value for a model.
+ *
+ * @param model Model containing filter match value.
+ *
+ * @return One of SEAUDIT_FILTER_MATCH_ALL or SEAUDIT_FILTER_MATCH_ANY.
+ */
+	extern seaudit_filter_match_e seaudit_model_get_filter_match(const seaudit_model_t * model);
+
+/**
+ * Set a model to either show (default behavior) or hide messages
+ * accepted by the filters.  Note that is independent from the setting
+ * given to seaudit_model_set_filter_match().
+ *
+ * @param model Model to modify.
+ * @param visible Messages to show if model has any filters.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int seaudit_model_set_filter_visible(seaudit_model_t * model, seaudit_filter_visible_e visible);
+
+/**
+ * Get the current filter visibility value for a model.
+ *
+ * @param model Model containing filter visibility value.
+ *
+ * @return One of SEAUDIT_FILTER_VISIBLE_SHOW or
+ * SEAUDIT_FILTER_VISIBLE_HIDE.
+ */
+	extern seaudit_filter_visible_e seaudit_model_get_filter_visible(const seaudit_model_t * model);
+
+/**
+ * Append a sort criterion to a model.  The next time the model's
+ * messages are retrieved they will be sorted by this criterion.  If
+ * the model already has sort criteria, they will have a higher
+ * priority than this new criterion.  Upon success, the model takes
+ * ownership of the sort object
+ *
+ * @param model Model to modify.
+ * @param sort Additional sort criterion.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int seaudit_model_append_sort(seaudit_model_t * model, seaudit_sort_t * sort);
+
+/**
+ * Remove all sort criteria from this model.  The next time the
+ * model's messages are retrieved they will be in the same order as
+ * provided by the model's log(s).
+ *
+ * @param model Model to modify.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int seaudit_model_clear_sorts(seaudit_model_t * model);
+
+/**
+ * Return a value indicating if this model has changed since the last
+ * time seaudit_model_get_messages() was called.  Note that upon a
+ * non-zero return value, the vector returned by
+ * seaudit_model_get_messages() might contain the same messages.  For
+ * example, the user could have removed all sorts but then re-inserted
+ * them in the same order.
+ *
+ * @param model Model to check.
+ *
+ * @return 0 if the model is unchanged, non-zero if it may have
+ * changed.
+ */
+	extern int seaudit_model_is_changed(const seaudit_model_t * model);
+
+/**
+ * Return a sorted list of messages associated with this model.  This
+ * will cause the model to recalculate, as necessary, all messages
+ * according to its filters and then sort them.
+ *
+ * @param log Log to which report error messages.
+ * @param model Model containing messages.
+ *
+ * @return A newly allocated vector of seaudit_message_t, pre-filtered
+ * and pre-sorted, or NULL upon error.  The caller is responsible for
+ * calling apol_vector_destroy() upon this value.
+ */
+	extern apol_vector_t *seaudit_model_get_messages(const seaudit_log_t * log, seaudit_model_t * model);
+
+/**
+ * Return a sorted list of malformed messages associated with this
+ * model.  This is the union of all malformed messages from the
+ * model's logs.  This will cause the model to recalculate, as
+ * necessary, all messages according to its filters.
+ *
+ * @param log Log to which report error messages.
+ * @param model Model containing malformed messages.
+ *
+ * @return A newly allocated vector of strings, or NULL upon error.
+ * Treat the contents of the vector as const char *.  The caller is
+ * responsible for calling apol_vector_destroy() upon this value.
+ */
+	extern apol_vector_t *seaudit_model_get_malformed_messages(const seaudit_log_t * log, seaudit_model_t * model);
+
+/**
+ * Hide a message from a model such that the next time
+ * seaudit_model_get_messages() is called, the given message will not
+ * be returned within the vector.
+ *
+ * @param model Model containing message to hide.
+ * @param message Message to be marked hidden.  If NULL, then do
+ * nothing.  It is safe to make duplicate calls to this function with
+ * the same message.
+ */
+	extern void seaudit_model_hide_message(seaudit_model_t * model, const seaudit_message_t * message);
+
+/**
+ * Return the number of avc allow messages currently within the model.
+ * This will cause the model to recalculate, as necessary, all
+ * messages according to its filters.
+ *
+ * @param log Log to which report error messages.
+ * @param model Model to get statistics.
+ *
+ * @return Number of allow messages in the model.  This could be zero.
+ */
+	extern size_t seaudit_model_get_num_allows(const seaudit_log_t * log, seaudit_model_t * model);
+
+/**
+ * Return the number of avc deny messages currently within the model.
+ * This will cause the model to recalculate, as necessary, all
+ * messages according to its filters.
+ *
+ * @param log Log to which report error messages.
+ * @param model Model to get statistics.
+ *
+ * @return Number of deny messages in the model.  This could be zero.
+ */
+	extern size_t seaudit_model_get_num_denies(const seaudit_log_t * log, seaudit_model_t * model);
+
+/**
+ * Return the number of boolean change messages currently within the
+ * model.  This will cause the model to recalculate, as necessary, all
+ * messages according to its filters.
+ *
+ * @param log Log to which report error messages.
+ * @param model Model to get statistics.
+ *
+ * @return Number of boolean messages in the model.  This could be
+ * zero.
+ */
+	extern size_t seaudit_model_get_num_bools(const seaudit_log_t * log, seaudit_model_t * model);
+
+/**
+ * Return the number of load messages currently within the model.
+ * This will cause the model to recalculate, as necessary, all
+ * messages according to its filters.
+ *
+ * @param log Log to which report error messages.
+ * @param model Model to get statistics.
+ *
+ * @return Number of load messages in the model.  This could be zero.
+ */
+	extern size_t seaudit_model_get_num_loads(const seaudit_log_t * log, seaudit_model_t * model);
+
+#ifdef  __cplusplus
+}
+#endif
+
+#endif