1 files changed, 194 insertions, 0 deletions
diff --git a/libapol/include/apol/policy-path.h b/libapol/include/apol/policy-path.h
new file mode 100644
index 0000000..771fdf5
--- /dev/null
+++ b/libapol/include/apol/policy-path.h
@@ -0,0 +1,194 @@
+/**
+ * @file
+ *
+ * An opaque structure that represents a policy "path".  A policy path
+ * may really be a base policy and a number of modules, thus a single
+ * string is not sufficient.
+ *
+ * @author Jeremy A. Mowery jmowery@tresys.com
+ * @author Jason Tang  jtang@tresys.com
+ *
+ * Copyright (C) 2006-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 APOL_POLICY_PATH_H
+#define APOL_POLICY_PATH_H
+
+#ifdef	__cplusplus
+extern "C"
+{
+#endif
+
+#include "vector.h"
+
+	typedef struct apol_policy_path apol_policy_path_t;
+
+/**
+ * Type of policy this path represents - either a single path, for a
+ * monolithic policy, or a path + multiple modules for modular policy.
+ */
+	typedef enum apol_policy_path_type
+	{
+		APOL_POLICY_PATH_TYPE_MONOLITHIC = 0,
+		APOL_POLICY_PATH_TYPE_MODULAR
+	} apol_policy_path_type_e;
+
+/**
+ * Create a policy path from scratch.  The resulting object represents
+ * the file or files needed to load a policy.
+ *
+ * @param path_type Type of policy to represent.
+ * @param path Primary path name.  For modular policies this is the
+ * base policy's path.
+ * @param modules Vector of strings representing modules' paths.  The
+ * vector can be NULL to mean no modules.  This parameter is ignored
+ * if path_type is not APOL_POLICY_PATH_TYPE_MODULAR.  The function
+ * will duplicate the vector and its contents.
+ *
+ * @return An apol_policy_path object, or NULL upon error.
+ */
+	extern apol_policy_path_t *apol_policy_path_create(apol_policy_path_type_e path_type, const char *path,
+							   const apol_vector_t * modules);
+
+/**
+ * Create a policy path, initialized from another policy path.  This
+ * function recursively duplicates all data within the original path.
+ *
+ * @param path Policy path to duplicate.
+ *
+ * @return An apol_policy_path object, or NULL upon error.
+ */
+	extern apol_policy_path_t *apol_policy_path_create_from_policy_path(const apol_policy_path_t * path);
+
+/**
+ * Create a policy path, initialize by the contents of a <em>policy
+ * path list</em> file.  Call apol_policy_path_to_filename() to write
+ * a policy path list to disk.
+ *
+ * @param filename Name of the file containing a policy path list.
+ *
+ * @return An apol_policy_path object, or NULL upon error.
+ */
+	extern apol_policy_path_t *apol_policy_path_create_from_file(const char *filename);
+
+/**
+ * Create a policy path, initialized by a special path format string.
+ * Call apol_policy_path_to_string() to create this string.
+ *
+ * @param path_string String containing initialization data for the
+ * object.
+ *
+ * @return An apol_policy_path object, or NULL upon error.
+ */
+	extern apol_policy_path_t *apol_policy_path_create_from_string(const char *path_string);
+
+/**
+ * Destroy the referencened policy path object.
+ *
+ * @param path Policy path to destroy.  The pointer will be set to
+ * NULL afterwards.  (If pointer is already NULL then do nothing.)
+ */
+	extern void apol_policy_path_destroy(apol_policy_path_t ** path);
+
+/**
+ * Compare two policy paths, determining if one is different than the
+ * other.  The returned value is stable, in that it may be used as the
+ * basis for sorting a list of policy paths.  Monolithic policies are
+ * considered "less than" modular policies.
+ *
+ * @param a First policy path to compare.
+ * @param b Second policy path to compare.
+ *
+ * @return < 0 if path A is "less than" B, > 0 if A is "greater than"
+ * B, or 0 if equivalent or undeterminable.
+ */
+	extern int apol_policy_path_compare(const apol_policy_path_t * a, const apol_policy_path_t * b);
+
+/**
+ * Get the type of policy this path object represents.
+ *
+ * @param path Policy path object to query.
+ *
+ * @return Type of policy the object represents.
+ */
+	extern apol_policy_path_type_e apol_policy_path_get_type(const apol_policy_path_t * path);
+
+/**
+ * Get the primary path name from a path object.  For monolithic
+ * policies this is the path to the policy.  For modular policies this
+ * is the base policy path.
+ *
+ * @param path Policy path object to query.
+ *
+ * @return Primary path, or NULL upon error.  Do not modify
+ * this string.
+ */
+	extern const char *apol_policy_path_get_primary(const apol_policy_path_t * path);
+
+/**
+ * Get the list of modules from a path object.  This will be a vector
+ * of strings.  It is an error to call this function for non-modular
+ * policies.
+ *
+ * @param path Policy path object to query.
+ *
+ * @return Vector of module paths, or NULL upon error.  Do not modify
+ * this vector or its contents.  Note that the vector could be empty.
+ */
+	extern const apol_vector_t *apol_policy_path_get_modules(const apol_policy_path_t * path);
+
+/**
+ * Write a human-readable <em>policy path list</em> to disk.  This
+ * file describes a policy path and is suitable as input to
+ * apol_policy_path_create_from_file().
+ *
+ * @param path Policy path to write to disk.
+ * @param filename Name of the file to write policy path list.  If the
+ * file already exists it will be overwritten.
+ *
+ * @return 0 on successful write, < 0 on error.
+ */
+	extern int apol_policy_path_to_file(const apol_policy_path_t * path, const char *filename);
+
+/**
+ * Encode a path object into a specially formatted string.  The
+ * resulting string is suitable as input to
+ * apol_policy_path_create_from_string().
+ *
+ * @param path Policy path object to encode.
+ *
+ * @return Formatted string for the path object, or NULL upon error.
+ * The caller is responsible for calling free() upon the returned
+ * value.
+ */
+	extern char *apol_policy_path_to_string(const apol_policy_path_t * path);
+
+/**
+ * Determine if a file is a policy path list.
+ *
+ * @param filename Name of the file to test.
+ *
+ * @return > 0 if the file is a policy path list, 0 if it is not,
+ * and < 0 on error.
+ */
+	extern int apol_file_is_policy_path_list(const char *filename);
+
+#ifdef	__cplusplus
+}
+#endif
+
+#endif