/*
 * Runtime Configuration defines...
 *
 * Copyright 2000 by Gray Watson
 *
 * This file is part of the rc package.
 *
 * Permission to use, copy, modify, and distribute this software for
 * any purpose and without fee is hereby granted, provided that the
 * above copyright notice and this permission notice appear in all
 * copies, and that the name of Gray Watson not be used in advertising
 * or publicity pertaining to distribution of the document or software
 * without specific, written prior permission.
 *
 * Gray Watson makes no representations about the suitability of the
 * software described herein for any purpose.  It is provided "as is"
 * without express or implied warranty.
 *
 * The author may be contacted via http://256.com/gray/
 *
 * $Id: rc.h,v 1.10 2000/03/09 04:00:41 gray Exp $
 */

#ifndef __RC_H__
#define __RC_H__

/* load error codes */
#define RC_ERROR_NONE		1	/* no errors */
#define RC_ERROR_FILE		2	/* could not open the rc file */
#define RC_ERROR_ALLOC		3	/* error allocating memory */
#define RC_ERROR_MAND		4	/* mand fields missing */
#define RC_ERROR_UNKNOWN	5	/* line is unknown */
#define RC_ERROR_TYPE		6	/* type is unknown */
#define RC_ERROR_LABEL		7	/* could not find label */
#define RC_ERROR_MISSING	8	/* did not reference token */
#define RC_ERROR_DUPLICATE	9	/* duplicate label used */
#define RC_ERROR_FACILITY	10	/* unknown syslog facility */

/* variable types */
#define RC_BOOL			1	/* bool char: on/off true/false 1/0 */
#define RC_CHAR			2	/* single character */
#define RC_CHAR_P		3	/* character string (alloced) */
#define RC_SHORT		4	/* short integer */
#define RC_U_SHORT		5	/* unsigned short integer */
#define RC_INT			6	/* integer */
#define RC_U_INT		7	/* unsigned integer */
#define RC_LONG			8	/* long integer */
#define RC_U_LONG		9	/* unsigned long integer */
#define RC_FLOAT		10	/* float */
#define RC_DOUBLE		11	/* double floating point */
#define RC_BIN			12	/* binary number - 0s and 1s */
#define RC_OCT			13	/* octal number - 0-7 */
#define RC_HEX			14	/* hexadecimal number - 0-9a-f */
#define RC_SIZE			15	/* long size which knows mMbBkKgG */
#define RC_U_SIZE		16	/* u_long size which knows mMbBkKgG */
#define RC_SYSLOG		17	/* syslog facility */
#define RC_ADDRESS		18	/* long hexadecimal address: 0x0-9a-f*/
#define RC_BOOL_INT		19	/* integer version of bool */

/* AND-ed with rc_type to specify that a variable is mandatory */
#define RC_MAND			0x1000
/* see rc_loc.h for internal flag values */

/*
 * This macro can be used to convert the type field in a rc list into
 * the type number for comparison to the above values.  This is
 * necessary because the RC library overloads the rc_type entry with
 * some flags during processing.
 */
#define RC_TYPE(type)		((type) & 0x0FFF)

typedef struct {
  char		*rc_label;		/* the label to search for */
  int		rc_type;		/* type of option from above list */
  void		*rc_variable;		/* variable pointer, if ! flag */
} rc_t;

#define RC_LAST			NULL	/* last entry in rc-list */

/* line-error function pointer */
typedef void	(*rc_err_t)(const char *path, const int line_n,
			    const int err, const char *data);

