/**
 *  @file
 *  Public Interface for querying portcons, netifcons, and nodecons of
 *  a policy.
 *
 *  @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_NETCON_QUERY_H
#define APOL_NETCON_QUERY_H

#ifdef	__cplusplus
extern "C"
{
#endif

#include "policy.h"
#include "vector.h"
#include "context-query.h"
#include <qpol/policy.h>

	typedef struct apol_portcon_query apol_portcon_query_t;
	typedef struct apol_netifcon_query apol_netifcon_query_t;
	typedef struct apol_nodecon_query apol_nodecon_query_t;

/******************** portcon queries ********************/

/**
 * Execute a query against all portcons within the policy.  The
 * returned portcons will be unordered.
 *
 * @param p Policy within which to look up portcons.
 * @param po Structure containing parameters for query.	 If this is
 * NULL then return all portcons.
 * @param v Reference to a vector of qpol_portcon_t.  The vector will
 * be allocated by this function. The caller must call
 * apol_vector_destroy() afterwards.  This will be set to NULL upon no
 * results or upon error.
 *
 * @return 0 on success (including none found), negative on error.
 */
	extern int apol_portcon_get_by_query(const apol_policy_t * p, const apol_portcon_query_t * po, apol_vector_t ** v);

/**
 * Allocate and return a new portcon query structure. All fields are
 * initialized, such that running this blank query results in
 * returning all portcons within the policy. The caller must call
 * apol_portcon_query_destroy() upon the return value afterwards.
 *
 * @return An initialized portcon query structure, or NULL upon error.
 */
	extern apol_portcon_query_t *apol_portcon_query_create(void);

/**
 * Deallocate all memory associated with the referenced portcon
 * query, and then set it to NULL.  This function does nothing if the
 * query is already NULL.
 *
 * @param po Reference to a portcon query structure to destroy.
 */
	extern void apol_portcon_query_destroy(apol_portcon_query_t ** po);

/**
 * Set a portcon query to return only portcons that use this protocol.
 *
 * @param p Policy handler, to report errors.
 * @param po Portcon query to set.
 * @param proto Limit query to only portcons with this protocol, or
 * negative to unset this field.
 *
 * @return Always 0.
 */
	extern int apol_portcon_query_set_protocol(const apol_policy_t * p, apol_portcon_query_t * po, int proto);

/**
 * Set a portcon query to return only portcons with this as their low
 * port.
 *
 * @param p Policy handler, to report errors.
 * @param po Portcon query to set.
 * @param low Limit query to only portcons with this low port, or
 * negative to unset this field.
 *
 * @return Always 0.
 */
	extern int apol_portcon_query_set_low(const apol_policy_t * p, apol_portcon_query_t * po, int low);

/**
 * Set a portcon query to return only portcons with this as their high
 * port.
 *
 * @param p Policy handler, to report errors.
 * @param po Portcon query to set.
 * @param high Limit query to only portcons with this high port, or
 * negative to unset this field.
 *
 * @return Always 0.
 */
	extern int apol_portcon_query_set_high(const apol_policy_t * p, apol_portcon_query_t * po, int high);

/**
 * Set a portcon query to return only portcons matching a context.
 * This function takes ownership of the context, such that the caller
 * must not modify nor destroy it afterwards.
 *
 * @param p Policy handler, to report errors.
 * @param po Portcon query to set.
 * @param context Limit query to only portcons matching this context,
 * or NULL to unset this field.
 * @param range_match Specifies how to match the MLS range within the
 * context.  This must be one of APOL_QUERY_SUB, APOL_QUERY_SUPER, or
 * APOL_QUERY_EXACT.  This parameter is ignored if context is NULL.
 *
 * @return Always returns 0.
 */
	extern int apol_portcon_query_set_context(const apol_policy_t * p,
						  apol_portcon_query_t * po, apol_context_t * context, unsigned int range_match);

/**
 * Creates a string containing the textual representation of
 * a portcon type.
 * @param p Reference to a policy.
 * @param portcon Reference to the portcon statement to be rendered.
 *
 * @return A newly allocated string on success, caller must free;
 * NULL on error.
 */
	extern char *apol_portcon_render(const apol_policy_t * p, const qpol_portcon_t * portcon);

/******************** netifcon queries ********************/

