A simple INI file manager - Version 2. More...

#include <IniManager.h>

Public Types
enum	INI_Return { INI_V1_FAIL = 0, INI_V1_SUCCESS = 1, INI_SUCCESS = 0, INI_NO_FILE_SPEC, INI_FILE_NOT_FOUND, INI_SECTION_NOT_FOUND, INI_KEY_NOT_FOUND, INI_BUF_TOO_SMALL, INI_INTERNAL_ERROR }
	Return values. More...
Public Member Functions
	INI (const char *file=NULL, int Version=2)
	Constructor for an INI file interface.
	~INI (void)
	destructor for the ini manager.
bool	Exists (const char *file=NULL)
	Determine if a file exists.
bool	SetFile (const char *file, int Version=2)
	set the file to use
const char *	GetFile (void)
	get the filename in use
INI_Return	ReadString (const char section, const char key, char buffer, size_t bufferSize, const char defaultString=NULL)
	Read a string from the ini file - if it exists.
long int	ReadLongInt (const char section, const char key, long int defaultValue)
	Read a long integer from the ini file - if it exists.
INI_Return	WriteString (const char section, const char key, const char *buffer, int len=-1)
	Writes a string into the ini file.
INI_Return	WriteLongInt (const char section, const char key, long int value)
	Writes a long integer into the ini file.
bool	GetNextSection (const char after, char buffer, size_t bufferSize)
	Get Section, or Next Section name.
bool	GetNextKey (const char Section, const char after, char *buffer, size_t bufferSize)
	Get the first Key, or the next Key, within a section.
const char *	GetReturnMessage (INI_Return retVal)
	Get the text message for an error return value from ReadString and WriteString.

Detailed Description

A simple INI file manager - Version 2.

This is a simple ini file manager intended for low duty cycle usage.

It follows an old "Windows" style of ini file format with section, key, and value.

Note:: An API change offers DIFFERENT AND INCOMPATIBLE return values from the WriteString and the ReadString APIs, however it is backward compatible, requiring a new parameter in the constructor or the SetFile API to access the new return values.; Version 1 by default will be deprecated in a future release, probably around mid to late 2017.

As a "simple" ini file manager, this version does not cache anything internally. This comes at the "cost" that each write transaction will read and replace the ini file. Read transactions will open and scan the file.

Also, an internal stack-frame buffer is used to manage the read operations. As such, no single record in the file can exceed this buffer size (compile time set with a default of 250 bytes).

 INI ini("/local/settings.ini");
 ...
 char buf[10];
 sprintf_s(buf, 10, "%d", daymask);
 if (INI::INI_SUCCESS == ini.WriteString("Alarm", "Daymask", buf)) {
     ...
 }
 ...
 uint8_t x = (uint8_t)ReadLongInt("Alarm", "Daymask", 0);
 ...

A single record for a section is surrounded with '[' and ']' and a new line appended. A single record for an entry within a section for a key, value pair is separated with an '=' and a new line appended.

 [section name]
 Key name=value for Key name
 Another key=another value

Definition at line 52 of file IniManager.h.

Member Enumeration Documentation

enum INI_Return

Return values.

Functions may return a status code as follows. Where the API supports a default, and on a Fail code, that value will be returned, if it fits in the available buffer.

Note:: Version 1 returned only a success or failure value from the ReadString and the WriteString APIs. Version 2 returns incompatible and different values. The selection of version 1 vs. version 2 is made in either the constructor, or in the SetFile API.

Enumerator:

INI_V1_FAIL	Version 1 return value - Fail.
INI_V1_SUCCESS	Version 1 return value - Success.
INI_SUCCESS	Success - operation succeeded.
INI_NO_FILE_SPEC	Fail - no file was specified.
INI_FILE_NOT_FOUND	Fail - ini file not found, or failed to open.
INI_SECTION_NOT_FOUND	Fail - section not found.
INI_KEY_NOT_FOUND	Fail - key not found.
INI_BUF_TOO_SMALL	Fail - buffer to small for value.
INI_INTERNAL_ERROR	Fail - internal error - can't alloc buffers.

Definition at line 67 of file IniManager.h.

Constructor & Destructor Documentation

INI	(	const char *	file = `NULL`,
		int	Version = `2`
	)

Constructor for an INI file interface.

Parameters:

[in]	file	is the filename to manage. Memory is allocated to hold a private copy of the filename. Be sure that this parameter has the right path prefix based on what file system you have.
[in]	Version	is an optional parameter that defines whether the return value of the ReadString and WriteString APIs are version 1 or version 2 compatible. The default is version 2.

Definition at line 47 of file IniManager.cpp.

~INI ( void )

destructor for the ini manager.

releases the memory allocation.

Definition at line 55 of file IniManager.cpp.

Member Function Documentation

bool Exists ( const char * file = NULL )

Determine if a file exists.

This API can be used to determine if a file exists. The file may be specified as a parameter, but if no parameter is supplied it will then check to see if the INI file exists. This is either the file passed to the constructor, or the file passed to the SetFile API.

Parameters:

[in] file is the optional filename to check for existance.

Returns:: true if the file exists.

Definition at line 162 of file IniManager.cpp.

const char* GetFile ( void )

get the filename in use

Returns:: pointer to the filename

Definition at line 127 of file IniManager.h.

bool GetNextKey	(	const char *	Section,
		const char *	after,
		char *	buffer,
		size_t	bufferSize
	)

Get the first Key, or the next Key, within a section.