#ifdef __cplusplus
extern "C" {
#endif

/*<<<<<<<<<<  The below prototypes are auto-generated by fillproto */

/*
 * const char *rc_type_string
 *
 * DESCRIPTION:
 *
 * Function to return the string representation of the type of an RC list
 * entry.
 *
 * RETURNS:
 *
 * Constant string type name or NULL on error.
 *
 * ARGUMENTS:
 *
 * rc_entry_p - pointer to an entry in a RC list.
 *
 * error_p - passes back the RC error number.
 */
extern
const char	*rc_type_string(const rc_t *rc_entry_p, int *error_p);

/*
 * int rc_value_string
 *
 * DESCRIPTION:
 *
 * Convert the value of a RC entry to its string equivalent in the buffer
 * provided.
 *
 * RETURNS:
 *
 * Returns RC error codes.
 *
 * ARGUMENTS:
 *
 * rc_entry_p - pointer to an entry in a RC list.
 *
 * buf - buffer to convert the value into.
 *
 * buf_size - size of the buffer.
 *
 * len_p - passes back the length of bytes copied into the buffer.
 */
extern
int	rc_value_string(const rc_t *rc_entry_p, char *buf,
			const int buf_size, int *len_p);

/*
 * int rc_process
 *
 * DESCRIPTION:
 *
 * Process a RC file and convert the strings into the RC list provided.
 * The RC list should then be passed to rc_cleanup so that allocations
 * can be frees.
 *
 * RETURNS:
 *
 * Returns RC error codes.
 *
 * ARGUMENTS:
 *
 * file - path of the RC file to be read and processed.
 *
 * rc_list - RC array to fill with the values from the file.  The rc_type
 * field of each entry will be altered to flag entries with memory
 * allocation.
 *
 * rc_err - function which will called to report each processing error
 * found in the RC file.
 */
extern
int	rc_process(const char *file, rc_t *rc_list, const rc_err_t rc_err);

/*
 * int rc_compare
 *
 * DESCRIPTION:
 *
 * Calls the error function for each lines that is in the RC file and not
 * in the RC list and vice versa.
 *
 * RETURNS:
 *
 * Returns RC error codes.
 *
 * ARGUMENTS:
 *
 * file - path of the RC file to be read and processed.
 *
 * rc_list - RC array to fill with the values from the file.  The rc_type
 * field of each entry will be altered to flag used entries.
 *
 * rc_err - function which will called to report each processing error
 * found in the RC file and for each RC list entry not listed in the
 * file.
 */
extern
int	rc_compare(const char *file, rc_t *rc_list, const rc_err_t rc_err);

/*
 * int rc_display
 *
 * DESCRIPTION:
 *
 * Prints the value of each of the entries in the RC_LIST to the standard
 * out stream.
 *
 * RETURNS:
 *
 * Returns RC error codes.
 *
 * ARGUMENTS:
 *
 * rc_list - RC array whose values we are to dump to stdout.
 */
extern
int	rc_display(const rc_t *rc_list);

/*
 * int rc_cleanup
 *
 * DESCRIPTION:
 *
 * Remove any allocations from the RC list after a rc_process was called.
 *
 * RETURNS:
 *
 * Returns RC error codes.
 *
 * ARGUMENTS:
 *
 * rc_list - RC array whose entries will be freed.  The rc_type field of
 * each entry will be altered to clear flags marking the memory
 * allocations and loaded status.
 */
extern
int	rc_cleanup(rc_t *rc_list);

/*
 * int rc_was_processed
 *
 * DESCRIPTION:
 *
 * Used to test whether a RC list has already been processed or not.
 *
 * RETURNS:
 *
 * Return 1 if the RC list has been processed already else 0.
 *
 * ARGUMENTS:
 *
 * rc_list - RC array to test.
 */
extern
int	rc_was_processed(rc_t *rc_list);

/*
 * int rc_entry_was_loaded
 *
 * DESCRIPTION:
 *
 * Used to test whether a RC list entry was loaded from the RC file
 * during a previous call to rc_process.
 *
 * RETURNS:
 *
 * Return 1 if the RC list entry was loaded already else 0.
 *
 * ARGUMENTS:
 *
 * rc_entry_ - pointer to a RC list entry to test.
 */
extern
int	rc_entry_was_loaded(const rc_t *rc_entry_p);

/*
 * int rc_entry_is_allocated
 *
 * DESCRIPTION:
 *
 * Used to test whether memory was allocated for a RC list entry during a
 * previous call to rc_process.
 *
 * RETURNS:
 *
 * Return 1 if the RC list entry has allocated memory else 0.
 *
 * ARGUMENTS:
 *
 * rc_entry_ - pointer to a RC list entry to test.
 */
extern
int	rc_entry_is_allocated(const rc_t *rc_entry_p);

/*
 * const char *rc_strerror
 *
 * DESCRIPTION:
 *
 * Used to pretty-print RC error codes.
 *
 * RETURNS:
 *
 * Returns the string equivalent of the error.
 *
 * ARGUMENTS:
 *
 * error - the error value to lookup.
 */
extern
const char	*rc_strerror(const int error);

/*<<<<<<<<<<   This is end of the auto-generated output from fillproto. */

#ifdef __cplusplus
}
#endif


#endif /* ! __RC_H__ */