/**
 * Execute a query against all netifcons within the policy.  The
 * returned netifcons will be unordered.
 *
 * @param p Policy within which to look up netifcons.
 * @param n Structure containing parameters for query.	If this is
 * NULL then return all netifcons.
 * @param v Reference to a vector of qpol_netifcon_t.  The vector will
 * be allocated by this function.  The caller must call
 * apol_vector_destroy() afterwards,.  This will be set to NULL upon
 * no results or upon error.
 *
 * @return 0 on success (including none found), negative on error.
 */
	extern int apol_netifcon_get_by_query(const apol_policy_t * p, const apol_netifcon_query_t * n, apol_vector_t ** v);

/**
 * Allocate and return a new netifcon query structure.	All fields are
 * initialized, such that running this blank query results in
 * returning all netifcons within the policy.  The caller must call
 * apol_netifcon_query_destroy() upon the return value afterwards.
 *
 * @return An initialized netifcon query structure, or NULL upon
 * error.
 */
	extern apol_netifcon_query_t *apol_netifcon_query_create(void);

/**
 * Deallocate all memory associated with the referenced netifcon
 * query, and then set it to NULL.  This function does nothing if the
 * query is already NULL.
 *
 * @param n Reference to a netifcon query structure to destroy.
 */
	extern void apol_netifcon_query_destroy(apol_netifcon_query_t ** n);

/**
 * Set a netifcon query to return only netifcons that use this device.
 *
 * @param p Policy handler, to report errors.
 * @param n Netifcon query to set.
 * @param dev Limit query to only netifcons that use this device, or
 * NULL to unset this field.
 *
 * @return 0 on success, negative on error.
 */
	extern int apol_netifcon_query_set_device(const apol_policy_t * p, apol_netifcon_query_t * n, const char *dev);

/**
 * Set a netifcon query to return only netifcons matching this context
 * for its interface.  This function takes ownership of the context,
 * such that the caller must not modify nor destroy it afterwards.
 *
 * @param p Policy handler, to report errors.
 * @param n Netifcon query to set.
 * @param context Limit query to only netifcon matching this context
 * for its interface, or NULL to unset this field.
 * @param range_match Specifies how to match the MLS range within the
 * context.  This must be one of APOL_QUERY_SUB, APOL_QUERY_SUPER, or
 * APOL_QUERY_EXACT.  This parameter is ignored if context is NULL.
 *
 * @return Always returns 0.
 */
	extern int apol_netifcon_query_set_if_context(const apol_policy_t * p,
						      apol_netifcon_query_t * n, apol_context_t * context,
						      unsigned int range_match);

/**
 * Set a netifcon query to return only netifcons matching this context
 * for its messages.  This function takes ownership of the context,
 * such that the caller must not modify nor destroy it afterwards.
 *
 * @param p Policy handler, to report errors.
 * @param n Netifcon query to set.
 * @param context Limit query to only netifcon matching this context
 * for its messages, or NULL to unset this field.
 * @param range_match Specifies how to match the MLS range within the
 * context.  This must be one of APOL_QUERY_SUB, APOL_QUERY_SUPER, or
 * APOL_QUERY_EXACT.  This parameter is ignored if context is NULL.
 *
 * @return Always returns 0.
 */
	extern int apol_netifcon_query_set_msg_context(const apol_policy_t * p,
						       apol_netifcon_query_t * n, apol_context_t * context,
						       unsigned int range_match);

/**
 * Creates a string containing the textual representation of
 * a netifcon type.
 * @param p Reference to a policy.
 * @param netifcon Reference to the netifcon statement to be rendered.
 *
 * @return A newly allocated string on success, caller must free;
 * NULL on error.
 */
	extern char *apol_netifcon_render(const apol_policy_t * p, const qpol_netifcon_t * netifcon);

/******************** nodecon queries ********************/

/**
 * Execute a query against all nodecons within the policy.  The
 * returned nodecons will be unordered.
 *
 * @param p Policy within which to look up nodecons.
 * @param n Structure containing parameters for query.	If this is
 * NULL then return all nodecons.
 * @param v Reference to a vector of qpol_nodecon_t.  The vector will
 * be allocated by this function.  The caller must call
 * apol_vector_destroy() afterwards.  This will be set to NULL upon no
 * results or upon error.
 *
 * @return 0 on success (including none found), negative on error.
 */
	extern int apol_nodecon_get_by_query(const apol_policy_t * p, const apol_nodecon_query_t * n, apol_vector_t ** v);

/**
 * Allocate and return a new nodecon query structure.  All fields are
 * initialized, such that running this blank query results in
 * returning all nodecons within the policy.  The caller must call
 * apol_nodecon_query_destroy() upon the return value afterwards.
 *
 * @return An initialized nodecon query structure, or NULL upon
 * error.
 */
	extern apol_nodecon_query_t *apol_nodecon_query_create(void);

/**
 * Deallocate all memory associated with the referenced nodecon
 * query, and then set it to NULL.  This function does nothing if the
 * query is already NULL.
 *
 * @param n Reference to a nodecon query structure to destroy.
 */
	extern void apol_nodecon_query_destroy(apol_nodecon_query_t ** n);

/**
 * Set a nodecon query to return only nodecons with this protocol,
 * either IPv4 or IPv6.
 *
 * @param p Policy handler, to report errors.
 * @param n Nodecon query to set.
 * @param proto Limit query to only this protocol, either QPOL_IPV4 or
 * QPOL_IPV6, or a negative value to unset this field.
 *
 * @return 0 if protocol was valid, -1 on error.
 */
	extern int apol_nodecon_query_set_protocol(const apol_policy_t * p, apol_nodecon_query_t * n, int proto);

/**
 * Set a nodecon query to return only nodecons with this address.  If
 * the protocol is QPOL_IPV4 then only the first element of the
 * address array is used, for QPOL_IPV6 all four are used.
 *
 * @param p Policy handler, to report errors.
 * @param n Nodecon query to set.
 * @param addr Array of no more than four elements representing the
 * address, or NULL to unset this field.  This function will make a
 * copy of the array.
 * @param proto Format of address, either QPOL_IPV4 or QPOL_IPV6.
 * This parameter is ignored if addr is NULL.
 *
 * @return 0 if protocol was valid, -1 on error.
 */
	extern int apol_nodecon_query_set_addr(const apol_policy_t * p, apol_nodecon_query_t * n, uint32_t * addr, int proto);

/**
 * Set a nodecon query to return only nodecons with this netmask.  If
 * the protocol is QPOL_IPV4 then only the first element of the mask
 * array is used, for QPOL_IPV6 all four are used.
 *
 * @param p Policy handler, to report errors.
 * @param n Nodecon query to set.
 * @param mask Array of no more than four elements representing the
 * netmask, or NULL to unset this field.  This function will make a
 * copy of the array.
 * @param proto Format of mask, either QPOL_IPV4 or QPOL_IPV6.  This
 * parameter is ignored if mask is NULL.
 *
 * @return 0 if protocol was valid, -1 on error.
 */
	extern int apol_nodecon_query_set_mask(const apol_policy_t * p, apol_nodecon_query_t * n, uint32_t * mask, int proto);

/**
 * Set a nodecon query to return only nodecons matching this context.
 * This function takes ownership of the context, such that the caller
 * must not modify nor destroy it afterwards.
 *
 * @param p Policy handler, to report errors.
 * @param n Nodecon query to set.
 * @param context Limit query to only nodecons matching this context,
 * or NULL to unset this field.
 * @param range_match Specifies how to match the MLS range within the
 * context.  This must be one of APOL_QUERY_SUB, APOL_QUERY_SUPER, or
 * APOL_QUERY_EXACT.  This parameter is ignored if context is NULL.
 *
 * @return Always returns 0.
 */
	extern int apol_nodecon_query_set_context(const apol_policy_t * p,
						  apol_nodecon_query_t * n, apol_context_t * context, unsigned int range_match);

/**
 * Creates a string containing the textual representation of
 * a nodecon type.
 * @param p Reference to a policy.
 * @param nodecon Reference to the nodecon statement to be rendered.
 *
 * @return A newly allocated string on success, caller must free;
 * NULL on error.
 */
	extern char *apol_nodecon_render(const apol_policy_t * p, const qpol_nodecon_t * nodecon);

#ifdef	__cplusplus
}
#endif

#endif				       /* APOL_NETCON_QUERY_H */