/*
 * File:        DbReader.h $XConsortium: DbReader.h /main/cde1_maint/1 1995/07/14 20:22:44 drk $
 *
 * Description: Public include file for the database reader.
 *
 * (c) Copyright 1987, 1988, 1989 by Hewlett-Packard Company
 *
 * (c) Copyright 1993, 1994 Hewlett-Packard Company			*
 * (c) Copyright 1993, 1994 International Business Machines Corp.	*
 * (c) Copyright 1993, 1994 Sun Microsystems, Inc.			*
 * (c) Copyright 1993, 1994 Novell, Inc.				*
 */


#ifndef _Dt_DbReader_h
#define _Dt_DbReader_h

#include <X11/Xlib.h>
#include <X11/Xresource.h>
#include <Dt/DbUtil.h>

#define DTRECORDIDENTIFIER NULL
#define DTUNLIMITEDFIELDS  0

/* one set of attribute/pair */
typedef struct
{
	XrmQuark                fieldName;
	char                    *fieldValue;
} DtDtsDbField;

/*
 * Opaque identifier used for identifying a database file name.  The opaque
 * identifier can be converted to an ascii string, using the function
 * _DtDbPathIdToString().
 */
#define DtDbPathId long

/*
 * All record converters should expect to be called with the parameters
 * indicated below:
 *
 *   fields:    This is an array of keyword/value pair strings, each
 *              representing one field value for this database record.  NOTE:
 *              the keywords have not been validated; this is the
 *              responsibility of the converter, and is usually accomplished
 *              by calling _DtValidateFieldNames().  The array is NULL
 *              terminated, with the last entry having both the 'fieldName'
 *              and 'fieldValue' pointers set to NULL.  The first entry always
 *              represents the record identifier, with the 'fieldName' set
 *              to the record type string, and the 'fieldValue' set to any
 *              remaining data specified on the record identifier line.
 *
 *   pathId:    Is an opaque identifier, which can be used to retrieve the name
 *              of the database file from which this record was obtained.  By
 *              calling _DtDbPathIdToString(), the database file, in
 *              "host:/path" format, can be obtained.
 *
 *   hostPrefix: If the database file was loaded from a machine other than the
 *               local machine, then this string indicates the host prefix, in
 *               "/nfs/<host>" format.  If the host was the local host, then
 *               this value is set to NULL.
 *
 *   rejectionStatus: This flag indicates whether any of the earlier record
 *                    converters had rejected this entry.  Certain classes
 *                    of converters may choose to ignore entries if they
 *                    had already been rejected.
 *
 * It is the responsibility of the converter to perform any necessary
 * verification of the passed in set of keywords; the function
 * _DtValidateFieldNames() is provided as a convenience function for performing
 * this type of validation.  Typically, the converter will write an error to
 * the user's errorlog file, if an invalid record is encountered.
 *
 * It is also the responsibility of the converter to allocate any memory needed
 * to store the new record.  The strings contained within the 'fields' array
 * will all be freed when the converter returns to _DtDbRead(), so the
 * converter should make copies of any information it wishes to use in the
 * future.  The converter is also responsible for adding the new record to
 * whatever storage array it is using to save record information.
 *
 * If the converter decides to reject the record, then it should return a
 * 'True' value.  If the record was acceptable, then 'False' should be
 * returned.
 */
typedef Boolean (*DtDbConverter) (DtDtsDbField * fields,
                                  DtDbPathId pathId,
                                  char * hostPrefix,
                                  Boolean rejectionStatus);

/*
 * This structure defines each record type which should be loaded by
 * _DtDbRead().  Since _DtDbRead() is capable of loading multiple record types
 * (i.e ACTION, DATA_CRITERIA, etc) in a single pass, the invoking function will
 * pass in an array of these structures, for which each element will define a
 * record type which should be loaded.  Each record definition requires the
 * following information:
 *
 *   recordKeyword: This is the keyword which uniquely identifies the record
 *                  which matches this definition.  Examples are "ACTION" and
 *                  "DATA_CRITERIA".
 *
 *   maxFields:     Indicates the maximum number of fields which is expected
 *                  by this record type; typically, this corresponds to the
 *                  number of distinct field keywords supported by this type
 *                  of record.  This feature is used to prevent runaway database
 *                  records from getting out of hand; a runaway database record
 *                  typically occurs when the user forgets to include line
 *                  continuation characters, and a long 'description' field
 *                  is entered.  If this parameter is set to
 *                  DTUNLIMITEDFIELDS, then the check for runaway records
 *                  will be disabled for records of this type.
 *
 *  converters:     This is a NULL-terminated array of function pointers, 
 *                  corresponding to the set of record converters which will 
 *                  be called, whenever a record of this type is encountered.  
 *                  The converters are called in order, and all converters will
 *                  be called, even if an earlier one rejects the record.  The
 *                  last entry in the array must be set to NULL.
 */
typedef struct {
   char * recordKeyword;
   int maxFields;
   DtDbConverter * converters;
} DtDbRecordDesc;


/*
 * _DtDbRead() is the function which causes the specified set of directories to
 * be searched for files ending with the specified suffix.  Although not
 * required, the set of directories to search is typically obtained by calling
 * _DtGetDatabaseDirPaths().  This function supports the loading of multiple
 * field types, all in a single pass of the database files.  This function does
 * not attempt to manage the memory used to store the information extracted from
 * the database files; it is the responsibility of the function calling this
 * procedure to initialize any storage, and it is the responsibility of the
 * record converters to allocate any memory needed to store and record, along
 * with adding the record to the appropriate storage array.
 *
 *  dirs:        The set of directories to be searched for database files.
 *
 *  suffix:      The file suffix (i.e. ".vf") used to qualify which files within
 *               the database directories should be loaded.
 *
 *  recordDescriptions: An array, where each entry describes a database record
 *                      which should be loaded during this pass of _DtDbRead().
 *                      See the definition for this structure, for more details.
 *
 *  int numRecordDescriptions:  The number of entries in the above array.
 */
#ifdef _NO_PROTO
extern void _DtDbRead ();
#else
extern void _DtDbRead (DtDirPaths * dirs,
                       char * suffix,
                       DtDbRecordDesc * recordDescriptions,
                       int numRecordDescriptions);
#endif


/*
 * _DtDbPathIdToString() is used to map a filename identifier, represented
 * by an opaque DtDbPathId value, into its corresponding ascii string
 * representation.  The returned string is owned by the calling application,
 * which should free it up when no longer needed.
 */
#ifdef _NO_PROTO
extern char * _DtDbPathIdToString();
#else
extern char * _DtDbPathIdToString ( DtDbPathId pathId );
#endif

#endif /* _Dt_DbReader_h */
/* DON'T ADD ANYTHING AFTER THIS #endif */
