ini::File Class Reference

An INI file contains information for programs. More...

#include <IniFile.h>

Public Member Functions
	File ()
	File (const std::string &rsFullFileName, TdOpenInifileMode openMode)
virtual	~File ()
int	getAsBlob (eut::Blob *&prBlob)
std::string	getFileName ()
int	getKeyValue (std::string &rsValue, std::string *psSection, std::string *psKey)
int	getLine (Line *&prRetVal, std::size_t nPosition, ptl::SeekMode eMode)
int	getLine (Line *&prRetVal, std::string *psSection, std::string *psKey=0)
int	insertLine (Line *pIniLine, ptl::InsertPosition eInsertPosition=ptl::InsertCURRENT, ptl::VH eBeforeBehind=ptl::BEHIND)
int	makeLines (eut::Blob *pBlob)
int	refresh ()
int	removeKey (const std::string &rsSection, const std::string &rsKey)
int	removeLine (ptl::ElementPosition eFirstLastCurrent=ptl::CURRENT_POS)
void	setFullFileName (const std::string &rsFullFileName)
int	setKeyValue (const std::string &rsSection, const std::string &rsKey, const std::string &rsValue)
int	store ()

Private Member Functions
	File (const File &)
File &	operator= (const File &)

Private Attributes
LineFactory	m_LineFactory
ptl::TDVList< Line >	m_LineList
std::string	m_sFileName

Detailed Description

An INI file contains information for programs.

An INI file can contain sections with variables and values and comments. The information can be created, read and maintained with ini::File.

Code snippets

In the following an INI file "test.ini" is created:

#include "IniFile.h"
#include "EuException.h"
#include <iostream>
 
int main(int argc, char *argv[])
{
  int         t_iErr = 0;
  ini::File * t_pIniFile = 0;
  //--------------------------------------------------------------------------
  // New Ini-File "test.ini"
  try
  {
    t_pIniFile = new ini::File( "test.ini", ini::bCreateInifile );
  }
  catch( eut::ErrorNException ERR )
  {
    std::cout << "Error :" << ERR.what() <<  "ErrNo.:" << ERR.error() << std::endl;
    return ERR.error();
  }
  // new sections with new keys
  if ( ! t_iErr ) t_iErr = t_pIniFile->setKeyValue( "[Section 1]", "Key 1.1", "Value 1.1" );
  if ( ! t_iErr ) t_iErr = t_pIniFile->setKeyValue( "[Section 1]", "Key 1.2", "Value 1.2" );
  if ( ! t_iErr ) t_iErr = t_pIniFile->setKeyValue( "[Section 2]", "Key 2.1", "Value 2.1" );
  if ( ! t_iErr ) t_iErr = t_pIniFile->setKeyValue( "[Section 2]", "Key 2.2", "Value 2.2" );
  // a comment
  ini::Line  *  t_pCommentLine = 0;
  try
  {
    t_pCommentLine = new ini::Line( "; comment 1" );
  }
  catch( eut::ErrorNException ERR )
  {
    std::cout << "Error :" << ERR.what() <<  "ErrNo.:" << ERR.error() << std::endl;
    t_iErr = ERR.error();
  }
  if ( ! t_iErr )
  {
    t_iErr = t_pIniFile->insertLine( t_pCommentLine );
  }
 
  // a lonly key
  if ( ! t_iErr ) t_iErr = t_pIniFile->setKeyValue( "", "Lonly Key 1", "Value 1" );
  // and store the Ini-File
  if ( ! t_iErr ) t_iErr = t_pIniFile->store();
  delete t_pIniFile; t_pIniFile = 0;
}

The INI file "test.ini" has the following contents:

[Section 1]
Key 1.1=Value 1.1
Key 1.2=Value 1.2
[Section 2]
Key 2.1=Value 2.1
Key 2.2=Value 2.2
; comment 1
Lonly Key 1=Value 1

In the INI file "test.ini" the key "Key 1.2" is fetched from the section "[Section 1]", displayed and changed to "new Value":

#include "IniFile.h"
#include "EuException.h"
#include <iostream>
 
int main(int argc, char *argv[])
{
  int         t_iErr = 0;
  ini::File * t_pIniFile = 0;
  //--------------------------------------------------------------------------
  // show and change a key in test.ini
  try
  {
    t_pIniFile = new ini::File( "test.ini", ini::bOpenInifile );
  }
  catch( eut::ErrorNException ERR )
  {
    std::cout << "Error :" << ERR.what() <<  "ErrNo.:" << ERR.error() << std::endl;
    return ERR.error();
  }
  // get the value from "Section 1", "Key 1.2"
  std::string t_sValue,
              t_sSection2( "[Section 1]" ),
              t_sKey( "Key 1.2" );
 
  t_iErr = t_pIniFile->getKeyValue( t_sValue, & t_sSection2, & t_sKey );
  if ( ! t_iErr ) std::cout << "The value from 'Section 1', 'Key 1.2' is: " << t_sValue << std::endl;
  if ( ! t_iErr ) t_iErr = t_pIniFile->setKeyValue( "[Section 1]", "Key 1.2", "new Value" );
  if ( ! t_iErr ) t_iErr = t_pIniFile->store();
  delete t_pIniFile; t_pIniFile = 0;
}

The INI file "test.ini" now has the following content:

[Section 1]
Key 1.1=Value 1.1
Key 1.2=new Value
[Section 2]
Key 2.1=Value 2.1
Key 2.2=Value 2.2
; comment 1
Lonly Key 1=Value 1

All entries can be identified...

#include "IniFile.h"
#include "EuException.h"
#include <iostream>
 
int main(int argc, char *argv[])
{
  int         t_iErr = 0;
  ini::File * t_pIniFile = 0;
  //--------------------------------------------------------------------------
  // show complete test.ini
  try
  {
    t_pIniFile = new ini::File( "test.ini", ini::bOpenInifile );
  }
  catch( eut::ErrorNException ERR )
  {
    std::cout << "Error :" << ERR.what() <<  "ErrNo.:" << ERR.error() << std::endl;
    return ERR.error();
  }
  ini::Line  *  t_pShowLine = 0;
 
  std::cout << "############# " << t_pIniFile->getFileName() << " #############" << std::endl;
  t_iErr = t_pIniFile->getLine( t_pShowLine, 0, ptl::START );
  while ( t_pShowLine )
  {
    std::cout << t_pShowLine->getText() << std::endl;
    // if section, show sectionlines
    if ( t_pShowLine->getType() == ini::LINE_TYPE::IniSECTION )
    {
      ini::Section  * t_pCastSectionLine = dynamic_cast<ini::Section*>(t_pShowLine);
      ini::Line     * t_pShowSectionLine = 0;
 
      t_iErr = t_pCastSectionLine->getSectionLine( t_pShowSectionLine, 0, ptl::START );
      while ( t_pShowSectionLine )
      {
        std::cout << t_pShowSectionLine->getText() << std::endl;
        t_iErr = t_pCastSectionLine->getSectionLine( t_pShowSectionLine, 1, ptl::CURRENT );
      }
      t_iErr = ( t_iErr == eut::ERR_RANGE ? 0 : t_iErr );
    }
    t_iErr = t_pIniFile->getLine( t_pShowLine, 1, ptl::CURRENT );
  }
  t_iErr = ( t_iErr == ptl::RANGE ? 0 : t_iErr );
  std::cout << "####################################" << std::endl;
  std::cout << "ErrNo.:" << t_iErr << std::endl;
  delete t_pIniFile; t_pIniFile = 0;
}

... and results in the following output:

############# test.ini #############
[Section 1]
Key 1.1=Value 1.1
Key 1.2=new Value
[Section 2]
Key 2.1=Value 2.1
Key 2.2=Value 2.2
; comment 1
Lonly Key 1=Value 1
####################################
ErrNo.:0

Author

Helmut Jakoby

Copyright

© 1995 Helmut Jakoby

Constructor & Destructor Documentation

File() [1/3]

ini::File::File	(	const std::string &	rsFullFileName,
		TdOpenInifileMode	openMode )

Constructor with parameter passing.

Parameters

[in]	rsFullFileName	The complete file name such as: "c:\windows\system.ini"
[in]	openMode	If openMode is ini::bCreateInifile, then an attempt is made to generate a new INI-file. If openMode is ini::bOpenInifile, then an attempt is made to read in the INI-file with the specified name.

Exceptions

eut::ErrorNException

An exception is thrown if an error occurs.

Referenced by File(), and operator=().

File() [2/3]

ini::File::File

(

)

Default constructor.

~File()

virtual ini::File::~File ( )

virtual

Destructor, memory is released.

File() [3/3]

ini::File::File ( const File & )

private

The copy constructor is not available.

References File().

Member Function Documentation

getAsBlob()

int ini::File::getAsBlob

(

eut::Blob *&

prBlob

)

Returns all entries of the file in one blob.

Parameters

[in,out]

prBlob

The File as blob.

Returns

A return value < 0 indicates an error.

Attention

The calling instance must remove the delivered blob from memory.

getFileName()

std::string ini::File::getFileName

(

)

Returns the name of the INI file.

Returns

The name.

getKeyValue()

int ini::File::getKeyValue	(	std::string &	rsValue,
		std::string *	psSection,
		std::string *	psKey )

Returns a KeyValue.

Parameters

[in,out]	rsValue	The found KeyValue as std::string.
[in]	psSection	If set and psKey not set -> Error. If set and psKey is also set, the Key from the psSection wanted. If not set and psKey is set, the Key without section is searched.
[in]	psKey	See psSection.

If there should be the following entry in an INI file:

[386enh]
woafont=app850.fon <- Variable with value

returns this function when calling:

int t_iErr = pMyIniFile->getKeyValue( sValue, "[386nh]", "woafont");

in rsValue "app850.fon" back.

Returns

A return value < 0 indicates an error.

getLine() [1/2]

int ini::File::getLine	(	Line *&	prRetVal,
		std::size_t	nPosition,
		ptl::SeekMode	eMode )

Returns an Line from the m_LineList with respect to the pass parameters.

Parameters

[in,out]	prRetVal	passed reference into which the found object "comes in"
[in]	nPosition	Offset relative to...
[in]	eMode	...Position

Parameter examples:

• Delivers first element from list: lPosition = 0; eMode = ptl::START
• Delivers last element from list: lPosition = 0; eMode = ptl::END
• Delivers current element from list: lPosition = 0; eMode = ptl::CURRENT_POS
• Delivers next element from list: lPosition = 1; eMode = ptl::CURRENT_POS
• Returns previous element from list: lPosition = -1; eMode = ptl::CURRENT_POS

Returns

A return < 0 indicates an error.

Attention

The returned object (in prRetVal) must not be removed from memory by the calling instance!

getLine() [2/2]

int ini::File::getLine	(	Line *&	prRetVal,
		std::string *	psSection,
		std::string *	psKey = 0 )

Returns a section or a key.

Parameters

[in,out]	prRetVal	If found, depending on the other parameters a pointer to an object of type Section or Key.
[in]	psSection	If set and psKey not set, the Section is searched for. If set and psKey is also set, the Key from the psSection wanted. If not set and psKey is set, the Key without section is searched.
[in]	psKey	See psSection.

Returns

A return value < 0 indicates an error.

Attention

The object returned in prRetVal must not be removed from memory by the calling instance!

insertLine()