This can be used to walk the list of keys in a file.

Parameters:

[in]	Section	is the name of the section to search.
[in]	After	is the name of the key to search after. When NULL, it is a "find-first" method.
[out]	buffer	is the caller provided buffer for this method to put the string into.
[in]	bufferSize	is the caller provided declaration of the available space.

Returns:: true if a new key was found, false otherwise.

Definition at line 105 of file IniManager.cpp.

bool GetNextSection	(	const char *	after,
		char *	buffer,
		size_t	bufferSize
	)

Get Section, or Next Section name.

This can be used to walk the list of section names in a file.

Parameters:

[in]	After	is the name of the section to search after. When NULL, it is a "find-first" method.
[out]	buffer	is the caller provided buffer for this method to put the string into.
[in]	bufferSize	is the caller provided declaration of the available space.

Returns:: true if a new section was found, false otherwise.

Definition at line 62 of file IniManager.cpp.

const char * GetReturnMessage ( INI_Return retVal )

Get the text message for an error return value from ReadString and WriteString.

Parameters:

[in] retVal is the return value from either the ReadString or the WriteString APIs.

Returns:: a pointer to a string which describes the return value.

Definition at line 546 of file IniManager.cpp.

long int ReadLongInt	(	const char *	section,
		const char *	key,
		long int	defaultValue
	)

Read a long integer from the ini file - if it exists.

This searches the ini file for the named section and key and if found it will return the long integer value from that entry.

Parameters:

[in]	section	is the name of the section to search.
[in]	key	is the name of the key to search.
[in]	defaultValue	is the default value to return if the entry is not found.

Returns:: the value read, or the defaultVaule; no failure code is returned.

Definition at line 274 of file IniManager.cpp.

INI::INI_Return ReadString	(	const char *	section,
		const char *	key,
		char *	buffer,
		size_t	bufferSize,
		const char *	defaultString = `NULL`
	)

Read a string from the ini file - if it exists.

This searches the ini file for the named section and key and if found it will return the string associated with that entry into a user supplied buffer.

Parameters:

[in]	section	is the name of the section to search.
[in]	key	is the name of the key to search.
[out]	buffer	is the caller provided buffer for this method to put the string into.
[in]	bufferSize	is the caller provided declaration of the available space.
[in]	defaultString	is an optional parameter that sets the buffer if the section/key is not found. if defaultString is NULL (or omitted), and if the item cannot be found, it will return INI_KEY_NOT_FOUND.

Returns:: INI_SUCCESS if the file, section, key, and value are found, and it fits into the specified buffer.; INI_NO_FILE_SPEC if the ini file was never set.; INI_FILE_NOT_FOUND if the ini file was specified, but cannot be found as specified.; INI_SECTION_NOT_FOUND if the section was not found.; INI_KEY_NOT_FOUND if the key was not found.; INI_BUF_TOO_SMALL if everything was found, but it could not fit into the specified buffer.

Definition at line 200 of file IniManager.cpp.

bool SetFile	(	const char *	file,
		int	Version = `2`
	)

set the file to use

If not set at the time of construction, or if a change is needed, this API can be used.

Parameters:

[in]	file	is the filename to manage.
[in]	Version	is an optional parameter that defines whether the return value of the ReadString and WriteString APIs are version 1 or version 2 compatible. The default is version 2.

Returns:: true if success, false if memory could not be allocated.

Definition at line 179 of file IniManager.cpp.

INI::INI_Return WriteLongInt	(	const char *	section,
		const char *	key,
		long int	value
	)

Writes a long integer into the ini file.

This writes a given long integer into an ini file in the named section and key.

Parameters:

[in]	section	is the name of the section to search.
[in]	key	is the name of the key to search.
[in]	value	is the long integer.

Returns:: INI_SUCCESS if the file, section, key, and value are written.; INI_NO_FILE_SPEC if the ini file was never set.; INI_FILE_NOT_FOUND if the ini file was specified, but cannot be found as specified.; INI_SECTION_NOT_FOUND if the section was not found.; INI_KEY_NOT_FOUND if the key was not found.; INI_BUF_TOO_SMALL if everything was found, but it could not fit into the specified buffer.

Definition at line 317 of file IniManager.cpp.

INI::INI_Return WriteString	(	const char *	section,
		const char *	key,
		const char *	buffer,
		int	len = `-1`
	)

Writes a string into the ini file.

This writes a given string into an ini file in the named section and key.

Parameters:

[in]	section	is the name of the section to search.
[in]	key	is the name of the key to search.
[in]	buffer	is the caller provided buffer containing the string to write. If buffer is NULL, then any existing entry is removed.
[in]	len	is the number of characters to write, if specified. If not specified, the length of the buffer defines the length to write.

Returns:: INI_SUCCESS if the file, section, key, and value are written.; INI_NO_FILE_SPEC if the ini file was never set.; INI_FILE_NOT_FOUND if the ini file was specified, but cannot be found as specified.; INI_SECTION_NOT_FOUND if the section was not found.; INI_KEY_NOT_FOUND if the key was not found.; INI_BUF_TOO_SMALL if everything was found, but it could not fit into the specified buffer.

Definition at line 329 of file IniManager.cpp.

Type:	Library
Created:	12 Aug 2013
Imports:	37
Forks:	0
Commits:	29
Dependents:	4
Dependencies:	0
Followers:	4

Important changes to repositories hosted on mbed.com

INI Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

INI Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning