[Top] [Contents] [Index] [ ? ]

Conf4C Tutorial & API Reference

@import "file://conf4c.css";

Conf4C Overview  Overview of the Conf4C Library; it's goals, design, and purpose
Conf4C Tutorial  Tutorial detailing how to use the Conf4C Library
Conf4C Reference  Reference documentation of the library's API
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Conf4C Overview

The Conf4C Library is a library designed to provide applications simple and direct access to a configuration file.

Introduction  
Configuration File Format  
Mailing List / Bug Reports  
Common Questions  
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Introduction

The following documents as thoroughly as possible the functions, structs, and functional requirements of the Conf4C library. This document is growing as I get time so please bear with me. author homepage

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Configuration File Format

Document file format restrictions for input config file

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Mailing List / Bug Reports

Mailing lists and bug reports - Getting help with LibConf4C

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Common Questions

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Conf4C Tutorial

The following provides a sample application listing and walks through each step of the source to better illustrate how to read a configuration file using LibConf4C.

Example Source  
Source Walkthrough  
Example Configuration File  
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Example Source 

#include <stdio.h>

#include "conf4c.h"

int
main (int argc, char **argv)
{
	Conf4CFile *c4cf;
	Conf4CFileAttrib *c4cfattrib;
	Conf4CParser *parser;
	Conf4CReader *c4cr;

	/* create an instance of Conf4CFile 		*/
	/* use values:					*/
	/* '#' denotes a comments			*/
	/* ' ' delimits a name / value pair		*/
	/* create room for 3 section types		*/
	/* create room for 3 instances of each type 	*/
	/* create froom for 5 entries in each instance	*/
	/* create room for 25 top level n/v entries 	*/
	c4cfattrib = conf4c_fileattrib_new ("apache.conf", "#", " ", CONF4C_DELIM_LAZY);
	c4cf = conf4c_file_new (3, 25);
	parser = conf4c_parser_new (c4cf, c4cfattrib);

	/* parse the file */
	conf4c_parser_parse (parser, 3, 5);
	
	/* create a reader to read the newly parsed file */
	c4cr = conf4c_reader_new (c4cf);

	/* now move the Conf4CReader through each and every name / value pair the */
	/* Conf4CFile contains, retreiving section types, section-instance names, */
	/* and both name and value strings along the way */
	do {
		printf ("Entering Section Type: %s\n", conf4c_reader_get_section_type (c4cr));

		do {
			printf ("\tListing Section Instance: %s\n", conf4c_reader_get_stor_name (c4cr));

			do {
				printf ("\t\t<Name : Value>: %s : %s\n", 
						conf4c_reader_get_value_name (c4cr), 
						conf4c_reader_get_value (c4cr));
			}while (conf4c_reader_next_name_value (c4cr));
		}while (conf4c_reader_next_stor (c4cr));
	}while (conf4c_reader_next_section (c4cr));

	/* or if you know the section-type and name of the */
	/* value you desire */
	printf ("IfModule type, prefork.c instance, MaxClients value: %s\n", 
			conf4c_reader_get_named_value (c4cr, "IfModule", "prefork.c", "MaxClients"));
	return 0;
}

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Source Walkthrough

To gain access to the LibConf4C functions and structures you must include the line: 

#include "conf4c.h"

In order to parse any configuration file you need to create at least three objects: Conf4CFileAttrib : Contains attributes about the configuration file to be parsed such as the filename, what denotes a comment, and what defines a name / value delimiter Conf4CParser : To perform the parsing of a configuration file Conf4CFile : Contains the parsed elements of a configuration file
To parse a configuration file which uses '#' as the start of a comment, a ' ' character as the delimiter between a name and a value, and a configuration file called `apache.conf': 
Conf4CFileAttrib *c4cfattrib = conf4c_fileattrib_new ("apache.conf", "#", " ", CONF4C_DELIM_LAZY);

Next, before parsing the configuration file memory must be allocated for storing the parsed configuration values. To create a Conf4CFile which allocates enough memory for (initially) 3 section types, and 25 instances in the base section (all name / value pairs outside of '<></>' section markers): 
Conf4CFile *c4cf = conf4c_file_new (3, 25);

Finally, create a Conf4CParser that will parse the configuration file specified by c4cfattrib and populate the Conf4CFile c4cf. Then to actually perform the parsing execute conf4c_parser_parse (). By passing values of '3' and '5', the parse function will (when creating new section types and section instances) allocate room for 3 section instances per section-type, and 5 name / value pairs per section instance. 
Conf4CParser *c4cp = conf4c_parser_new (c4cf, c4cfattrib);
conf4c_parser_parse (3, 5);

At this point the Conf4CFile has been populated by the conf4c_parser_parse function. To easily access the contents of a parsed Conf4CFile you will also want to create a Conf4CReader. 
Conf4CReader *c4cr = conf4c_reader_new (c4cf);

Now to iterate through every name / value pair contained within the Conf4CFile begin three while loops. The outermost loop will traverse all configured section-types. The second loop will traverse each section instance of each section-type. And the innermost loop will traverse the name / value pairs of each section instance. 
/* when a Conf4CReader is initialized it is already pointing at the */
/* first name / value pair of the first section instance of the first section-type */
do {
	do {
		do {
		} while (conf4c_reader_next_name_value (c4cr));
	} while (conf4c_reader_next_stor (c4cr));
} while (conf4c_reader_next_section (c4cr));

Then at each level you can access values such as section type, section instance name, name-value name, and name-value value with the functions: 
conf4c_reader_get_section_type ()
conf4c_reader_get_stor_name ()
conf4c_reader_get_value_name ()
conf4c_reader_get_value ()

Or gain direct access with: 
conf4c_reader_get_named_value ()

For more information about the Conf4CReader and its functionality see the Conf4C Reference.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Example Configuration File 

### Main Configuration Section
###
ServerRoot /usr/lib/apache2 			# Section-Type = ' ', Section Instance Name = ' '
PidFile /var/run/apache2.pid			# These are 5 name / value pairs with a delimiter of ' '
ErrorLog logs/error_log				# each at the top-most section-type and instance
LogLevel warn
DocumentRoot /var/www/localhost/htdocs

###
### Global Configuration
###
# For Apache2 we load all conf files in conf/modules.d
Include conf/modules.d/*.conf			# more top-most name / value pairs
Include conf/commonapache2.conf

###
### IP Address/Port
###
#BindAddress *
Listen 80

###
### Log configuration Section
###
<IfModule mod_log_config.c>			# Section-Type = 'IfModule', Section Instance Name = 'mod_log_config.c'
CustomLog logs/access_log combined env=!VLOG	# this name / value pair will be added to the 'mod_log_config.c' section
</IfModule>					# instance of the 'IfModule' section-type

###
### Virtual Hosts 
###

Include conf/vhosts/vhosts.conf			# This name / value pair, being outside of any <></> section identifiers
						# will be added to the top-most collection of name / value pairs
###
### Performance settings Section
###
#
# Timeout: The number of seconds before receives and sends time out.
#
Timeout 300					# More top-most name / value pairs

KeepAlive On

MaxKeepAliveRequests 100

KeepAliveTimeout 15

<IfModule prefork.c>				# Section-Type = 'IfModule' (like above) and
StartServers         5				# section instance name = 'prefork.c'
MinSpareServers      5				# These name / value pairs will be added to the 'prefork.c' instance
MaxSpareServers     10				# of the 'IfModule' section-type
MaxClients         150
MaxRequestsPerChild  0
</IfModule>

<IfModule worker.c>				# Another section instance of the 'IfModule' section type
StartServers         2
MaxClients         150
MinSpareThreads     25
MaxSpareThreads     75
ThreadsPerChild     25
MaxRequestsPerChild  0
</IfModule>

<IfModule perchild.c>				# Yet another 'IfModule' section-type instance
NumServers           5
StartThreads         5
MinSpareThreads      5
MaxSpareThreads     10
MaxThreadsPerChild  20
MaxRequestsPerChild  0
</IfModule>

Alias /awstatsclasses "/etc/awstats/wwwroot/classes/"	
Alias /awstatscss "/etc/awstats/wwwroot/css/"
Alias /awstatsicons "/etc/awstats/wwwroot/icon/"
ScriptAlias /awstats/ "/etc/awstats/wwwroot/cgi-bin/"

<Directory "/etc/awstats/wwwroot">		# A second section-type (Conf4CSection) will be added to accomodate
    Options None				# a new section-type of 'Directory' with '"/etc/awstats/wwwroot"' as
    AllowOverride None				# the first instance of this new section-type
    Order allow,deny
    Allow from all
</Directory>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Conf4C Reference

The following contains a listing of each object / data type and its associated functions.

Conf4CReader  
Conf4CParser  
Conf4CFileAttrib  
Conf4CFile  
Conf4CSection  
Conf4CStor  
Conf4CValue  
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Conf4CReader

Conf4CReader - A convenience object used to easily read a parsed Conf4CFile

Synopsis 

#include "conf4cfile.h"

struct Conf4CReader;

Conf4CReader *	conf4c_reader_new			(Conf4CFile *c4cf);
Conf4CReader *	conf4c_reader_get_named_value		(Conf4CReader *c4cr,
							 const char *type,
							 const char *stor,
							 const char *name);

/* Conf4CSection manipulation functions */
int		conf4c_reader_get_section_count		(Conf4CReader *c4cr);
int		conf4c_reader_set_current_section	(Conf4CReader *c4cr,
							 const unsigned int sect_index);
int		conf4c_reader_set_typed_section	(Conf4CReader *c4cr,
							 const char *type);
int		conf4c_reader_next_section		(Conf4CReader *c4cr);
char *		conf4c_reader_get_section_type		(Conf4CReader *c4cr);

/* Conf4CStor manipulation functions */
int		conf4c_reader_get_stor_count		(Conf4CReader *c4cr);
int		conf4c_reader_set_current_stor		(Conf4CReader *c4cr,
							 const unsigned int stor_index);
int		conf4c_reader_set_named_stor	(Conf4CReader *c4cr,
							 const char *name);
int		conf4c_reader_next_stor			(Conf4CReader *c4cr);
char *		conf4c_reader_get_stor_name		(Conf4CReader *c4cr);

/* name / value manipulation functions */
int		conf4c_reader_get_name_value_count	(Conf4CReader *c4cr);
int		conf4c_reader_set_current_name_value	(Conf4CReader *c4cr,
							 const unsigned int nv_index);
int		conf4c_reader_set_named_value	(Conf4CReader *c4cr,
							 const char *name);
int		conf4c_reader_next_name_value 		(Conf4CReader *c4cr);
char *		conf4c_reader_get_value_name		(Conf4CReader *c4cr);
char *		conf4c_reader_get_value			(Conf4CReader *c4cr);

Description

The Conf4CReader allows an application to easily traverse an already parsed Conf4CFile, providing simple sequential access to all name / value pairs obtained from a configuration file.

Details

struct Conf4CReader 

struct Conf4CReader;
This should not be accessed directly. Use the accessor functions below.

conf4c_reader_new () 

Conf4CReader * conf4c_reader_new (Conf4CFile *c4cf);
Creates a new Conf4CReader.

 
c4cf : an initialized and parsed (see conf4c_file_parse ()) Conf4CFile
Returns : a new Conf4CReader

conf4c_reader_get_named_value () 

int conf4c_reader_get_named_value 	(Conf4CReader *c4cr,
					 const char *type,
					 const char *stor,
					 const char *name);
Retrieves the specified value.

 
c4cr : a Conf4CReader
type : the name of the section-type containing the desired value
stor : the name of the section instance containing the desired value
name : the name of the desired value
Returns : the desired value or NULL if the value is not found

conf4c_reader_get_section_count () 

int conf4c_reader_get_section_count (Conf4CReader *c4cr);
Returns the number of section types captured from the parsed configuration file.

 
c4cr : a Conf4CReader

conf4c_reader_set_current_section () 

int conf4c_reader_set_current_section	(Conf4CReader *c4cr,
					 const unsigned int sect_index);
Points the Conf4CReader to the Conf4CSection at sect_index.

 
c4cr : a Conf4CReader
sect_index : the index of the desired Conf4CSection
Returns : a 0 if the sect_index is invalid

conf4c_reader_next_section () 

int conf4c_reader_next_section	(Conf4CReader *c4cr);
Moves the Conf4CReader on to the next Conf4CSection.

 
Returns : a 0 if the end of the Conf4CSection array has been reached

conf4c_reader_get_section_type () 

char * conf4c_reader_get_section_type	(Conf4CReader *c4cr);
Returns the section type of the current section.

conf4c_reader_set_typed_section () 

int conf4c_reader_set_typed_section	(Conf4CReader *c4cr,
					 const char *type);
Points the Conf4CReader to the Conf4CSection instances of type type.

 
c4cr : a Conf4CReader
type : the type of the desired section
Returns : a 0 if the section type is not found

conf4c_reader_get_stor_count () 

int conf4c_reader_get_stor_count	(Conf4CReader *c4cr);
Returns the number of Conf4CStor instances held within the current Conf4CSection.

conf4c_reader_set_current_stor () 

int conf4c_reader_set_current_stor 	(Conf4CReader *c4cr,
					 const unsigned int stor_index);
Sets the current Conf4CStor to that of the stor_index'th instance.

 
Returns : a 0 if the stor_index is invalid

conf4c_reader_set_named_stor () 

int conf4c_reader_set_named_stor	(Conf4CReader *c4cr,
					 const char *name);
Points the Conf4CReader to the Conf4CStor with name name.

 
c4cr : a Conf4CReader
name : the name of the desired section
Returns : a 0 if the section instance is not found

conf4c_reader_next_stor () 

int conf4c_reader_next_stor (Conf4CReader *c4cr);
Moves the Conf4CReader on to the next Conf4CStor instance within the current Conf4CSection.

 
Returns : 0 if no more Conf4CStor instances exist

conf4c_reader_get_stor_name () 

char * conf4c_reader_get_stor_name (Conf4CReader *c4cr);
Returns the name of the current Conf4CStor (the name of the current section instance).

conf4c_reader_get_name_value_count () 

int conf4c_reader_get_name_value_count (Conf4CReader *c4cr);
Returns the number of name / value pairs within the current Conf4CStor.

conf4c_reader_set_current_name_value () 

int conf4c_reader_set_current_name_value	(Conf4CReader *c4cr,
						 const unsigned int nv_index);
Points Conf4CReader at the nv_index'th name / value pair.

 
Returns : 0 if the specified nv_index is invalid (greater than the number of available name / value pairs)

conf4c_reader_set_named_value () 

int conf4c_reader_set_named_value	(Conf4CReader *c4cr,
					 const char *name);
Points Conf4CReader at the name / value pair with name name.

 
Returns : 0 if the specified name / value pair is not found

conf4c_reader_next_name_value () 

int conf4c_reader_next_name_value (Conf4CReader *c4cr);
Moves the Conf4CReader on to the next name / value pair.

 
Returns : 0 if the available name / value pairs have been exceeded

conf4c_reader_get_value_name () 

char * conf4c_reader_get_value_name (Conf4CReader *c4cr);
Returns the name portion of the current name / value pair.

conf4c_reader_get_value () 

char * conf4c_reader_get_value (Conf4CReader *c4cr);
Returns the value portion of the current name / value pair.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Conf4CParser

Conf4CParser - Provides a configuration-file parsing function.

Synopsis 

#include "conf4cfile.h"
#include "conf4cfileattrib.h"

struct Conf4CParser;

Conf4CParser *		conf4c_parser_new			(Conf4CFile *c4cf,
					 			 Conf4CFileAttrib *c4cfattrib);
int			conf4c_parser_parse			(Conf4CParser *c4cp,
								 const unsigned int instances,
								 const unsigned int entries);
Conf4CFile *		conf4c_parser_get_conf4cfile		(Conf4CParser *c4cp);
Conf4CFileAttrib *	conf4c_parser_get_conf4cfileattrib	(Conf4CParser *c4cp);

Description

The Conf4CParser is provided to separate the actual configuration file parsing algorithm from the remainder of the library; allowing for the user to implement their own parsing function (perhaps necessary for customizations and extensions to the Conf4CFileAttrib struct).

Details

Conf4CParser 

struct Conf4CParser;
This should not be accessed directly. Use the accessor functions below.

conf4c_parser_new () 

Conf4CParser * conf4c_parser_new	(Conf4CFile *c4cf,
					 Conf4CFileAttrib *c4cfattrib);
Creates a new instance of Conf4CParser.

 
c4cf : 		the Conf4CFile to be populated by the parsing
c4cfattrib : 	the attributes of the configuration file (delimiter and comment definitions) that allow the file
			to be parsed; not to mention the file name of the configuration file

conf4c_parser_parse () 

int conf4c_parser_parse	(Conf4CParser *c4cp,
			 const unsigned int instances,
			 const unsigned int entries);
Parses the configuration file specified by the member variable c4cfattrib and stores the results in the second member: c4cf.

 
c4cp : a Conf4CParser
instances : the expected number of instances of each section type
entries : the expected number of name / value pairs per section instance
Returns : an int indicating success or error during the parse; 1 = success, 0 = error

conf4c_parser_get_conf4cfile () 

Conf4CFile * conf4c_parser_get_conf4cfile	(Conf4CParser *c4cp);
Returns the stored Conf4CFile (a useless function until after conf4c_parser_parse has been called).

conf4c_parser_get_conf4cfileattrib () 

Conf4CFileAttrib * conf4c_parser_get_conf4cfileattrib	(Conf4CParser *c4cp);
Returns the stored Conf4CFileAttrib.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Conf4CFileAttrib

Conf4CFileAttrib - A collection of configuration file attributes

Synopsis 

enum Conf4CDelimType;

struct Conf4CFileAttrib;

Conf4CFileAttrib *	conf4c_fileattrib_new			(const char *fname,
								 const char *comment,
								 const char *delim,
								 Conf4CDelimType dtype);
char *			conf4c_fileattrib_get_filename		(Conf4CFileAttrib *c4cfattrib);
char * 			conf4c_fileattrib_get_commentmarker	(Conf4CFileAttrib *c4cfattrib);
char *			conf4c_fileattrib_get_delimiter		(Conf4CFileAttrib *c4cfattrib);
Conf4CDelimType		conf4c_fileattrib_get_delimiter_type	(Conf4CFileAttrib *c4cfattrib);

Description

The Conf4CFileAttrib maintains a list of attributes about a configuration file such as what denotes a comment, the delimiter which divides a name from a value, and how the delimiter should be treated. The Conf4CFileAttrib also maintains the filename of the configuration file.

Details

enum Conf4CDelimType 

typedef enum 
{
	DELIM_STRICT = 1,
	DELIM_LAZY
} Conf4CDelimType;
The delimiter type informs the parser of how the delimiter is to be treated. A value of DELIM_STRICT will require that the entire delimiter value be found in its entirity between a name / value pair. A value of DELIM_LAZY will find the first occurrence of a character specified within the delimiter string and continue until a character not within the delimieter 'set' is found.

Conf4CFileAttrib 

struct Conf4CFileAttrib;
This should not be accessed directly. Use the accessor functions below.

conf4c_fileattrib_new () 

Conf4CFileAttrib * conf4c_fileattrib_new	(const char *fname,
						 const char *comment,
						 const char *delimiter,
						 Conf4CDelimType dtype);
Creates a new instance of Conf4CFileAttrib.

 
fname : the filename of the configuration file
comment : the string which specifies a comment
delimiter : the string which specifies the seperation between name and value
dtype : how the delimiter is to be interpreted

conf4c_fileattrib_get_filename () 

char * conf4c_fileattrib_get_filename (Conf4CFileAttrib *c4cfattrib);
Returns the filename stored within the Conf4CFileAttrib.

 
c4cfattrib : a Conf4CFileAttrib

conf4c_fileattrib_get_commentmarker 

char * conf4c_fileattrib_get_commentmarker (Conf4CFileAttrib *c4cfattrib);
Returns the comment string which indicates the start of a comment within the configuration file.

 
c4cfattrib : a Conf4CFileAttrib

conf4c_fileattrib_get_delimiter () 

char * conf4c_fileattrib_get_delimiter (Conf4CFileAttrib *c4cfattrib);
Returns the delimiter string.

 
c4cfattrib : a Conf4CFileAttrib

conf4c_fileattrib_get_delimiter_type () 

Conf4CDelimType conf4c_fileattrib_get_delimiter_type (Conf4CFileAttrib *c4cfattrib);
Returns the stored delimiter type.

 
c4cfattrib : a Conf4CFileAttrib
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Conf4CFile

Conf4CFile - A logical construction of a configuration file

Synopsis 

#include "conf4csection.h"
#include "conf4cvector.h"

struct Conf4CFile;

Conf4CFile *	conf4c_file_new				(const char *fname,
							 const char *comment,
							 const char *delim,
							 Conf4CDelimType dtype,
							 const unsigned int type_capacity,
							 const unsigned int instance_capacity,
							 const unsigned int entry_capacity,
					 		 const unsigned int base_entry_capacity);
int		conf4c_file_add_section			(Conf4CFile *c4cf,
					 		 Conf4CSection *csect);
char *		conf4c_file_get_filename		(Conf4CFile *c4cf);
int		conf4c_file_get_section_count		(const Conf4CFile *c4cf);
char *		conf4c_file_get_section_type		(const Conf4CFile *c4cf,
							 const unsigned int index);
int 		conf4c_file_get_section_index		(const Conf4CFile *c4cf,
							 const char *type);
Conf4CSection *	conf4c_file_get_section_by_index	(const Conf4CFile *c4cf,
							 const unsigned int index);
Conf4CSection * conf4c_file_get_section_by_type		(const Conf4CFile *c4cf,
							 const char *type);

Description

Conf4CFile maintains a logical view of a configuration file's contents in terms of sections, section-instances, and name / value pairs.

struct Conf4CFile 

struct Conf4CFile;
This should not be accessed directly. Use the accessor functions below.

conf4c_file_new () 

Conf4CFile * conf4c_file_new 	(const char *fname,
				 const char *comment,
				 const char *delim,
				 Conf4CDelimType dtype,
				 const unsigned int type_capacity,
				 const unsigned int instance_capacity,
				 const unsigned int entry_capacity,
				 const unsigned int base_entry_capacity);
Creates a new Conf4CFile.

 
Returns : a newly created Conf4CFile, unparsed

conf4c_file_add_section () 

int	conf4c_file_add_section	(Conf4CFile *c4cf,
				 Conf4CSection *csect);
Adds a Conf4CSection instance to the Conf4CFile.

 
c4cf : a Conf4CFile
csect : the Conf4CSection instance to add to c4cf
Returns : an int value indicating success or failure; 1 = success, 0 = failure

conf4c_file_get_filename () 

char *	conf4c_file_get_filename	(const Conf4CFile *c4cf);
Returns the filename of the Conf4CFile instance's configuration file.

 
c4cf : a Conf4CFile

conf4c_file_get_section_count () 

int	conf4c_file_get_section_count	(const Conf4CFile *c4cf);
Returns the number of Conf4CSections contained within the Conf4CFile.

 
c4cf : a Conf4CFile

conf4c_file_get_section_type () 

char *	conf4c_file_get_section_type	(const Conf4CFile *c4cf,
					 const unsigned int index);
Returns the type of the Conf4CSection indicated by the specified index.

 
c4cf : a Conf4CFile
index : a positive index indicating which Conf4CSection to reference
Returns : a NULL value if the index is invalid

conf4c_file_get_section_index () 

int	conf4c_file_get_section_index	(const Conf4CFile *c4cf,
					 const char *type);
Locates a Conf4CSection by its type and returns the index of the specified section.

 
c4cf : a Conf4CFile
type : a string specifying the section type
Returns : a -1 if the specified section type is not found

conf4c_file_get_section_by_index () 

Conf4CSection *	conf4c_file_get_section_by_index	(const Conf4CFile *c4cf
								 const unsigned int index);
Returns a pointer to the indexed Conf4CSection.

 
c4cf : a Conf4CFile
index : the index of the desired Conf4CSection
Returns : NULL is the index is invalid

conf4c_file_get_section_by_type () 

Conf4CSection	conf4c_file_get_section_by_type	(const Conf4CFile *c4cf,
							 const char *type);
Returns a pointer to the identified Conf4CSection.

 
c4cf : a Conf4CFile
type : a string identifying the section type
Returns : NULL if the specified section type is not found
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Conf4CSection

Conf4CSection - A container which manages instances of a Section type

Synopsis 

#include "conf4cstor.h"
#include "conf4cvector.h"

struct Conf4CSection;

Conf4CSection *	conf4c_section_new 			(const char *type,
				    	 	 	 const int initial_capacity);
int		conf4c_section_add_stor 		(Conf4CSection *csect,
					 	 	 Conf4CStor *cs);
Conf4CStor *	conf4c_section_get_stor_by_name		(const Conf4CSection *csect,
						 	 const char *name);
Conf4CStor *	conf4c_section_get_stor_by_index	(const Conf4CSection *csect,
							 const unsigned int index);
int 		conf4c_section_get_stor_count		(const Conf4CSection *csect);
char *		conf4c_section_get_type			(const Conf4CSection *csect);
char *		conf4c_section_get_stor_name 		(const Conf4CSection *csect, 
							 const int index);
int		conf4c_section_get_stor_index		(const Conf4CSection *csect,
							 const char *name);

Description

Conf4CSection contains all instances of a specific section type. A Conf4CSection is also identified by it's type.

Details

struct Conf4CSection 

struct Conf4CSection;
This should not be accessed directly. Use the accessor functions below.

conf4c_section_new () 

Conf4CSection *	conf4c_section_new	(const char *type,
				 	 const int initial_capacity);

 
type : A string indicating the section-type
initial_capacity : The number of Conf4CStor instances to allocate for, initially
Returns : a Conf4CSection

conf4c_section_add_stor () 

int	conf4c_section_add_stor (Conf4CSection csect, Conf4CStor *cs);
Add a Conf4CStor to a Conf4CSection.

 
csect : a Conf4CSection
cs : the Conf4CStor to add
Returns : an int indicating success or failure; 1 = success, 0 = failure

conf4c_section_get_stor_by_name () 

Conf4CStor * conf4c_section_get_stor_by_name (const Conf4CSection *csect, const char *name);
Retrieve a Conf4CStor by the stor's name.

 
csect: a Conf4CSection
name: the name of the Conf4CStor instance
Returns: NULL if the named Conf4CStor is not found

conf4c_section_get_stor_by_index () 

Conf4CStor * conf4c_section_get_stor_by_index (const Conf4CSection *csect, const unsigned int index);
Retrieve a Conf4CStor by the stor's index.

 
csect: a Conf4CSection
index: the index of the Conf4CStor instance within the collection
Returns: NULL if the index is invalid

conf4c_section_get_stor_count () 

int conf4c_section_get_stor_count (const Conf4CSection *csect);

 
csect: a Conf4CSection
Returns: the number of Conf4CStor instances stored within the Conf4CSection

conf4c_section_get_type () 

char * conf4c_section_get_type (const Conf4CSection *csect);

 
csect : a Conf4CSection
Returns : the type of the Conf4CSection

conf4c_section_get_stor_name () 

char * conf4c_section_get_stor_name (const Conf4CSection *csect, const int index);

 
csect: a Conf4CSection
index: the index of a Conf4CStor within the collection
Returns: the name of the indicated Conf4CStor instance or NULL if index is invalid

conf4c_section_get_stor_index () 

int conf4c_section_get_stor_index (const Conf4CSection *csect, const char *name);

 
csect: a Conf4CSection
name: the name of the Conf4CStor instance
Returns: the index of the named Conf4CStor or -1 if the instance is not found
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Conf4CStor

Conf4CStor - A collection of Conf4CValue instances representing a specific section-type instance

Synopsis 

#include "conf4cvalue.h"
#include "conf4cvector.h"

struct Conf4CStor;

Conf4CStor * 	conf4c_stor_new 		(const char *name, 
						 const int initial_capacity);
int		conf4c_stor_add_conf4cvalue 	(Conf4CStor *cs, 
						 Conf4CValue *cv);
char *		conf4c_stor_get_name 		(const Conf4CStor *cs);
int		conf4c_stor_get_value_count 	(const Conf4CStor *cs);
char *		conf4c_stor_get_value_name 	(const Conf4CStor *cs, 
						 int index);
Conf4CValue *	conf4c_stor_get_value_by_name 	(const Conf4CStor *cs, 
						 const char *name);
Conf4CValue *	conf4c_stor_get_value_by_index 	(const Conf4CStor *cs, 
						 const unsigned int index);
int		conf4c_stor_get_value_index 	(const Conf4CStor *cs, 
						 const char *name);

Description

Sections of a configuration file are recognized as name / value pairs existing between '<section_type instance_name></section_type>' pairs. A Conf4CStor maintains the name / value pairs which exist between the opening and closing section tags and is identified by 'instance_name'.

Details

struct Conf4CStor 

struct Conf4CStor;
This should not be accessed directly. Use the accessor functions below.

conf4c_stor_new () 

Conf4CStor * conf4c_stor_new (const char *instance_name, const int initial_capacity);
Creates a new Conf4CStor struct.

conf4c_stor_add_conf4cvalue () 

int conf4c_stor_add_conf4cvalue (Conf4CStor *cs, Conf4CValue cv);
Add a Conf4CValue to an instance of Conf4CStor.

 
cs: the Conf4CStor instance to add the Conf4CValue to
cv: a Conf4CValue
Returns: an int value indicating success or failure; 1 = success and 0 = failure

conf4c_stor_get_name () 

char * conf4c_stor_get_name (const Conf4CStor *cs);
Return the 'instance_name' of the Conf4CStor.

 
cs: a Conf4CStor
Returns: the 'instance_name' of the specified Conf4CStor

conf4c_stor_get_value_count () 

int conf4c_stor_get_value_count (const Conf4CStor *cs);
Returns the number of name / value pairs contained in the Conf4CStor.

 
cs: a Conf4CStor
Returns: the number of stored Conf4CValue instances

conf4c_stor_get_value_name () 

char * conf4c_stor_get_value_name (const Conf4CStor *cs, int index);
Fetch the name of a Conf4CValue instance contained within a Conf4CStor

 
cs: a Conf4CStor
index: an integer identifying which Conf4CValue instance to reference
Returns: the name of the specified Conf4CValue or NULL if the index is invalid

conf4c_stor_get_value_by_index () 

Conf4CValue * conf4c_stor_get_value_by_index (const Conf4CStor *cs, const unsigned int index);
Retrieve the Conf4CValue located at index 'index'.

 
cs: a Conf4CStor
index: an integer identifying which Conf4CValue instance to return
Returns: the Conf4CValue located at 'index' or NULL if the index is invalid

conf4c_stor_get_value_by_name () 

Conf4CValue * conf4c_stor_get_value_by_name (const Conf4CStor *cs, const char *name);
Retrieve the Conf4CValue named 'name'.

 
cs : a Conf4CStor
name : the 'name' portion of a name / value pair
Returns : a Conf4CValue instance or NULL if no Conf4CValue is found with name 'name'.

conf4c_stor_get_value_index () 

int conf4c_stor_get_value_index (const Conf4CStor *cs, const char *name);
Obtain the index of the Conf4CValue identified by 'name'.

 
cs: a Conf4CStor
name: the 'name' portion of a name / value pair
Returns: the index of the specified Conf4CValue or -1 if the Conf4CValue is not found
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Conf4CValue

Conf4CValue - Struct for management and storage of a single name / value pair

Synopsis 

struct Conf4CValue;

Conf4CValue * 	conf4c_value_new (const char *name, const char *value);
Conf4CValue * 	conf4c_value_update (Conf4CValue *cv, const char *value);
Conf4CValue * 	conf4c_value_get_name (const Conf4CValue *);
Conf4CValue * 	conf4c_value_get_value (const Conf4CValue *);

Description

The Conf4CValue struct encapsulates a name / value pair of a configuration file.

Details

struct Conf4CValue 

struct Conf4CValue;
This should not be accessed directly. Use the accessor functions below.

conf4c_value_new () 

Conf4CValue * conf4c_value_new (const char *name, const char *value);
Creates a new Conf4CValue struct.

conf4c_value_update () 

Conf4CValue * conf4c_value_update (Conf4CValue *cv, const char *value);
Updates the value portion of the specified name / value pair.

 
cv: a Conf4CValue
value: a string configuration value
Returns: the updated Conf4CValue

conf4c_value_get_name () 

char * conf4c_value_get_name (const Conf4CValue *cv);
Retrieves the name of the name / value pair.

 
cv: a Conf4CValue
Returns: The name of the stored name / value pair.

conf4c_value_get_value () 

char * conf4c_value_get_value (const Conf4CValue *cv);
Retrieves the value of the name / value pair.

 
cv: a Conf4CValue
Returns: The string value of the stored name / value pair.
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Index

[Top] [Contents] [Index] [ ? ]

Table of Contents

[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on October, 29 2004 using texi2html 1.70.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back previous section in reading order 1.2.2
[ > ] Forward next section in reading order 1.2.4
[ << ] FastBack beginning of this chapter or previous chapter 1
[ Up ] Up up section 1.2
[ >> ] FastForward next chapter 2
[Top] Top cover (top) of document  
[Contents] Contents table of contents  
[Index] Index index  
[ ? ] About about (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated on October, 29 2004 using texi2html 1.70.