int ini::File::insertLine	(	Line *	pIniLine,
		ptl::InsertPosition	eInsertPosition = ptl::InsertCURRENT,
		ptl::VH	eBeforeBehind = ptl::BEHIND )

Inserts the transferred entry into the m_LineList.

Parameters

[in]	pIniLine	The object of the class Line to be inserted
[in]	eInsertPosition	Shows where the data object is inserted in the list is to be inserted. Possible parameters are ptl::InsertHEAD (on Start), ptl::InsertLAST (at the end) or ptl::InsertCURRENT (at the current element).
[in]	eBeforeBehind	Specifies whether the new element is before or after the, element specified in the eInsertPosition parameter. Possible Parameters are BEHIND and BEFORE

Returns

A return value < 0 indicates an error.

Attention

ini::File assumes responsibility for the Line transferred in pIniLine. This means that the calling instance must not remove the passed object from memory!

References ptl::BEHIND, and ptl::InsertCURRENT.

makeLines()

int ini::File::makeLines

(

eut::Blob *

pBlob

)

Creates the individual entries in the INI file from the blob passed.

Parameters

[in]

pBlob

The blob with the contents of an INI file. The blob is evaluated and all entries are created.

Returns

A return value < 0 indicates an error.

operator=()

File & ini::File::operator= ( const File & )

private

Assignment operator is not available.

References File().

refresh()

int ini::File::refresh

(

)

The INI file from m_sFileName is read in.

Returns

A return < 0 indicates an error.

Warning

All possible changes are discarded.

removeKey()

int ini::File::removeKey	(	const std::string &	rsSection,
		const std::string &	rsKey )

Removes an entry

Parameters

[in]	rsSection	Section
[in]	rsKey	entry

Removes an entry as follows:

• If section is passed, this is searched for. If present and entry is not set, the section is removed from the INI file.
• If entry is passed, the variable from the entry is searched for in the section or INI file. If found, the variable is removed from the section or INI file.

Returns

A return value < 0 indicates an error.

removeLine()

int ini::File::removeLine

(

ptl::ElementPosition

eFirstLastCurrent = ptl::CURRENT_POS

)

Removes the entry from the m_LineList.

If a subsequent element exists, it becomes the current element, otherwise the previous element if it exists. The destructor is called from the removed entry.

Parameters

[in]

eFirstLastCurrent

The following values are possible: ptl::FIRST_POS, ptl::LAST_POS, (default) ptl::CURRENT_POS, ptl::NEXT_POS and ptl::PREVIOUS_POS.

Returns

A return value < 0 indicates an error.

References ptl::CURRENT_POS.

setFullFileName()

void ini::File::setFullFileName

(

const std::string &

rsFullFileName

)

Sets the name of the INI file.

Parameters

[in]

rsFullFileName

The complete file name such as: "c:\windows\system.ini"

setKeyValue()

int ini::File::setKeyValue	(	const std::string &	rsSection,
		const std::string &	rsKey,
		const std::string &	rsValue )

Sets an entry

Parameters

[in]	rsSection	The section either with '[' and ']' or without these two characters.
[in]	rsKey	The entry
[in]	rsValue	The value

Sets an entry like this:

• If section is passed, it is searched for. If it does not exist, the section is created. If no section is passed, the INI file is the section.
• If entry and value are passed, the variable from the entry is searched for in the section. If it is found, the value is set, otherwise the entire variable with value is inserted.

Returns

A return value < 0 indicates an error.

store()

int ini::File::store

(

)

The INI file from m_sFileName is saved.

Returns

A return < 0 indicates an error.

Member Data Documentation

m_LineFactory

LineFactory ini::File::m_LineFactory

private

The LineFactory returns an INI file entry according to type.

m_LineList

ptl::TDVList<Line> ini::File::m_LineList

private

List of entries in this INI file.

m_sFileName

std::string ini::File::m_sFileName

private

The name of the INI file is stored in this attribute.

---

The documentation for this class was generated from the following file:

• IniFile.h